Tokenization

General information

Payment Page allows you to create tokens. Tokens are stored in the merchant web service side and can be used for purchase processing through Payment Page and Gate and for payout processing by using Gate.

Token is a unique, random sequence of 64 characters associated with a specific payment card within the payment platform.

Token is created based on customer payment information, such as payment card number, name and surname of cardholder and card expiration date. Tokenization can be performed in the following cases:

• Payment Page is opened in the Card Tokenize mode.
• Purchase processing with saving payment information in the Purchase mode completes successfully.
• The first purchase or payout processing using payment card completes successfully—if this option is available in the merchant project. In order to configure automatic tokenization using this option, contact ITX technical support (support@kzitx.com).

A token is created with the same expiration date equal as the expiration date of the underlying payment card, and its status is set to active. Once the token expires, its status is set to expiry. If the token is deleted on request from the web service, its status is set to revoke. Tokens with statuses expiry or revoke are not valid and cannot be used for to initiate a payment.

To delete token or obtain payment information related to the token, you need to use Gate. For more information, see Using tokens.

When tokenization is used via Payment Page, basic steps that the customer performs include specifying card details and waiting for notification about the result. Following the successful generation of the payment card token, the details of this card are shown on the saved payment instruments list of the payment method selection page.

Workflow

In terms of performing tokenization by using Payment Page, the merchant web service is required to do the following:

1. Create and send a request for opening Payment Page to the payment platform.
2. Receive the callback with the result of the request processing from the payment platform.

Request format

The format of the request for opening Payment Page to perform tokenization is the same as the request format described in the Payment Page API Description section. When creating request, you should consider the following:

1. The request must contain the following required parameters:
   • mode—the indicator of the Payment Page operation mode. The value must be card_tokenize.
   • project_id—the project ID obtained from ITX.
   • customer_id—the customer ID unique within the project.
   • signature—the signature created after you specify all the required parameters. For more information about signature generation, see Signature generation and verification.
2. To display Payment Page in a required language, you need to additionally specify in the request the language_codeparameter and the language code in accordance with ISO 639-1 alpha-2 as its value. If this parameter is not specified in the request, Payment Page is displayed either in English (for all countries except for Russia) or in Russian (for Russia), according to IP address of the customer.
3. If needed, you can also add any other additional parameters supported by Payment Page in the Card Tokenize mode. The full list of parameters for opening Payment Page is provided in the Payment Page invocation parameters section.

Thus, a correct payment request must include identifier of the Payment Page operation mode, project and customer IDs and signature.

{
   "mode": "card_tokenize",
   "project_id": "112",
   "customer_id": "cust_123",
   "signature": "TSzdE5rJZaA9VyJtnfRI362oGpfXriFf82MxF..."
}

https://paymentpage.kzitx.com/payment?signature=A%2Fqqxsl59tRrtACreixy8sieSfxR%2BC...&mode=card_tokenize&project_id=112&customer_id=cust_123&region_code=EU&language_code=en

Callback format

The format of the callback to notify the merchant about token creation is the same as the format described in the Callbacks in Payment Page section.

The following is an example of a token (token) created for the customer cust_123 in terms of the project 112. Date and time of token creation (token_created_at) as well as the current status of the token (token_status) are also specified.

{
    "project_id": 112,
    "customer": {
        "id": "customer_123"
        },
    "request": {
        "id": "3c7f53fdbb5b8c96f9707457d75f",
        "action": "tokenize",
        "status": "success"
    },
    "token": "2f0e75befacca30623354f9ffb0f44a80bee52982c39727b85039ef6f64309a1",
    "token_created_at": "2020-03-28 13:30:57",
    "token_status": "active",
    "signature": "mTHcy5wvpOYkl9S5eLJZ..."
}