Generating a Signature - Checkout documentation

A Signature is the parameter used for message authentication and it is calculated based on the concatenation of fields. Signature is created based on the JSON prepared for the request, using one of SHA224/SHA256/SHA284/SHA512 algorithms. Only the values of the fields are concatenated, not the names of the parameters.

WARNING

Requests sent to ZEN.COM checkout that do not have the calculated signature parameter or contain an incorrectly calculated Signature will be rejected by ZEN.COM.

INFO

For below examples:
SHA: SHA256
paywallSecret: c8c93c452d38acf3183d2f08fee60aa7

How to generate Signature?

signature = signatureAlgorithm(key1=val1&key2=val2&…&keyN=valNpaywallSecret)

Convert the JSON object to a flat structure.

Prepare the JSON request based on required and optional parameters

💡

Example of JSON

{
   "terminalUuid":"05b692d0-00b9-48f7-92ca-1509f055df2e",
   "amount":1000,
   "currency":"PLN",
   "merchantTransactionId":"trasaction1",
   "customer":{
      "id":"CustomerId328642",
      "firstName":"John",
      "lastName":"Doe",
      "email":"[email protected]"
   },
   "items":[
      {
         "code":"itemCode1",
         "category":"itemCategory1",
         "name":"itemName1",
         "price":200,
         "quantity":2,
         "lineAmountTotal":400
      },
      {
         "code":"itemCode2",
         "category":"itemCategory2",
         "name":"itemName2",
         "price":300,
         "quantity":2,
         "lineAmountTotal":600
      }
   ],
   "billingAddress":{
      "id":"bAId1",
      "firstName":"John",
      "lastName":"Doe",
      "country":"PL",
      "street":"streetName",
      "city":"cityName",
      "countryState":"stateName",
      "province":"provinceName",
      "buildingNumber":"1",
      "roomNumber":"11",
      "postcode":"23-232",
      "companyName":"Company Name",
      "phone":"+48555555555",
      "taxId":"12345678"
   },
   "shippingAddress":{
      "id":"sA1",
      "firstName":"John",
      "lastName":"Doe",
      "country":"PL",
      "street":"streetName",
      "city":"cityName",
      "countryState":"stateName",
      "province":"provinceName",
      "buildingNumber":"1",
      "roomNumber":"11",
      "postcode":"11",
      "companyName":"Company Name",
      "phone":"+48555555555"
   },
   "urlFailure":"https://backtoshop/failure",
   "urlRedirect":"https://backtoshop/redirect",
   "urlSuccess":"https://backtoshop/success",
   "customIpnUrl":"https://backtoshop/notiify",
   "language":"pl"
}

Convert the JSON object to a flat structure.

For non-empty attributes of the object (value <> null), a list of elements 'name=value' should be created by mapping as follows:

Simple attributes should be represented as attributeName=value

💡

Example of simple attribute flat structure
terminalUuid=05b692d0-00b9-48f7-92ca-1509f055df2e

Attributes that are complex objects should be represented as complexAttributeName.attributeName=value

💡

Example of complex object flat structure
billingAddress.firstName=John

Collections should be represented as collectionName[index].attributeName=value, where the index starts at 0

💡

Example of collection flat structure
items[0].code=itemCode1

The elements in the constructed list should be converted to lowercase

💡

Example of elements converted to lowercase
billingAddress.firstName=Jan → billingaddress.firstname=john

The list of elements created in this way should be sorted alphabetically, treating each element as a whole string.

The sorted list of elements should be joined with the & character, creating a single string

💡

Example of joined elements
amount=1000&billingaddress.buildingnumber=1&billingaddress.city=cityname

💡

Example flat form request amount=1000&billingaddress.buildingnumber=1&billingaddress.city=cityname&billingaddress.companyname=company name&billingaddress.country=pl&billingaddress.countrystate=statename&billingaddress.firstname=john&billingaddress.id=baid1&billingaddress.lastname=doe&billingaddress.phone=+48555555555&billingaddress.postcode=23-232&billingaddress.province=provincename&billingaddress.roomnumber=11&billingaddress.street=streetname&billingaddress.taxid=12345678&currency=pln&customer.email=[email protected]&customer.firstname=john&customer.id=customerid328642&customer.lastname=doe&customipnurl=https://backtoshop/notiify&items[0].category=itemcategory1&items[0].code=itemcode1&items[0].lineamounttotal=400&items[0].name=itemname1&items[0].price=200&items[0].quantity=2&items[1].category=itemcategory2&items[1].code=itemcode2&items[1].lineamounttotal=600&items[1].name=itemname2&items[1].price=300&items[1].quantity=2&language=pl&merchanttransactionid=trasaction1&shippingaddress.buildingnumber=1&shippingaddress.city=cityname&shippingaddress.companyname=company name&shippingaddress.country=pl&shippingaddress.countrystate=statename&shippingaddress.firstname=john&shippingaddress.id=sa1&shippingaddress.lastname=doe&shippingaddress.phone=+48555555555&shippingaddress.postcode=11&shippingaddress.province=provincename&shippingaddress.roomnumber=11&shippingaddress.street=streetname&terminaluuid=05b692d0-00b9-48f7-92ca-1509f055df2e&urlfailure=https://backtoshop/failure&urlredirect=https://backtoshop/redirect&urlsuccess=https://backtoshop/success

