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.
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.
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]
N
This is ID of the merchant's customer provided by merchant
shippingAddress[firstName]
N
First name of the buyer
shippingAddress[lastName]
N
Last name of the buyer
shippingAddress[country]
N
Country of the buyer
shippingAddress[street]
N
Street of the buyer
shippingAddress[city]
N
City of the buyer
shippingAddress[countryState]
N
Country state of the buyer
shippingAddress[province]
N
Province of the buyer
shippingAddress[buildingNumber]
N
Building number of the buyer
shippingAddress[roomNumber]
N
Room number of the buyer
shippingAddress[postcode]
N
Postcode of the buyer
shippingAddress[companyName]
N
Company name of the buyer
shippingAddress[phone]
N
Phone of the buyer
billingAddress[id]
N
This is ID of the merchant's customer provided by merchant.
billingAddress[firstName]
N
First name of the buyer
billingAddress[lastName]
N
Last name of the buyer
billingAddress[country]
N
Country of the buyer
billingAddress[street]
N
Street of the buyer
billingAddress[city]
N
City of the buyer
billingAddress[countryState]
N
Country state of the buyer
billingAddress[province]
N
Province of the buyer
billingAddress[buildingNumber]
N
Building number of the buyer
billingAddress[roomNumber]
N
Room number of the buyer
billingAddress[postcode]
N
Postcode of the buyer
billingAddress[companyName]
N
Company name of the buyer
billingAddress[phone]
N
Phone of the buyer
billingAddress[taxId]
N
Tax Id of the buyer
urlReturn
N
Return URL
customIpnUrl
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
amount=100¤cy=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
signature = signatureAlgorithm(key1=val1&key2=val2&...&keyN=valN< paywallSecret>);
Below, you can see an example of such a signature:
amount=100¤cy=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.
To learn all about payment methods available in ZEN, check the Payments section in the ZEN Features chapter.
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.
For each transaction, ZEN sends you an Instant Payment Notification (IPN).
There are two ways to provide an IPN URL address to ZEN:
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""
}
sha256({transaction.merchantTransactionId}{transaction.currency}{transaction.amount}{transactionStatus}{merchantIpnSecret})
When you have completed all the previous steps, you can carry out a test payment.
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.
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
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.
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.
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: