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
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 *
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][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 successful 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:
- 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¤cy=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.
IPN contains information about authorized amount in “authorization” object. If the owner of the fee is merchant, then the “authorization” contains amount equal to transaction cost, as the fee is subtracted from the amount paid by buyer. If the owner of the fee is buyer then the “authorization” contains final amount, currency and fee as the fee is calculated based on the base amount of the order and added to the final price.
For each finalized transaction, ZEN sends you an Instant Payment Notification (IPN). There are two ways to provide 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 the API Integration or the Paywall Integration with each request, you can provide a customIpnUrl for this request as an optional field. If you leave this field is 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
Note: You should create hash for particular values using sha256 and compare the result with the hashed values of the received IPN.
- 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.
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.
- Initiate card transactions using a widget.