Guides

Tokenization

Learn about tokenization and how to manage your tokens.

Suggest Edits

Tokenization is the process of protecting sensitive payment data by replacing it with another value called a token. These tokens can then been used to process the payment without actual bank details being exposed. The actual primary account number (PAN) is held safe in a secure token vault.

Card tokenization

How is card tokenization put to use in the payments industry?

  1. The first is when businesses keep your “card on file” for subscription billing and recurring payments.
  2. The second is on eCommerce sites that offer frequent, returning customers “one-click” checkouts.

Tokens API server-side

The Paybyrd's tokens API offers you a way to manage tokens that will facilitate the payment experience.
All the tokens requests should be addressed to the endpoint /api/v2/tokens.

Create a card token

The tokenization process is basically performed in 5 steps:

  1. API request with card data and custom information
  2. Card holder authentication on 3DS
  3. Card verification (zero auth)
  4. Card data securily stored and token generation
  5. Confirmation

On the first step you will create a new token providing all the necessary information for the next steps. Paybyrd will trigger the 3D Secure authentication by default. Once the authentication is performed successfully by the card holder, the card verification will occur automatically. For that, you must provide the parameter RedirectUrl. Paybyrd will use this URL to redirect the customer in the end of the whole process. You can also use this page to query the token status and take the shopper to the page you want.

You can see below an example of how to create a new token triggering the 3D Secure flow which will be fully managed by Paybyrd:

curl --request POST \
--url https://gateway.paybyrd.com/api/v2/tokens \
--header 'X-Api-Key: 5E37D19C-F99C-445F-8B77-1463EFC66C7B' \
--header 'Content-Type: application/json' \
--data-raw '{
    "type": "card",
    "currency": "EUR",
    "card": {
        "number": "5277801257221511",
        "expiration": "06/26",
        "cvv": "123",
        "holder": "Peter Parker"
    },
    "customReference": "PeterP",
    "alias": "PeterCard",
    "redirectUrl": "https://www.paybyrd.com"
}'

{
    "currency": "EUR",
    "card": {
        "number": "527780******1511",
        "expiration": "06/26",
        "cvv": "**********************************",
        "holder": "Peter Parker"
    },
    "action": {
        "type": "redirect",
        "url": "https://link-s.paybyrd.com/3ds_Q44clBT77"
    },
    "transactionId": "cb503fa2-fb6e-45ba-a97f-0283cce5cc30",
    "tokenId": "2349c7fd-3f1b-4188-b98e-3dcead913ef6",
    "customReference": "PeterP",
    "alias": "PeterCard",
  	"code": "BYRD207",
    "description": "Pending redirect",
}

In order to know whether the token creation was accepted or not for both scenarios, you must check the code field. For successful scenarios the expected code is BYRD207 and the description is Pending redirect (codes list). That means an extra step has to be taken in order to complete de process. The action node contains what the next step is.

Some of our customers have their own 3D Secure provider and the card holder authentication is performed before calling Paybyrd's API. For that case you must provide the authentication data and Paybyrd will respond with code BYRD200 and no extra step is required.

📘

Info

The customReference field is a custom identifier that allows you to create a virtual wallet, being possible to store one or more tokens under it. Later on you can also query all the tokens associated with it.

That's all! The token was created! You can now use it when creating new payments by providing the generated tokenId.

Create payments with a token

Creating a new payment with a token is very simple. You just have to provide the tokenId and no card data is needed. Please see the example below:

curl --request POST \
--url https://gateway.paybyrd.com/api/v2/payment \
--header 'x-api-key: 5E37D19C-F99C-445F-8B77-1463EFC66C7B' \
--header 'Content-Type: application/json' \
--data-raw '{
     "type": "Card",
     "amount": "12.00",
     "currency": "EUR",
     "tokenId": "b01f4ae4-9671-4d19-b4c9-9eebcb64d08b"
}'

{
    "type": "Card",
    "currency": "EUR",
    "brand": "MASTER",
    "fingerprint": "281fd780-4949-4981-b702-37acf1ece998",
    "code": "BYRD200",
    "description": "Operation successfully completed",
    "transactionId": "209854cb-c071-44a0-850e-dfcb336c29b3",
    "amount": "12.00",
    "card": {
        "number": "900010******1111",
        "expiration": "12/25"
    }
}

Manage your tokens

Get token by tokenId

You can query your tokens by calling the tokens API with the tokenId as you can see in the example below:

curl
--request GET 'https://gateway.paybyrd.com/api/v2/tokens/2349c7fd-3f1b-4188-b98e-3dcead913ef6' \
--header 'X-Api-Key: 5E37D19C-F99C-445F-8B77-1463EFC66C7B'

{
    "tokenId": "2349c7fd-3f1b-4188-b98e-3dcead913ef6",
    "customReference": "PeterP",
    "alias": "PeterCard"
}

Get token by customReference

