Paywall Direct Integration
ZEN allows you to start accepting more than 150 global and local payment options (including credit cards, instant bank transfers, and many more). The following document will guide you through the integration process and introduce the main features of the Paywall integration.
Paywall transactions are made by posting form data (described below) to checkout.zen.com/payment.
-
Allowed HTTPs requests
- PRODUCTION environment:
POST form data to https://checkout.zen.com/payment.
- PRODUCTION environment:
-
Credentials required to use Paywall integration
Name Description Terminal UUID To start using ZEN Paywall user needs to be able to authorize his requests. It is done by adding a Terminal UUID key to the request header. In order to retrieve your Terminal UUID please: - Login to ZEN account
- Open menu and go to Store settings in the Sell online section
- Visit API & Documentation section
- Terminal UUID corresponds with terminalUuid used in the paywall integration
Paywall Secret To create POST signature, the user needs to use Paywall secret. In order to retrieve it: - Login to ZEN account
- Open menu and go to Store settings in the Sell online section
- Visit API & Documentation section
- Copy Paywall secret
IPN Secret IPN (Instant Payment Notification) notifies user about the status of transaction. In order to verify whether IPN is authorized by ZEN user needs an IPN secret. In order to retrieve it: - Login to ZEN account
- Open menu and go to Store settings in the Sell online section
- Visit API & Documentation section
- Copy IPN secret
-
Form data fields
In order to create a checkout user should POST proper form data to ZEN. Below table covers description of the form data fields.
Name Allowed values Required field Description terminalUuid: string Y In order to obtain terminalUuid: - Login to ZEN account
- Open menu and go to Store settings in the Sell online section
- Visit API & Documentation section
- 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 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 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 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 successUrl string <= 256 characters url N Success URL failureUrl string <= 256 characters url N Failure URL returnUrl string <= 256 characters url N Return URL customIpnUrl string <= 256 characters url N Custom IPN URL -
Form data example:
terminalUuid: FF7C0356-AF09-4988-9F14-EB11BC682112
amount: 100
currency: PLN
merchantTransactionId: 163e9f97-2271-4f3d-922a-4a2bcaa47560
customer[firstName]: John
customer[lastName]: Doe
customer[email]: [email protected]
items[0][code]: IDS123
items[0][category]: category
items[0][name]: Multipla
items[0][price]: 100
items[0][quantity]: 1
items[0][lineAmountTotal]: 100
signature: 479acd1858e991b7aeba39ed9f7d7a288a3bb739a07e1a0e32fa9e5bafea0ff8;sha256 -
Example of a form POST:
terminalUuid=FF7C0356-AF09-4988-9F14-EB11BC682112&amount=100¤cy=PLN&merchantTransactionId=469cf1b7-53a4-47c4-8324-5ad549954dd6&customer%5BfirstName%5D=John&customer%5BlastName%5D=Doe&customer%5Bemail%5D=john%40doe.pl&items%5B0%5D%5Bcode%5D=IDS123&items%5B0%5D%5Bcategory%5D=category&items%5B0%5D%5Bname%5D=Multipla&items%5B0%5D%5Bprice%5D=100&items%5B0%5D%5Bquantity%5D=1&items%5B0%5D%5BlineAmountTotal%5D=100&signature=abb1fcaa93efaf00763693fdfc5061f5fb0023e6006f3704b1feecf0fe16c332%3Bsha256
-
Creating signature
In order to verify received form-data belongs to authorized merchant ZEN verifies signature of the received POST. Signature is created using example presented below and hashing it using sha224, sha256, sha384, sha512 algorithm, all fields are sorted alphabetically:
signature = signatureAlgorithm(key1=val1&key2=val2&...&keyN=valN< paywallSecret>);
Signature generation example:
sha256(key1=val1&key2=val2&...&keyN=valN5cb0d6819386637557d1e8b1075450db);sha256
-
IPN API Secrets
In order to verify whether IPN (instant payment notification) is sent by ZEN you should use the IPN Secret. The below values are hashed using sha256 algorithm to create “hash” field:
Instant payment notification object:{
type: string;
transactionId: string;
merchantTransactionId: string;
amount: string;
currency: string;
status: string;
orderCreatedAt?: string;
orderCompleteAt?: string;
refundedAmount?: number;
provisionAmount?: number;
hash: string;
paymentMethod: {
pspId: string;
name: string;
channel: string;
parameters?: {[key: string]: string};
}
processingTime?: boolean;
customer: {
id?: string;
firstName?: string;
lastName?: string;
email: string;
phone?: string;
accountId?: string;
ip: string;
country: string;
}
securityStatus?: string;
sendPush?: number;
isCash?: boolean;
email?: string;
riskData?: {[key: string]: string | object};
hasRecurringShield?: number;
includedFeeVat?: string;
ssRequestId?: string;
cardToken?: string;
}
hash = sha256()
Paywall Settings
Once redirected to ZEN Paywall buyer will be presented with payment methods allowed to process currency of the transaction. You can further manage the list of allowed payment methods by logging into your ZEN account and selecting Store settings from the main menu. Payment methods page includes a list of all payment methods configured on your paywall. By clicking on any of the icons you can turn in on (color) or off (grayed out).