On this page

Before you begin
Setting up ZEN checkout
Creating a request
Generating a signature
Payments setup
Instant Payment Notification
Hash calculation
Testing payments
Testing refund payments
Locating transactions in ZEN account
Finding settlements
PayPal

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

Log in to your ZEN panel, open the menu and go to Store settings > Payment methods.
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.
Next, locate your integration credentials. See how to get integration credentials.
Then, create a working POST request. See more in the POST checkout part.
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/checkouts

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

Name

Allowed values

Required field

Description

terminalUuid:

string

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})?$

Amount of the transaction.

currency:

string 3 characters

Currency in ISO 4217 alphabetic code of the transaction (it will determine payment methods displayed on the paywall). Must be written in all capital letters.

merchantTransactionId:

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

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

Merchant’s code for the sold item

items[0][category]:

string <= 64 characters

Merchant’s category for the sold item

items[0][name]:

string <= 128 characters

Name of the sold item

items[0][price]:

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

Unit price of the sold item

items[0][quantity]:

number

Quantity of the sold items

items[0][lineAmountTotal]:

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

Total price of the sold items

signature:

Signature of the post

shippingAddress[id]

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

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

shippingAddress[firstName]

string <= 128 characters

First name of the buyer

shippingAddress[lastName]

string <= 128 characters

Last name of the buyer

shippingAddress[country]

string 2 characters ^[A-Z]+$

Country of the buyer

billingAddress[street]

string <= 128 characters

Street of the buyer

billingAddress[city]

string <= 128 characters

City of the buyer

billingAddress[countryState]

string <= 128 characters

Country of the buyer

billingAddress[province]

string <= 128 characters

Province of the buyer

billingAddress[buildingNumber]

string <= 32 characters

Building number of the buyer

billingAddress[roomNumber]

string <= 32 characters

Room number of the buyer

billingAddress[postcode]

string [ 5 .. 6 ] characters

Postcode of the buyer

billingAddress[companyName]

string <= 128 characters

Company name of the buyer

billingAddress[phone]

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

Phone of the buyer

billingAddress[taxId]

string <= 128 characters

Tax Id of the buyer

urlRedirect

string <= 256 characters url

URL for redirection after transaction. Used if „urlSuccess” and „urlFailure” were not specified

urlSuccess

string <= 256 characters url

URL for redirection after successful transaction

urlFailure

string <= 256 characters url

URL for redirection after successful transaction

customIpnUrl

string <= 256 characters url

* Customer information (firstName, lastName, email) can be omit during transaction initiation.
In such cases, checkout, during transaction process, will create a pop-up requesting customer to provide those information.

Request to initiate checkout should be prepared as JSON and send 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”,

„signature”: „16a36c391255e99596f12d802bf8fbba9b3414a23fc85bbf21974c05183961f3;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 based on the JSON prepared for the request, using one of SHA224/SHA256/SHA284/SHA512 algorithms

To generate signature, following actions should be applied:

JSON should be converted to flat form:

Simple parameters should be converted to format: parameter=value (example: currency=EUR)
Complex parameters should be converted to format: complexParameter.parameter=value (example: customer.firstname=John)
Collections should be converted to format: collection[number].parameter=value where first number is 0 (example: items[0].name=product)
Whole list should be converted to lowercase
List should be sorted in alphabetical order
Sorted parameters should be connected with „&”
At the end of the list, paywall secret should be added

Received list, with paywall secret at the end, should be hashed using one of the SHA224/SHA256/SHA284/SHA512 algorithms

To received hash, „;” and name of the algoritm (in lowercase) should be added (example: ;sha256)

Formula to generate signature:

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

Below, you can find an example of signature generation process:

paywallSecret used for the example: c8c93c452d38acf3183q2n08fee60aa7

JSON prepared for the hashing part:

amount=1000&billingaddress.buildingnumber=1&billingaddress.city=cityname&billingaddress.companyname=company name&billingaddress.country=pl&billingaddress.countrystate=statename&billingaddress.firstname=jan&billingaddress.id=baid1&billingaddress.lastname=kowalski&billingaddress.phone=+48555555555&billingaddress.postcode=23-232&billingaddress.province=provincename&billingaddress.roomnumber=11&billingaddress.street=streetname&billingaddress.taxid=12345678&currency=eur&[email protected]&customer.firstname=jan&customer.id=customerid328642&customer.lastname=kowalski&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=jan&shippingaddress.id=sa1&shippingaddress.lastname=kowalski&shippingaddress.phone=+48555555555&shippingaddress.postcode=11-111&shippingaddress.province=provincename&shippingaddress.roomnumber=11&shippingaddress.street=streetname&terminaluuid=19b692d0-00b9-48f7-92ca-1509f055df2e&urlfailure=https://backtoshop/failure&urlredirect=https://backtoshop/redirect&urlsuccess=https://backtoshop/successc8c93c452d38acf3183q2n08fee60aa7

Sha256 hashing was applied to the list and hash was generated:

447c885cbff1e2d1e717c720003b095c039ebb87059b0deb7d134c09c91c0a7f

„;sha256” was added to received hash to get signature:

Signature: 447c885cbff1e2d1e717c720003b095c039ebb87059b0deb7d134c09c91c0a7f;sha256

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).

IPN with status „ACCEPTED” is confirmation of successful transaction. Once you receive IPN with status „ACCEPTED” you can finalize the order.

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

In the Credentials tab in the ZEN panel, you can provide the IPN URL address. See how to get integration credentials.
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.
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