> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paybyrd.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 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
1. The customer enters card details once (via [Card Collect](/embed/card-collect) or [Checkout](/embed/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`
```bash Create token request theme={null}
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"
}'
```
```json Response theme={null}
{
"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](/embed/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](/embed/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.
```bash Create payment with tokenization highlight={18-22} theme={null}
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"
}
}
}'
```
```json Response theme={null}
{
"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` or a `customReference` in place of card details:
```json Using tokenId highlight={7} theme={null}
{
"type": "Card",
"isoAmount": 1000,
"currency": "EUR",
"orderRef": "ORDER-001",
"card": {
"tokenId": "ecf4a873-59fd-4300-a6e6-330d267ebbb2"
}
}
```
```json Using customReference highlight={7} theme={null}
{
"type": "Card",
"isoAmount": 1000,
"currency": "EUR",
"orderRef": "ORDER-001",
"card": {
"customReference": "CUSTOMER-42"
}
}
```
## Managing tokens
### Get token by tokenId
```bash Retrieve token using tokenID theme={null}
curl --request GET \
--url https://gateway.paybyrd.com/api/v2/tokens/2349c7fd-3f1b-4188-b98e-3dcead913ef6 \
--header 'x-api-key: {your_api_key}'
```
```json Response theme={null}
{
"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.
```bash Return all tokens for a customer reference theme={null}
curl --request GET \
--url 'https://gateway.paybyrd.com/api/v2/tokens?customReference=CUSTOMER-42' \
--header 'x-api-key: {your_api_key}'
```
```json Response theme={null}
{
"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.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.