Saving and tokenizing cards - ZEN API documentation

INFO

This feature is only supported for API Integration.

You can save card data in the form of a token and use it for future Transactions instead of asking the Customer to fill in card details each time they make a Transaction. Saving and tokenizing cards are required for one-click card Payments as well as recurring Payments.

To save and tokenize card:

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.

In the paymentSpecificaData object, send all data according to the API Reference documentation and make sure that:

paymentSpecificaData.type is set to onetime

paymentSpecificaData.saveCard is set to true

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.

DANGER

The id parameter aggregated in the customer object is not mandatory. However, if it is not sent to ZEN.COM as part of the Transaction request, it will not be possible to retrieve purchase card details later using the https://api.zen.com/v3/customers/{merchantCustomerId}/payments/card/{id} and https://api.zen.com/v3/customers/{merchantCustomerId}/payments/card/{id} endpoints. Customer ID should be provided using UUID data format.

💡

Example of JSON

{
  "merchantTransactionId": "99aba298-f9a5-99b8-5df8-b31180358dd3",
  "paymentChannel": "PCL_CARD",
  "amount": "123.45",
  "currency": "USD",
   "fraudFields": {
   "fingerPrintId": "ZEN;eyJ3ZXAzaW9uIjoab",
   "referrer": null,
},         
    "items": [
    {
      "code": "product_1",
      "category": "default_category",
      "type": "physical",
      "name": "product_name_example",
      "price": "123.45",
      "quantity": 1,
      "lineAmountTotal": "123.45"
    }
  ],
   "customer":{
      "id":"4a3b5c7d-1e3f-abcd-1a3f5f7f9bab"
      "firstName":"John",
      "lastName":"Doe",
      "email":"[email protected]",
      "phone":"+48 123 456 789",
      "ip":"127.0.0.1"
   },
  "paymentSpecificData": {
    "browserDetails": {
      "acceptHeader": "accept_header_string",
      "colorDepth": "1",
      "javaEnabled": true,
      "lang": "EN",
      "screenHeight": "1080",
      "screenWidth": "1920",
      "timezone": "1",
      "windowSize": "05",
      "userAgent": "Mozilla/5.0 (Linux; Android 10; K) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Mobile Safari/537.36"
    "saveCard": true,
    "card": {
      "number": "1234567899876543",   
      "expiryDate": "1228",
      "cvv": "123",
      "cardHolderName" : "Demo Company"
    },
    "type": "onetime",
    "avsCheck": false,
    "descriptor": "onetime e-commerce transaction"
  }
}

Send the request

Send the POST request to:

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

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

Receive the ZEN.COM response

Receive the ZEN.COM response with generated an unique token associated with this card which will be saved in the Shop. Token will be placed in: cardInfo.token parameter

💡

Example of JSON response with card token

{
   "id":"43d435a2-1abc-4321-8fd1-432148712345",
   "merchantTransactionId":"99aba298-f9a5-99b8-5df8-b31180358dd3",
   "amount":"123.45",
   "currency":"USD",
   "createdAt":"2024-12-27T10:49:57.230Z",
   "modifiedAt":"2024-12-27T10:49:58.990Z",
   "type":"TRT_PURCHASE",
   "status":"ACCEPTED",
   "paymentChannel":"PCL_CARD",
   "actions":{
      "capture":false,
      "cancel":false,
      "refund":false,
      "redirect":true,
      "authorization":false
   },
   "fraudFields":{
      "channel":"PTS_ZEN_API",
      "apiIntegration":"true"
   },
   "meta":{
      "threeDs":{
         "emv3DSFlow":"ChallengeFlow"
      }
   },
   "customer":{
      "id":"4a3b5c7d-1e3f-abcd-1a3f5f7f9bab"
      "firstName":"John",
      "lastName":"Doe",
      "email":"[email protected]",
      "phone":"+48 123 456 789",
      "ip":"127.0.0.1"
   },
   "items":[
      {
         "code":"product_1",
         "category":"default_category",
         "type":"physical",
         "name":"product_name_example",
         "price":"123.45",
         "authPrice":"123.45",
         "quantity":1,
         "lineAmountTotal":"123.45",
         "authLineAmountTotal":"123.45"
      }
   ],
   "cashback":{
      "active":false
   },
   "source":{
      "channel":"PTS_ZEN_API"
   },
   "merchantAction":{
      "action":"REDIRECT",
      "data":{
         "redirectUrl":"https://cardauth.zen.com/threeds/4/process/dMR2MZ7fscf2kD4Qcwg8Ir1lbWrXWohgwyY2hvfsZeR3Y2b4zp2acWhv0ABCDx8P/53d515a2-3bec-8203-8fd1-242548703311/191821e8-81c6-446d-c5bf-3a1675ffa48b"
      }
   },
   "verifyReturnmac":"201234a8-81c6-446d-b5da-3a4321ffa48b",
   "cardInfo":{
      "bank":"UAB ZEN.com",
      "country":"EE",
      "organization":"COR_MASTERCARD",
      "organizationBrand":"CCB_MASTERCARD",
      "segment":"CSG_COMMERCIAL",
      "token": "a1234567-8bc9-4321-d123-4e9876f7g444"
      "type":"CDT_DEBIT",
      "lastFourDigits":"6543",
      "expirationDate":"2028-12-31",
      "bin":"123456",
      "eea":true,
      "commercial":true
   },
   "authorization":{
      "amount":"123.45",
      "currency":"USD"
   }
}

The card data are saved for the Customer as provided in the POST /transactions request: customer.id. This identifier will be used to manage saved/tokenized card data. Tokenized cards are saved in PAYMENT PROFILES.

CAUTION

ThecardInfo.token parameter will be sent in Response when Transaction status is set to Accepted

You can carry out the following actions with all saved card tokens:

Endpoint	Request type	Description
Fetch card list	`GET`	Request a list of all saved cards (for provided external-customer-id, as described in the Saving and tokenizing cards section)
Fetch card	`GET`	Request data of a particular saved card (for provided card id, obtained in point 1)
Update card details	`PATCH`	Update data of a particular saved card (for provided card id, obtained in point 1)
Remove card	`DELETE`	Delete a previously saved card (for provided card if, obtained in point 1)