Purchase Transaction with limited Payment methods

You can limit your checkout to particular Payment method or Payment channel. By providing one of parameters specifiedPaymentMethod or specifiedPaymentChannel you can prevent your Customers from using other methods in Payment session. The specifiedPaymentMethod and specifiedPaymentChannel parameters are a crucial elements that enables to:

Initiate Transactions using a specific designated Payment method when a Merchant chooses to offer only that particular Payment option to their Customers or when the Merchant wants only that Payment option to be visible at ZEN.COM checkout.

Initiate card transactions using a widget.

To properly use the parameter, during Payment initiation, instead of the standard PaymentChannel parameter, use „specifiedPaymentChannel” to declare the preferred Payment channel visible in the checkout Payment process. This allows to precisely specify the preferred Payment method for a given Transaction.

specifiedPaymentMethodparameter is responsible for limiting Payment methods on ZEN.COM checkout. All Payment channels related to the limited Payment method will be displayed on ZEN.COM checkout.

specifiedPaymentChannelparameter is responsible for limiting Payment channels on ZEN.COM checkout. Only limited Payment channels will be displayed on ZEN.COM checkout.

💡

Example

specifiedPaymentMethod: PME_PBL – will limit ZEN.COM checkout to all Payment channels under Pay by Link Payment method. It means, the Customer will see all banks aggregated under this Payment Methods.

specifiedPaymentChannel: PCL_CITI - will limit ZEN.COM checkout to only one Payment channel from PME_PBL Payment method. It means, the Customer will see only one bank aggregated under this Payment method.

The Merchant's Shop, when initiating a purchase Transaction, sends the mandatory and optional parameters (specifiedPaymentMethod or specifiedPaymentChannel) 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

Start with creating a working POST request as shown in Prepare the communication chapter. Remember to add specifiedPaymentMethod or specifiedPaymentChannel parameter to the request.

DANGER

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

💡

Example of JSON with limited Payment channel using specifiedPaymentChannel parameter

{
 "terminalUuid":"19b692d0-00b9-48f7-92ca-1509f055df2e",
 "amount":1000,
 "currency":"PLN",
 "specifiedPaymentChannel":"PCL_PBL_CITI",
 "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_PBL",
  "channel": "PCL_PBL_CITI",
  "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",
"signature": "820310D37DBBC763549ACE38E7D2106FE69BAB4E3D9CF6C525294F384E453EA5"
}

💡

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_PBL",
  "channel": "PCL_PBL_CITI",
  "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",
"signature": "870704D37DBBC763549ACE38E7D2106FE69BAB4E3D9CF6C525294D384U453PA5"
}