ZEN checkout integration

ZEN allows direct checkout integration without a complex API implementation through ZEN checkout integration.

 

With ZEN checkout integration, the process only requires communication that initiates a paywall hosted on the ZEN side.

 

If you cannot find the e-commerce platform your store is powered by in our /plugin list/, or your e-commerce platform does not support complex API integration, then this method may be right for you.

 

Before you begin

  1. Log in to your ZEN panel, open the menu and go to Store settings > Payment methods.
  2. Now, select payment methods which you would like to enable on your checkout page.
    Note: For a multiple-terminal setup, please make sure to select the desired terminal from the dropdown list.
  3. Next, locate your integration credentials. See how to get integration credentials.
  4. Then, create a working POST request. See more in the ZEN API documentation.
  5. Finally, correctly receive an IPN from ZEN. 

 

Setting up ZEN checkout

To set up ZEN checkout, you should POST proper form data to this ZEN URL address: https://secure.zen.com/api/payment

 

The below table provides the full description of the form data fields.

Name
Allowed values
Required field
Description

terminalUuid:

string

Y

In order to obtain terminalUuid:
3.1. Login to ZEN account
3.2. Open menu and go to Store settings in the Sell online section
3.3. Visit API & Documentation section
3.4. Terminal UUID corresponds with terminalUuid used in the paywall integration

amount:

string^(?=.*[0-9])\d{1,16}(?:\.\d{1,12})?$

Y

Amount of the transaction. Decimal values are not accepted.
amount of “100” equals one full unit of currency.

currency:

string 3 characters

Y

Currency of the transaction (it will determine payment methods displayed on the paywall)

merchantTransactionId:

