Card tokenization

Tokenization of the card data is the process where sensitive cardholder data is replaced with a unique string of characters (token), which can be used in subsequent transactions instead of using the card details. This is particularly useful for recurring payments (e.g., subscriptions, installments, etc.). The token can be stored in your system. With the token, you can both charge the card and process refunds. Check how to use a saved token to make a payment.

Before you start

Ensure that:

• You have API authorization data.
• You handle transaction notifications.
• You have card payments enabled.

Tokenization during a card transaction

Process a card payment and additionally receive a payment token as a result. This scenario is also referred to as tokenization during a card transaction.

This tokenization method is useful in scenarios such as:

• Subscription platform with a fixed monthly fee - the first month of the subscription is charged immediately, and within the same transaction you save the card for further, automatic billing.
• A store saving the card on the first order - the payer pays for their first order, and at the same time you save their card so they can select it for future purchases.
• A service with annual billing - the first annual payment is also the moment the card is saved for subsequent, yearly billing cycles.

Send a request to create a card transaction

To create a card transaction, send a POST request to the endpoint:

https://api.tpay.com/transactions

In the request, specify the following parameters:

The basic request body should look as follows:

{
  "amount": 0.1,
  "description": "Test card payment",
  "payer": {
    "email": "[email protected]",
    "name": "John Doe"
  },
  "pay": {
    "groupId": 103,
    "cardPaymentData": {
      "save": 1
    }
  }
}

After sending the request, you will receive a TransactionCreated schema in response.

Key response parameters:

Example response:

{
  "result": "success",
  "requestId": "858fa92dc62db44e2c1f",
  "transactionId": "01K5BK4HEPB0WBCGT51FMTYSYJ",
  "title": "TR-CWM-CNYHA6X",
  "posId": "ps_e4dkPVDEm4Jg7267",
  "status": "pending",
  "date": {
    "creation": "2024-06-06 21:31:35",
    "realization": null
  },
  "amount": 0.1,
  "currency": "PLN",
  "description": "Test card payment",
  "hiddenDescription": "",
  "payer": {
    "payerId": "py_a9rjlZWxRLdG1bqY",
    "email": "[email protected]",
    "name": "John Doe",
    "phone": "",
    "address": "",
    "city": "",
    "country": "PL",
    "postalCode": ""
  },
  "payments": {
    "status": "pending",
    "method": "pay_by_link",
    "amountPaid": 0,
    "date": {
      "realization": null
    }
  },
  "transactionPaymentUrl": "https://secure.tpay.com/?title=TR-CWM-CNYHA6X&uid=01HZQGHZP5P3P7YV8A4BRVDX17"
}

Redirect the Payer to the Transaction Panel

Redirect the payer to the URL provided in the response under transactionPaymentUrl.

The payer will then fill out the form with their card details and submit it.

3D Secure authentication (3DS)

If necessary, we will redirect the payer to the issuing bank's page for 3D Secure authentication.

3D Secure is an authentication protocol aimed at enhancing the security of online card transactions. The 3D Secure process works by adding an additional authentication step before the transaction is approved.

The payer is asked to provide additional authentication data, which could be a password, SMS code, fingerprint, bank app authorization, or other identity verification methods.

If the payer successfully completes the authentication process, the transaction will be processed to authorization. Otherwise, the transaction is declined.

Payer will be redirected to success or error page

Once the card payment is completed, the payer will be redirected to a success page or error page depending on whether the transaction was successful or not.

Handle notification

We will inform you about the transaction status via a transaction webhook. Check the details.

Additional parameters that will be sent to the transaction webhook include:

Tokenization without charging the card

Tokenization without charging the payer's card is a scenario where the payer provides their card number. In this process, we authenticate the payer using 3D Secure (3DS) but do not charge the payer's account any amount. At the end, we issue the token corresponding to the card.

This tokenization method is useful in scenarios such as:

• Free trial period - you save the payer's card at the start of the trial period, without collecting any fee; the first actual payment occurs once the trial ends.
• Saving a card in the customer's account - the payer adds a card in their account settings, without placing an order first, so they can use it for future purchases.
• Pay-as-you-go service - you save the card when the payer registers, and billing happens later, depending on actual usage.

Send a request to create tokenization without charging

To start with the tokenization without charging, send a POST request to the endpoint:

https://api.tpay.com/tokens

In the request, specify the following parameters:

The basic request body should look as follows:

{
  "payer": {
    "name": "John Doe",
    "email": "[email protected]"
  },
  "callbackUrl": "https://your-page.com/webhook/tokens"
}

Example:

curl --location 'https://api.tpay.com/tokens' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <access_token> \
--data-raw '{
    "payer": {
        "name": "John Doe",
        "email": "[email protected]"
    },
    "callbackUrl": "https://your-page.com/webhook/tokens"
}'

After sending the request, you will receive a CardTokenizationCreated schema in response.

Key response parameters:

Example response:

