Using tokens

Token is a unique, random sequence of 64 characters associated in Gate with a specific bank card and the customer in the project. Token does not contain a confidential information and can be stored in your system without threatening to violate the standards of secure bank card data storage.

By using Gate you can create tokens automatically or by request and make puchases and payouts by using existing tokens.

Statuses of tokens

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

Table 1. Possible token statuses
Status Description
active Token is active and can be used to perform payments and payouts
revoke Token is revoked and cannot be used to perform payment and payouts
expiry Token has expired and cannot be used to perform payment and payouts

Automatic token generation

Automatic generation procedure creates a token when the first successful purchase or payout is performed by using a bank card, as well as after holding the funds on a bank card.

The generated token and the date when it was created are returned in the payment callback. For more information about callbacks, see in Callbacks.

Tip: To enable automatic token generation, contact technical support by email support@ecommpay.com.

Token generation by request

Another way to generate a token is to send a request to generate a token. In the request you send the data required to generate the token.

The generated token and the time it was created at are returned in the token generation response.

Token generation request

Note: POST the /v2/customer/card/tokenize request.

Specify the project id, customer data and data of customer bank card in the request.

You receive in the callback a bank card token and the time when it was generated. For more information about callbacks, see in Callbacks.

Figure: Example of the request for token generation

{
    "customer": {
        "id": "1707",
        "ip_address": "1.87.128.111",
        "project_id": 11,
        "signature": "LLmhbDKdNhNLT+Qkr2SzbLbFYNxC9sZLnQKkrTFYNN06NMPmZS/BfWGucWQVZ2WM3v5N709w=="
    },
    "card": {
        "pan": "4314220000000056",
        "year": 2020,
        "month": 5,
        "card_holder": "PAUL SMITH"
    }
}

Payment by token

Gate enables customers to process fast payments by using a previously generated bank card token.

Note: The token is unique to the bank card. When processing payments by bank card a valid token that already exists will be returned.

The token is unique to the bank card. When processing payments by bank card a valid token that already exists will be returned. In this case, if the card expiration date is different from the one specified when the token was generated, the token is not generated anew, but the expiration date of the token is updated.

Additional information about the token-based payments see in One-time purchases.

Payout by token

Gate enables you to process the payout of funds to a customer's bank card by using a previously generated token. Additional information about the token-based payouts see Payouts.

Receiving card data by token

If you need to receive bank card data and information about the payment instrument to which this card is linked, send a request to Gate.

Note: POST the /v2/customer/card/bytoken request.

In the request, specify the project ID, customer ID and token.

You receive in the callback the masked bank card data and other information on the customer payment instrument.

Figure: Example of the request for receiving card data by token

{
	"customer": {
		"project_id": 12,
		"id":"test_customer",
		"signature":"2tlMuYxLW9Yu6RETr8pdCfmi0UPE8JguQjXWH6naCA9Ts6o4EVPjLyfbOQ+9ajAteg5lPk96Q=="
	},
	"token":"959c664ad64b8caa54bb7836ddc737fd1a3e6c7045679d71d89caff6c242a039"
}

Figure: Example of the callback with the payment instrument information

{
    "account": {
        "id": 2932,
        "number": "431422******0056",
        "type": "card",
        "additional": {
            "country": "GB",
            "phone": "4314220000000056",
            "email": "john@gmail.com",
            "card": {
                "expiry": "01/20",
                "holder": "JOHN JOHNSON",
                "type": "visa"
            }
          },
          "recurring_enable": false
        },
        "token": "959c664ad64b8caa54bb7836ddc777fd1a3e6c704b59bd71d89caff6c242a039"
    },
    "signature": "62kPxuCGqN4KDrxqqsuWnv0LOjdvUydWCxDmN+AVW7/5UtLlmVL+SIyfbxot/Nf+47DEsAuW76DIgBg=="
}

Card verification by token

Gate enables you to perform the customer's bank card verification by using a previously generated token. The information about the token-based verification is provided in the Payment instrument verification section.

Revoke of a token

A token can be revoked in one of the following happens: you revoke the token or the payment card expires.

In the former case, if required, you can revoke a token from Gate by sending a request to revoke the token. Gate revokes the token.

Request to revoke a token

Note: POST the /v2/customer/card/token/revoke request.

Specify the customer data in your system and the token to be revoked.

You receive in the callback the result of revoking of the token.

Callback after generating or revoking a token

Once you pass a token generation or token revoke request to the /v2/customer/card/tokenize endpoint, the payment platform returns a callback with the request execution result. The following table shows the parameters included in the callback. For more information about callbacks, see Callbacks.
Table 2. Callback objects and parameters related to token creation or revoke
Parameter Description tree

general
object, required

 The object with the general request data. 1

project_id
string, required

The unique identifier of your project.

Example: 42.

 1-11

customer_id
string, optional

 The unique identifier of the customer in your project. 1-21

signature
string, required

 Callback signature 1-31

request
object, required

 The object with the request data 2

id
integer, required

Unique identifier of the request

Example: 3718000054

 2-12

action
string, optional

 Type of the request. The following options are available:
  • tokenize—token creation request
  • token_revoke—token revoke request
  • parameter is missing from callback — token is expired and deactivated. The platform initiates a callback with missing action automatically, immediately after the token expires. Such callback is not issued in response to a request.
 2-22

status
string, required

 The request status. The following options are available:
  • success—request successfully completed
  • error—error(s) encountered when processing request. The error details are passed in the errors array.
 2-32

errors
array, optional

 Array of error messages. 2-42

ErrorItem
object, required

 The object with information about a single error. 2-4-12-4

code
string, optional

Error code.

Example: 10309.

 2-4-1-12-4-1

message
string, optional

A message that clarifies the error cause.

Example: Attempt to make COF purchase without registered recurrent payments.

 2-4-1-22-4-1

field
string, optional

 The parameter in which the error occurred if it was defined 2-4-1-32-4-1

token
string, optional

 Token of the customer bank card. The token is generated automatically when a successful payment is performed if the appropriate option is enabled. 3

token_created_at
string, optional

The date and time the token was generated.

Example: 2017-07-21T03:31:24+0000

 4

token_status
string, optional

Token status.

Example: active

 5

Figure: Callback after token generation

"general":{
   "project_id":12,
   "signature":"\/gmTHcy5wvrFD4ISuWEiV8+nOa3aqnLnyJ\/AupOYkl9S5eLJZ",
"request": {
			"id": "3c7f53fdbb5b8c96f9707457d75f",
			"action": "tokenize",
			"status": "success"
		},
"token":"2f0e75befacca30623354f9ffb0f44a80bee52982c39727b85039ef6f64309a1",
"token_created_at":"2017-11-28 13:30:57",
"token_status":"active"
}