Skip to main content
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

  1. The customer enters card details once (via Card Collect or Checkout)
  2. Paybyrd authenticates the cardholder, verifies the card, and stores it securely
  3. Paybyrd returns a tokenId or stores the token against a customReference you define
  4. 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:
  1. You send a token creation request with card data
  2. Paybyrd triggers 3DS authentication for the cardholder
  3. After successful authentication, Paybyrd runs a zero-amount card verification
  4. The card data is stored securely and a token is generated
  5. 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. Checkout tokenization flow

​
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. Checkout payment with token flow

​
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.