Purchase Transaction - Checkout documentation

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.

Create a POST request

DANGER

Request header with Authorization parameter is obliged for all requests sent to ZEN.COM API. Authorization value is the Checkout Secret parameter you can find in your my.zen.com Merchant portal.

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"
}

Send the request

Send the POST request to:

test environment: https://secure.zen-test.com/api/checkouts

production environment: https://secure.zen.com/api/checkouts

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"}

Redirect the Customer to the ZEN.COM checkout page

Redirect the Customer to the ZEN.COM checkout page according to the received response.

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"
}