> ## 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 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 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 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 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. 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: ```json theme={null} { "type": "Card", "isoAmount": 1000, "currency": "EUR", "orderRef": "ORDER-001", "card": { "tokenId": "ecf4a873-59fd-4300-a6e6-330d267ebbb2" } } ``` Alternatively, pay using a `customReference`: ```json theme={null} { "type": "Card", "isoAmount": 1000, "currency": "EUR", "orderRef": "ORDER-001", "card": { "customReference": "CUSTOMER-42" } } ``` ## Managing tokens ### Get token by tokenId ```bash 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 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 theme={null} curl --request GET \ --url 'https://gateway.paybyrd.com/api/v2/tokens?customReference=CUSTOMER-42' \ --header 'x-api-key: {your_api_key}' ``` ```json 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.