Add unique Merchant paywallSecret parameter

To the resulting string, the Merchant paywallSecret parameter should be appended at the end.

💡

Example flat form request with paywallSecret parameter
amount=1000&billingaddress.buildingnumber=1&billingaddress.city=cityname&billingaddress.companyname=company name&billingaddress.country=pl&billingaddress.countrystate=statename&billingaddress.firstname=john&billingaddress.id=baid1&billingaddress.lastname=doe&billingaddress.phone=+48555555555&billingaddress.postcode=23-232&billingaddress.province=provincename&billingaddress.roomnumber=11&billingaddress.street=streetname&billingaddress.taxid=12345678&currency=pln&customer.email=[email protected]&customer.firstname=john&customer.id=customerid328642&customer.lastname=doe&customipnurl=https://backtoshop/notiify&items[0].category=itemcategory1&items[0].code=itemcode1&items[0].lineamounttotal=400&items[0].name=itemname1&items[0].price=200&items[0].quantity=2&items[1].category=itemcategory2&items[1].code=itemcode2&items[1].lineamounttotal=600&items[1].name=itemname2&items[1].price=300&items[1].quantity=2&language=pl&merchanttransactionid=trasaction1&shippingaddress.buildingnumber=1&shippingaddress.city=cityname&shippingaddress.companyname=company name&shippingaddress.country=pl&shippingaddress.countrystate=statename&shippingaddress.firstname=john&shippingaddress.id=sa1&shippingaddress.lastname=doe&shippingaddress.phone=+48555555555&shippingaddress.postcode=11&shippingaddress.province=provincename&shippingaddress.roomnumber=11&shippingaddress.street=streetname&terminaluuid=05b692d0-00b9-48f7-92ca-1509f055df2e&urlfailure=https://backtoshop/failure&urlredirect=https://backtoshop/redirect&urlsuccess=https://backtoshop/successc8c93c452d38acf3183d2f08fee60aa7

Encode object using SHA algorithm

The entire object should then be encoded using one of the algorithms: SHA224 / SHA256 / SHA284 / SHA512 (choose one of described).

INFO

For individual API test requests SHA algorithms encoding, you can use for example this website. For production requests, use encoding solutions implemented in your software or available through an additional subscription.

💡

Encoded string sample
6a3493c9a0213fd8a33032bc268da8592218e4bfdfe33c139160369e125366e0

Add name of hashing alrgorithm

To the encoded string, add a semicolon ; followed by the lowercase name of the hashing algorithm used. For described example it is sha256. This will result in the final value of the "signature" attribute.

💡

Example of signature parameter
6a3493c9a0213fd8a33032bc268da8592218e4bfdfe33c139160369e125366e0

Add name of hashing alrgorithm

The generated signature attribute should be added to the input object

💡

Example ofsignature parameter final value
"signature": "6a3493c9a0213fd8a33032bc268da8592218e4bfdfe33c139160369e125366e0;sha256"

💡

Example of JSON request with Signature parameter

{
 "terminalUuid":"05b692d0-00b9-48f7-92ca-1509f055df2e",
 "amount":1000,
 "currency":"PLN",
 "merchantTransactionId":"trasaction1",
 "customer":{
    "id":"CustomerId328642",
    "firstName":"John",
    "lastName":"Doe",
    "email":"[email protected]"
 },
 "items":[
    {
       "code":"itemCode1",
       "category":"itemCategory1",
       "name":"itemName1",
       "price":200,
       "quantity":2,
       "lineAmountTotal":400
    },
    {
       "code":"itemCode2",
       "category":"itemCategory2",
       "name":"itemName2",
       "price":300,
       "quantity":2,
       "lineAmountTotal":600
    }
 ],
 "billingAddress":{
    "id":"bAId1",
    "firstName":"John",
    "lastName":"Doe",
    "country":"PL",
    "street":"streetName",
    "city":"cityName",
    "countryState":"stateName",
    "province":"provinceName",
    "buildingNumber":"1",
    "roomNumber":"11",
    "postcode":"23-232",
    "companyName":"Company Name",
    "phone":"+48555555555",
    "taxId":"12345678"
 },
 "shippingAddress":{
    "id":"sA1",
    "firstName":"John",
    "lastName":"Doe",
    "country":"PL",
    "street":"streetName",
    "city":"cityName",
    "countryState":"stateName",
    "province":"provinceName",
    "buildingNumber":"1",
    "roomNumber":"11",
    "postcode":"11",
    "companyName":"Company Name",
    "phone":"+48555555555"
 },
 "urlFailure":"https://backtoshop/failure",
 "urlRedirect":"https://backtoshop/redirect",
 "urlSuccess":"https://backtoshop/success",
 "customIpnUrl":"https://backtoshop/notiify",
 "language":"pl",
 "signature":"6a3493c9a0213fd8a33032bc268da8592218e4bfdfe33c139160369e125366e0;sha256"
}