It's also possible to search your created tokens by customReference. In this endpoint, instead of only one token, the API will return all the created tokens with the passed customReference.

curl --location --request GET 'https://gatewaysandbox.paybyrd.com/api/v2/tokens?customReference=PeterP' \
--header 'X-Api-Key: 5E37D19C-F99C-445F-8B77-1463EFC66C7B'

{
    "pagination": {
        "pageNumber": 0,
        "pageSize": 10,
        "total": 1,
        "totalAvailable": 1,
        "returned": 1
    },
    "success": true,
    "data": [
        {
            "tokenId": "2349c7fd-3f1b-4188-b98e-3dcead913ef6",
            "customReference": "PeterP",
            "alias": "PeterCard"
        }
    ]
}

Tokenization on hosted form client-side

The hosted form shifts the responsability of dealing with the checkout payment experience to Paybyrd. Tokenization is also available if you use this feature, but it works slightly different from the server-sideintegration. The main differences are:

  • You will not call the api/v2/tokens API to create the token. Instead you will provide the tokenOptionsnode in the order creation request.
  • All the payment flow is handled by Paybyrd. We will collect the card data, trigger the 3D Secure authentication and complete the payment.
  • A notification will be sent to you when the process is completed.

📘

Hosted form

If you wish to know more about the hosted form integration, please check Hosted form section.

Create token

To create a token using our checkout page, first you need to create an order and provide the customReference field. Paybyrd will respond with the order data and the checkout URL, that leads to our checkout page, where customers will provide the card information. On this page, they will find a checkbox to authorize the tokenization process during the payment.

Once the card holder clicks on pay, we will do the 3DS Auth and then create the payment. As long as the payment is approved, you will receive the webhook with the created token. If you don't receive the webhook, it's possible to query the token from customReference using the Tokens API.

Here you can find a create order request and response:

curl --location --request POST 'https://gateway.paybyrd.com/api/v2/orders' \
--header 'Content-Type: application/json' \
--header 'X-Api-Key: 5E37D19C-F99C-445F-8B77-1463EFC66C7B' \
--data-raw '{
    "amount": "100.00",
    "orderRef": "OrderReference",
    "currency": "EUR",
    "shopper": {
        "email": "[email protected]",
        "firstName": "Dear",
        "lastName": "Customer",
        "phoneCountryCode": 351,
        "phoneNumber": "999888777"
    },
    "orderOptions": {
        "redirectUrl": "https://redirect.url"
    },
    "paymentOptions": {
        "tokenOptions": {
            "customReference": "custom_wallet_aggregate"
        }
    },
    "code": "order_code",
    "description": "order_description"
}'

{
    "orderDate": "2022-03-08T18:15:52Z",
    "status": "created",
    "checkoutUrl": "https://link.paybyrd.com/chk_d1OSV7s2N",
    "index": 1,
    "transactions": [],
    "orderId": "5d46449e-d3d8-41ce-af56-5fb74313beb2",
    "amount": "100.00",
    "currency": "EUR",
    "orderRef": "OrderReference",
    "shopper": {
        "shopperId": "9de838ff-594a-44eb-baf7-a8dd34ae959d",
        "email": "m***********[email protected]",
        "firstName": "D**r",
        "lastName": "C*****r",
        "phoneCountryCode": 3*1,
        "phoneNumber": "99*******77",
        "shippingType": "Undefined"
    },
    "orderOptions": {
        "redirectUrl": "https://redirect.url",
        "culture": "en-US"
    },
    "paymentOptions": {
        "useSimulated": false,
        "cardOptions": {
            "isPreAuth": false
        },
        "tokenOptions": {
            "customReference": "custom_wallet_aggregate"
        }
    },
    "terminalOptions": {
        "notifyChanges": false
    },
    "code": "BYRD200",
    "description": "Operation successfully completed",
    "tags": 0,
    "checkoutKey": "eyJMaXZlIjpmYWxzZSwiUGVyc29uSWQiOjEwLCJBbW91bnQiOiIxMDAuMDAiLCJDdXJyZW5jeSI6IkVVUiIsIk9yZGVyUmVmIjoiT1JEMTIzIiwiT3JkZXJJZCI6IjVkNDY0NDllLWQzZDgtNDFjZS1hZjU2LTVmYjc0MzEzYmViMiJ9"
}

Use the token

To use a token during the checkout, you will have to create an order providing the customReference which was created in the previous step.

🚧

CustomReference Validation

The customReference is optional in order creation. If informed, make sure that token customReference is equal to order customReference. Otherwise, the payment will fail.

Inside the create response, you will find a checkout URL, that leads to our checkout page, where, as long as the given customReference has some token related to it, we will try to use it during the payment.

But, for security matters, two-factor authentication will always happen. We will send a code to customer's email and phone number to avoid fraud. Then, we will validate the code and try to create the payment.

📘

Two-factor authentication

The two-factor authentication make use of the Time-based One-Time Password

Updated about 2 years ago