string [ 1 .. 128 ] characters ^[a-zA-Z0-9?&:\-\/=.,#]+$

Y

Merchant’s unique identifier of the transaction. No two requests sent by merchant can have same value in this field. Otherwise, the transactions with duplicate number will be immidiately rejected by ZEN.

customer[firstName]:

string <= 128 characters

Y

First name of the buyer

customer[lastName]:

string <= 128 characters

Y

Last name of the buyer

customer[email]:

string <= 256 characters

Y

Email address of the buyer

items[0][code]:

string <= 64 characters

N

Merchant’s code for the sold item

items[0][category]:

string <= 64 characters

N

Merchant’s category for the sold item

items[0][name]:

string <= 128 characters

Y

Name of the sold item

items[0][price]:

string^-?(?=.*[1-9])\d{1,16}(?:\.\d{1,12})?$

Y

Unit price of the sold item

items[0][price]:aitems[0][quantity]:

number

Y

Quantity of the sold items

items[0][lineAmountTotal]:

string^-?(?=.*[1-9])\d{1,16}(?:\.\d{1,12})?$

Y

Total price of the sold items

signature:

Y

Signature of the post

shippingAddress[id]

string <= 64 characters ^[a-zA-Z0-9_-]+$

N

This is ID of the merchant's customer provided by merchant

shippingAddress[firstName]

string <= 128 characters

N

First name of the buyer

shippingAddress[lastName]

string <= 128 characters

N

Last name of the buyer

shippingAddress[country]

string 2 characters ^[A-Z]+$

N

Country of the buyer

shippingAddress[street]

string <= 128 characters

N

Street of the buyer

shippingAddress[city]

string <= 128 characters

N

City of the buyer

shippingAddress[countryState]

string <= 128 characters

N

Country state of the buyer

shippingAddress[province]

string <= 128 characters

N

Province of the buyer

shippingAddress[buildingNumber]

string <= 32 characters

N

Building number of the buyer

shippingAddress[roomNumber]

string <= 32 characters

N

Room number of the buyer

shippingAddress[postcode]

string [ 5 .. 6 ] characters

N

Postcode of the buyer

shippingAddress[companyName]

string <= 128 characters

N

Company name of the buyer

shippingAddress[phone]

string [ 2 .. 64 ] characters ^[0-9\+]+$

N

Phone of the buyer

billingAddress[id]

string <= 64 characters ^[a-zA-Z0-9_-]+$

N

This is ID of the merchant's customer provided by merchant.

billingAddress[firstName]

string <= 128 characters

N

First name of the buyer

billingAddress[lastName]

string <= 128 characters

N

Last name of the buyer

billingAddress[country]

string 2 characters ^[A-Z]+$

N

Country of the buyer

billingAddress[street]

string <= 128 characters

N

Street of the buyer

billingAddress[city]

string <= 128 characters

N

City of the buyer

billingAddress[countryState]

string <= 128 characters

N

Country state of the buyer

billingAddress[province]

string <= 128 characters

N

Province of the buyer

billingAddress[buildingNumber]

string <= 32 characters

N

Building number of the buyer

billingAddress[roomNumber]

string <= 32 characters

N

Room number of the buyer

billingAddress[postcode]

string [ 5 .. 6 ] characters

N

Postcode of the buyer

billingAddress[companyName]

string <= 128 characters

N

Company name of the buyer

billingAddress[phone]

string [ 2 .. 64 ] characters ^[0-9\+]+$

N

Phone of the buyer

billingAddress[taxId]

string <= 128 characters

N

Tax Id of the buyer

urlReturn

string <= 256 characters url

N

Return URL

customIpnUrl

string <= 256 characters url

N

Form data is created by setting all parameters in alphabetical order and adding a signature parameter at the end. 

 

Important: The alphabetical order is case-sensitive. You should put all capital letters before lowercase letters.

 

Below, you will find examples of how POST is created and how the signature is generated.

 

"paywallSecret" that was used for the signature generation in this example:

5cb0d681938ae17557d1e7b3075450db

 

Form data example

amount:100
currency:PLN
customIpnUrl: https://example.ipn 
customer[email]: john@doe.com
customer[firstName]: John
customer[lastName]: Doe
items[0][category]: category 
items[0][code]:  IDS123
items[0][lineAmountTotal]: 100
items[0][name]: item
items[0][price]: 100
items[0][quantity]: 1
merchantTransactionId: 163e9f97-2271-4f3d-922a-4a2bcaa47560
terminalUuid: FF7C0356-BD13-4988-9F14-EB11BC682112
urlReturn: https://example.return
signature: FB5EE6CAC07F7C85BC3FEAE9B683BDBF9B9F363038D7A033C87816134396C3F6

 

 

Example of a form POST

amount=100&currency=PLN&customIpnUrl=https://example.ipn&customer[email]=john@doe.com&customer[firstName]=John&customer[lastName]=Doe&items[0][category]=category&items[0][code]=IDS123&items[0][lineAmountTotal]=100&items[0][name]=item&items[0][price]=100&items[0][quantity]=1&merchantTransactionId=163e9f97-2271-4f3d-922a-4a2bcaa47560&terminalUuid=FF7C0356-BD13-4988-9F14-EB11BC682112&urlReturn=https://example.return&signature=FB5EE6CAC07F7C85BC3FEAE9B683BDBF9B9F363038D7A033C87816134396C3F6;sha256

To verify whether the received form data belongs to an authorized merchant, ZEN verifies the signature of the received POST.

 

Generating a signature

A signature is created using sha256 algorithm

 

signature = signatureAlgorithm(key1=val1&key2=val2&...&keyN=valN< paywallSecret>);

 

Below, you can see an example of such a signature:

 

amount=100&currency=PLN&customIpnUrl=https://example.ipn&customer[email]=john@doe.com&customer[firstName]=John&customer[lastName]=Doe&items[0][category]=category&items[0][code]=IDS123&items[0][lineAmountTotal]=100&items[0][name]=item&items[0][price]=100&items[0][quantity]=1&merchantTransactionId=163e9f97-2271-4f3d-922a-4a2bcaa47560&terminalUuid=FF7C0356-BD13-4988-9F14-EB11BC682112&urlReturn=https://example.return5cb0d681938ae17557d1e7b3075450db

 

You can verify the generated signature by using the HTML code

 

When you paste the proper values into the code, it will generate a signature. If both signatures are identical, this means the generation process has been carried out correctly.

 

You can also use this HTML code to verify the validity of the provided data. To do this, select the Pay button - if the checkout process is initiated, the provided data is valid.

 

Please note that the initiated checkout process has a real connection with our system and your ZEN account. Once paid, the transaction will be processed and settled to your account.

 

Payments setup

Payment methods

To learn all about payment methods available in ZEN, check the Payments section in the ZEN Features chapter.

 

Enabling payment methods

You can find all available payment methods in your ZEN panel in the Store settings option. You can turn them ON and OFF at any time according to your preferences. The methods which logos are colorful are the ones enabled. On the checkout page, your customers will only see the methods which are turned ON. 

 

Instant Payment Notification

For each transaction, ZEN sends you an Instant Payment Notification (IPN).

 

There are two ways to provide an IPN URL address to ZEN:

 

  1. In the Credentials tab in the ZEN panel, you can provide the IPN URL address. See how to get integration credentials.
  2. If you are using the API integration or the Checkout integration with each request, you can provide a customIpnUrl for this request as an optional field. If you leave this field blank, ZEN will use the IPN URL address from pt. 1.
  3. To verify whether the IPN is sent by ZEN, you should use the IPN API Secret. See how to get integration credentials.
    Note: You should use hash for particular values using sha256 and compare the result with the hashed values of the received IPN.

 

Below, you can find an example of an IPN

 

""type"":""TRT_PURCHASE"",
   ""transactionId"":"" 2d36ff20-017d-4c63-b626-407edb369cc2"",
   ""merchantTransactionId"":"" feb78e88-47bc-428a-8ea4-806535aaf2de"",
   ""amount"":""100"",
   ""currency"":""PLN"",
   ""status"":""PENDING"",
   ""hash"":""28EE6604A8A40ACC8B8CE0B8DE9AAC87A4E24BBF0388A48ED164E512C8073C7E"",
   ""signature"":""D3739E5ADCC20E436DEE8F386C81B1C3ACCCE0558FAB65EC924564F998F983EE"",
   ""paymentMethod"":{
      ""name"":""PME_PBZ"",
      ""channel"":""PCL_PBZ"",
      ""parameters"":{
      }
   },
   ""customer"":{
      ""firstName"":""John"",
      ""lastName"":""Doe"",
      ""email"":""john@doe.pl"",
      ""ip"":""172.89.0.1"",
      ""country"":""US""
   },
   ""securityStatus"":""pending"",
   ""riskData"":{
   },
   ""email"":""john@doe.pl""
}

 

