Prepare the communication - Checkout documentation

Before you create your first Transaction and send it to the ZEN.COM Payment system, you must set up communication on your side. To do this:

Prepare an endpoint

Add an endpoint on your Shop's server that will create a request to the ZEN.COM checkout. The parameters sent in the checkout session are responsible for controlling what your Customer sees on the Payment page (for example: ordered products, order currency and the available Payment methods associated with it, total order amount).

Define the parameters

Using table of communication parameters define all required and optional parameters to add to JSON request send to ZEN.COM.

Prepare request header

DANGER

Request header with Authorization parameter is obliged for all requests sent to ZEN.COM API. Authorization value is the Terminal API key parameter you can find in your my.zen.com Merchant portal.

Prepare JSON request

Using defined parameters prepare JSON ready to send to ZEN.COM with application/json header.

💡

Example of JSON

{
   "terminalUuid":"19b692d0-00b9-48f7-92ca-1509f055df2e",
   "amount":1000,
   "currency":"EUR",
   "merchantTransactionId":"trasaction1",
   "customer":{
      "id":"CustomerId328642",
      "firstName":"Jan",
      "lastName":"Kowalski",
      "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":"Jan",
      "lastName":"Kowalski",
      "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":"Jan",
      "lastName":"Kowalski",
      "country":"PL",
      "street":"streetName",
      "city":"cityName",
      "countryState":"stateName",
      "province":"provinceName",
      "buildingNumber":"1",
      "roomNumber":"11",
      "postcode":"11-111",
      "companyName":"Company Name",
      "phone":"+48555555555"
   },
   "urlFailure":"https://backtoshop/failure",
   "urlRedirect":"https://backtoshop/redirect",
   "urlSuccess":"https://backtoshop/success",
   "customIpnUrl":"https://backtoshop/notiify",
   "language":"pl"
}

Add signature

The JSON object (Content-Type: application/json), which will be the future body content of the Merchant's request call to ZEN.COM, should be extended by adding the signature attribute. A signature is created based on the JSON prepared for the request, using one of SHA224/SHA256/SHA284/SHA512 algorithms.

💡

Example of JSON with signature parameter added

{
   "terminalUuid":"19b692d0-00b9-48f7-92ca-1509f055df2e",
   "amount":1000,
   "currency":"EUR",
   "merchantTransactionId":"trasaction1",
   "customer":{
      "id":"CustomerId328642",
      "firstName":"Jan",
      "lastName":"Kowalski",
      "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":"Jan",
      "lastName":"Kowalski",
      "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":"Jan",
      "lastName":"Kowalski",
      "country":"PL",
      "street":"streetName",
      "city":"cityName",
      "countryState":"stateName",
      "province":"provinceName",
      "buildingNumber":"1",
      "roomNumber":"11",
      "postcode":"11-111",
      "companyName":"Company Name",
      "phone":"+48555555555"
   },
   "urlFailure":"https://backtoshop/failure",
   "urlRedirect":"https://backtoshop/redirect",
   "urlSuccess":"https://backtoshop/success",
   "customIpnUrl":"https://backtoshop/notiify",
   "language":"pl",
   "signature":"16a36c391255e99596f12d802bf8fbba9b3414a23fc85bbf21974c05183961f3;sha256"
}

Prepare success and failure pages

Prepare publicly accessible success and failure pages and URLs to which ZEN.COM will redirect your Customers for successful and failed Transactions. If you did not specify success and / or failure URLs during the onboarding stage of your Shop, or if you would like to change them dynamically for each Transaction, you can do so by sending the parameters urlSuccess and urlFailure to ZEN.COM.

Prepare a link to initiate ZEN.COM checkout.

To allow initiating a Payment process, place a link (e.g. button) in your Shop that triggers the ZEN.COM checkout.