Tokenization

Tokenization replaces sensitive card data with a reusable token. Tokens support one-click payments, subscriptions, and recurring charges without storing raw card numbers on your servers.

How it works

The customer enters card details once (via Card Collect or Checkout)
Paybyrd authenticates the cardholder, verifies the card, and stores it securely
Paybyrd returns a tokenId or stores the token against a customReference you define
On future payments, pass the tokenId or customReference instead of card details

Server-side tokenization

Create a token by calling the tokens endpoint directly from your backend. Token creation runs in five steps:

You send a token creation request with card data
Paybyrd triggers 3DS authentication for the cardholder
After successful authentication, Paybyrd runs a zero-amount card verification
The card data is stored securely and a token is generated
Paybyrd redirects the customer to your redirectUrl

curl --request POST \
  --url https://gateway.paybyrd.com/api/v2/tokens \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: {your_api_key}' \
  --data '{
    "card": {
      "number": "4111111111111111",
      "expiration": "12/30",
      "cvv": "123",
      "holder": "Jane Doe"
    },
    "customReference": "CUSTOMER-42",
    "alias": "Main card",
    "redirectUrl": "https://your-site.com/tokenization-complete"
  }'

{
  "card": {
    "number": "411111******1111",
    "expiration": "12/30",
    "cvv": "**********************************",
    "holder": "Jane Doe"
  },
  "action": {
    "type": "redirect",
    "url": "https://link.paybyrd.com/3ds_yvLu4cxe8"
  },
  "transactionId": "cb503fa2-fb6e-45ba-a97f-0283cce5cc30",
  "tokenId": "2349c7fd-3f1b-4188-b98e-3dcead913ef6",
  "customReference": "CUSTOMER-42",
  "alias": "Main card",
  "code": "BYRD207",
  "description": "Pending redirect"
}

Always tokenize from your backend — never from client-side JavaScript with raw card data.

The initial response returns code BYRD207 (pending redirect). Provide a redirectUrl in your request so the customer can be redirected back after 3DS authentication completes. The customReference field acts as a virtual wallet identifier — multiple tokens can be stored under the same reference and queried together later. The alias field is an optional human-readable label for the token.

Client-side tokenization with Card Collect

Use the Card Collect library to collect card details in a PCI-compliant iframe and receive a tokenId client-side, which you then send to your backend.

Checkout tokenization

When using Checkout, tokenization is triggered through the order creation request and handled automatically by Paybyrd.

Create a token via Checkout

Include tokenOptions.customReference in your order creation request. During the payment flow, the customer sees a checkbox to consent to saving their card.

curl --request POST \
  --url https://gateway.paybyrd.com/api/v2/orders \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: {your_api_key}' \
  --data '{
    "amount": "100.00",
    "orderRef": "ORDER-001",
    "currency": "EUR",
    "shopper": {
      "email": "customer@example.com",
      "firstName": "Jane",
      "lastName": "Doe"
    },
    "orderOptions": {
      "redirectUrl": "https://your-site.com/order-complete"
    },
    "paymentOptions": {
      "tokenOptions": {
        "customReference": "CUSTOMER-42"
      }
    }
  }'

{
  "orderId": "5d46449e-d3d8-41ce-af56-5fb74313beb2",
  "status": "created",
  "checkoutUrl": "https://link.paybyrd.com/chk_d1OSV7s2N",
  "amount": "100.00",
  "currency": "EUR",
  "orderRef": "ORDER-001",
  "paymentOptions": {
    "tokenOptions": {
      "customReference": "CUSTOMER-42"
    }
  },
  "code": "BYRD200",
  "description": "Operation successfully completed"
}

If the customer consents and the payment is approved, Paybyrd delivers the token details via webhook. If the webhook is not received, query the token by customReference using the tokens API. The Checkout handles card collection, 3DS authentication, and payment completion — no direct calls to the tokens endpoint are needed.

Use a token via Checkout

To use a saved token in a subsequent Checkout payment, create an order with the same customReference used during token creation. The Checkout page will display the saved card to the customer.

The customReference in the order must match the customReference used during tokenization. If they differ, the payment will fail.

For security, Paybyrd requires two-factor authentication before charging a saved card. A one-time code is sent to the customer’s email and phone number.

Using a token for payment

Pass the tokenId in place of card details:

{
  "type": "Card",
  "isoAmount": 1000,
  "currency": "EUR",
  "orderRef": "ORDER-001",
  "card": {
    "tokenId": "ecf4a873-59fd-4300-a6e6-330d267ebbb2"
  }
}

Alternatively, pay using a customReference:

{
  "type": "Card",
  "isoAmount": 1000,
  "currency": "EUR",
  "orderRef": "ORDER-001",
  "card": {
    "customReference": "CUSTOMER-42"
  }
}

Managing tokens

Get token by tokenId

curl --request GET \
  --url https://gateway.paybyrd.com/api/v2/tokens/2349c7fd-3f1b-4188-b98e-3dcead913ef6 \
  --header 'x-api-key: {your_api_key}'

{
  "tokenId": "2349c7fd-3f1b-4188-b98e-3dcead913ef6",
  "customReference": "CUSTOMER-42",
  "alias": "Main card"
}

Get tokens by customReference

Returns all tokens stored under the same customReference, with paginated results.

curl --request GET \
  --url 'https://gateway.paybyrd.com/api/v2/tokens?customReference=CUSTOMER-42' \
  --header 'x-api-key: {your_api_key}'

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

Security considerations

Tokens are bound to your API key and cannot be used by other merchants.
CVV is never stored and is not required for subsequent tokenized payments (subject to payment method rules).
3DS may still be triggered on tokenized payments depending on issuer and transaction risk.

Get Started

Advanced

How it works

Server-side tokenization

Client-side tokenization with Card Collect

Checkout tokenization

Create a token via Checkout

Use a token via Checkout

Using a token for payment

Managing tokens

Get token by tokenId

Get tokens by customReference

Security considerations

​How it works

​Server-side tokenization

​Client-side tokenization with Card Collect

​Checkout tokenization

​Create a token via Checkout

​Use a token via Checkout

​Using a token for payment

​Managing tokens

​Get token by tokenId

​Get tokens by customReference

​Security considerations

How it works

Server-side tokenization

Client-side tokenization with Card Collect

Checkout tokenization

Create a token via Checkout

Use a token via Checkout

Using a token for payment

Managing tokens

Get token by tokenId

Get tokens by customReference

Security considerations