Overview #

The Pay by Token API allows merchants to execute a payment using a previously registered customer and card token. This allows a transaction to be processed without sending the customer’s card details again.

The transaction is executed using the customerId and customerTokenId returned by the Execute API when tokenization is enabled.

Environment #

Endpoint #

POST

Execute/PayByToken

Content Type #

application/json

Request #

Request Headers #

Request Method #

POST

Sample Request #

{
    "amount": 1,
    "terminalId": 380024,
    "merchantId": 74417,
    "customerId": "fe60f286-b67e-47b2-81db-168d27f97288",
    "customerTokenId": "73b76aca-3876-4db9-859c-f56872c779c2",
    "requestDateTime": "2023-07-24T15:48:26.101Z",
    "clientMail": "client-email@test.com",
    "currencyCode": "512",
    "transactionId": "fa4d322e-55f6-41db-8b9b-7acf8fcc1390",
    "secureHashValue": "84EB3BF8F62EF25717D1E9E13C3CFB719A890980BBF2631AFD8965182ADE1754"
}

Token Information #

The customerId and customerTokenId are obtained from the Execute API response when IsTokenized is true.

These values can subsequently be used to execute a payment without requiring the customer to provide their full card details again.

Request Parameters #

Response #

Successful Response #

A successful transaction returns success: true and a response code of 00.

Sample Success Response #

{
    "success": true,
    "responseCode": "00",
    "message": "Success",
    "data": {
        "systemTraceNr": null,
        "message": "CAPTURED - ",
        "transactionId": "b81e7509-6ca0-4ab2-89c1-f373bbd4d91b",
        "isOtpRequired": false,
        "hostResponseData": {
            "TransactionId": "202431897300287",
            "Rrn": "431880000100",
            "TrackId": "b81e75096ca04ab289c1f373bbd4d91b",
            "PaymentId": null,
            "Auth": "490908"
        },
        "terminalId": 221143,
        "transactionTypeId": 2,
        "transactionTypeDisplayName": "Purchase",
        "customerId": null,
        "merchantId": 7921,
        "currency": null,
        "amount": 1,
        "currencyId": 512
    },
    "errorList": []
}

Success Response Parameters #

Tokenized Payment Details #

When the Execute API returns IsTokenized as true, the response can contain:

• customerId
• customerTokenId

These identifiers can be securely stored by the merchant and used for subsequent Pay by Token transactions.

The merchant can execute a subsequent transaction by providing:

customerId
customerTokenId

This eliminates the need to send the customer’s full card information for subsequent tokenized payments.

Important: Token identifiers should be treated as sensitive payment-related data and must be stored and transmitted securely.

Failure Response #

If the transaction cannot be processed, the API returns success: false along with a response code and an errorList describing the failure.

Sample Failure Response #

{
    "success": false,
    "responseCode": "61",
    "message": "APGEX: 62cfc42bff3b",
    "data": null,
    "errorList": [
        "Token Not Found"
    ]
}

Failure Response Parameters #

Common Failure Example #

Token Not Found #

{
    "success": false,
    "responseCode": "61",
    "message": "APGEX: 62cfc42bff3b",
    "data": null,
    "errorList": [
        "Token Not Found"
    ]
}

This response indicates that the supplied customerId and/or customerTokenId could not be found or could not be used to process the transaction.

Transaction Flow #

The Pay by Token process follows these general steps:

1. The customer completes an initial payment transaction.
2. If tokenization is enabled, the Execute API returns customerId and customerTokenId.
3. The merchant securely stores the token identifiers.
4. For a subsequent payment, the merchant sends the customerId and customerTokenId to the Execute/PayByToken endpoint.
5. The payment is processed without sending the customer’s full card details.
6. The API returns the transaction result and payment host information.

Note: Ensure that the correct merchant credentials, terminal ID, and environment-specific configuration are used when switching between UAT and Production.