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.
We distinguish two possibilities: tokenization during a card transaction (same as purchase transaction) and tokenization without charging the card (known also as Account Verification Transaction).
Before you start
Ensure that:
- You have API authorization data.
- You handle transaction notifications.
- You handle tokenization notifications.
- You have card payments enabled.
Tokenization during a card transaction
Execute card payments and receive a payment token by using the transaction creation endpoint with groupId: 103.
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
Check the details in the API Reference documentation: POST /transactions
In the request, specify the following parameters:
amount | Transaction amount (in PLN). |
description | Description of the transaction visible to the payer. |
payer.email | Payer's email address. |
payer.name | Payer's name and surname. |
pay.groupId | Payment group identifier for cards: 103. |
pay.cardPaymentData.save | 1 - parameter indicating the request for issuance of a payment token. |
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:
result | success - The transaction was successfully created. |
status | pending - The transaction is awaiting payment. |
transactionPaymentUrl | URL to redirect the payer to. |
Example response:
{ "result": "success", "requestId": "858fa92dc62db44e2c1f", "transactionId": "ta_9jQLGqzeY2eOVK01", "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 autohrization. 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:
card_token | Card token, use it for subsequent transactions. |
token_expiry_date | Token expiry date in the format MMYY. Present only if the token has an expiry date. |
card_tail | The last 4 digits of the tokenized card number. |
card_brand | The brand of the tokenized card. Possible values are Visa or Mastercard. |
Tokenization without charging
Tokenization without charging the payer's card is a method of storing the card where the payer provides the card number to go through the token issuance process. In this process, we authenticate the payer using 3D Secure (3DS) but do not charge the payer's account any amount. At the end of hte process we provide you with the payment token.
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
Check the details in the API Reference documentation: POST /tokens
In the request, specify the following parameters:
payer.email | Payer's email address. |
payer.name | Payer's name and surname. |
callbackUrl | The endpoint address to which we will send the tokenization status information. |
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:
result | success - Tokenization was successfully created. |
id | Tokenization identifier. |
url | URL to redirect the payer to in order to complete the tokenization process. |
Example response:
Store the id parameter in your system.
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 token will be issued. Otherwise, the tokenization process is aborted.
Payer will be redirected to success or error page
Once the card details are saved, the payer will be redirected to a success page or error page depending on whether the tokenization was successful or not.
Handle notification
We will notify you of the tokenization status at the tokenization webhook address you provided in the request body (callbackUrl). Check details..
Tokenization Plus
Tokenization Plus is a program 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: scheme token, Visa token, or Mastercard token.
Through the Tokenization Plus service, Tpay will use the network token for transaction processing instead of the original card data.
The main advantage of a network token is that if the tokenized card expires and the cardholder receives a new one, the network token is automatically updated, 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 notification, enabling them to contact the payer and ensure payment continuity if needed.
As part of the Tokenization Plus program, we also provide the card image (CardArt) and notify your system of any updates to the card, such as expiration, removal, or changes to the card image.
The Tokenization Plus method is currently only available for the Elavon acquirer. Check if your card payments are processed through the Elavon acquirer.
Token creation
You can create a token by implementing:
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
After sending the request, you will receive a GetToken schema in response.
Response parameters:
expirationDate | Card expiration date in the format MMRR |
tokenStatus | Token status (ACTIVE, DELETED, SUSPENDED). |
cardTail | The last 4 digits of the card number |
cardImage | URL with the card image |
Sample response:
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.
The token deletion process is asynchronous.
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 card image.
The URL to which we will send the status change notification is the callbackUrl, parameter provided during the creation of the payment token.
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.