API Integration Guide

caution

Whilst we do have an API to collect and tokenise card details, this requires PCI DSS certification. Please utilise our Payment Plugin to collect payment details for tokenisation. Contact us for more information if you do have PCI DSS certification.

info

This guide relies on information presented in the Payment Plugin Guide.

Overview

By utilising our payment plugin for secure tokenisation, and out /v2/payments and /v2/proxies API endpoints, you can safely take card, PayTo, and bank payments via API call.

Tokenisation

Please refer to our Payment Plugin Guide for information on how to implement our payment plugin and details about tokenisation.

• Load the payment plugin using Mode: 1

• When payer enters their payment details, a payload (callback and/or webhook) will be returned with a token.

• This token can then be either stored in a secure database against a customer or other identifiable entity, or used immediately.

Checking Token/Proxy status & pricing

• To check token status or get fee pricing (to display any fees that are passed on to the payer), you can use our /v2/proxies API.

• You can also use the API to check PayTo mandate status. Please see the PayTo Guide for more details.

Example response

GET /v2/proxies/\{token\}

{
  "accountType": "Card",
  "cardHolderName": "Test Card",
  "cardNumber": "555555XXXXXX4444",
  "cardExpiry": "1230",
  "cardType": "MasterCard"
}

• To get the fees for a token, and given amount, see the below examples

Example response

GET /v2/proxies/\{token\}/pricing?paymentAmount=384.26

{
  "pricing": {
    "customerFee": 38.43,
    "merchantFee": 0,
    "processingAmount": 422.69,
    "paymentAmount": 384.26
  }
}

Making Payments

Once the token is obtained, you can charge the token using the /v2/payments API.

caution

Although in the API, customerEmail, customerName, and merchantUniquePaymentId are listed as optional - this is a legacy trait and all of these parameters should be treated as required to ensure there are no payment issues in the future.

info

Whilst both will work for card tokens, we strongly recommend using paymentAccountProxy instead of cardProxy to pass tokens via API to cover bank and PayTo tokens as well.

• Pass the payment token using paymentAccountProxy, along with customer details and payment amount as a POST to /v2/payments

Example response

POST /v2/payments

{
  "paymentReference": "101994",
  "customerName": "Bolvar Fordragon",
  "customerReference": "CR-MKV4IG3D-JJM",
  "paymentStatus": "Successful",
  "baseAmount": 53.24,
  "fundsToMerchant": 53.24,
  "customerFee": 5.32,
  "merchantFee": 0,
  "paymentAmount": 58.56,
  "accountOrCardNo": "555555XXXXXX4444",
  "paymentAccount": "Card",
  "processingDate": "2026-01-26T23:08:10.6705202",
  "settlementDate": "2026-01-28T00:00:00",
  "processorReference": "fdf7281d280072bc4aa3",
  "isPaymentSettledToMerchant": false,
  "paymentCard": "MasterCard",
  "additionalReference": "API Example Test",
  "merchantName": "Menethil",
  "merchantCode": "1337",
  "merchantUniquePaymentId": "PAY-1769429288200",
  "isPaymentRetryScheduled": false,
  "isPaymentRecalled": false,
  "isPaymentRefunded": false,
  "transactionType": 1,
  "transactionTypeDisplay": "Charge",
  "isPaymentChargeBacked": false,
  "paymentSourceDisplay": "Api Tokenised Payment",
  "customerCode": "TR16553015"
}

• For more information on the paymentStatus codes please see our Status Codes

• For more information on collecting payment information from API OR plugin payments, please see our Reconciliation Guide.

• For more information on charging a CML linked Customer entity (an entity that has a customer account with Zenith payments), please see our Zenith Customer Entity Guide )