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.

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

Development Documentation