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

Purchase Transaction

integration code.jpg
The Merchant's Shop, when initiating a purchase Transaction, sends the mandatory and optional parameters to the ZEN.COM Payment system in request to process the Transaction and then return the Payment status in response. All parameters are sent via the POST method.
Some Payment methods and/or Payment channels may require specific parameters to be provided when registering a purchase Transaction. Please refer to the detailed guidelines available here.
1
Create a POST request
Create a POST request as shown in Prepare the communication chapter.
💡
Example of JSON
{
   "terminalUuid":"19b692d0-00b9-48f7-92ca-1509f055df2e",
   "amount":1000,
   "currency":"PLN",
   "merchantTransactionId":"trasaction1",
   "customer":{
      "id":"CustomerId328642",
      "firstName":"John",
      "lastName":"Doe",
      "email":"[email protected]"
   },
   "items":[
      {
         "code":"itemCode1",
         "category":"itemCategory1",
         "name":"itemName1",
         "price":50,
         "quantity":4,
         "lineAmountTotal":200
      },
      {
         "code":"itemCode2",
         "category":"itemCategory2",
         "name":"itemName2",
         "price":100,
         "quantity":2,
         "lineAmountTotal":200
      }
   ],
   "billingAddress":{
      "id":"bAId1",
      "firstName":"John",
      "lastName":"Doe",
      "country":"PL",
      "street":"streetName",
      "city":"cityName",
      "countryState":"stateName",
      "province":"provinceName",
      "buildingNumber":"1",
      "roomNumber":"11",
      "postcode":"23-232",
      "companyName":"Company Name",
      "phone":"+48555555555",
      "taxId":"12345678"
   },
   "shippingAddress":{
      "id":"sA1",
      "firstName":"John",
      "lastName":"Doe",
      "country":"PL",
      "street":"streetName",
      "city":"cityName",
      "countryState":"stateName",
      "province":"provinceName",
      "buildingNumber":"1",
      "roomNumber":"11",
      "postcode":"11-111",
      "companyName":"Company Name",
      "phone":"+48555555555"
   },
   "urlFailure":"https://backtoshop/failure",
   "urlRedirect":"https://backtoshop/redirect",
   "urlSuccess":"https://backtoshop/success",
   "customIpnUrl":"https://backtoshop/notiify",
   "language":"pl",
   "signature":"16a36c391255e99596f12d802bf8fbba9b3414a23fc85bbf21974c05183961f3;sha256"
}
2
Send the request
Send the POST request to:
1.
test environment: https://secure.zen-test.com/api/checkouts
2.
production environment: https://secure.zen.com/api/checkouts
3
Receive the ZEN.COM response
Receive the ZEN.COM response which contains redirectUrl parameter (e.g. { "redirectUrl": "string"}).
💡
Example POST /api/checkouts response
{  
"redirectUrl": "https://secure.zen.com/0192310a-8289-7bcf-bf72-d867faa019b4"
}
4
Redirect the Customer to the ZEN.COM checkout page
Redirect the Customer to the ZEN.COM checkout page according to the received response.
5
Receive the IPN transaction notification
Receive the transaction status information sent by ZEN.COM in the IPN message.
💡
Example of ACCEPTED status response
{
   "type":"TRT_PURCHASE",
   "transactionId":"4321ab1c-d567-89de-f89g-h009i8b5d321",
   "merchantTransactionId":"12a3b098-a4a5-4f2a-9763-4a32d5ge32dc",
   "amount":"400.00",
   "currency":"PLN",
   "status":"ACCEPTED",
   "paymentMethod":{
      "name":"PME_BLIK",
      "channel":"PCL_BLIK",
      "parameters":{
         
      }
   },
   "customer":{
      "firstName":"John",
      "lastName":"Doe",
      "email":"[email protected]",
      "ip":"32.62.182.52",
      "country":"PL"
   },
   "securityStatus":"pending",
   "riskData":{
      
   },
   "email":" [email protected] ",
   "authorization":{
      "amount":"400.00",
      "currency":"PLN"
   },
   "hash":"B328EFG0ECA29B7RR815635F2F8D08039998F4B72FE4D7B148615EA460421B21"
}
💡
Example of REJECTED status response
{
  "type":"TRT_PURCHASE",
  "transactionId":"4321ab1c-d567-89de-f89g-h009i8b5d321",
  "merchantTransactionId":"12a3b098-a4a5-4f2a-9763-4a32d5ge32dc",
  "amount":"400.00",
  "currency":"PLN",
  "status":"REJECTED",
  "paymentMethod":{
     "name":"PME_BLIK",
     "channel":"PCL_BLIK",
     "parameters":{
        
     }
  },
  "customer":{
     "firstName":"John",
     "lastName":"Doe",
     "email":"[email protected]",
     "ip":"42.62.192.22",
     "country":"PL"
  },
  "securityStatus":"pending",
  "riskData":{
     
  },
  "email":" [email protected] ",
  "authorization":{
     "amount":"400.00",
     "currency":"PLN"
  },
  "hash":"c528EFG0ECA29f4RR815635F2F8D08039998F4B72FE4D7B148615EA460421B21"
}
Modified at 2026-09-29 09:02:45
Previous
Generating a Signature
Next
Purchase Transaction with limited Payment methods