Tokenization

General information

Payment Page allows creating tokens. Tokens are stored on the merchant web service side and can be used for purchase processing by using Payment Page and Gate and for payout processing by using Gate.

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

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 to merchant project. In order to configure automatic tokenization using this option, contact ecommpay technical support (support@ecommpay.com).

In each case for a particular payment card one token is created with the expiration date equal to the expiration date of the payment card, and the status of the token is active. Once the token expires, the status is set to expiry. If the token is deleted on request from the web service, the status is set to revoke. In both cases (expiry and revoke) payment processing using this token is unavailable.

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 ecommpay.
   • 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, the payment form is displayed in the language selected automatically (by the browser language, by the region, or by default—learn more).
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 Parameters for opening payment form 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.ecommpay.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 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.

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