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

 

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

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.

currency:

string 3 characters

Y

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?&:\-\/=.,#]+$

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 *
Providing this data increases the approval rate for card payments

First name of the buyer

customer[lastName]:

string <= 128 characters

Y *
Providing this data increases the approval rate for card payments

Last name of the buyer

customer[email]:

string <= 256 characters

Y *
Providing this data increases the approval rate for card payments

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][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

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

urlRedirect

string <= 256 characters url

N

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

urlSuccess

string <= 256 characters url

N

URL for redirection after successful transaction

urlFailure

string <= 256 characters url

N

URL for redirection after failure transaction

customIpnUrl

string <= 256 characters url

N

specifiedPaymentMethod

string

N

Code to limit checkout to one payment method. Check limiting checkout for more information

specifiedPaymentChannel

string

N

Code to limit checkout to one payment channel. Check limiting checkout for more information

* 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.
Y – required; N – No required

  

  

Limiting checkout to desired payment method or payment channel

You can limit your checkout to particular payment method or payment channel.
By providing one of „specifiedPaymentMethod” or „specifiedPaymentChannel” you can prevent your buyers from using other methods in payment session.

You can either initiate the checkout with chosen method or chosen channel.
Examples:
„specifiedPaymentMethod”: „PME_BOACOMPRA” – will limit checkout to all channels under BOACOMPRA payment method.
vs
„specifiedPaymentChannel”:” PCL_BOACOMPRA_PAGOEFECTIVO”- this will limit checkout to only one channel from BOACCOMPRA payment method.

To get information about available payment methods codes and payment channels codes please contact us at [email protected] and provide us with your terminal ID

 

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”

}

 

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:

  1. Simple parameters should be converted to format: parameter=value (example: currency=EUR)
  2. Complex parameters should be converted to format: complexParameter.parameter=value (example: customer.firstname=John)
  3. Collections should be converted to format: collection[number].parameter=value  where first number is 0 (example: items[0].name=product)
  4. Whole list should be converted to lowercase
  5. List should be sorted in alphabetical order
  6. Sorted parameters should be connected with „&”
  7. 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

Instant Payment Notification (IPN) is a mechanism that informs your system about payment statuses, outcomes of actions such as refunds, and the reception of results for certain local payment methods and other events.

Key advantages of IPN:

  1. Automatic event updates: IPN automatically updates events triggered by requests from your end. For example, when a customer initiates a refund or when an up-to-date sales report is required.
  2. Asynchronous request processing: In the case of IPN, requests are processed asynchronously. For many payment methods, the waiting time for a response may be longer, but with IPN notification of a successfully completed payment, you receive automatic information.

To handle IPN, you need to:

  1. Provide an endpoint on your server: You must provide an endpoint that will receive and process IPN POST from ZEN. Depending on your network requirements and security, it may be necessary to add our IP address to the whitelist on your firewall.
  2. Configure IPN: Set up IPN to specify which events should be monitored and transmitted to your system. You can configure this in two ways, following the documentation.

For each finalized transaction, ZEN sends you an IPN. There are two ways to provide the IPN URL to ZEN:

  1. In the Credentials tab in the Merchant panel, you can provide the IPN URL address.
  2. If you are using API Integration or Paywall 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 point 1. To verify whether the IPN is sent by ZEN, you should use the IPN API Secret. Note: You should create a hash for particular values using sha256 and compare the result with the hashed values of the received IPN.

  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

„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”:[email protected],
     „ip”:”172.89.0.1″,
     „country”:”US”
   },
„securityStatus”:”pending”,
„riskData”:{
   },
„email”:[email protected]
}

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.

  •  Create an order at your store and follow through with all the steps.
  • Upon payment completion, our system should display a success message at the end of the checkout.
  • 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

  • Log in to your ZEN panel, open the menu and select the Payments section.
  • Locate the transaction which you would like to refund and display its details.
  • 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

  • Prepare the POST /transactions/refund according to our API documentation.
  • 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:

  • First, log in to your ZEN panel.
  • From the menu, select Store settings and then click on the black-and-white PayPal logotype.
  • 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.
  • 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.



