Checkout documentation
Go to zen.comGo to myZEN.com
Documentation
Documentation
  • Sandbox
  • Plugin integration
  • API business
  • API reference
  • API transfers
  • Merchant panel
  • Brandbook
Go to zen.comGo to myZEN.com
Documentation
Documentation
  • Sandbox
  • Plugin integration
  • API business
  • API reference
  • API transfers
  • Merchant panel
  • Brandbook
  1. Integration
  • About ZEN
    • First steps with ZEN
    • Who we are
    • What we provide
    • How we provide
  • Introduction
    • Definitions
    • Environments
    • Payment methods
    • Currencies
    • Languages
    • About ZEN checkout
    • Payment process
    • Revenue streams
    • Authorization & authentication
  • Account registration & configuration
    • Before you begin
    • Registration
    • Configuration
    • Merchant’s panel
    • Payments setup
    • Locating Transactions in my.zen.com
    • Finding settlements
  • Features
    • Available features
    • 3-Domain Secure (3DS)
    • Account Funding Transactions (AFT)
    • Authorization fee
    • Card widget
    • Cashback
    • Currency Conversion Service
    • Hosted Payout Page
    • Shop logo on ZEN.COM checkout
    • Instant Payment Notification (IPN)
  • Integration
    • Integration checklist
    • Communication parameters
    • Prepare the communication
    • Generating a Signature
    • Purchase Transaction
    • Purchase Transaction with limited Payment methods
    • Refund Transaction
    • Transaction statuses
    • Recurring Payments
      • About recurring
      • Purchase Transaction
  1. Integration

Communication parameters

integration code.jpg
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.
NameAllowed valuesRequired fieldDescription
terminalUuidstringYesYour individual Terminal's UUID
amountnumberYesAmount of the transaction.
currencystring 3 charactersYesCurrency in ISO 4217 alphabetic code of the transaction (it will determine payment methods displayed on the paywall). Must be written in all capital letters.
merchantTransactionIdstring [ 1 .. 128 ] characters ^[a-zA-Z0-9?&:-/=.,#]+$YesMerchant’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 immediately rejected by ZEN.
signatureParameter used for message authentication and it is calculated based on the concatenation of fieldsYesSignature of the post
originMerchantTransactionIdstring < = 128 charactersNoOrigin Merchant Transaction ID used by Merchant to gather more than one unique merchantTransactionId's Example: 23beb187-f8a3-44b8-9ef8-b31180358dd3
customer.idstring < = 128 charactersNoCustomer Id in Merchant's system
customer.firstNamestring < = 128 charactersNoFirst name of the Customer
customer.lastNamestring < = 128 charactersNoLast name of the Customer
customer.emailstring < = 256 charactersNoEmail address of the Customer
customer.phonestring < = 64 characters match pattern: ^[0-9+]+$NoCustomer's phone number
items.codestring < = 64 charactersNoMerchant’s code for the sold item
items.categorystring < = 64 charactersNoMerchant’s category for the sold item
items.namestring < = 128 charactersNoName of the sold item
items.pricestring^-?(?=.* [1-9])\d{1,16}(?:.\d{1,12})?$NoUnit price of the sold item
items.quantitynumberNoQuantity of the sold items
items.lineAmountTotalnumberNoTotal price of the sold items
shippingAddress.idstring < = 64 characters ^[a-zA-Z0-9_-]+$NoThis is ID of the merchant’s customer provided by merchant
shippingAddress.firstNamestring < = 128 charactersNoFirst name of the Customer
shippingAddress.lastNamestring < = 128 charactersNoLast name of the Customer
shippingAddress.countrystring 2 characters ^[A-Z]+$NoCountry of the Customer
shippingAddress.citystring 128 characters ^[A-Z]+$NoCountry of the Customer
shippingAddress.buildingNumberstring < = 128 charactersNoBuilding number of the Customer
shippingAddress.roomNumberstring < = 32 charactersNoRoom number of the Customer
billingAddress.streetstring < = 128 charactersNoStreet of the Customer
billingAddress.citystring < = 128 charactersNoCity of the Customer
billingAddress.countryStatestring < = 128 charactersNoCountry of the Customer
billingAddress.provincestring < = 128 charactersNoProvince of the Customer
billingAddress.buildingNumberstring < = 128 charactersNoBuilding number of the Customer
billingAddress.roomNumberstring < = 32 charactersNoRoom number of the Customer
billingAddress.postcodestring [ 5 .. 6 ] charactersNoPostcode of the Customer
billingAddress.companyNamestring < = 128 charactersNoCompany name of the Customer
billingAddress.phonestring [ 2 .. 64 ] characters ^[0-9+]+$NoPhone of the Customer
billingAddress.taxIdstring < = 128 charactersNoTax Id of the Customer
urlRedirectstring < = 256 characters urlNoURL for redirection after transaction. Used if „urlSuccess” and „urlFailure” were not specified
urlSuccessstring < = 256 characters urlNoURL for redirection after successful Transaction
urlFailurestring < = 256 characters urlNoURL for redirection after failure Transaction
customIpnUrlstring < = 256 characters urlNoURL address used by ZEN to send IPN to
specifiedPaymentMethodstringNoCode to limit checkout to one payment method. Check limiting checkout for more information
specifiedPaymentChannelstringNoCode to limit checkout to one payment channel. Check limiting checkout for more information
commentstring < = 512 charactersNoAny Merchant comment associated with the Transaction
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.
Instant bank transfer (PME_BANK_TRANSFER)
Klarna
Polish Pay-by-link (PBL)
PayPo Poland
PayPo Romania
Modified at 2026-10-27 13:42:16
Previous
Integration checklist
Next
Prepare the communication