Merchant Secret used for this example is:

 

aeb8e7bf-0009-4f30-b521-1136fd336ae6

 

with

 

merchantTransactionID = feb78e88-47bc-428a-8ea4-806535aaf2de
currency = PLN
amount = 100
transactionStatus = PENDING
merchantIpnSecret = aeb8e7bf-0009-4f30-b521-1136fd336ae6

 

we get

 

sha256(feb78e88-47bc-428a-8ea4-806535aaf2dePLN100PENDINGaeb8e7bf-0009-4f30-b521-1136fd336ae6)

 

which gives 

 

hash = 28EE6604A8A40ACC8B8CE0B8DE9AAC87A4E24BBF0388A48ED164E512C8073C7E

 

The received hash is equal to the hash received in IPN. This confirms that IPN was sent by ZEN.

 

To confirm that the IPN was successfully received, your system must send the following response

 

-content type: application/json

 

Response:

 

{
    ""status"": ""ok""
}

 

Note: If you don’t confirm that the IPN has been received, ZEN will continue to re-send IPN to your URL address.

 

Hash calculation

Hash values are calculated as follows:

 

sha256({transaction.merchantTransactionId}{transaction.currency}{transaction.amount}{transactionStatus}{merchantIpnSecret})

 

Testing payments


When you have completed all the previous steps, you can carry out a test payment.

  1.  Create an order at your store and follow through with all the steps.
  2. Upon payment completion, our system should display a success message at the end of the checkout.
  3. Check for the new transaction in your ZEN panel.

 

Testing refund payments

Transactions processed via ZEN can be partially or fully refunded to the payer.

 

Refunds can be processed in two ways: in the ZEN panel or via API.

 

Processing refunds in the ZEN panel

  1. Log in to your ZEN panel, open the menu and select the Payments section.
  2. Locate the transaction which you would like to refund and display its details.
  3. Click on the Refund button, and specify the amount to be refunded.

 

 The refunded amount cannot be lower than the min. transaction value, nor greater than the amount of refunded transaction.

 

API

  1. Prepare the POST /transactions/refund according to our API documentation.
  2. The refunded amount cannot be lower than the min. transaction value, nor greater than the amount of refunded transaction.

transactionId - id of the transaction to be refunded provided by ZEN
merchantTransactionId - id of the refund transaction from your system. It must be unique (no 2 transactions, no matter the type, can have same merchantTransactionId

 

Locating transactions in ZEN account

You can display, search and filter all transactions processed with ZEN in your ZEN merchant panel.

 

 To do this, go to your ZEN panel and select the Payments section from the menu. 

 

 You can also create a detailed report of all transactions made in a specified period. To learn how to do this, read the Reports chapter.

 

Finding settlements

Each transaction in your store is settled to your ZEN IBAN account (unless specified otherwise in the contract or T&C of your payment processor, e.g. PayPal).

 

The settlement time depends on the settlement delay and the security deposit values per payment method. ZEN specifies settlement delay and security deposit periods in your contract, T&C, and an email confirming the activation of your store in ZEN.

 

You can find all the settlements for specified currencies in your ZEN account’s transaction history.

 

PayPal 

You can connect your PayPal account with ZEN to enable your customers to pay and process their payments through PayPal.

 

Please note that the settlement and pricing terms must be agreed upon between PayPal and you. ZEN does not participate in either of those processes and only enables redirecting payers to the PayPal checkout page.

 

To process PayPal transactions:

 

  1. First, log in to your ZEN panel.
  2. From the menu, select Store settings and then click on the black-and-white PayPal logotype.
  3. The PayPal login popup will appear on the screen. Log in or create a new account to connect your PayPal account with ZEN and follow the account connection steps.
  4. Once PayPal and ZEN accounts have been connected you can:
    • process PayPal transactions via API according to the API integration chapter.
    • enable PayPal on your ZEN checkout as presented in the Enabling payments section of the API integration chapter.