Widget

Widget is an additional feature available in ZEN designed exclusively for processing card transactions. This widget offers several advantages, including:

  • Customized Appearance: With the widget, you can create payments on a page that seamlessly matches the look and layout of your online store.
    You can customize the widget’s appearance to perfectly fit your website.
  • Transparent Integration: The widget allows for card payments without the need to redirect the customer to an external payment page.
    This means that the entire payment process takes place on your website, enhancing the convenience for customers.
  • Card Data Security: The widget minimizes PCI DSS compliance requirements. This is crucial for security, as it eliminates the need to store sensitive information.
  • Intuitive Creator: To create the right widget for your store, you can use the intuitive creator available at this link: https://developer-configurator.zen.com/. With this tool, you can quickly tailor the widget’s appearance and behaviour to your needs.
  • Transaction Result Handling: The widget provides an easy and intuitive way to inform the customer about the transaction outcome.
    If the transaction is successful, a confirmation message is sent to the dashboard, and in case of a rejected transaction, you receive a rejection message.
  • Boosts Conversions: Widget integration adds flexibility and increases conversions, meaning more successful transactions, because
    the payment takes place on the store’s side.

This additional module is intended for integration with the checkout process. Invoking the widget is not significantly different from initiating a standard payment transaction during the checkout process. However, you need to include the „specifiedPaymentChannel” parameter in the request content, which must always be declared as „PCL_CARD”. To initiate a transaction using the widget, the merchant should use the following URL instead of the standard URL for initiating transactions:  https://secure.zen.com/api/checkouts/type=widget In response to the request, instead of a redirection URL, you will receive an „Id” identifier, which should be used instead of „checkoutId” in the „openPopup(„checkoutId”);” function in the code that you took after customizing the widget according to your needs. The „Id” is a unique value generated for each registered transaction, which will be processed by the widget to finalize the transaction. This value serves to clearly identify and conclude the transaction process.

In summary, the ZEN platform widget is a tool that facilitates card payments, providing a personalized appearance, data security, and support for various transaction outcomes, all without the need to redirect the customer to an external payment page.

To change the language displayed on the widget, simply provide the appropriate lang parameter when building the iframe link. The widget supports the following languages:

  • cs: Česky
  • da: Dansk
  • de: Deutsch
  • el: Ελληνικά
  • en: English
  • es: Español
  • et: Eesti
  • fr: Français
  • he: עברית
  • it: Italiano
  • lt: Lietuvių kalba
  • lv: Latviešu valoda
  • nb: Norsk Bokmål
  • nl: Nederlands
  • pl: Polski
  • pt-BR: Português (Brasil)
  • pt: Português (Portugal)
  • ro: Română
  • ru: русский
  • sk: Slovenčina
  • sl: Slovenski jezik
  • sv: Svenska
  • uk: Українська

To specify the language, simply add the lang parameter to the iframe link.


Specified Payment Channel

The „specifiedPaymentChannel” parameter is a crucial element that enables us to:

  • Initiate transactions using a specific designated payment method when a partner chooses to offer only that particular payment option to their customers or when the partner wants only that payment option to be visible at checkout.
  • Initiate card transactions using a widget.

To properly use the parameter: During payment initiation, instead of the standard „PaymentChannel” parameter, we use „specifiedPaymentChannel” to declare the preferred payment channel visible in the checkout payment process. This allows us to precisely specify the preferred payment method for a given transaction.

Below, you can find an example how use that parameter:

{
„terminalUuid”: „TERMINAL_UUID”,
„amount”: 125,
„currency”: „USD”,
„merchantTransactionId”: „transaction1”,
„specifiedPaymentChannel”: „PCL_CARD”,
„items”: [
{
„name”: „itemName1”,
„price”: 125,
„quantity”: 1,
„lineAmountTotal”: 125
}],
„signature”: „generated_signature”
}

Store logo on ZEN checkout

It is possible to add, remove and manage your store logos directly via ZEN’s panel and visualize them on ZEN checkout page. Go to ZEN panel page to see all details, how to configure and manage your logos or download quick manual.