Tokenization

General information

Token is a unique string of 64 characters associated within the payment platform with a certain payment card.

You can store tokens in your system and use them to perform purchase through Payment Page. Tokens contain no confidential information and can be stored in your system without violation of any payment card data security standards.

This section covers information about creating tokens when using Payment Page. For information about using tokens in purchase processing, see Purchase processing with Payment Page. For information about using tokens for payment card verification, see Payment card verification.

The payment platform creates tokens based on customer payment information, such as payment card number, cardholder's first and last names, and card expiration date.

Tokens are created in the following cases:

  • You submit to the payment platform a request to create a token.
  • The first purchase on the payment card is completed successfully (if tokenization option is enabled in your project).
  • Purchase with saving payment information is completed successfully (if tokenization option is enabled in your project).
Tip: To enable automatic tokenization option in your project, reach out to Rocketpay technical support (support@rocketpay.kz).

The token is created with the same expiration date as the expiration date of the associated payment card.

To revoke a token, perform a payout to the customer, or get bank card details from the token, you need to use Gate. For more information, see Tokens.

When a token is created through Payment Page, the customer should specify card details and receive a notification about the result. After the token is successfully created, the corresponding card will be shown to the customer in the saved payment instruments list on the payment method selection page when the customer starts a new purchase.

Workflow

To create a token by using Payment Page:

  1. Build and submit to the payment platform a request to open Payment Page to create a token.
  2. Accept the callback with the result of the request processing from the payment platform.

Request

To open Payment Page and create a token, send a request with the following parameters to the payment platform.

Table 1. Basic parameters of a request to Payment Page to create a token

strictly required—the parameter must be in the initial request.
Parameter Description

mode
string, strictly required

Payment Page mode. To create a token you need to specify card_tokenize in this parameter.

Example: card_tokenize

project_id
integer
strictly required

Project ID you obtained from Rocketpay when integrating.

Example: 123

customer_id
string
strictly required

Unique ID of the customer within your project.

Example: customer_123

signature
string
strictly required

 Signature created after you've specified all the request parameters. For more information about signature generation, see Signature generation and verification.
You can also add any other optional parameters to the request, if necessary. For the list of all the parameters possible in requests to Payment Page, see Payment Page invocation parameters.

Here is an example of the data from a request to open Payment Page to create a token by using EPayWidget:

EPayWidget.run(
    {
   "mode": "card_tokenize",
   "project_id": "123",
   "customer_id": "customer_123",
   "signature": "TSzdE5rJZaA9VyJtnfRI362oGpfXriFf82MxF..."
   }
)

Figure: Example of a GET request to open Payment Page to create a token

https://paymentpage.rocketpay.kz/payment?signature=A%2Fqqxsl59tRrtACreixy8sieSfxR%2BC...&mode=card_tokenize&project_id=123&customer_id=customer_123&region_code=EU&language_code=en

Callback

The payment platform sends you the callback with the token you requested and some information related to the token creation. For more information about the callback structure, see Callbacks in Payment Page.

The following is an example of a callback that contains the requested token and the information that the token was created for the customer customer_123 within the project 123.

Figure: Example of a callback with information about a token

{
    "project_id": 123,
    "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..."
}

Statuses of tokens

The status of the token defines if the token can be used to perform payments.

Status Description
active Token is valid and can be used for payments
revoke Token is revoked and cannot be used for payments
expiry Token has expired and cannot be used for payments

Related links