Communication parameters - Checkout documentation

Request to initiate checkout should be prepared as JSON and send with application/json header. The table below contains a list of all mandatory parameters that you must send to ZEN.COM when initiating a Transaction. These are marked with 'Y' in the 'Required field' column. The table also includes a list of optional parameters that you can, but are not required to, send when initiating a Transaction. These are marked with 'N' in the 'Required field' column. We recommend that all parameters listed below be sent at the start of the Transaction.

WARNING

The API is case-sensitive at every level, both in parameter names and parameter values. Spaces in parameter names and special characters are not allowed.

WARNING

The values of the transmitted parameters should be encoded in UTF-8, along with handling the transport protocol in compliance with standard HTTPs service calls.

Name	Allowed values	Required field	Description
`terminalUuid`	string	Y	Go here to check out how to get your credentials
`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.id`	string < = 128 characters	N	Customer Id in Merchant's system
`customer.firstName`	string < = 128 characters	Y (1) (Providing this data increases the approval rate for card payments)	First name of the Customer
`customer.lastName`	string < = 128 characters	Y (1) (Providing this data increases the approval rate for card payments)	Last name of the Customer
`customer.email`	string < = 256 characters	Y (1) (Providing this data increases the approval rate for card payments)	Email address of the Customer
`customer.phone`	string < = 64 characters match pattern: ^[0-9+]+$	N	Customer's phone number
`items.code`	string < = 64 characters	N (1)	Merchant’s code for the sold item
`items.category`	string < = 64 characters	N	Merchant’s category for the sold item
`items.name`	string < = 128 characters	Y	Name of the sold item
`items.price`	string^-?(?=.* [1-9])\d{1,16}(?:.\d{1,12})?$	Y	Unit price of the sold item
`items.quantity`	number	Y	Quantity of the sold items
`items.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 Customer
`shippingAddress.lastName`	string < = 128 characters	N	Last name of the Customer
`shippingAddress[country]`	string 2 characters ^[A-Z]+$	N	Country of the Customer
`billingAddress[street]`	string < = 128 characters	N	Street of the Customer
`billingAddress[city]`	string < = 128 characters	N	City of the Customer
`billingAddress[countryState]`	string < = 128 characters	N	Country of the Customer
`billingAddress[province]`	string < = 128 characters	N	Province of the Customer
`billingAddress[buildingNumber]`	string < = 32 characters	N	Building number of the Customer
`billingAddress[roomNumber]`	string < = 32 characters	N	Room number of the Customer
`billingAddress[postcode]`	string [ 5 .. 6 ] characters	N	Postcode of the Customer
`billingAddress[companyName]`	string < = 128 characters	N	Company name of the Customer
`billingAddress[phone]`	string [ 2 .. 64 ] characters ^[0-9+]+$	N	Phone of the Customer
`billingAddress[taxId]`	string < = 128 characters	N	Tax Id of the Customer
`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 failure Transaction
`customIpnUrl`	string < = 256 characters url	N	URL address used by ZEN to send IPN to
`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

(1) 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

Certain Payment methods / Payment channels necessitate the provision of additional parameters at the initiation of the Transaction, beyond those specified above. Please consult the list of Payment methods / Payment channels that require these additional parameters in order for the Transaction to be successfully registered. Failure to provide the required parameters at the start of the transaction will result in an error being returned by our system due to the absence of the necessary parameters.

Polish Pay-by-link (PBL)

PayPo Poland

PayPo Romania