Tokens

Token is a unique string of 64 characters associated within the payment platform with a certain payment card. Tokens contain no confidential information and can be stored in your system without violation of any payment card data security standards.

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

Statuses of tokens

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

Creating a token by request

To create a token by using Gate you need to:

1. Build and submit a request with all the required parameters and the signature to the actual URL of the Rocketpay payment platform.
2. Accept a callback with the token and some related information from the payment platform.

Request

This section provides instructions on how to build and submit the request to create a token.

{
    "customer": {
        "id": "customer_123",
        "ip_address": "198.51.100.47",
        "project_id": 123,
        "signature": "LLmhbDKdNhNLT+Qkr2SzbLbFYNxC9sZLnQKkrTFYNN06NMPmZS/BfWGucWQVZ2WM3v5N709w=="
    },
    "card": {
        "pan": "1122334455667788",
        "year": 2025,
        "month": 8,
        "card_holder": "JOHN DOE"
    }
}

Callback

The payment platform returns a callback with the token and some related information. For more information about the general callback structure, see Callbacks in Gate.

The following is an example of a callback with the token and the information that it was created for the payment card of the customer customer_123 within the project 123.

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

Automatic token generation

The payment platform can automatically generate a token when the bank card is used for the first successful purchase, payout, or authorization hold.

The payment platform will return a callback with information about the generated token and the exact time when it was created. For more information about callbacks, see Callbacks in Gate.

Payment by using token

Gate allows customers to make payments by using existing tokens.

The token is unique to the bank card. When processing payments with a card that already has a valid token, the payment platform does not create a new token. If the card expiration date is different from the one specified when the token was created, payment platform does not create a new token, but updates its expiration date instead.

For more information about the token-based payments, see One-time purchase.

Payout by token

When using Gate, you can make a payout to the customer's bank card by using a previously generated token. For more information about the token-based payouts, see Payout by token.

Getting card information by token

If you need to get a payment card's details, send a corresponding request to Gate. This section provides the instructions on how to build and submit a request for card details.

{
"customer": {
    "project_id": 123,
    "id":"customer_123",
    "signature":"2tlMuYxLW9Yu6RE...teg5lPk96Q=="
},
"token":"959c664ad64b8caa54bb7836ddc737fd1a3e6c7045679d71d89caff6c242a039"
}

The payment platform will send you the callback with the card details and its number masked.

{
"account": {
    "id": 2932,
    "number": "112233******7788",
    "type": "card",
    "additional": {
        "country": "GB",
        "phone": "4487775556776",
        "email": "johndoe@example.com",
        "card": {
            "expiry": "08/25",
            "holder": "JOHN DOE",
            "type": "visa"
            }
        },
    "recurring_enable": false
    },
"token": "959c664ad64b8caa54bb7836ddc777fd1a3e6c704b59bd71d89caff6c242a039"
    },
"signature": "62kPxuCGqN4KDrxqqsuWnv0LOjdvUydWCxDmN+AVW7/5UtLlmVL+SIyfbxot/Nf+47DEsAuW76DIgBg=="
}

Card verification by token

Gate allows you to verify customer's card by using a previously generated token. For more information about the token-based verification, see Payment card verification.

Revoking a token

Tokens are revoked in one of the following cases:

• the underlying payment card expires;
• you submit to the payment platform a request to revoke the token.

Request to revoke a token

This section provides the informationon how to build the request to revoke a token.

{
"customer": {
    "project_id": 123,
    "id":"customer_123",
    "signature":"2tlMuYxLW9Yu6RE...teg5lPk96Q=="
},
"token":"959c664ad64b8caa54bb7836ddc737fd1a3e6c7045679d71d89caff6c242a039"
}

The payment platform will send you a callback with the result of revoking the token. For more information about callbacks regarding tokens, see Token-related callback parameters.