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 terminalId 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 terminalId: string Y In order to obtain terminalId: - Login to ZEN account
- Open menu and go to Store settings in the Sell online section
- Visit API & Documentation section
- Terminal UUID corresponds with terminalId 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 N First name of the buyer customer[lastName]: string <= 128 characters N 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 N Name of the sold item items[0][price]: string^-?(?=.*[1-9])\d{1,16}(?:\.\d{1,12})?$ N Unit price of the sold item items[0][quantity]: number N Quantity of the sold items items[0][lineAmountTotal]: string^-?(?=.*[1-9])\d{1,16}(?:\.\d{1,12})?$ N Total price of the sold items version: 1.0.0;form Version of the Paywall signature: Signature of the post -
Form data example:
terminalId: 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
version: 1.0.0;form
signature: 479acd1858e991b7aeba39ed9f7d7a288a3bb739a07e1a0e32fa9e5bafea0ff8;sha256 -
Example of a form POST:
terminalId=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&version=1.0.0%3Bform&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< serviceKey>);
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).