Payout Transaction - ZEN API documentation

INFO

A payout Transaction using the ZEN.COM API is only possible to a card or a digital wallet.

Transfer to card or digital wallet is a service that involves transferring funds from the Merchant’s account to the card account of the recipient. This is a one-way operation that allows the transfer of funds from one account to another to fund the card / digital wallet of the owner.

As part of the payout Transaction, the following actions are possible:
Create Transaction
Capture Transaction
Cancel Transaction
Renew Transaction
Get Transaction details (with ZEN.COM's id)
Get Transaction details (with Merchant's id)

Transfer to Card

Transfer to card enables quick and convenient transfer of funds to payment cards, which is particularly useful for urgent Payments such as salaries or insurance claims. Processing Transactions using the ZEN.COM API allows for process automation, which can expedite fund transfers and reduce the risk of human errors.

INFO

Please note that customer parameter is used to describe the sender of the funds (client of ZEN.COM's Merchant), where receiver parameter is used to describe the receiver of the funds. The customer parameter and the receiverparameter can be:

the same person where the sender is the receiver,

other persons where the sender is another person than the receiver.

INFO

Please note that items object is used to describe the title of the payout Transaction.

To Create the payout Transaction:

CAUTION

To use the service and perform a payout Transaction to a card, it is necessary to first:

Create the recipient

Create the recipient (Customer) using a POST request to the endpoint https://api.zen.com/v3/customers

Add the payout card

Add the payout card to that recipient using a POST request to the endpoint https://api.zen.com/v2/payout-profiles/card.

For more information how to add the Customer and the payout card please go to the Customers management chapter.

Create a POST request

CAUTION

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.

Create a POST request as shown in Prepare the communication chapter.

TIP

To increase the approval rate on Payments, you should fill in information such as the Customer’s first and last name, email, phone number, ip address.

💡

Example of JSON

{
   "merchantTransactionId":"22abc123-f9a5-99b8-5df8-b31180358dd3",
   "paymentChannel":"PCL_CARD",
   "amount":"123.45",
   "currency":"USD",
   "items":[
      {
         "name":"refunded_product_name_example",
         "price":"123.45",
         "quantity":1,
         "lineAmountTotal":"123.45"
      }
   ],
   "customer":{
      "id":"99A321B0-EA00-4A21-B78D-8032D981ADBA",
      "firstName":"John",
      "lastName":"Doe",
      "email":"[email protected]",
      "phone":"+48 123 456 789",
      "ip":"127.0.0.1"
   },
   "paymentSpecificData":{
      "cardToken":"1234A56B-B9EE-4A5F-828F-D498344E25B3",
      "type":"cardpayout",
      "recipient":{
         "firstName":"Joanna",
         "lastName":"Doe"
      }
   },   
   "billingAddress":{
      "street":"Example street",
      "city":"Example city",     
      "postcode":"00-001",
      "country":"PL"
      }
   }

INFO

Please note: for cardToken parameter use the id parameter from https://api.zen.com/v2/payout-profiles/card ZEN.COM API response.

Send the request

Send the POST request to:

test environment: https://api.zen-test.com/v1/payouts

production environment: https://api.zen.com/v1/payouts

Receive the ZEN.COM response

Receive the ZEN.COM response.

💡

Example of JSON response

{
    "id": "12abcdef-g345-4842-89ba-9c698ae15637",
    "merchantTransactionId": "22abc123-f9a5-99b8-5df8-b31180358dd3",
    "amount": "123.45",
    "currency": "USD",
    "createdAt": "2025-01-21T10:24:30.573Z",
    "modifiedAt": "2025-01-21T10:24:30.730Z",
    "type": "TRT_SENDOUT",
    "status": "PENDING",
    "paymentChannel": "PCL_CARD",
    "actions": {
        "capture": false,
        "cancel": false,
        "refund": false,
        "redirect": false,
        "authorization": false
    },
    "fraudFields": {
        "channel": "PTS_ZEN_API",
        "apiIntegration": "true"
    },
    "customer": {
        "id": "99A321B0-EA00-4A21-B78D-8032D981ADBA",
        "firstName": "John",
        "lastName": "Doe",
        "email": "[email protected]",
        "phone": "+48 123 456 789",
        "ip": "127.0.0.1",
        "country": "LT"
    },
    "billingAddress": {
        "country": "PL",
        "city": "Example city",
        "postcode": "00-001",
        "street": "Example street"
    },
    "items": [
        {
            "name": "refunded_product_name_example",
            "price": "123.45",
            "authPrice": "123.45",
            "quantity": 1,
            "lineAmountTotal": "123.45",
            "authLineAmountTotal": "123.45"
        }
    ],
    "source": {
        "channel": "PTS_ZEN_API"
    },
    "cardInfo": {
        "bank": "Bank name",
        "country": "PL",
        "organization": "COR_MASTERCARD",
        "organizationBrand": "CCB_MASTERCARD",
        "token": "1234A56B-B9EE-4A5F-828F-D498344E25B3",
        "segment": "CSG_INDIVIDUAL",
        "type": "CDT_DEBIT",
        "lastFourDigits": "1234",
        "bin": "111222",
        "eea": true,
        "commercial": false,
        "merchantCardToken": "1234A56B-B9EE-4A5F-828F-D498344E25B3"
    },
    "authorization": {
        "amount": "123.45",
        "currency": "USD"
    }
}

INFO

Please note: merchantCardToken, token and cardToken parameters are using id parameter from https://api.zen.com/v2/payout-profiles/card ZEN.COM API response.