COF payments by using token

Gate allows you to accept payments by debiting customer bank card using a pre-generated token. The debiting is made without re-entering the card details; in other words, the customer does not need to fill in the card details. Also, the important benefit of the feature is that the merchant can store the token on their server.

COF payments by using token has several advantages over other recurring payment methods:
  • Reuse previously saved card tokens in other merchant projects In the standard COF payment processing, a recurring payment can be initiated only in the project in which the initial payment was completed. The feature allows you to make the first payment in one project, and then use the token you received in the callback for payments in other projects. The feature may be useful for the merchants that hold multiple projects with the payment platform Rocketpay and need to make payments in the projects which are different from the one where the initial payment was processed.
  • Lower number of payments declined due to provider unavailability The payment platform mitigates the high decline rate problem by routing payments to different providers which are more available. Unlike the standard COF payment processing in which COF payments are registered with a single provider and must be processed only by this provider, the COF payments by using token feature allows processing payments by using different providers.

The basic scenario

Listed below are the basic steps for processing COF payment by using token (For more information about tokens, see Tokens.):

  1. The customer makes a initial payment or initial verification of their card in the merchant's web service—the operation is processed by Payment Page or Gate.
    Attention: The first step is very important and absolutely required for COF payments by using token to work properly. Without the initial successful payment or card verification procedure the COF payments feature will not function!
  2. Once successful payment or card verification procedure is complete, the merchant receives a callback with the card token.
  3. The merchant uses the token to initiate recurring purchases. The COF payments by using token feature does not require any additional card details.

Technical implementation

The initial payment or card verification operation

  1. Complete the initial (first) payment with card validation or the card validation operation. The payment or the card validation operation can be made either through Payment Page or Gate.

    For more information about one-time purchases by using Payment Page, see Purchase processing with Payment Page, for more information about one-time purchases by using Gate, see One-step purchase. For more information about card verification, see Payment card verification.

  2. Once the payment or card verification is successfully completed, accept the callback with the card token and store the token for future reference.
    Here is an example of the callback with the token:

    Figure: Example of the callback with the token

    { "account": { "number": "424242******4243", "token": "f365bb1729f9b72fd9c09703a751c979f3becc679f29c3e35c91d18070d15654", "type": "visa", "card_holder": "JOHN SMITH", "id": 45678, "expiry_month": "08", "expiry_year": "2025" }, "customer": { "id": "customer_12", "phone": "44991234567" }, "payment": { "date": "2019-01-11T13:02:42+0000", "id": "456789", "method": "card", "status": "success", "sum": { "amount": 400000, "currency": "USD" }, "type": "purchase", "description": "" }, "project_id": 42, "operation": { "id": 969000002636, "type": "sale", "status": "success", "date": "2019-01-11T13:02:42+0000", "created_date": "2019-01-11T13:01:45+0000", "request_id": "c6eed1eb14c629b4ef20b3b8086d...d04132c34b0088cbc0be4667c", "sum_initial": { "amount": 400000, "currency": "USD" }, "sum_converted": { "amount": 400000, "currency": "USD" }, "provider": { "id": 408, "payment_id": "330157196", "date": "2019-01-11T13:02:32+0000", "auth_code": "", "endpoint_id": "612266625" }, "code": "0", "message": "Success", "eci": "07" }, "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...==" }

    The token is required for future purchases, that is why you are required to store it for future use.

Recurrent payment by using the token
  1. Create and submit a request for recurrent payment by using the token to the /v2/payment/card/sale/token endpoint by using the POST method. Besides the required parameters specified in the API specification, the request must contain the following parameters:
    • token—the card token from the callback received when making the initial purchase or card verification operation
    • payment—object with payment details:
      • extra_param—this parameter must be specified in the request and always set to recurring

    Here is an example of the request for the recurrent payment by using the token:

    Figure: Example of the request for the recurrent payment by using the token:

    { "general": { "project_id": 111, "payment_id": "45611111", "signature": "s2eoM1aloGxDhYsLCpfwnnbL0FQ.....tnrMsFsc9gH" }, "customer": { "ip_address": "248.1.1.1", "id": "1" }, "payment": { "amount": 1000, "currency": "KZT", "extra_param": "recurring" }, "token": "f365bb1729f9b72fd9c09703a751c979f3becc679f29c3e35c91d18070d15654", "card": { "save": false } }

    No additional card information is required to successfully process this request.

Ask your key account manager for the details about enabling and using the COF payments by using token feature.