{
  "result": "success",
  "requestId": "34d5c290829d7a92c8c6",
  "id": "TO-BRA-01HZKX1YR6KDGH79YTVY4KCQ6B",
  "url": "https://cards.tpay.com/pay/01HZKX1Z0JSC4DX7KS2ANC459R"
}

Redirect the payer to the transaction panel

Redirect the payer to the URL provided in the response under url.

The payer will then fill out the form with their card details and submit it.

3D Secure authentication (3DS)

If necessary, we will redirect the payer to the issuing bank's page for 3D Secure authentication.

3D Secure is an authentication protocol aimed at enhancing the security of online card transactions. The 3D Secure process works by adding an additional authentication step before the transaction is approved.

The payer is asked to provide additional authentication data, which could be a password, SMS code, fingerprint, bank app authorization, or other identity verification methods.

If the payer successfully completes the authentication process, the tokenization will be passed for authorization. Otherwise, it will be declined.

Payer will be redirected to success or error page

Once the payment is completed, the payer will be redirected to a success page or error page depending on whether the transaction was successful or not.

Handle notification

We will inform you of the tokenization result at the address provided in the callbackUrl parameter. Check the details.

If you have not set the Token Notification URL in the Merchant Panel, or you set it with the Allow overwriting the token notification URL option enabled, we will also send notifications about later token updates to that same address (callbackUrl). Check the details.

Tokenization Plus

Tokenization Plus is a card tokenization method that, in addition to issuing a token for future card transactions, also performs network tokenization of the card data in the background. Network tokenization means replacing card details with a network token issued directly by card networks such as Visa or Mastercard. Other common names for a network token include: network token, scheme token, Visa token, or Mastercard token.

Through the Tokenization Plus service, Tpay will use the network token for transaction processing instead of the card data. The value of a network token is that if the tokenized card expires and the payer receives a new one in its place, the network token will be automatically renewed, meaning recurring payments can continue without requiring any action from the merchant or the cardholder. If a network-tokenized card is suspended or closed, the merchant will receive a corresponding notification, enabling them, for example, to contact the payer to ensure payment continuity.

As part of the Tokenization Plus program, we provide the card image for tokens and inform you of every change to the card.

Token creation

You will automatically receive a token under Tokenization Plus by creating a token using either of the two methods described in this document - you don't need to configure anything additionally:

• Tokenization during a card transaction.
• Tokenization without charging the card.

Retrieve token status with card image

To retrieve the token status along with the card image, send a GET request to the endpoint:

https://api.tpay.com/tokens/{tokenValue}

Replace {tokenValue} with the token value received in the webhook notification tokens.

Example URL:

https://api.tpay.com/tokens/bfbde8ba10da6215fe92fb28b8787d154afc5cdacaee72fbb91042ccf544f871

Response parameters:

Sample response for a network token (Tokenization Plus):

{
  "paymentInstrument": "NETWORK_TOKEN",
  "expirationDate": "0427",
  "tokenStatus": "ACTIVE",
  "cardTail": "9588",
  "cardImage": "https://cards-img.tpay.com/01ABCDEFGH23456IJKLM7890NO_01ABCDEFGH23456IJKLMN7890V"
}

Sample response for a standard card-on-file:

{
  "paymentInstrument": "COF",
  "expirationDate": "0427",
  "tokenStatus": null,
  "cardTail": "9588",
  "cardImage": null
}

The URL returned in the cardImage field contains a ready-to-display visualization of the payer's card, which you can present, for example, in the customer panel next to the saved payment method. This applies only to network tokens (paymentInstrument: NETWORK_TOKEN).

Token deletion

To delete and deactivate a payment token, send a DELETE request to the endpoint:

https://api.tpay.com/tokens/{tokenValue}

Replace {tokenValue} with the token value received in the webhook notification tokens.

Example URL:

https://api.tpay.com/tokens/bfbde8ba10da6215fe92fb28b8787d154afc5cdacaee72fbb91042ccf544f871

After sending the request, you will receive a response HTTP Status 204 - No Content.

Handling notification of token status or card image change

We will notify you via notification for token or card update of any change in the status of the payment token or the card image.

We describe in detail how the URL for this notification is determined in the Token or card update notification section.

After receiving the notification of a token status change, we recommend re-fetching the token status along with the card image to update the information in your system.

Payment with a saved token

You can use the obtained token to charge the payer's card without having to re-enter their card details - e.g., for recurring payments (subscriptions, installments) or a repeat order. This applies to every token described in this document, regardless of whether it was created under Tokenization Plus or as a standard card-on-file - the way it is used is identical.

To pay with a saved token, create a transaction (POST /transactions) just like a regular card payment, and then pay for it with the token by sending a POST request to the endpoint:

https://api.tpay.com/transactions/{transactionId}/pay

In the request, specify the following parameters:

{
  "groupId": 103,
  "cardPaymentData": {
    "token": "t59c2810d59285e3e0ee9d1f1eda1c2f4c554e24"
  },
  "cof": "recurring"
}

After sending the request, you will receive the same TransactionCreated schema in response as for a standard card transaction.