# 3DS Merchant Setup
Source: https://developers.pcibooking.net/account-setup/3ds-merchant-setup

Configure 3D Secure merchant settings in PCI Booking. MPI credentials, 3DS2 support, and card scheme enrollment.

3D Secure authentication requires merchant information to be presented to the cardholder during the challenge screen. By default, PCI Booking provides its own merchant details, meaning the cardholder sees "PCI Booking" as the merchant name during the 3DS challenge. To display your own merchant name instead, you can provide your merchant details to PCI Booking.

## How It Works

When a 3DS challenge is triggered during card capture, the card network displays merchant information to the cardholder. This information helps the cardholder recognize the transaction and reduces false declines.

If you do not provide your own merchant details, PCI Booking's default merchant information is used. With the default configuration, 3DS authentication is limited to Visa and Mastercard cards only.

## Three Scenarios

### You only collect cards

You capture card details on behalf of another entity (e.g. an OTA collecting cards for a hotel), and payment processing happens outside PCI Booking. No additional configuration is needed. PCI Booking's default merchant information is used for the 3DS challenge.

### You collect and charge directly

You capture card details and process payments directly as the merchant (e.g. an online retailer). Submit your merchant information through the [3DS merchant information form](https://pcibooking.net/3d-secure-merchant-information-required/) to replace PCI Booking's default details with yours. The cardholder will see your merchant name during the 3DS challenge.

### You collect and charge on behalf of multiple merchants

You capture cards and process payments for multiple different merchants (e.g. a PMS provider serving multiple hotels). Each merchant needs its own 3DS merchant details.

1. Download the [merchant information spreadsheet template](https://pcibooking.net/wp-content/uploads/2023/06/3DS-merchant-data.xlsx).
2. Fill in the merchant details for each of your merchants.
3. Submit the completed spreadsheet to [support@pcibooking.net](mailto:support@pcibooking.net).
4. When generating a card capture form, include the `merchantName` parameter to specify which merchant's 3DS details to use for that transaction.

## What Information Is Needed

The data falls into three categories:

* **Merchant identity**. Business name (as displayed to the cardholder during the 3DS challenge), website URL, and country.
* **Acquirer details**. The acquiring bank name, plus per-card-network identifiers: Acquirer BIN, Merchant ID (MID), and Merchant Category Code (MCC). Only provide these for the card networks you process (Visa, Mastercard, American Express, Discover).
* **Reference**. A unique identifier for each merchant, used to match the `merchantName` parameter in your API calls.

For a single merchant, submit via the [online form](https://pcibooking.net/3d-secure-merchant-information-required/). For multiple merchants, download the [spreadsheet template](https://pcibooking.net/wp-content/uploads/2023/06/3DS-merchant-data.xlsx), fill in one row per merchant, and send to [support@pcibooking.net](mailto:support@pcibooking.net).

## Next Steps

<CardGroup>
  <Card title="Hosted Card Entry Form" icon="book" href="/capture-cards/hosted-card-entry-form">
    Card capture with 3DS support
  </Card>

  <Card title="Card By Link" icon="book" href="/capture-cards/card-by-link">
    Remote card capture with 3DS support
  </Card>

  <Card title="3DS Auth Management" icon="book" href="/manage-tokens/3ds-auth-management">
    Manage stored 3DS authentication data
  </Card>
</CardGroup>


# Apple Pay Setup
Source: https://developers.pcibooking.net/account-setup/applepay-setup

Configure Apple Pay with PCI Booking. Certificate generation, merchant ID registration, and domain verification.

**Requires:** [Apple Developer Program](https://developer.apple.com/programs/) membership (\$99/year).

Apple Pay setup involves creating a Merchant ID, verifying your domain, and generating two certificates in the Apple Developer Portal.

## 1. Create a Merchant ID

A Merchant ID identifies you as a merchant who can accept payments via Apple Pay.

1. Sign in to your [Apple Developer Account](https://developer.apple.com/account/).
2. Go to **Certificates, Identifiers & Profiles** > **Identifiers**.
3. Click **+** to add a new identifier.
4. Select **Merchant IDs**.
5. Enter a **description** and a **unique identifier** (e.g. `merchant.com.example.yourbusiness`).
6. Click **Continue**, review, and **Register**.

## 2. Verify Your Domain

Apple requires your domain to be verified before Apple Pay can be used on it.

1. Go back to your **Merchant ID** page in the developer portal.
2. Under your Merchant ID, click **Edit** and then **Verify Your Domain**.
3. Enter the domain name (e.g. `example.com`).
4. Download the **Apple Pay Verification File** (`apple-developer-merchantid-domain-association`).
5. Upload the file to the `.well-known` directory on your domain. The full URL should be: `https://yourdomain.com/.well-known/apple-developer-merchantid-domain-association`
6. Return to the Apple Developer Portal and click **Verify**.

<Warning>
  The file must be served over HTTPS without redirects. Download the file only once. Repeated downloads generate new content.
</Warning>

## 3. Create Payment Processing Certificate

This certificate is used to handle payment data securely.

1. Generate a Certificate Signing Request (CSR):

```bash theme={null}
openssl ecparam -genkey -name prime256v1 -out ~/mykey.key -noout
openssl req -new -sha256 -key ~/mykey.key -out ~/request.csr -subj /CN=www.mydomain.com
```

2. In the Apple Developer Portal, select your **Merchant ID**.
3. Under **Apple Pay Payment Processing Certificate**, click **Create Certificate**.
4. Upload your `request.csr`.
5. Download the certificate (`apple_pay.cer`).
6. Convert to PEM:

```bash theme={null}
openssl x509 -inform DER -in ~/apple_pay.cer -out ~/apple_pay.pem
```

## 4. Create Merchant Identity Certificate

This certificate allows your server to authenticate itself to Apple's servers.

1. Generate a CSR and key file:

```bash theme={null}
openssl req -out ~/uploadMe.csr -new -newkey rsa:2048 -nodes -keyout ~/clientCertificate.key
```

<Info>
  In the prompt, enter your details. The **Common Name** should match the one used in the previous step. When asked for a password, leave it blank and press Enter.
</Info>

2. In the Apple Developer Portal, select your **Merchant ID**.
3. Under **Apple Pay Merchant Identity Certificate**, click **Create Certificate**.
4. Upload your `uploadMe.csr`.
5. Download the certificate (`merchant_id.cer`).
6. Convert to PEM:

```bash theme={null}
openssl x509 -inform der -in ~/merchant_id.cer -out ~/clientCertificate.pem
```

## 5. Store in PCI Booking

After completing the steps above, you should have these files:

| File                    | Generated In |
| ----------------------- | ------------ |
| `mykey.key`             | Step 3       |
| `apple_pay.pem`         | Step 3       |
| `clientCertificate.key` | Step 4       |
| `clientCertificate.pem` | Step 4       |

When creating the eWallet account in PCI Booking, provide:

| Field                                   | Value                                                                            |
| --------------------------------------- | -------------------------------------------------------------------------------- |
| **eWallet Type**                        | ApplePay                                                                         |
| **Merchant Identifier**                 | Your Apple Merchant ID (e.g. `merchant.com.example.yourbusiness`)                |
| **Merchant Display Name**               | Name shown to payers                                                             |
| **Domain Name**                         | Domain where Apple Pay button is hosted (must match the CN in your certificates) |
| **Client Certificate PEM**              | Contents of `clientCertificate.pem`                                              |
| **Client Certificate Private Key PEM**  | Contents of `clientCertificate.key`                                              |
| **Payment Certificate Private Key PEM** | Contents of `mykey.key`                                                          |
| **Payment Certificate PEM**             | Contents of `apple_pay.pem`                                                      |

## Testing

Use [Apple Pay Sandbox](https://developer.apple.com/apple-pay/sandbox-testing/) with test cards in Safari on macOS or iOS.

## Next Steps

<CardGroup>
  <Card title="Payments Library Credentials" icon="book" href="/account-setup/payments-library-credentials">
    Overview of all payment method credentials
  </Card>

  <Card title="Payments Library Overview" icon="book" href="/payments-library/overview">
    Integrate the library in your checkout page
  </Card>
</CardGroup>


# BankPay Setup
Source: https://developers.pcibooking.net/account-setup/bankpay-setup

Configure BankPay (open banking) payments in PCI Booking. Account setup and testing.

BankPay enables customers to pay directly from their bank account via Open Banking. Instead of entering card details, the customer selects their bank from a list, authenticates with their banking credentials, and authorizes the payment. Funds move directly from the customer's bank account to your designated recipient account.

Through PCI Booking's [Payments Library](/payments-library/overview), you can offer BankPay alongside card payments and other methods on the same checkout page.

## How BankPay Works with PCI Booking

When a customer selects BankPay at checkout, the Payments Library presents a bank selection screen. The customer chooses their bank, is redirected to their bank's authentication page, and authorizes the payment. Once authorized, the payment is processed and PCI Booking notifies your system. No card data or banking credentials pass through your servers.

BankPay supports **CHARGE** operations only. Tokenization and 3D Secure are not applicable to BankPay transactions.

## Prerequisites

* A PCI Booking merchant account with BankPay enabled
* A bank account with a valid IBAN and BIC/SWIFT code to receive funds
* Coordination with PCI Booking to configure your Open Banking provider

## Setup

BankPay setup requires coordination with the PCI Booking team. Contact [support@pcibooking.net](mailto:support@pcibooking.net) to get started. Our team will guide you through account eligibility, provider configuration, and testing.

## Store in PCI Booking

Once configured, create an eWallet account in PCI Booking with:

| Field                     | Description                                      | Required |
| ------------------------- | ------------------------------------------------ | -------- |
| **eWallet Type**          | BankPay                                          | Yes      |
| **Merchant Identifier**   | Unique identifier for your merchant account      | Yes      |
| **Merchant Display Name** | Business name shown during bank selection        | Yes      |
| **Recipient Bank IBAN**   | Your bank account IBAN where funds are deposited | Yes      |
| **Recipient Bank BIC**    | BIC/SWIFT code for your recipient bank account   | Yes      |

You can store credentials through the [PCI Booking portal](https://users.pcibooking.net) or programmatically via the [Store Credentials API](/api-reference/payments-library-accounts/store-credentials).

## Testing

Contact the PCI Booking team to receive sandbox credentials for BankPay testing. In sandbox mode, you can simulate bank selection and authorization without processing real payments, allowing you to verify the full flow before going live.

<Info>
  BankPay is available for charge operations only. It does not support tokenization, pre-authorization, or 3D Secure flows.
</Info>

## Next Steps

<CardGroup>
  <Card title="Payments Library Credentials" icon="book" href="/account-setup/payments-library-credentials">
    Overview of all payment method credentials
  </Card>

  <Card title="Payments Library Overview" icon="book" href="/payments-library/overview">
    Integrate the library in your checkout page
  </Card>
</CardGroup>


# Card By Link Templates
Source: https://developers.pcibooking.net/account-setup/card-by-link-templates

Customize email and SMS templates for Card by Link requests. Branding, language, and content configuration.

When sending a [Card By Link](/capture-cards/card-by-link) request, PCI Booking sends an email or SMS to the cardholder with a link to a card capture page. You can customize the content of these messages and the landing page through the portal. This lets you create a fully branded experience for your cardholders, from the initial notification through the card entry form.

## Template Types

PCI Booking provides three template types that you can customize independently:

| Template               | Purpose                                                                     | Character Limit                              |
| ---------------------- | --------------------------------------------------------------------------- | -------------------------------------------- |
| **Email**              | Full email sent to the cardholder with a link to the card capture page      | No fixed limit                               |
| **Text Message (SMS)** | Short SMS message with a link to the card capture page                      | 117 characters (link appended automatically) |
| **Landing Page**       | The hosted card capture page where the cardholder enters their card details | No fixed limit                               |

Each template type supports multiple languages. You specify the language in the [Card By Link API request](/api-reference/tokenize-cards/cotp-send-card-form), and PCI Booking uses the matching template for that language.

## Dynamic Variables

Templates support dynamic variables that are replaced with actual values when the message is sent. Variable values are provided in the Card By Link API request. Common variables include the recipient's name, payment amount, currency, and a description of what the payment is for.

This allows a single template to serve many different transactions, with each message personalized to the specific cardholder and payment context.

## Access Template Settings

1. Log in to the [PCI Booking portal](https://users.pcibooking.net).
2. Navigate to **GUI Settings** > **Customization** > **Customize Templates**.

The page has three sections: email, text message, and landing page.

## Customize Email

1. In the **Customize Emails** section, select email type **Card Over The Phone**.
2. Choose the language to edit (you specify the language in the API request).
3. Edit the following fields:
   * **Subject** - the email subject line
   * **Message Body** - supports dynamic variables like recipient name, amount, description. Values are provided in the API request.
   * **Go to action button** - text for the button that links to the card capture page
4. Use **Preview** to see your changes.
5. Click **Set New Text** to save.

## Customize Text Message

1. In the **Customize Text Message** section, select the language to edit.
2. Edit the message text. Maximum 117 characters (including spaces and punctuation).
3. The link to the landing page is added automatically at the end.
4. Click **Set New Text** to save.

<Warning>
  Keep SMS messages concise. The 117-character limit includes spaces and punctuation. The secure link is appended automatically and does not count toward this limit.
</Warning>

## Customize Landing Page

1. In the **Customize Landing Page** section, select the language to edit.
2. Edit the following sections:
   * **Header** - text above the card form. Supports dynamic variables.
   * **Card Capture Title** - title text above the card form fields.
   * **Footer** - text below the card form. Supports dynamic variables.
3. Use **Preview** to see your changes.
4. Click **Set New Text** to save.

<Info>
  You can send custom header and footer values in the Card By Link API request. If provided, these override the template values set in the portal. This is useful when different transactions require different messaging without changing the default template.
</Info>

## Branding Tips

For a fully branded cardholder experience, combine template customization with [white-label email](/account-setup/white-label-email) configuration. This ensures the email sender address, message content, and card capture page all reflect your brand rather than PCI Booking's.


# Client Certificates
Source: https://developers.pcibooking.net/account-setup/client-certificates

Upload client certificates for mutual TLS authentication when PCI Booking connects to your payment gateway.

Some third parties require certificate-based authentication (mutual TLS) when connecting to their APIs. PCI Booking can present a client certificate on your behalf when forwarding requests via [Token Replacement in Request](/use-tokens/token-replacement-in-request) or [Tokenization on Response](/capture-cards/tokenization-on-response).

Upload your certificates to PCI Booking, then reference them by name in your [target profiles](/account-setup/target-profiles).

## Uploading a Certificate

1. Log in to the [PCI Booking portal](https://users.pcibooking.net).
2. Navigate to **PCI Shield Settings** > **Client Certificate**.
3. Provide the following:

| Field                     | Description                                                                   |
| ------------------------- | ----------------------------------------------------------------------------- |
| **Certificate file**      | The certificate file in `.cer` or `.pfx` format.                              |
| **Certificate name**      | A reference name you will use when configuring profiles and gateway requests. |
| **Installation password** | The password associated with the certificate file.                            |

4. Submit. The certificate appears in your list and is available for use across your account.

## Managing Certificates

From the same screen you can view all uploaded certificates and delete any that are no longer needed.

## Where Certificates Are Used

* **[Target Profiles](/account-setup/target-profiles)**. Assign a client certificate to a profile for mutual TLS with a specific third party.
* **[Universal Payment Gateway](/use-tokens/universal-payment-gateway)**. Some PSPs require client certificates for API authentication.

## Next Steps

<CardGroup>
  <Card title="Target Profiles" icon="book" href="/account-setup/target-profiles">
    Configure profiles that use client certificates
  </Card>

  <Card title="Security Settings" icon="book" href="/account-setup/security-settings">
    Other account-level security configurations
  </Card>
</CardGroup>


# Content Filters
Source: https://developers.pcibooking.net/account-setup/content-filters

Define XML, JSON, form-encoded, and query string content filters that tell PCI Booking where card data fields are in your messages

A content filter is an XML configuration within a [target profile](/account-setup/target-profiles) that tells PCI Booking exactly where card data fields are located in a message. Content filters are used for both **tokenization** (extracting card data) and **token replacement** (injecting card data).

## Supported Message Formats

Content filters support four message formats. Set the `type` attribute on the `<transform>` element to match your message format.

| Format                | Type Value    | Selector Syntax | Description                              |
| --------------------- | ------------- | --------------- | ---------------------------------------- |
| **XML body**          | `body`        | XPath           | XML or SOAP message bodies               |
| **JSON body**         | `body`        | JSONPath        | JSON message bodies                      |
| **Form-encoded body** | `body`        | Field name      | `application/x-www-form-urlencoded` data |
| **URL query string**  | `querystring` | Parameter name  | Card data in URL query parameters        |

PCI Booking detects whether body content is XML, JSON, or form-encoded based on the content type header.

## Content Filter Structure

A content filter is an XML document with this general structure:

```xml theme={null}
<ContentDefinition>
  <transform type="body">
    <content selector="XPath or JSONPath to card block">
      <number selector="path/to/card/number" />
      <expYear selector="path/to/exp/year" />
      <expMonth selector="path/to/exp/month" />
      <securityCode selector="path/to/cvv" />
      <nameOnCard selector="path/to/name" />
      <type selector="path/to/card/type" />
    </content>
  </transform>
</ContentDefinition>
```

The `<content>` element's `selector` attribute points to the parent element containing card fields. Each child element then uses a relative selector to locate its specific field within that parent.

## Format Examples

<Tabs>
  <Tab title="XML Body">
    For XML messages, use XPath expressions. Use `local-name()` to match elements regardless of XML namespace prefix.

    **Tokenization filter** (extracting card data):

    ```xml theme={null}
    <ContentDefinition>
      <transform type="body">
        <content selector="//*[local-name()='PaymentCard']">
          <number selector="*[local-name()='CardNumber']" />
          <expYear selector="*[local-name()='ExpireDate']/@Year" format="YYYY" />
          <expMonth selector="*[local-name()='ExpireDate']/@Month" format="MM" />
          <nameOnCard selector="*[local-name()='CardHolderName']" />
          <securityCode selector="*[local-name()='SeriesCode']/@SeriesCode" />
          <type selector="@CardCode" />
        </content>
      </transform>
    </ContentDefinition>
    ```

    **Token replacement filter** (injecting card data):

    ```xml theme={null}
    <ContentDefinition>
      <transform type="body">
        <content selector="//*[local-name()='PaymentCard']">
          <number selector="*[local-name()='CardNumber']" />
          <expYear selector="*[local-name()='ExpireDate']/@Year" format="YYYY" />
          <expMonth selector="*[local-name()='ExpireDate']/@Month" format="MM" />
          <nameOnCard selector="*[local-name()='CardHolderName']" />
          <securityCode selector="*[local-name()='SeriesCode']/@SeriesCode" />
          <type selector="@CardCode">
            <list>
              <item key="VI" value="Visa" />
              <item key="MC" value="MasterCard" />
              <item key="AX" value="AMEX" />
              <item key="DC" value="DinersClub" />
              <item key="JC" value="JCB" />
            </list>
          </type>
        </content>
      </transform>
    </ContentDefinition>
    ```
  </Tab>

  <Tab title="JSON Body">
    For JSON messages, use JSONPath expressions.

    ```xml theme={null}
    <ContentDefinition>
      <transform type="body">
        <content selector="$..BankCard">
          <number selector="CardNo" />
          <expYear selector="ExpirationYear" format="YYYY" />
          <expMonth selector="ExpirationMonth" format="MM" />
          <nameOnCard selector="CardHolder" />
          <securityCode selector="CVV" />
          <type selector="CardType" />
        </content>
      </transform>
    </ContentDefinition>
    ```

    <Info>
      When working with JSON, you can use the `tryJsonNumber` attribute on numeric fields (`number`, `expYear`, `expMonth`, `issueNumber`, `type`) to output values as JSON numbers instead of strings.
    </Info>
  </Tab>

  <Tab title="Form-Encoded">
    For `application/x-www-form-urlencoded` data, selectors are the field names directly.

    ```xml theme={null}
    <ContentDefinition>
      <transform type="body">
        <content>
          <number selector="ccNumber" />
          <expYear selector="ccExpYear" format="YY" />
          <expMonth selector="ccExpMonth" format="M" />
          <nameOnCard selector="ccName" />
          <securityCode selector="ccCVV" />
        </content>
      </transform>
    </ContentDefinition>
    ```
  </Tab>

  <Tab title="Query String">
    For card data passed as URL query parameters, set `type="querystring"`.

    ```xml theme={null}
    <ContentDefinition>
      <transform type="querystring">
        <content>
          <number selector="cc" />
          <expYear selector="exp_year" format="YYYY" />
          <expMonth selector="exp_month" format="MM" />
          <securityCode selector="cvv" />
        </content>
      </transform>
    </ContentDefinition>
    ```
  </Tab>
</Tabs>

## Card Data Fields

Each `<content>` element can map the following card fields:

| Element          | Description                         | Attributes                                                          |
| ---------------- | ----------------------------------- | ------------------------------------------------------------------- |
| `<number>`       | Full card number (PAN)              | `selector`, `substring`, `dataSubstring`                            |
| `<expYear>`      | Expiration year                     | `selector`, `format` (`YYYY` or `YY`), `substring`, `dataSubstring` |
| `<expMonth>`     | Expiration month                    | `selector`, `format` (`MM` or `M`), `substring`, `dataSubstring`    |
| `<securityCode>` | CVV / CVC / CID                     | `selector`, `substring`, `dataSubstring`                            |
| `<nameOnCard>`   | Cardholder name                     | `selector`, `substring`, `dataSubstring`                            |
| `<type>`         | Card brand (Visa, MasterCard, etc.) | `selector`, child `<list>` for mapping                              |
| `<issueNumber>`  | Card issue number                   | `selector`                                                          |

### Format Attributes

The `format` attribute controls how date fields are read and written:

* **`expYear`**: `YYYY` (default, four digits) or `YY` (two digits)
* **`expMonth`**: `MM` (two digits with leading zero) or `M` (default, no leading zero)

### Substring Extraction

When a third party combines multiple values into a single field, use substring extraction to isolate the part you need.

* **`substring`** - extracts a portion of the value when **reading** from the message (tokenization). Format: `"startPosition"` or `"startPosition,length"` (zero-based).
* **`dataSubstring`** - extracts a portion of the replacement data when **writing** to the message (token replacement). Same format as `substring`.

Example: expiration date sent as `0125` (MMYY) in a single field:

```xml theme={null}
<expMonth selector="expDate" substring="0,2" format="MM" />
<expYear selector="expDate" substring="2,2" format="YY" />
```

### Card Type Mapping

When a third party uses different card type codes than PCI Booking, add a `<list>` child element to the `<type>` field to map between them.

```xml theme={null}
<type selector="@CardCode">
  <list>
    <item key="VI" value="Visa" />
    <item key="MC" value="MasterCard" />
    <item key="AX" value="AMEX" />
    <item key="DC" value="DinersClub" />
    <item key="DN" value="Dankort" />
    <item key="JC" value="JCB" />
    <item key="UP" value="UnionPay" />
  </list>
</type>
```

The `key` is the third party's code. The `value` is PCI Booking's card type name (see [Supported Card Types](/reference/card-types) for the full list).

## 3D Secure Fields

Content filters can also map 3DS authentication data alongside card fields. Add these as siblings to the card field elements inside `<content>`:

| Element          | Description                                    |
| ---------------- | ---------------------------------------------- |
| `<auth>`         | Authentication value (CAVV or AAV)             |
| `<eci>`          | Electronic Commerce Indicator                  |
| `<xid>`          | 3DS v1 transaction identifier                  |
| `<acs>`          | ACS Transaction ID (3DS v2)                    |
| `<version>`      | 3DS protocol version                           |
| `<merchantName>` | Merchant name used in the 3DS challenge        |
| `<sli>`          | Security Level Indicator (MasterCard-specific) |

Example with 3DS fields:

```xml theme={null}
<content selector="//*[local-name()='PaymentCard']">
  <number selector="*[local-name()='CardNumber']" />
  <expYear selector="*[local-name()='ExpireDate']/@Year" />
  <expMonth selector="*[local-name()='ExpireDate']/@Month" />
  <auth selector="*[local-name()='ThreeDSecure']/*[local-name()='AuthValue']" />
  <eci selector="*[local-name()='ThreeDSecure']/*[local-name()='ECI']" />
  <xid selector="*[local-name()='ThreeDSecure']/*[local-name()='XID']" />
</content>
```

## Multiple Cards in One Message

If a message contains multiple cards (e.g., a batch of reservations), add a `reservationSelector` attribute to the `<content>` element. This XPath expression identifies each repeating card block, and PCI Booking processes each one independently.

```xml theme={null}
<content selector="//*[local-name()='PaymentCard']"
         reservationSelector="//*[local-name()='Reservation']">
  <number selector="*[local-name()='CardNumber']" />
  <!-- other fields -->
</content>
```

PCI Booking iterates over every element matching `reservationSelector` and applies the card field selectors within each.

## Next Steps

<CardGroup>
  <Card title="Target Profiles" icon="book" href="/account-setup/target-profiles">
    Create and manage profiles that use content filters
  </Card>

  <Card title="Supported Card Types" icon="code" href="/reference/card-types">
    Full list of card type values for card type mapping
  </Card>

  <Card title="Tokenization on Response" icon="book" href="/capture-cards/tokenization-on-response">
    Tokenize card data from third-party responses
  </Card>

  <Card title="Token Replacement in Request" icon="book" href="/use-tokens/token-replacement-in-request">
    Replace tokens with real card data in outbound requests
  </Card>
</CardGroup>


# Custom Translations
Source: https://developers.pcibooking.net/account-setup/custom-translations

Translate PCI Booking hosted card forms into any language. Override default labels, placeholders, and error messages.

PCI Booking's card entry forms, card display pages, and error messages come with default text in English and several other languages. Custom translations let you override any of this text with your own wording or add support for additional languages.

## What Can Be Customized

All user-facing text rendered by PCI Booking can be customized per language:

* Form labels and placeholders (e.g. "Card Number", "Expiration Date")
* Validation and error messages
* Instructions and helper text
* Card type display names

## How It Works

PCI Booking uses a three-tier priority system for each text element:

1. **Your custom value** (highest priority). Text you provide for a specific language.
2. **System default in selected language**. PCI Booking's built-in translation for that language.
3. **System default in English** (fallback). Used when no translation exists for the selected language.

When rendering a form, PCI Booking checks for your custom value first. If none exists, it falls back to the system default for that language, then to English.

## Setting Up Translations

1. Log into the [PCI Booking portal](https://users.pcibooking.net).
2. Navigate to **GUI Settings** > **Language Settings**.
3. Select the target language from the dropdown.
4. The page displays all text elements with three columns: the English default, the system default for the selected language, and your custom value.
5. Enter your custom text in the "User Custom Value" field for any element you want to override.
6. Save your changes.

## Supported Languages

The following languages are supported across card entry forms, card display forms, CVV capture forms, and property emails. Pass the language code in the `Language` parameter when creating a form.

| Language            | Code | Direction |
| ------------------- | ---- | --------- |
| Afrikaans           | af   | LTR       |
| Arabic              | ar   | RTL       |
| Catalan             | ca   | LTR       |
| Chinese             | CN   | LTR       |
| Chinese (Taiwan)    | ct   | LTR       |
| Croatian            | hr   | LTR       |
| Czech               | cs   | LTR       |
| Danish              | da   | LTR       |
| Dutch               | NL   | LTR       |
| English             | EN   | LTR       |
| Estonian            | et   | LTR       |
| Finnish             | fi   | LTR       |
| French              | FR   | LTR       |
| German              | DE   | LTR       |
| Greek               | el   | LTR       |
| Hebrew              | HE   | RTL       |
| Hindi               | hi   | LTR       |
| Hungarian           | hu   | LTR       |
| Italian             | IT   | LTR       |
| Japanese            | JA   | LTR       |
| Korean              | ko   | LTR       |
| Latvian             | lv   | LTR       |
| Lithuanian          | lt   | LTR       |
| Norwegian           | no   | LTR       |
| Polish              | pl   | LTR       |
| Portuguese          | pt   | LTR       |
| Portuguese (Brazil) | pb   | LTR       |
| Russian             | ru   | LTR       |
| Slovak              | sk   | LTR       |
| Slovenian           | sl   | LTR       |
| Spanish             | ES   | LTR       |
| Swedish             | sv   | LTR       |
| Thai                | th   | LTR       |
| Turkish             | TR   | LTR       |
| Zulu                | zu   | LTR       |

<Info>
  Arabic and Hebrew use right-to-left (RTL) text direction. PCI Booking handles RTL layout automatically when these languages are selected.
</Info>

## Next Steps

<CardGroup>
  <Card title="Hosted Card Entry Form" icon="book" href="/capture-cards/hosted-card-entry-form">
    The card capture form where translations are displayed
  </Card>

  <Card title="Card Display" icon="book" href="/use-tokens/card-display">
    Card display pages that use the same translation system
  </Card>
</CardGroup>


# PSP Credentials
Source: https://developers.pcibooking.net/account-setup/gateway-credentials

Store payment gateway credentials in PCI Booking to process payments via the Universal Payment Gateway.

PSP credentials are your payment gateway account details (API keys, merchant IDs, terminal IDs, etc.) stored securely in PCI Booking. When you process payments through the [Universal Payment Gateway](/use-tokens/universal-payment-gateway), PCI Booking uses these stored credentials to authenticate with your PSP on your behalf.

Storing credentials in PCI Booking means your systems never need to hold or transmit sensitive PSP authentication details.

## What They Store

Each PSP requires different credential fields. A stored credential set includes:

* **PSP type**. Which payment processor (Stripe, Adyen, Worldpay, etc.).
* **Account credentials**. The PSP-specific authentication fields (API keys, merchant IDs, terminal IDs, passwords, etc.).
* **Credential ID**. A unique reference you assign when storing (typically combining the PSP name and a customer or merchant identifier).

## How to Use Stored Credentials

### Setup workflow

1. **Retrieve the credential structure** for your PSP. The API returns the exact fields required for that gateway, which you can use to build a collection form.
2. **Store your credentials** by submitting the required fields with a unique credential ID.
3. **Reference the credential ID** in your UPG requests using the `credentialsId` query parameter.

### API operations

| Operation                  | API Reference                                                                               | Description                                       |
| -------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------- |
| **Get available gateways** | [Get Payment Gateways](/api-reference/process-cards/get-payment-gateways)                   | List all supported PSPs                           |
| **Retrieve structure**     | [Retrieve Credential Structure](/api-reference/process-cards/retrieve-credential-structure) | Get required credential fields for a specific PSP |
| **Store**                  | [Store Credentials](/api-reference/process-cards/store-credentials)                         | Save your PSP credentials with a unique ID        |
| **List**                   | [List Credentials](/api-reference/process-cards/list-credentials)                           | View all stored credential sets for your account  |
| **Delete**                 | [Delete Credentials](/api-reference/process-cards/delete-credentials)                       | Remove a stored credential set                    |

<Warning>
  Stored credentials are encrypted at rest and never returned in full via the API. Only metadata (PSP name, credential ID) is returned when listing.
</Warning>

## Inline vs Stored Credentials

You can provide PSP credentials in two ways when making a UPG request:

* **Stored** (recommended). Pre-save credentials as described above and pass the `credentialsId` in your request. Keeps credentials out of your transaction code entirely.
* **Inline**. Include the PSP name and credential key-value pairs directly in the request body. Useful for testing or one-off transactions.

See [Universal Payment Gateway](/use-tokens/universal-payment-gateway#providing-psp-credentials) for details on both modes.

## Benefits

* **Security**. PSP credentials stored in PCI Booking's secure environment, not in your systems.
* **PSP portability**. Switch processors by creating new credentials and updating the ID in your requests. No code changes.
* **Multi-PSP support**. Store credentials for multiple PSPs and select which to use per transaction.
* **Same token, any PSP**. A single card token can be sent to any PSP by changing the credential ID.

## Next Steps

<CardGroup>
  <Card title="Universal Payment Gateway" icon="book" href="/use-tokens/universal-payment-gateway">
    Process payments using stored credentials
  </Card>

  <Card title="Charge" icon="book" href="/use-tokens/charge">
    Example requests with both inline and stored credentials
  </Card>

  <Card title="Gateway Guidance" icon="book" href="/use-tokens/gateway-guidance">
    PSP-specific parameter requirements
  </Card>

  <Card title="Credential Management API Reference" icon="code" href="/api-reference/process-cards/retrieve-credential-structure">
    Full API documentation
  </Card>
</CardGroup>


# Google Pay Setup
Source: https://developers.pcibooking.net/account-setup/googlepay-setup

Configure Google Pay with PCI Booking. Merchant ID setup and integration options.

Google Pay lets customers pay using cards stored in their Google account. When a customer clicks the Google Pay button on your checkout page, they select a stored card from their Google account, authenticate if required, and the payment is processed without the customer manually entering card details.

Through PCI Booking's [Payments Library](/payments-library/overview), Google Pay is offered alongside card payments, Apple Pay, PayPal, and other methods on the same checkout page.

## How Google Pay Works with PCI Booking

When a customer selects Google Pay at checkout, the Payments Library displays the native Google Pay payment sheet. The customer chooses a payment method from their Google account and authorizes the transaction. PCI Booking receives encrypted payment data from Google and processes it securely. No card data passes through your servers.

Google Pay supports all operations: **CHARGE**, **TOKENIZE**, **CHARGE\_AND\_TOKENIZE**, **PREAUTH\_AND\_TOKENIZE**, and **GATEWAY\_TOKENIZE**. 3D Secure is handled natively by Google Pay.

**Browser support:** Chrome on Android and desktop Chrome with a linked Google account.

## Prerequisites

* A Google account with access to the [Google Pay & Wallet Console](https://pay.google.com/business/console/)
* A PCI Booking merchant account

## 1. Create a Business Profile

1. Go to the [Google Pay & Wallet Console](https://pay.google.com/business/console/).
2. Sign in with your Google account.
3. Complete the business profile setup, including your business name, address, and website.

## 2. Register Your Website

1. Add your website URL in the console.
2. Select your integration type (gateway integration is used with PCI Booking).
3. Submit for approval. Google reviews your website and integration before granting production access.

## 3. Get Your Merchant ID

After Google approves your integration, you receive a **Merchant ID**. This is required for production.

<Info>
  You can test without a Merchant ID using Google's test environment. The Merchant ID is only required for production.
</Info>

## 4. Store in PCI Booking

Create an eWallet account in PCI Booking with:

| Field                     | Description                                                      | Required |
| ------------------------- | ---------------------------------------------------------------- | -------- |
| **eWallet Type**          | GooglePay                                                        | Yes      |
| **Merchant Identifier**   | Your Google Pay Merchant ID from the Google Pay Business Console | Yes      |
| **Merchant Display Name** | Business name shown in the Google Pay payment sheet              | Yes      |

You can store credentials through the [PCI Booking portal](https://users.pcibooking.net) or programmatically via the [Store Credentials API](/api-reference/payments-library-accounts/store-credentials).

## Testing

You can test Google Pay without a production Merchant ID. In test mode, the Google Pay payment sheet shows test cards that do not process real payments. Once your integration is approved and you have a Merchant ID, switch to production mode to accept real payments.

<Warning>
  Google Pay buttons only appear when the Payments Library detects a compatible browser and a Google account with saved payment methods. Use `checkAvailability()` in the Payments Library to verify support before rendering the button.
</Warning>

## Next Steps

<CardGroup>
  <Card title="Payments Library Credentials" icon="book" href="/account-setup/payments-library-credentials">
    Overview of all payment method credentials
  </Card>

  <Card title="Payments Library Overview" icon="book" href="/payments-library/overview">
    Integrate the library in your checkout page
  </Card>
</CardGroup>


# Manage Users and API Keys
Source: https://developers.pcibooking.net/account-setup/manage-users

Create users, set roles, generate API keys, and manage access control for your PCI Booking account.

PCI Booking allows multiple users per account. Each user has their own permissions and up to 5 API keys.

## Users

When your account is created, it has one administrator user. You can add more users as needed.

### View Users

1. Log in to the [PCI Booking portal](https://users.pcibooking.net).
2. Navigate to **Account Settings** > **View Accounts**.
3. The list shows all currently active users. Check **Show closed** to include deactivated users.
4. Click a user row to edit their information, permissions, and [relay restrictions](/account-setup/security-settings).

### Add a User

1. Navigate to **Account Settings** > **Add Account**.
2. Fill in the required fields:
   * **User ID** (must be unique within the account)
   * **Temporary Password** (the user receives an email to change it on first login)
   * **Email**, **Name**, **Phone**
3. Assign permissions based on the user's role:
   * **Messaging** - send and receive PCI messages
   * **Tokenization** - tokenize card data
   * **Retrieve cards** - retrieve and relay card data to third parties. Consider setting up [relay restrictions](/account-setup/security-settings) for this permission.
   * **Property management** - manage properties
   * **System configurator** - configure account settings

## API Keys

Each user can have up to 5 API keys. All [authentication methods](/getting-started/authentication) are based on API keys.

### Generate a New API Key

1. Navigate to **Account Settings** > **Account Settings**.
2. Under the **API Access** section, click **Generate API Key**.
3. Enter a name for the key (useful when managing multiple keys).
4. The API key is displayed.

<Warning>
  Copy and store the API key immediately. Once you close the dialog, you cannot view the key again. If you lose a key, you must generate a new one.
</Warning>

### Delete an API Key

1. Find the key in the API keys list.
2. Click the delete icon.
3. Confirm deletion.

<Warning>
  Deleting an API key cannot be undone. Make sure the key is no longer in use before deleting it.
</Warning>

### Verify an API Key

Use the [Authenticate](/api-reference/general/authenticate) endpoint to check if an API key is valid.


# Payments Library Credentials
Source: https://developers.pcibooking.net/account-setup/payments-library-credentials

Generate and manage API credentials for PCI Booking's client-side JavaScript Payments Library.

The [Payments Library](/payments-library/overview) supports multiple payment methods beyond card payments. Each method requires you to set up credentials with the payment provider and store them in PCI Booking.

## How It Works

1. **Set up an account** with the payment provider (Apple, Google, PayPal, etc.).
2. **Obtain credentials** from the provider (API keys, merchant IDs, certificates).
3. **Store credentials** in the PCI Booking portal as an eWallet account.
4. **Reference the stored account** when initializing the Payments Library in your checkout page.

## Supported Payment Methods

| Method         | Setup Guide                                        | What You Need                                                                          |
| -------------- | -------------------------------------------------- | -------------------------------------------------------------------------------------- |
| **Apple Pay**  | [Apple Pay Setup](/account-setup/applepay-setup)   | Apple Developer Program membership, Merchant ID, domain verification, two certificates |
| **Google Pay** | [Google Pay Setup](/account-setup/googlepay-setup) | Google Pay Business Console account, Merchant ID                                       |
| **PayPal**     | [PayPal Setup](/account-setup/paypal-setup)        | PayPal Business account, Client ID and Secret                                          |
| **BankPay**    | [BankPay Setup](/account-setup/bankpay-setup)      | Bank account IBAN/BIC, coordination with PCI Booking team                              |
| **UPI**        | [UPI Setup](/account-setup/upi-setup)              | UPI Virtual Payment Address, coordination with PCI Booking team                        |

## API Operations

You can also manage credentials programmatically:

| Operation              | API Reference                                                                                           |
| ---------------------- | ------------------------------------------------------------------------------------------------------- |
| **Retrieve structure** | [Retrieve Credential Structure](/api-reference/payments-library-accounts/retrieve-credential-structure) |
| **Store**              | [Store Credentials](/api-reference/payments-library-accounts/store-credentials)                         |
| **List**               | [List Credentials](/api-reference/payments-library-accounts/list-credentials)                           |
| **Delete**             | [Delete Credentials](/api-reference/payments-library-accounts/delete-credentials)                       |

<Warning>
  Storing credentials with an ID that already exists will overwrite the existing credentials.
</Warning>

## Next Steps

<CardGroup>
  <Card title="Payments Library Overview" icon="book" href="/payments-library/overview">
    Integrate the library in your checkout page
  </Card>

  <Card title="Supported Payment Methods" icon="book" href="/payments-library/supported-methods">
    Browser support, device requirements, and supported operations per method
  </Card>
</CardGroup>


# PayPal Setup
Source: https://developers.pcibooking.net/account-setup/paypal-setup

Configure PayPal payments in PCI Booking. API credentials, webhook setup, and testing.

**Requires:** Verified [PayPal Business](https://www.paypal.com/business) account.

PayPal allows customers to pay using their PayPal balance, linked bank accounts, or cards stored in their PayPal account. Through PCI Booking's [Payments Library](/payments-library/overview), PayPal is offered alongside card payments and other methods on the same checkout page.

## How PayPal Works with PCI Booking

When a customer selects PayPal at checkout, the Payments Library opens a PayPal authorization window. The customer logs in to their PayPal account, selects a funding source, and authorizes the payment. Once authorized, PCI Booking completes the charge and notifies your system. No payment credentials pass through your servers.

PayPal supports **CHARGE** operations only. Tokenization and 3D Secure are not applicable to PayPal transactions.

## Prerequisites

* A verified [PayPal Business](https://www.paypal.com/business) account
* A PCI Booking merchant account

## 1. Access Developer Dashboard

1. Go to the [PayPal Developer Dashboard](https://developer.paypal.com/dashboard/).
2. Sign in with your PayPal Business account.

## 2. Create an App

1. Navigate to **Apps & Credentials**.
2. Select **Live** (or **Sandbox** for testing).
3. Click **Create App**.
4. Enter a name and select **Merchant** as the app type.
5. Click **Create App**.

## 3. Copy Credentials

* **Client ID** - visible under the app name.
* **Secret** - click **Show** to reveal.

Keep these credentials secure. You will need both the Client ID and Secret to configure PayPal in PCI Booking.

## 4. Store in PCI Booking

Create an eWallet account in PCI Booking with:

| Field                   | Description               | Required |
| ----------------------- | ------------------------- | -------- |
| **eWallet Type**        | PayPal                    | Yes      |
| **Merchant Identifier** | Your PayPal Client ID     | Yes      |
| **Secret**              | Your PayPal Client Secret | Yes      |

You can store credentials through the [PCI Booking portal](https://users.pcibooking.net) or programmatically via the [Store Credentials API](/api-reference/payments-library-accounts/store-credentials).

## Testing

PayPal provides a full sandbox environment for testing. To test your integration:

1. In the PayPal Developer Dashboard, switch to **Sandbox** mode and create a sandbox app with its own Client ID and Secret.
2. Create [sandbox test accounts](https://developer.paypal.com/tools/sandbox/) (both buyer and seller) to simulate transactions.
3. Store the sandbox credentials in PCI Booking (use a separate eWallet account for testing).
4. Use the sandbox buyer account to complete a test payment through your checkout page.

Sandbox transactions do not involve real money and do not appear on any live PayPal account.

<Info>
  When you are ready to go live, replace the sandbox credentials with your live Client ID and Secret from the PayPal Developer Dashboard.
</Info>

## Next Steps

<CardGroup>
  <Card title="Payments Library Credentials" icon="book" href="/account-setup/payments-library-credentials">
    Overview of all payment method credentials
  </Card>

  <Card title="Payments Library Overview" icon="book" href="/payments-library/overview">
    Integrate the library in your checkout page
  </Card>
</CardGroup>


# Security Settings
Source: https://developers.pcibooking.net/account-setup/security-settings

Configure IP restrictions, callback URL whitelisting, and card display permissions in your PCI Booking account

PCI Booking provides several security features you can enable to restrict access and control how card data flows through your account. We recommend employing as many of these as possible based on your needs.

## IP Restrictions

Restrict which IP addresses can call the PCI Booking API. Only requests from approved IPs are accepted.

### Setup

1. Log into the [PCI Booking portal](https://users.pcibooking.net).
2. Navigate to **PCI Shield Settings** > **IP Restriction Settings**.
3. Add new IP ranges using the plus icon. Enter a descriptive name and specify starting/ending IP addresses. For a single IP, use the same value for both.
4. Edit or delete existing entries by selecting them.

<Warning>
  Before enabling IP restrictions, make sure your current IP address is included. These settings also control portal access, so an incorrect configuration can lock you out.
</Warning>

## Relay Restrictions

Control which destination URLs can receive card data via [token replacement](/use-tokens/token-replacement-in-request). Only whitelisted destinations are permitted.

Relay restrictions are configured per user. Each user can have different approved destinations.

### Setup

1. Log into the [PCI Booking portal](https://users.pcibooking.net).
2. Navigate to **Account Settings** > **View Accounts**.
3. Select the user.
4. Under **Whitelist endpoints for retrieving cards**, add or remove destinations.

When whitelisting, provide the domain with protocol. For example, if relaying to `https://api.example.com/payments/process`, enter `https://api.example.com`.

<Info>
  If no whitelist is configured, the user can relay to any destination without restriction. Once you add the first entry, only whitelisted destinations are allowed.
</Info>

<Info>
  If you use a [CVV retention policy](/capture-cards/cvv-retention-policy), make sure the CVV relay destinations are included in the whitelist.
</Info>

## User and Permission Management

PCI Booking accounts support multiple users, each with specific permissions controlling what actions they can perform. When adding users who have card retrieval permissions, consider also setting up [relay restrictions](#relay-restrictions) for them.

See [Manage Users](/account-setup/manage-users) for full details on viewing, adding, and configuring users and their API keys.

## Whitelisting PCI Booking at Third Parties

When PCI Booking sends requests to third parties on your behalf (via token replacement or the gateway), the requests come from PCI Booking's IP addresses. We recommend whitelisting these IPs with the third parties you integrate with.

Contact [support@pcibooking.net](mailto:support@pcibooking.net) for the current list of PCI Booking IP addresses.

## Gateway Sender Whitelisting

When using the PCI Booking [gateway](/capture-cards/tokenization-on-request), third-party requests are forwarded to you from PCI Booking. From your server's perspective, all requests come from PCI Booking's servers, not the original sender.

PCI Booking passes the original sender's IP via the `X-Forwarded-For` header. This header contains multiple IP addresses:

* **First IP** - the original sender
* **Middle IPs** - PCI Booking internal addresses (can be ignored)
* **Last IP** - PCI Booking's external web server

```http theme={null}
X-Forwarded-For: 109.76.169.47, 172.200.3.67, 34.243.68.114
```

In this example, `109.76.169.47` is the original sender and `34.243.68.114` is PCI Booking's server.

To set up whitelisting on your end:

1. Accept requests where the **last** IP in `X-Forwarded-For` is a PCI Booking IP (contact [support@pcibooking.net](mailto:support@pcibooking.net) for the current list).
2. Filter by the **first** IP to verify the original sender, just as you would without PCI Booking in the middle.

## CVV Retention Policy

Set automatic deletion timelines for CVV data and control where cards with CVV can be relayed. This is a separate feature with its own configuration. See [CVV Retention Policy](/capture-cards/cvv-retention-policy) for full details.

## Token Housekeeping

We recommend regularly auditing your token database against PCI Booking's records to identify and remove stale card data. Delete tokens you no longer need using the [Delete Token](/manage-tokens/delete-tokens) operation.


# Stylesheets
Source: https://developers.pcibooking.net/account-setup/stylesheets

Customize the look and feel of PCI Booking's hosted card forms and card display pages with your own CSS

Stylesheets customize the appearance of PCI Booking's hosted forms (card capture, CVV capture, card display, and Card By Link). Upload your own CSS to match your brand. PCI Booking applies the stylesheet when rendering the form.

## How It Works

1. **Create a stylesheet** with your custom CSS rules.
2. **Give it a unique name** that you will reference in your API requests.
3. **Reference the stylesheet name** when generating a card entry or display form. PCI Booking renders the form with your styles applied.

If no stylesheet is specified, PCI Booking applies default styling.

## Managing Stylesheets via the Portal

1. Log into the [PCI Booking portal](https://users.pcibooking.net).
2. Navigate to **GUI Settings** > **Stylesheet Settings**.
3. Click the plus icon to create a new stylesheet.
4. Provide:
   * **Resource name** - a unique name used to reference this stylesheet in API requests.
   * **Resource description** - a free-text description for your reference.
   * **Resource Content LTR** - CSS rules for left-to-right page layouts.
   * **Resource Content RTL** - CSS rules for right-to-left page layouts (e.g. Arabic, Hebrew).

## Managing Stylesheets via the API

<Warning>
  The user performing API actions must have the `System Configurator` permission. If you are unsure, check with your account administrator or [contact our support team](mailto:support@pcibooking.net).
</Warning>

You can also manage stylesheets programmatically:

| Operation      | API Reference                                                     | Description                                          |
| -------------- | ----------------------------------------------------------------- | ---------------------------------------------------- |
| **Add/Update** | [Add or Update CSS](/api-reference/general/add-update-css)        | Create a new stylesheet or overwrite an existing one |
| **List**       | [List CSS Records](/api-reference/general/list-css-records)       | Retrieve all stylesheets in your account             |
| **Retrieve**   | [Retrieve CSS Record](/api-reference/general/retrieve-css-record) | Get the content of a specific stylesheet             |
| **Delete**     | [Delete CSS Record](/api-reference/general/delete-css-record)     | Remove a stylesheet                                  |

<Info>
  When updating a stylesheet via the API, the new content overwrites the existing content entirely.
</Info>

## Next Steps

<CardGroup>
  <Card title="Hosted Card Entry Form" icon="book" href="/capture-cards/hosted-card-entry-form">
    Card capture form that uses stylesheets
  </Card>

  <Card title="Card Display" icon="book" href="/use-tokens/card-display">
    Card display form that uses stylesheets
  </Card>

  <Card title="Custom Translations" icon="book" href="/account-setup/custom-translations">
    Customize form text and labels
  </Card>
</CardGroup>


# Success and Failure URLs
Source: https://developers.pcibooking.net/account-setup/success-and-failure-urls

Configure redirect URLs for hosted card entry form completion and error scenarios.

The card capture and CVV capture forms redirect the cardholder to your pages after submission. You provide a success URL and a failure URL. PCI Booking redirects to the appropriate page based on the outcome.

## Success Page

Your success URL receives non-sensitive card capture data as query string parameters. Build your URL with placeholders for the parameters you need, and PCI Booking replaces them with actual values on redirect.

### Available Parameters

| Parameter               | Description                                    |
| ----------------------- | ---------------------------------------------- |
| `{cardToken}`           | The card token created for this card           |
| `{cardType}`            | Card type (Visa, MasterCard, etc.)             |
| `{cardNumber}`          | Masked card number (first 6 and last 4 digits) |
| `{expiration}`          | Card expiration date                           |
| `{cardHolderName}`      | Cardholder name                                |
| `{cvv}`                 | Masked CVV (if captured)                       |
| `{threeDSecIndication}` | 3DS authentication status                      |

### Example

```text theme={null}
https://mysite.com/success?cardToken={cardToken}&cardType={cardType}&cardNumber={cardNumber}&expiration={expiration}&cardHolderName={cardHolderName}&cvv={cvv}&threeDSecIndication={threeDSecIndication}
```

Include only the parameters you need. At minimum, include `{cardToken}` to receive the token for subsequent API calls.

<Warning>
  Submit all URLs in encoded format.
</Warning>

## Failure Page

The failure URL is a static URL. You do not need to add placeholders. PCI Booking automatically appends query parameters with the failure details.

### Parameters Appended by PCI Booking

| Parameter                     | Description                                             | Always Present |
| ----------------------------- | ------------------------------------------------------- | -------------- |
| `reason`                      | Description of what went wrong                          | Yes            |
| `gatewayResultCode`           | PSP result code (when using UPG with charge-on-capture) | No             |
| `gatewayResultSubCode`        | PSP sub-code                                            | No             |
| `gatewayResultDescription`    | PSP result description                                  | No             |
| `gatewayResultSubDescription` | PSP sub-description                                     | No             |

### Example: What You Configure

```text theme={null}
https://mysite.com/failure
```

### Example: What the Redirect Looks Like

After a failed card capture:

```text theme={null}
https://mysite.com/failure?reason=Bad%20or%20missing%20authorization%20data
```

After a failed charge-on-capture (with UPG gateway details):

```text theme={null}
https://mysite.com/failure?reason=%5BDeclined%5D%20Card%20declined&gatewayResultCode=05&gatewayResultDescription=Do%20Not%20Honor
```

## Next Steps

<CardGroup>
  <Card title="Hosted Card Entry Form" icon="book" href="/capture-cards/hosted-card-entry-form">
    Card capture form that uses these redirect URLs
  </Card>

  <Card title="CVV Capture" icon="book" href="/capture-cards/cvv-capture">
    CVV-only capture form that uses the same redirect mechanism
  </Card>
</CardGroup>


# Target Profiles
Source: https://developers.pcibooking.net/account-setup/target-profiles

Configure target profiles with content filters to define how PCI Booking tokenizes and detokenizes card data in API requests and responses

A target profile is a reusable configuration that tells PCI Booking how to exchange card data with a specific third party. Each profile defines the message format, where card fields are located, and what certificates to use for the connection.

Profiles are used by:

* [Tokenization on Response](/capture-cards/tokenization-on-response) - extract card data from third-party responses
* [Tokenization on Request](/capture-cards/tokenization-on-request) - extract card data from inbound third-party requests
* [Token Replacement in Request](/use-tokens/token-replacement-in-request) - inject card data into outbound requests
* [Token Replacement in Response](/use-tokens/token-replacement-in-response) - inject card data into responses

You create a profile once per third-party message format, then reference it by name in your API calls.

## Profile Settings

| Setting                           | Required         | Description                                                                                                                                                        |
| --------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Name**                          | Yes              | Unique alphanumeric identifier used to reference the profile in API calls. Cannot be changed after creation.                                                       |
| **Description**                   | No               | Free-text notes documenting what this profile is for.                                                                                                              |
| **HTTP Client Certificate**       | No               | Client certificate for mutual TLS authentication with the third party. Upload certificates via [Client Certificates](/account-setup/client-certificates).          |
| **Content Signing Certificate**   | No               | Certificate for digitally signing outbound message content.                                                                                                        |
| **Card URI HTTP Header**          | For tokenization | HTTP header name where PCI Booking places the token URI when tokenizing card data. Required when using a tokenization content filter.                              |
| **Tokenization Content Filter**   | See below        | XML structure defining where card fields are in the message, used when extracting and tokenizing card data. See [Content Filters](/account-setup/content-filters). |
| **Retrieve Cards Content Filter** | See below        | XML structure defining where to inject card data when replacing tokens. See [Content Filters](/account-setup/content-filters).                                     |

<Info>
  At least one content filter (tokenization or retrieve cards) is required. A profile used only for tokenization needs only the tokenization filter. A profile used only for token replacement needs only the retrieve cards filter. Many profiles have both.
</Info>

## Two Types of Content Filters

Each profile can contain two separate content filters, each serving a different direction of data flow:

* **Tokenization filter** - tells PCI Booking how to **read** card data from the message (for tokenization operations). PCI Booking locates the card fields, extracts the values, stores them securely, and replaces them with tokens.

* **Retrieve cards filter** - tells PCI Booking how to **write** card data into the message (for token replacement operations). PCI Booking locates the token placeholders and injects the real card data.

In many cases the same XML structure works for both directions, but some integrations require different selectors for reading vs. writing.

## Creating a Profile

1. Log in to the [PCI Booking portal](https://users.pcibooking.net).
2. Navigate to **PCI Shield Settings** > **PCI Shield Profile Settings**.
3. Click the plus icon to create a new profile.
4. Enter a **Name** (alphanumeric, cannot be changed later).
5. Configure the settings from the table above.
6. Add at least one content filter (tokenization, retrieve cards, or both).
7. Save the profile.

From this screen you can also view, edit, clone, or delete existing profiles.

<Warning>
  The profile **Name** cannot be changed after creation. Choose a descriptive name that identifies the third party and message format (e.g., `BookingComXML`, `SabreGDS`).
</Warning>

## Universal Profiles (Pre-Built)

Many PCI Booking customers connect to the same third parties (booking platforms, OTAs, channel managers, GDS providers). For these common integrations, PCI Booking maintains [universal profiles](/capture-cards/universal-tokenization) that are already built and ready to use.

Reference the universal profile name in your request instead of creating a custom one.

Check with [support@pcibooking.net](mailto:support@pcibooking.net) to see if a universal profile already exists for your third party.

<Info>
  Need help creating a custom profile? Send a sample of the message you exchange with the third party to [support@pcibooking.net](mailto:support@pcibooking.net). Our team will build the profile for you.
</Info>

## Next Steps

<CardGroup>
  <Card title="Content Filters" icon="book" href="/account-setup/content-filters">
    Define where card fields appear in a message using selectors
  </Card>

  <Card title="Client Certificates" icon="book" href="/account-setup/client-certificates">
    Upload certificates for mutual TLS
  </Card>

  <Card title="Tokenization on Response" icon="book" href="/capture-cards/tokenization-on-response">
    Tokenize card data from third-party responses
  </Card>

  <Card title="Token Replacement in Request" icon="book" href="/use-tokens/token-replacement-in-request">
    Replace tokens with real card data in outbound requests
  </Card>
</CardGroup>


# UPI Setup
Source: https://developers.pcibooking.net/account-setup/upi-setup

Configure UPI payments in PCI Booking for Indian payment processing.

UPI (Unified Payments Interface) enables instant bank-to-bank payments for merchants operating in India. Built by the National Payments Corporation of India (NPCI), UPI allows customers to pay directly from their bank account using a Virtual Payment Address (VPA), without sharing card or bank details with the merchant.

Through PCI Booking's [Payments Library](/payments-library/overview), you can offer UPI as a payment method alongside card payments, Apple Pay, Google Pay, and other options on the same checkout page.

## How UPI Works with PCI Booking

When a customer selects UPI at checkout, the Payments Library presents a UPI payment flow. The customer authorizes the payment through their UPI app (such as Google Pay, PhonePe, or Paytm), and funds transfer instantly from the customer's bank to your account. PCI Booking handles the secure communication and transaction signing so no sensitive payment data passes through your servers.

UPI supports **CHARGE** operations only. Tokenization and 3D Secure are not applicable to UPI transactions.

## Prerequisites

* A PCI Booking merchant account with UPI enabled
* A registered UPI Virtual Payment Address (VPA) for receiving payments
* Your business must be registered to accept payments in India

## Setup

UPI setup requires coordination with the PCI Booking team. Contact [support@pcibooking.net](mailto:support@pcibooking.net) to get started. Our team will guide you through account eligibility, regional requirements, and testing.

## Store in PCI Booking

Once configured, create an eWallet account in PCI Booking with:

| Field                   | Description                                       | Required |
| ----------------------- | ------------------------------------------------- | -------- |
| **eWallet Type**        | UPI                                               | Yes      |
| **Merchant Identifier** | Your UPI Virtual Payment Address (VPA)            | Yes      |
| **Salt**                | Cryptographic salt for secure transaction signing | Yes      |

You can store credentials through the [PCI Booking portal](https://users.pcibooking.net) or programmatically via the [Store Credentials API](/api-reference/payments-library-accounts/store-credentials).

## Testing

Contact the PCI Booking team to receive sandbox credentials for UPI testing. Sandbox mode lets you simulate UPI transactions without processing real payments, so you can verify your integration before going live.

<Info>
  UPI is available for charge operations only. It does not support tokenization, pre-authorization, or 3D Secure flows.
</Info>

## Next Steps

<CardGroup>
  <Card title="Payments Library Credentials" icon="book" href="/account-setup/payments-library-credentials">
    Overview of all payment method credentials
  </Card>

  <Card title="Payments Library Overview" icon="book" href="/payments-library/overview">
    Integrate the library in your checkout page
  </Card>
</CardGroup>


# White Label Email Domain
Source: https://developers.pcibooking.net/account-setup/white-label-email

Send Card by Link emails from your own domain. DKIM and SPF configuration for branded email delivery.

By default, emails sent by PCI Booking (such as [Card By Link](/capture-cards/card-by-link) requests) come from the `pcibooking.net` domain. You can configure your own email domain so these emails appear to come from your company, increasing trust and reducing the chance of them being flagged as spam.

## Why Use White-Label Emails

When cardholders receive an email asking them to enter payment details, the sender domain plays a major role in whether they trust the message. Emails from an unfamiliar domain are more likely to be ignored, marked as spam, or flagged by corporate email filters.

White-label email addresses this by sending messages from your own domain. Benefits include:

* **Brand trust.** Cardholders see your company name and domain in the "from" address, making them more likely to open the email and complete the card capture.
* **Better deliverability.** Emails sent from a properly configured domain with SPF records are less likely to be caught by spam filters or quarantined by corporate mail gateways.
* **Consistent branding.** Combined with [custom templates](/account-setup/card-by-link-templates), white-label emails give cardholders a fully branded experience from sender address to landing page.

## What Changes for the Cardholder

Once white-label is configured, the cardholder sees your domain in the email "from" address instead of `pcibooking.net`. The email content, links, and card capture page function identically. The secure card capture link still points to PCI Booking's hosted page, keeping card data out of your systems.

## Setup

<Warning>
  Before enabling this feature, contact [support@pcibooking.net](mailto:support@pcibooking.net) and provide the email addresses from your domain for verification. Do not enable white-label emails until you receive confirmation that verification is complete.
</Warning>

### 1. Add SPF Record

SPF (Sender Policy Framework) tells receiving mail servers that PCI Booking is authorized to send emails on behalf of your domain. Add the following to the SPF TXT record of your domain:

```
include:pcibooking.net
```

A complete SPF record might look like:

```
v=spf1 include:pcibooking.net include:amazonses.com ~all
```

### 2. Wait for DNS Propagation

Changes take effect after your domain's TTL (Time to Live) period. If the email domain is not configured correctly, emails fall back to the PCI Booking domain automatically.

### 3. Test

After configuring the SPF record and receiving confirmation from support, send a test Card By Link request. Verify that the email arrives from your domain rather than `pcibooking.net`.

<Info>
  Configuration changes propagate according to the TTL set in your DNS TXT record. Allow sufficient time before testing.
</Info>

## Troubleshooting

If emails are still arriving from `pcibooking.net` after configuration:

* **DNS propagation delay.** SPF record changes can take up to 48 hours to fully propagate, depending on your domain's TTL setting.
* **Incorrect SPF syntax.** Verify your SPF record includes `include:pcibooking.net` and does not exceed the 10-lookup limit imposed by the SPF specification.
* **Verification not complete.** Confirm with PCI Booking support that your domain verification has been finalized on their end.


# Contact Verification
Source: https://developers.pcibooking.net/additional-functions/contact-verification

Verify that a property's email and phone number are valid and reachable using OTP.

Contact Verification lets you confirm that the email address and phone number you have on file for a property are valid and reachable. PCI Booking handles the entire verification flow: sending the email, hosting the verification page, and delivering the OTP via SMS or voice call.

## Use Cases

* **Validating newly submitted details.** When a property submits contact details through a self-service portal, trigger a verification to confirm they are correct before storing them.
* **Periodic re-verification.** Contact details can become outdated without notice. Periodically re-verify stored details to detect stale information and prompt the property to update their records.

## How It Works

1. **You create a verification request.** Call the [Create a Verification](/api-reference/additional/create-verification) endpoint with the property's email, phone number, and name. You can optionally set an expiration time, language, callback URL, and metadata.

2. **PCI Booking sends an email.** The property receives an email with a greeting and a secure link. The link expires after the time you specified (default: 10 minutes).

3. **The property verifies their phone number.** When they click the link, PCI Booking shows a hosted page where they enter their phone number and receive a 6-digit OTP via SMS or voice call. The OTP expires in 10 minutes.

4. **Verification completes.** After entering the correct code, the session status changes to `Verified`. If the code is wrong or the link expires, the status becomes `Failed` or `Expired`.

## Checking Results

You have two options for getting the verification outcome:

### Polling

Call [Get Verification Status](/api-reference/additional/get-verification-status) to check whether the session is still `Pending`, or has reached a terminal state (`Verified`, `Failed`, `Expired`). Once terminal, call [Get Verification Results](/api-reference/additional/get-verification-results) for the full outcome.

### Callback

If you provided a `callbackUrl` when creating the verification, PCI Booking sends a POST request to that URL when the session reaches a terminal state. The payload contains the session ID, final status, completion time, and your metadata. See [Receive Result Notification](/api-reference/additional/receive-result-notification) for the payload format.

<Info>
  Callback delivery is best-effort. If your endpoint is unreachable, the failure is logged but does not affect the verification outcome. Use polling as a fallback.
</Info>

## Verification Statuses

| Status     | Description                                                                 |
| ---------- | --------------------------------------------------------------------------- |
| `Pending`  | The verification was created but the property has not yet clicked the link. |
| `OtpSent`  | The property clicked the link and an OTP was sent to their phone.           |
| `Verified` | The property successfully entered the correct OTP.                          |
| `Failed`   | The verification failed (wrong code, too many attempts, etc.).              |
| `Expired`  | The verification link expired before the property completed the process.    |

## Security

* Each OTP is a single-use 6-digit code, hashed and salted before storage. PCI Booking does not retain the plain-text code.
* Two-factor verification (email link + phone OTP) ensures the property controls both channels.
* Verification links are time-limited and single-use.

## Next Steps

<CardGroup>
  <Card title="Create a Verification" icon="code" href="/api-reference/additional/create-verification">
    Initiate a new contact verification request.
  </Card>

  <Card title="Get Verification Status" icon="code" href="/api-reference/additional/get-verification-status">
    Check if a verification is still pending or complete.
  </Card>

  <Card title="Get Verification Results" icon="code" href="/api-reference/additional/get-verification-results">
    Retrieve the full outcome of a completed verification.
  </Card>

  <Card title="Receive Result Notification" icon="code" href="/api-reference/additional/receive-result-notification">
    Callback payload format for automated processing.
  </Card>
</CardGroup>


# Data Block Tokenization
Source: https://developers.pcibooking.net/additional-functions/data-blocks

Store, retrieve, and manage arbitrary data securely using PCI Booking's Data Block service.

The Data Block service lets you store any non-card data securely in PCI Booking's infrastructure. Each data block gets a unique token ID, and the content is stored in a GDPR-compliant location of your choice.

Data blocks can hold text, JSON, XML, images, PDFs, or any other content up to 50 MB per block.

<Warning>
  Data blocks are **not** PCI compliant. Do not store credit card information in data blocks. Use PCI Booking's [card tokenization](/capture-cards/overview) for card data.
</Warning>

## How It Works

A data block has two parts: **metadata** (reference, location, timestamps) and **content** (the actual data). You create and manage them separately:

1. **Create** a data block to get a token ID. At this point you set the storage location and an optional reference for searching later.
2. **Upload** content to the data block using the token ID.
3. **Download** the content whenever you need it.

You can also update the metadata (reference, location), search across your data blocks by reference, and delete blocks you no longer need.

## Storage Locations

When creating a data block, you choose where the data is stored. Available locations:

| Code | Location          |
| ---- | ----------------- |
| `IE` | Ireland (default) |
| `US` | United States     |
| `DE` | Germany           |
| `GB` | United Kingdom    |
| `FR` | France            |
| `CA` | Canada            |
| `AU` | Australia         |
| `SG` | Singapore         |
| `JP` | Japan             |
| `KR` | South Korea       |
| `IN` | India             |
| `CN` | China             |
| `BR` | Brazil            |

## Common Workflow

### Store a document

```bash theme={null}
# 1. Create the data block (metadata only)
curl -X POST https://service.pcibooking.net/api/dataBlock \
  -H "Authorization: APIKEY your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "Reference": "booking-12345",
    "DataBlockLocation": "DE"
  }'
# Response includes the token ID, e.g. "Id": "22222222"

# 2. Upload the content
curl -X PUT https://service.pcibooking.net/api/datablock/22222222/data \
  -H "Authorization: APIKEY your-api-key" \
  -H "Content-Type: application/pdf" \
  --data-binary @invoice.pdf
```

### Retrieve a document

```bash theme={null}
# Download by token ID
curl https://service.pcibooking.net/api/datablock/22222222/data \
  -H "Authorization: APIKEY your-api-key" \
  -o invoice.pdf
```

### Find data blocks by reference

```bash theme={null}
curl "https://service.pcibooking.net/api/dataBlock?reference=booking-12345" \
  -H "Authorization: APIKEY your-api-key"
```

## Metadata Fields

Each data block tracks the following metadata:

| Field               | Description                                                             |
| ------------------- | ----------------------------------------------------------------------- |
| `Id`                | The unique token ID for this data block.                                |
| `Reference`         | Your custom reference string for searching.                             |
| `DataBlockLocation` | The storage region code.                                                |
| `ContentType`       | The MIME type of the uploaded content. Set automatically on upload.     |
| `DataSize`          | The size of the uploaded content in bytes. Set automatically on upload. |
| `CreationTime`      | When the data block was created.                                        |
| `LastModifiedTime`  | When the content was last uploaded or replaced.                         |
| `LastAccessedTime`  | When the content was last downloaded.                                   |
| `UserId`            | The API user who created the data block.                                |
| `OwnerId`           | The account that owns the data block.                                   |

## Next Steps

<CardGroup>
  <Card title="Create a Data Block" icon="code" href="/api-reference/additional/create-data-block">
    Create a new data block and get its token ID.
  </Card>

  <Card title="Upload Content" icon="code" href="/api-reference/additional/upload-data-block-content">
    Upload content to an existing data block.
  </Card>

  <Card title="Download Content" icon="code" href="/api-reference/additional/download-data-block-content">
    Download the content of a data block.
  </Card>

  <Card title="Search Data Blocks" icon="code" href="/api-reference/additional/search-data-blocks">
    Find data blocks by reference.
  </Card>
</CardGroup>


# Network Tokenization
Source: https://developers.pcibooking.net/additional-functions/network-tokenization

Replace stored card numbers with network-issued tokens from Visa, Mastercard, and Amex for higher approval rates and automatic card updates.

## What Is Network Tokenization?

Network tokenization replaces a card's primary account number (PAN) with a token issued by the card network (Visa, Mastercard, or Amex). Unlike PCI Booking's vault tokens, which are internal references, network tokens are recognized by issuers and can improve authorization rates.

A network token is:

* **Bound to your merchant.** It cannot be used by anyone else.
* **Automatically updated.** When the issuer replaces, renews, or re-issues the card, the network updates the token. No action needed on your side.
* **Tied to a cryptogram.** Each transaction generates a unique cryptogram, reducing fraud risk.

## Why Use It?

| Benefit                     | How                                                         |
| --------------------------- | ----------------------------------------------------------- |
| Higher approval rates       | Issuers recognize network tokens as lower risk              |
| Fewer expired card declines | Network auto-updates token when card is renewed or replaced |
| Reduced fraud               | Per-transaction cryptograms prevent token reuse             |
| Card-on-file compliance     | Meets Visa and Mastercard card-on-file mandates             |

Network tokenization is most valuable for **recurring payments** and **card-on-file** scenarios where you store a card long-term and charge it repeatedly.

## How It Works with PCI Booking

PCI Booking acts as the Token Requestor with the card networks. You don't need a direct relationship with Visa, Mastercard, or Amex token services.

### From raw card data

1. You submit card details and cardholder info to PCI Booking's [Network Tokenize a Card](/api-reference/additional/network-tokenize-card) endpoint.
2. PCI Booking submits the request to the card network.
3. The network issues a network token.
4. PCI Booking stores the network token and returns a PCI Booking token URI.

### From an existing PCI Booking token

If you already have a card stored as a PCI Booking token:

1. Call [Network Tokenize from Token](/api-reference/additional/network-tokenize-from-token) with the existing token URI.
2. PCI Booking retrieves the card data internally, submits to the network, and stores the resulting network token as a new PCI Booking token.
3. Optionally delete the original token by setting `deleteExisting=true`.

In both cases, the resulting PCI Booking token works exactly like any other token for charges, relay, and display.

## Supported Networks

| Network    | Supported |
| ---------- | --------- |
| Visa       | Yes       |
| Mastercard | Yes       |
| Amex       | Yes       |

Not all cards can be network-tokenized. The issuing bank must support it for the specific card. If a card cannot be tokenized, the API returns error code `-150`.

## Cardholder Information

The card networks use cardholder information for risk scoring when deciding whether to approve the tokenization request. Providing more data increases the chance of approval:

* **Required:** First name, last name, IP address, country code
* **Recommended:** Email, phone, billing address, postal code
* **Optional:** Device location (latitude/longitude), device and account trust scores

## Lifecycle Management

Network tokens are managed through PCI Booking:

* **Automatic updates.** When the underlying card is renewed or replaced, the network notifies PCI Booking and the token is updated automatically. This is the primary benefit for card-on-file use cases.
* **Deletion.** Use [Delete Network Token](/api-reference/additional/delete-network-token) to remove a network token from both the card network and PCI Booking. Always delete network tokens you no longer need.
* **Metadata.** Use [Retrieve Token Metadata](/api-reference/manage-tokens/retrieve-token-metadata) to check if a token is network-tokenized. The `NetworkTokenInfo` field is present for network tokens.

## When to Use Network Tokenization

**Good fit:**

* Subscriptions and recurring billing
* Card-on-file for returning customers
* Travel bookings with future charge dates
* Any scenario where you store a card and charge it later

**Not needed:**

* One-time payments where the card is used immediately and not stored
* Token replacement (relay) workflows where you only pass card data to a third party

## Related

* [Network Tokenize a Card](/api-reference/additional/network-tokenize-card) - API reference
* [Network Tokenize from Token](/api-reference/additional/network-tokenize-from-token) - API reference
* [Delete Network Token](/api-reference/additional/delete-network-token) - API reference
* [Update an Expired Card](/use-cases/update-expired-card) - Manual expiry updates (network tokenization handles this automatically)


# Virtual Cards
Source: https://developers.pcibooking.net/additional-functions/virtual-cards

Issue single-use virtual cards through supported providers and automatically tokenize them in PCI Booking.

## What Are Virtual Cards?

Virtual cards are temporary card numbers issued programmatically for a specific transaction or purpose. They have a set spending limit, an authorization window, and can be restricted to a single use. Once the transaction is complete or the card expires, it cannot be used again.

## Why Use Them?

| Benefit               | How                                                           |
| --------------------- | ------------------------------------------------------------- |
| Fraud protection      | Single-use card cannot be reused if intercepted               |
| Spend control         | Set maximum amount and authorization date range               |
| Reconciliation        | Each virtual card maps to a specific booking or transaction   |
| No real card exposure | The supplier receives a virtual card, not your funding source |

Virtual cards are common in the travel industry for paying hotels, airlines, and other suppliers without exposing the company's actual payment credentials.

## How It Works with PCI Booking

PCI Booking integrates with virtual card providers (VCPs) and handles the full flow:

1. You call [Issue Virtual Card](/api-reference/additional/issue-virtual-card) with the provider credentials, amount, currency, and authorization date range.
2. PCI Booking requests a virtual card from the provider.
3. The provider issues the card.
4. PCI Booking automatically tokenizes the issued card and returns a PCI Booking token URI in the `Location` header.

The issued card number and CVV are masked in the API response. You only receive the PCI Booking token, which you can then use like any other token: relay it to a supplier, display it, or process a payment.

## Supported Providers

Use the [List Virtual Card Providers](/api-reference/additional/list-virtual-card-providers) endpoint to see all currently supported providers and their required credentials. This endpoint is public and requires no authentication.

Each provider has its own credential structure. Use [Retrieve VCP Credential Structure](/api-reference/additional/retrieve-vcp-credential-structure) to get the exact fields needed for a specific provider before storing credentials.

## Setting Up Credentials

You have two options for providing VCP credentials:

**Option 1: Pass credentials per request.** Include `ProviderName` and `Credentials` in each [Issue Virtual Card](/api-reference/additional/issue-virtual-card) request body.

**Option 2: Store credentials in PCI Booking.** Use [Store Credentials](/api-reference/process-cards/store-credentials) to save your VCP credentials once, then pass the `credentialsId` query parameter on each issuance request. This is more secure and avoids sending credentials repeatedly.

## Issuance Parameters

When issuing a virtual card, you control:

| Parameter           | Description                                              |
| ------------------- | -------------------------------------------------------- |
| **MaxValue**        | Maximum amount and currency the card can be charged      |
| **MinAuthDate**     | Earliest date the card accepts authorizations            |
| **MaxAuthDate**     | Latest date the card accepts authorizations              |
| **UniqueReference** | Your own reference for reconciliation (e.g., booking ID) |
| **CustomData**      | Provider-specific additional data                        |

## Using the Issued Card

Once issued, the virtual card is a standard PCI Booking token. You can:

* **Relay it** to a hotel or supplier via [Token Replacement in Request](/use-tokens/token-replacement-in-request)
* **Display it** to an agent via [Card Display](/use-tokens/card-display)
* **Query its metadata** via [Retrieve Token Metadata](/api-reference/manage-tokens/retrieve-token-metadata)
* **Delete it** via [Delete Token](/api-reference/manage-tokens/delete-token) when no longer needed

## Typical Workflow

A travel platform issuing a virtual card to pay a hotel:

1. **Issue** a virtual card with the booking amount and check-in/check-out dates as the authorization window.
2. **Relay** the token to the hotel's payment system using token replacement.
3. The hotel charges the virtual card.
4. **Reconcile** using the `UniqueReference` you set (e.g., your booking ID).
5. **Delete** the token after the transaction is settled.

## Related

* [Issue Virtual Card](/api-reference/additional/issue-virtual-card) - API reference
* [List Virtual Card Providers](/api-reference/additional/list-virtual-card-providers) - See supported providers
* [Get Virtual Card Provider](/api-reference/additional/get-virtual-card-provider) - Provider details
* [Retrieve VCP Credential Structure](/api-reference/additional/retrieve-vcp-credential-structure) - Required credential fields
* [Store Credentials](/api-reference/process-cards/store-credentials) - Save VCP credentials
* [Token Replacement in Request](/use-tokens/token-replacement-in-request) - Relay card data to suppliers


# Create Data Block
Source: https://developers.pcibooking.net/api-reference/additional/create-data-block

POST https://service.pcibooking.net/api/dataBlock
Create a new data block and receive its token ID.

<Card title="Data Block Tokenization Guide" icon="book" href="/additional-functions/data-blocks">
  Store and manage arbitrary data securely with GDPR-compliant storage locations
</Card>

Creates a new data block and returns its token ID. Data blocks let you store arbitrary sensitive data (such as identity documents, contracts, or personal information) in PCI Booking's secure vault with a choice of GDPR-compliant storage regions. After creating the block, use the [Upload Content](/api-reference/additional/upload-data-block-content) endpoint to attach the actual data.

## Error Responses

| HTTP Status | Error Code | Description                                                                                                                            |
| ----------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| 400         | -125       | Validation error. The request body is missing or contains invalid fields (e.g. bad `Reference` format or invalid `DataBlockLocation`). |
| 401         | -1003      | Not authenticated. The API key is missing or invalid.                                                                                  |
| 403         | -1003      | Not authorized. The API key does not have the `CanWriteData` permission.                                                               |
| 500         | -150       | Internal system error.                                                                                                                 |

## Parameter Constraints

| Parameter           | Constraint                                                                                                                                                               |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `Reference`         | Must match the pattern `[a-zA-Z0-9_\-@#=\"']{0,64}`. Letters, digits, underscore, hyphen, at-sign, hash, equals, double-quote, and single-quote only. Max 64 characters. |
| `DataBlockLocation` | One of: `US`, `IN`, `KR`, `SG`, `AU`, `JP`, `CA`, `DE`, `IE`, `GB`, `FR`, `BR`. If omitted, defaults to the user's country when supported, otherwise `IE` (Ireland).     |

## Parameters

### Headers

<ParamField type="string">
  Your API key prefixed with `APIKEY`. Example: `APIKEY your-api-key`. See the [Authentication guide](/getting-started/authentication).
</ParamField>

### Request Body

<ParamField type="string">
  A reference value which can then be used to query for this card token.
</ParamField>

<ParamField type="string">
  The location to store this data block. Available locations: **US**, **IN**, **KR**, **SG**, **AU**, **JP**, **CA**, **CN**, **DE**, **IE**, **GB**, **FR**, **BR**. For the default location (Ireland), enter `null`.
</ParamField>

<RequestExample>
  ```javascript Node.js theme={null}
  const response = await fetch('https://service.pcibooking.net/api/dataBlock', {
    method: 'POST',
    headers: {
      'Authorization': 'APIKEY your-api-key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      Reference: 'booking_12345',
      DataBlockLocation: 'DE'
    })
  });

  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://service.pcibooking.net/api/dataBlock',
      headers={
          'Authorization': 'APIKEY your-api-key',
          'Content-Type': 'application/json'
      },
      json={
          'Reference': 'booking_12345',
          'DataBlockLocation': 'DE'
      }
  )

  print(response.json())
  ```
</RequestExample>

## Response

<ResponseExample>
  ```json 201 theme={null}
  {
      "UserId": "Nadya",
      "OwnerId": "Frodo",
      "Id": "22222222",
      "Reference": "my reference",
      "ContentType": null,
      "DataSize": null,
      "CreationTime": "2019-01-16T11:21:25.3241104Z",
      "LastAccessedTime": null,
      "LastModifiedTime": null,
      "DataBlockLocation": "DE"
  }
  ```

  ```json 400 theme={null}
  {
      "code": -125,
      "message": "Bad input data",
      "moreInfo": "...",
      "errorList": null
  }
  ```

  ```json 401 theme={null}
  {
      "code": -1003,
      "message": "Not authorized to access this resource",
      "moreInfo": "Bad or missing authorization data, expected APIKEY",
      "errorList": null
  }
  ```
</ResponseExample>


# Create a Verification
Source: https://developers.pcibooking.net/api-reference/additional/create-verification

POST https://service.pcibooking.net/api/verify
Initiate a new contact details verification via email and OTP.

<Card title="Contact Verification Guide" icon="book" href="/additional-functions/contact-verification">
  How the email + OTP verification flow works end-to-end
</Card>

Initiates a new contact details verification. PCI Booking sends an email containing a secure link to the provided address. When the recipient clicks the link, they verify their phone number using a one-time passcode (OTP) sent via SMS or voice call.

## Error Responses

| HTTP Status | Error Code | Description                                                                                                                            |
| ----------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| 400         | -125       | Validation error. Required fields are missing or have invalid format (e.g. invalid email, phone number, or `ttlMinutes` out of range). |
| 401         | -1003      | Not authenticated. The API key is missing or invalid.                                                                                  |
| 500         | -150       | Internal system error. Identity could not be resolved after authentication.                                                            |

## Parameter Constraints

| Parameter     | Constraint                                                                                                                                                                                   |
| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `email`       | Required. Must be a valid email address.                                                                                                                                                     |
| `phone`       | Required. International format with country code, no leading `+` sign. Must contain 8 to 20 digits.                                                                                          |
| `personName`  | Optional. Max 100 characters.                                                                                                                                                                |
| `language`    | Optional. Defaults to `en`. Supported: `en`, `es`, `fr`, `de`, `it`, `pt`, `nl`, `pl`, `ru`, `ja`, `ko`, `zh`, `ar`, `hi`, `tr`, `sv`, `da`, `nb`, `no`, `ro`, `is`, plus regional variants. |
| `ttlMinutes`  | Optional. Integer from 1 to 30. Defaults to 10.                                                                                                                                              |
| `callbackUrl` | Optional. Must be a valid URL.                                                                                                                                                               |

<Info>
  Phone numbers must be in international format, including the country code, without a leading `+` sign (e.g. `972544735557`).
</Info>

## Parameters

### Headers

<ParamField type="string">
  Your API key prefixed with `APIKEY`. Example: `APIKEY your-api-key`. See the [Authentication guide](/getting-started/authentication).
</ParamField>

### Contact Details

<ParamField type="string">
  The email address to send the verification link to.
</ParamField>

<ParamField type="string">
  The phone number to verify via OTP, in international format without a leading `+` sign (e.g. `972544735557`).
</ParamField>

<ParamField type="string">
  The name of the recipient. Shown in the email greeting and verification screens.
</ParamField>

### Message Options

<ParamField type="string">
  The name that appears as the SMS sender (supported in most countries).
</ParamField>

<ParamField type="string">
  The language for the email and verification page, as a two-letter ISO 639-1 code (e.g. `en`).
</ParamField>

<ParamField type="number">
  How long the verification link stays valid, in minutes. Allowed range: 1 to 30.
</ParamField>

### Callback & Tracking

<ParamField type="string">
  A URL to which PCI Booking will POST the result when the session reaches a terminal state. See [Receive Result Notification](/api-reference/additional/receive-result-notification).
</ParamField>

<ParamField type="string">
  A free-form reference string stored with the session and echoed back in all responses and callbacks.
</ParamField>

<RequestExample>
  ```javascript Node.js theme={null}
  const response = await fetch('https://service.pcibooking.net/api/verify', {
    method: 'POST',
    headers: {
      'Authorization': 'APIKEY your-api-key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      email: 'john.doe@example.com',
      phone: '972544735557',
      personName: 'John Doe',
      language: 'en',
      ttlMinutes: 15,
      callbackUrl: 'https://yourplatform.com/verify-callback',
      metadata: 'MY-REFERENCE_098'
    })
  });

  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://service.pcibooking.net/api/verify',
      headers={
          'Authorization': 'APIKEY your-api-key',
          'Content-Type': 'application/json'
      },
      json={
          'email': 'john.doe@example.com',
          'phone': '972544735557',
          'personName': 'John Doe',
          'language': 'en',
          'ttlMinutes': 15,
          'callbackUrl': 'https://yourplatform.com/verify-callback',
          'metadata': 'MY-REFERENCE_098'
      }
  )

  print(response.json())
  ```
</RequestExample>

## Response

| Field       | Type     | Description                                                                                      |
| ----------- | -------- | ------------------------------------------------------------------------------------------------ |
| `verifyId`  | string   | The unique ID of the verification session. Use this in all subsequent status and results calls.  |
| `status`    | string   | The initial status. Always `Pending` on creation.                                                |
| `expiresAt` | datetime | The UTC datetime at which the verification link expires, based on `ttlMinutes`. ISO 8601 format. |

<ResponseExample>
  ```json 200 theme={null}
  {
      "verifyId": "xLoat3F385vvFRbgI2usOeuXKXQoB8kv",
      "status": "Pending",
      "expiresAt": "2026-03-15T18:44:21Z"
  }
  ```

  ```json 400 theme={null}
  {
      "code": -125,
      "message": "Bad input data",
      "moreInfo": "...",
      "errorList": null
  }
  ```
</ResponseExample>


# Delete Data Block
Source: https://developers.pcibooking.net/api-reference/additional/delete-data-block

DELETE https://service.pcibooking.net/api/dataBlock/{id}
Delete a data block by its ID.

<Card title="Data Block Tokenization Guide" icon="book" href="/additional-functions/data-blocks">
  Store and manage arbitrary data securely with GDPR-compliant storage locations
</Card>

Permanently deletes a data block and its stored content. Use this to fulfill data deletion requests or when the stored data is no longer needed.

## Error Responses

| HTTP Status | Error Code | Description                                                                                                 |
| ----------- | ---------- | ----------------------------------------------------------------------------------------------------------- |
| 401         | -1003      | Not authenticated. The API key is missing or invalid.                                                       |
| 403         | -1003      | Not authorized. The authenticated user does not own this data block or lacks the `CanWriteData` permission. |
| 404         | -160       | Data block not found. No data block exists with the specified ID.                                           |
| 500         | -150       | Internal system error.                                                                                      |

## Parameters

### Headers

<ParamField type="string">
  Your API key prefixed with `APIKEY`. Example: `APIKEY your-api-key`. See the [Authentication guide](/getting-started/authentication).
</ParamField>

### Path Parameters

<ParamField type="string">
  The ID of the data block returned in the [create method](/api-reference/additional/create-data-block).
</ParamField>

<RequestExample>
  ```javascript Node.js theme={null}
  const dataBlockId = '22222222';

  const response = await fetch(`https://service.pcibooking.net/api/dataBlock/${dataBlockId}`, {
    method: 'DELETE',
    headers: {
      'Authorization': 'APIKEY your-api-key'
    }
  });

  console.log(response.status); // 204 on success
  ```

  ```python Python theme={null}
  import requests

  data_block_id = '22222222'

  response = requests.delete(
      f'https://service.pcibooking.net/api/dataBlock/{data_block_id}',
      headers={
          'Authorization': 'APIKEY your-api-key'
      }
  )

  print(response.status_code)  # 204 on success
  ```
</RequestExample>

## Response

<ResponseExample>
  ```text 204 theme={null}
  No content returned.
  ```

  ```json 400 theme={null}
  {
      "code": -125,
      "message": "Bad input data",
      "moreInfo": "...",
      "errorList": null
  }
  ```

  ```json 401 theme={null}
  {
      "code": -1003,
      "message": "Not authorized to access this resource",
      "moreInfo": "Bad or missing authorization data, expected APIKEY",
      "errorList": null
  }
  ```

  ```json 404 theme={null}
  {
      "code": -1001,
      "message": "Uri not found",
      "moreInfo": "Data block not found",
      "errorList": null
  }
  ```
</ResponseExample>


# Delete Network Token
Source: https://developers.pcibooking.net/api-reference/additional/delete-network-token

DELETE https://service.pcibooking.net/api/networkToken
Delete a network token from both the card network and PCI Booking storage.

Deletes a network token from the card network (Visa, Mastercard, or Amex) and removes the corresponding PCI Booking token.

## Error Responses

| Code    | HTTP Status | Condition                                                                |
| ------- | ----------- | ------------------------------------------------------------------------ |
| `-1003` | `401`       | API key is missing or invalid.                                           |
| `-1003` | `401`       | Authenticated user does not own the token.                               |
| `-125`  | `400`       | Request body validation failed (missing required fields).                |
| `-150`  | `500`       | Failed to delete the token from the network or from PCI Booking storage. |

## Parameter Constraints

* **TokenId**: Required, maximum 255 characters.
* **Reason**: Optional, maximum 255 characters.

## Parameters

### Headers

<ParamField type="string">
  Your API key prefixed with `APIKEY`. Example: `APIKEY your-api-key`. See the [Authentication guide](/getting-started/authentication).
</ParamField>

### Request Body

<ParamField type="string">
  The card network brand. One of: `Visa`, `MasterCard`, `Amex`.
</ParamField>

<ParamField type="string">
  The network token identifier (as returned during network tokenization). Maximum 255 characters.
</ParamField>

<ParamField type="string">
  The source of the delete request (network-specific enum value).
</ParamField>

<ParamField type="string">
  Reason for deleting the network token. Maximum 255 characters.
</ParamField>

<RequestExample>
  ```javascript Node.js theme={null}
  const response = await fetch('https://service.pcibooking.net/api/networkToken', {
    method: 'DELETE',
    headers: {
      'Authorization': 'APIKEY your-api-key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      Brand: 'Visa',
      TokenId: '4895370012003478',
      Source: 'CardHolder',
      Reason: 'Customer requested token removal'
    })
  });

  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={null}
  import requests

  response = requests.delete(
      'https://service.pcibooking.net/api/networkToken',
      headers={
          'Authorization': 'APIKEY your-api-key',
          'Content-Type': 'application/json'
      },
      json={
          'Brand': 'Visa',
          'TokenId': '4895370012003478',
          'Source': 'CardHolder',
          'Reason': 'Customer requested token removal'
      }
  )

  print(response.json())
  ```
</RequestExample>

## Response

**200** - Network token deleted. Returns `true` if the token was successfully deleted from the card network.

<ResponseExample>
  ```json 200 theme={null}
  true
  ```

  ```json 401 theme={null}
  {
      "code": -1003,
      "message": "Not authorized to access this resource",
      "moreInfo": "User is not the owner of this bank card",
      "errorList": null
  }
  ```

  ```json 400 theme={null}
  {
      "code": -125,
      "message": "Bad input data",
      "moreInfo": "...",
      "errorList": null
  }
  ```
</ResponseExample>


# Download Data Block Content
Source: https://developers.pcibooking.net/api-reference/additional/download-data-block-content

GET https://service.pcibooking.net/api/datablock/{id}/data
Download the content of a data block.

<Card title="Data Block Tokenization Guide" icon="book" href="/additional-functions/data-blocks">
  Store and manage arbitrary data securely with GDPR-compliant storage locations
</Card>

Downloads the content stored in a data block. The response body contains the raw data with the same content type that was used when uploading. Use this to retrieve sensitive documents or data that were previously stored via the [Upload Content](/api-reference/additional/upload-data-block-content) endpoint.

## Error Responses

| HTTP Status | Error Code | Description                                                                                                    |
| ----------- | ---------- | -------------------------------------------------------------------------------------------------------------- |
| 401         | -1003      | Not authenticated. The API key is missing or invalid.                                                          |
| 403         | -1003      | Not authorized. The authenticated user does not own this data block or lacks the `CanRetrieveData` permission. |
| 404         | -160       | Data block not found, or the data block exists but has no uploaded content.                                    |
| 500         | -150       | Internal system error.                                                                                         |

## Parameters

### Headers

<ParamField type="string">
  Your API key prefixed with `APIKEY`. Example: `APIKEY your-api-key`. See the [Authentication guide](/getting-started/authentication).
</ParamField>

### Path Parameters

<ParamField type="string">
  The ID of the data block returned in the [create method](/api-reference/additional/create-data-block).
</ParamField>

<RequestExample>
  ```javascript Node.js theme={null}
  const dataBlockId = '22222222';

  const response = await fetch(`https://service.pcibooking.net/api/datablock/${dataBlockId}/data`, {
    headers: {
      'Authorization': 'APIKEY your-api-key'
    }
  });

  const content = await response.text();
  console.log(content);
  ```

  ```python Python theme={null}
  import requests

  data_block_id = '22222222'

  response = requests.get(
      f'https://service.pcibooking.net/api/datablock/{data_block_id}/data',
      headers={
          'Authorization': 'APIKEY your-api-key'
      }
  )

  print(response.text)
  ```
</RequestExample>

## Response

<ResponseExample>
  ```text 200 theme={null}
  The response body contains the uploaded content with the original Content-Type header.
  ```

  ```json 400 theme={null}
  {
      "code": -125,
      "message": "Bad input data",
      "moreInfo": "...",
      "errorList": null
  }
  ```

  ```json 401 theme={null}
  {
      "code": -1003,
      "message": "Not authorized to access this resource",
      "moreInfo": "Bad or missing authorization data, expected APIKEY",
      "errorList": null
  }
  ```

  ```json 404 theme={null}
  {
      "code": -1001,
      "message": "Uri not found",
      "moreInfo": "Data block not found",
      "errorList": null
  }
  ```
</ResponseExample>


# Get Data Block Details
Source: https://developers.pcibooking.net/api-reference/additional/get-data-block-details

GET https://service.pcibooking.net/api/dataBlock/{id}
Retrieve the details and metadata of an existing data block.

<Card title="Data Block Tokenization Guide" icon="book" href="/additional-functions/data-blocks">
  Store and manage arbitrary data securely with GDPR-compliant storage locations
</Card>

Retrieves the metadata of an existing data block, including its reference, storage location, owner, and creation date. This does not return the stored content itself; use [Download Content](/api-reference/additional/download-data-block-content) to retrieve the actual data.

## Error Responses

| HTTP Status | Error Code | Description                                                                                                    |
| ----------- | ---------- | -------------------------------------------------------------------------------------------------------------- |
| 401         | -1003      | Not authenticated. The API key is missing or invalid.                                                          |
| 403         | -1003      | Not authorized. The authenticated user does not own this data block or lacks the `CanRetrieveData` permission. |
| 404         | -160       | Data block not found. No data block exists with the specified ID.                                              |
| 500         | -150       | Internal system error.                                                                                         |

## Parameters

### Headers

<ParamField type="string">
  Your API key prefixed with `APIKEY`. Example: `APIKEY your-api-key`. See the [Authentication guide](/getting-started/authentication).
</ParamField>

### Path Parameters

<ParamField type="string">
  The ID of the data block returned in the [create method](/api-reference/additional/create-data-block).
</ParamField>

<RequestExample>
  ```javascript Node.js theme={null}
  const dataBlockId = '22222222';

  const response = await fetch(`https://service.pcibooking.net/api/dataBlock/${dataBlockId}`, {
    headers: {
      'Authorization': 'APIKEY your-api-key'
    }
  });

  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={null}
  import requests

  data_block_id = '22222222'

  response = requests.get(
      f'https://service.pcibooking.net/api/dataBlock/{data_block_id}',
      headers={
          'Authorization': 'APIKEY your-api-key'
      }
  )

  print(response.json())
  ```
</RequestExample>

## Response

<ResponseExample>
  ```json 200 theme={null}
  {
      "UserId": "Nadya",
      "OwnerId": "Frodo",
      "Id": "22222222",
      "Reference": "my reference",
      "ContentType": "text/plain",
      "DataSize": 6750,
      "CreationTime": "2019-01-16T11:21:25.3241104Z",
      "LastAccessedTime": "2019-01-17T10:21:25.3241104Z",
      "LastModifiedTime": "2019-01-17T06:21:25.3241104Z",
      "DataBlockLocation": "DE"
  }
  ```

  ```json 400 theme={null}
  {
      "code": -125,
      "message": "Bad input data",
      "moreInfo": "...",
      "errorList": null
  }
  ```

  ```json 401 theme={null}
  {
      "code": -1003,
      "message": "Not authorized to access this resource",
      "moreInfo": "Bad or missing authorization data, expected APIKEY",
      "errorList": null
  }
  ```

  ```json 404 theme={null}
  {
      "code": -1001,
      "message": "Uri not found",
      "moreInfo": "Data block not found",
      "errorList": null
  }
  ```
</ResponseExample>


# Get Verification Results
Source: https://developers.pcibooking.net/api-reference/additional/get-verification-results

GET https://service.pcibooking.net/api/verify/{verificationId}/results
Retrieve the final outcome of a completed contact verification.

<Card title="Contact Verification Guide" icon="book" href="/additional-functions/contact-verification">
  How the email + OTP verification flow works end-to-end
</Card>

Retrieves the final outcome of a completed verification, indicating whether the contact details were successfully confirmed by the recipient.

## Error Responses

| HTTP Status | Error Code | Description                                                                                            |
| ----------- | ---------- | ------------------------------------------------------------------------------------------------------ |
| 400         | -125       | Validation error. The `verificationId` format is invalid (must be a 32-character alphanumeric string). |
| 401         | -1003      | Not authenticated. The API key is missing or invalid.                                                  |
| 404         | -160       | Verification not found. No verification session exists with the specified ID.                          |

## Parameter Constraints

| Parameter        | Constraint                                                                                   |
| ---------------- | -------------------------------------------------------------------------------------------- |
| `verificationId` | Required. Must be a 32-character alphanumeric string matching the pattern `[a-zA-Z0-9]{32}`. |

<Warning>
  Results are only available once the verification status has transitioned to a terminal state (`Verified`, `Failed`, or `Expired`). Call the [Get Verification Status](/api-reference/additional/get-verification-status) endpoint first and only call this endpoint once the session has completed.
</Warning>

## Parameters

### Headers

<ParamField type="string">
  Your API key prefixed with `APIKEY`. Example: `APIKEY your-api-key`. See the [Authentication guide](/getting-started/authentication).
</ParamField>

### Path Parameters

<ParamField type="string">
  The unique session ID returned in `verifyId` when the verification was created.
</ParamField>

<RequestExample>
  ```javascript Node.js theme={null}
  const verificationId = 'xLoat3F385vvFRbgI2usOeuXKXQoB8kv';

  const response = await fetch(`https://service.pcibooking.net/api/verify/${verificationId}/results`, {
    headers: {
      'Authorization': 'APIKEY your-api-key'
    }
  });

  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={null}
  import requests

  verification_id = 'xLoat3F385vvFRbgI2usOeuXKXQoB8kv'

  response = requests.get(
      f'https://service.pcibooking.net/api/verify/{verification_id}/results',
      headers={
          'Authorization': 'APIKEY your-api-key'
      }
  )

  print(response.json())
  ```
</RequestExample>

## Response

| Field         | Type     | Description                                                                                                                 |
| ------------- | -------- | --------------------------------------------------------------------------------------------------------------------------- |
| `verifyId`    | string   | The unique ID of the verification session.                                                                                  |
| `status`      | string   | The final status. Possible values: `Verified`, `Failed`, `Expired`.                                                         |
| `verified`    | boolean  | `true` if the recipient successfully confirmed their contact details, otherwise `false`.                                    |
| `completedAt` | datetime | The UTC datetime at which the verification was completed. Returns `null` if the session expired before the recipient acted. |
| `expiresAt`   | datetime | The UTC datetime at which the verification link expired or will expire.                                                     |
| `phoneNumber` | string   | The phone number submitted for verification, as provided in the original request.                                           |
| `personName`  | string   | The recipient name as provided in the original request.                                                                     |
| `language`    | string   | The language used for the verification message.                                                                             |
| `callbackUrl` | string   | The callback URL provided in the original request. Returns `null` if not provided.                                          |
| `senderName`  | string   | The SMS sender name used for the verification message.                                                                      |
| `metadata`    | string   | The metadata string provided in the original request. Returns `null` if not provided.                                       |

<ResponseExample>
  ```json 200 theme={null}
  {
      "verifyId": "xLoat3F385vvFRbgI2usOeuXKXQoB8kv",
      "status": "Verified",
      "verified": true,
      "completedAt": "2026-03-15T18:47:10Z",
      "expiresAt": "2026-03-15T18:44:21Z",
      "phoneNumber": "972544735557",
      "personName": "John Doe",
      "language": "en",
      "callbackUrl": "https://yourplatform.com/verify-callback",
      "senderName": "SMS Sender",
      "metadata": "MY-REFERENCE_098"
  }
  ```

  ```json 400 theme={null}
  {
      "code": -125,
      "message": "Bad input data",
      "moreInfo": "...",
      "errorList": null
  }
  ```
</ResponseExample>


# Get Verification Status
Source: https://developers.pcibooking.net/api-reference/additional/get-verification-status

GET https://service.pcibooking.net/api/verify/{verificationId}
Check the current status of a contact verification request.

<Card title="Contact Verification Guide" icon="book" href="/additional-functions/contact-verification">
  How the email + OTP verification flow works end-to-end
</Card>

Retrieves the current status of a verification request. Use this endpoint to poll and determine whether the recipient has acted on the verification link, or whether the session is still pending or has expired.

## Error Responses

| HTTP Status | Error Code | Description                                                                                            |
| ----------- | ---------- | ------------------------------------------------------------------------------------------------------ |
| 400         | -125       | Validation error. The `verificationId` format is invalid (must be a 32-character alphanumeric string). |
| 401         | -1003      | Not authenticated. The API key is missing or invalid.                                                  |
| 404         | -160       | Verification not found. No verification session exists with the specified ID.                          |

## Parameter Constraints

| Parameter        | Constraint                                                                                   |
| ---------------- | -------------------------------------------------------------------------------------------- |
| `verificationId` | Required. Must be a 32-character alphanumeric string matching the pattern `[a-zA-Z0-9]{32}`. |

## Parameters

### Headers

<ParamField type="string">
  Your API key prefixed with `APIKEY`. Example: `APIKEY your-api-key`. See the [Authentication guide](/getting-started/authentication).
</ParamField>

### Path Parameters

<ParamField type="string">
  The unique session ID returned in `verifyId` when the verification was created.
</ParamField>

<RequestExample>
  ```javascript Node.js theme={null}
  const verificationId = 'xLoat3F385vvFRbgI2usOeuXKXQoB8kv';

  const response = await fetch(`https://service.pcibooking.net/api/verify/${verificationId}`, {
    headers: {
      'Authorization': 'APIKEY your-api-key'
    }
  });

  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={null}
  import requests

  verification_id = 'xLoat3F385vvFRbgI2usOeuXKXQoB8kv'

  response = requests.get(
      f'https://service.pcibooking.net/api/verify/{verification_id}',
      headers={
          'Authorization': 'APIKEY your-api-key'
      }
  )

  print(response.json())
  ```
</RequestExample>

## Response

| Field         | Type     | Description                                                                                 |
| ------------- | -------- | ------------------------------------------------------------------------------------------- |
| `verifyId`    | string   | The unique ID of the verification session.                                                  |
| `status`      | string   | The current status. Possible values: `Pending`, `OtpSent`, `Verified`, `Failed`, `Expired`. |
| `completedAt` | datetime | The UTC datetime at which the verification was completed. Returns `null` if still pending.  |
| `metadata`    | string   | The metadata string provided in the original request. Returns `null` if not provided.       |

<ResponseExample>
  ```json 200 theme={null}
  {
      "verifyId": "xLoat3F385vvFRbgI2usOeuXKXQoB8kv",
      "status": "Pending",
      "completedAt": null,
      "metadata": "MY-REFERENCE_098"
  }
  ```

  ```json 400 theme={null}
  {
      "code": -125,
      "message": "Bad input data",
      "moreInfo": "...",
      "errorList": null
  }
  ```
</ResponseExample>


# Get Virtual Card Provider
Source: https://developers.pcibooking.net/api-reference/additional/get-virtual-card-provider

GET https://service.pcibooking.net/api/VirtualCard/{name}
Retrieve details and credential requirements for a specific virtual card provider.

Returns details for a specific virtual card provider, including the credential fields required for issuing cards.

This endpoint is publicly accessible and does not require authentication.

## Error Responses

| Code | HTTP Status | Condition                                                    |
| ---- | ----------- | ------------------------------------------------------------ |
| N/A  | `404`       | Virtual card provider with the specified name was not found. |

## Parameters

### Path Parameters

<ParamField type="string">
  The name of the virtual card provider (e.g. `WEX`, `Rapyd`).
</ParamField>

<RequestExample>
  ```javascript Node.js theme={null}
  const providerName = 'WEX';

  const response = await fetch(`https://service.pcibooking.net/api/VirtualCard/${providerName}`);

  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={null}
  import requests

  provider_name = 'WEX'

  response = requests.get(
      f'https://service.pcibooking.net/api/VirtualCard/{provider_name}'
  )

  print(response.json())
  ```
</RequestExample>

## Response

<ResponseExample>
  ```json 200 theme={null}
  {
      "Name": "WEX",
      "CredentialsNames": [
          "MerchantID",
          "SharedSecret",
          "Account",
          "RebatePWD"
      ],
      "ProviderUrl": "https://www.wexinc.com"
  }
  ```

  ```text 404 theme={null}
  Virtual card provider with name [InvalidName] not found
  ```
</ResponseExample>


# Issue Virtual Card
Source: https://developers.pcibooking.net/api-reference/additional/issue-virtual-card

POST https://service.pcibooking.net/api/VirtualCard
Issue a single-use virtual card through a supported provider and automatically tokenize it.

Issues a virtual card through a supported provider (e.g. WEX, Rapyd) and automatically stores the issued card as a PCI Booking token. The card number and CVV in the response are masked for security.

The token URI is returned in the `Location` response header.

## Error Responses

| Code    | HTTP Status | Condition                                                                               |
| ------- | ----------- | --------------------------------------------------------------------------------------- |
| `-1003` | `401`       | API key is missing or invalid.                                                          |
| `-125`  | `400`       | Invalid provider name, missing required fields, or credential validation failed.        |
| `-125`  | `400`       | The `credentialsId` was provided but credentials were not found or could not be parsed. |
| `-150`  | `500`       | Virtual card was issued but could not be tokenized internally.                          |

## Parameters

### Headers

<ParamField type="string">
  Your API key prefixed with `APIKEY`. Example: `APIKEY your-api-key`. See the [Authentication guide](/getting-started/authentication).
</ParamField>

### Query String

<ParamField type="string">
  The ID of [stored credentials](/api-reference/process-cards/store-credentials) for a virtual card provider. When provided, `ProviderName` and `Credentials` in the request body are ignored.
</ParamField>

<ParamField type="string">
  Token storage region. One of: `US`, `IN`, `AU`, `JP`, `CA`, `IE`, `GB`, `BR`. If omitted, uses the account default.
</ParamField>

### Request Body

<ParamField type="string">
  The virtual card provider name (e.g. `WEX`, `Rapyd`). See [List Virtual Card Providers](/api-reference/additional/list-virtual-card-providers) for available providers. Not required when `credentialsId` is provided.
</ParamField>

<ParamField type="object">
  Provider-specific credential key-value pairs. Not required when `credentialsId` is provided. See the provider's credential structure for required fields.
</ParamField>

<ParamField type="object">
  The virtual card issuance request.

  <Expandable title="Properties">
    <ParamField type="object">
      Maximum amount that can be charged on the virtual card.

      <Expandable title="Properties">
        <ParamField type="number">
          The maximum charge amount.
        </ParamField>

        <ParamField type="string">
          ISO 4217 currency code (e.g. `USD`, `EUR`).
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="string">
      Earliest date the card can be authorized. ISO 8601 format.
    </ParamField>

    <ParamField type="string">
      Latest date the card can be authorized. ISO 8601 format.
    </ParamField>

    <ParamField type="string">
      Your own reference for this virtual card. If omitted, the provider assigns one.
    </ParamField>

    <ParamField type="object">
      Arbitrary provider-specific data.
    </ParamField>
  </Expandable>
</ParamField>

<RequestExample>
  ```javascript Node.js theme={null}
  const response = await fetch('https://service.pcibooking.net/api/VirtualCard?tokenLocation=IE', {
    method: 'POST',
    headers: {
      'Authorization': 'APIKEY your-api-key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      ProviderName: 'WEX',
      Credentials: {
        MerchantID: 'your-merchant-id',
        SharedSecret: 'your-shared-secret',
        Account: 'your-account',
        RebatePWD: 'your-rebate-password'
      },
      Request: {
        MaxValue: {
          Amount: 500.00,
          CurrencyCode: 'USD'
        },
        MinAuthDate: '2026-07-10T00:00:00Z',
        MaxAuthDate: '2026-08-10T00:00:00Z',
        UniqueReference: 'booking-98765'
      }
    })
  });

  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://service.pcibooking.net/api/VirtualCard',
      headers={
          'Authorization': 'APIKEY your-api-key',
          'Content-Type': 'application/json'
      },
      params={
          'tokenLocation': 'IE'
      },
      json={
          'ProviderName': 'WEX',
          'Credentials': {
              'MerchantID': 'your-merchant-id',
              'SharedSecret': 'your-shared-secret',
              'Account': 'your-account',
              'RebatePWD': 'your-rebate-password'
          },
          'Request': {
              'MaxValue': {
                  'Amount': 500.00,
                  'CurrencyCode': 'USD'
              },
              'MinAuthDate': '2026-07-10T00:00:00Z',
              'MaxAuthDate': '2026-08-10T00:00:00Z',
              'UniqueReference': 'booking-98765'
          }
      }
  )

  print(response.json())
  ```
</RequestExample>

## Response

**201** - Virtual card issued and tokenized. The `Location` header contains the PCI Booking token URI.

### Response Fields

<ParamField type="string">
  The PCI Booking token for the issued virtual card.
</ParamField>

<ParamField type="object">
  The virtual card provider's response.

  <Expandable title="Properties">
    <ParamField type="string">
      The outcome. One of: `Success`, `Accepted`, `Rejected`, `TemporaryFailure`, `FatalFailure`.
    </ParamField>

    <ParamField type="string">
      Detailed explanation of the result.
    </ParamField>

    <ParamField type="object">
      The maximum value set on the issued card.
    </ParamField>

    <ParamField type="object">
      The issued card details (number and CVV are masked).
    </ParamField>

    <ParamField type="string">
      The reference for this virtual card.
    </ParamField>

    <ParamField type="string">
      The unique ID assigned by the virtual card provider.
    </ParamField>

    <ParamField type="string">
      The name of the virtual card provider.
    </ParamField>
  </Expandable>
</ParamField>

<ResponseExample>
  ```json 201 theme={null}
  {
      "CardToken": "tok_abc123def456",
      "ProviderResponse": {
          "Result": "Success",
          "Message": "Card issued successfully",
          "MaxValue": {
              "Amount": 500.00,
              "CurrencyCode": "USD"
          },
          "VirtualCard": {
              "Number": "411111******1234",
              "ExpirationMonth": 12,
              "ExpirationYear": 2027,
              "SecurityCode": "***"
          },
          "UniqueReference": "booking-98765",
          "CardId": "vcc_provider_id_123",
          "ProviderName": "WEX"
      }
  }
  ```

  ```json 400 theme={null}
  {
      "code": -125,
      "message": "Bad input data",
      "moreInfo": "Virtual card provider with name [InvalidName] not found",
      "errorList": null
  }
  ```

  ```json 401 theme={null}
  {
      "code": -1003,
      "message": "Not authorized to access this resource",
      "moreInfo": "Bad or missing authorization data, expected APIKEY",
      "errorList": null
  }
  ```
</ResponseExample>


# List Virtual Card Providers
Source: https://developers.pcibooking.net/api-reference/additional/list-virtual-card-providers

GET https://service.pcibooking.net/api/VirtualCard
Retrieve the list of supported virtual card providers and their credential requirements.

Returns all supported virtual card providers, sorted alphabetically by name. Each entry includes the provider name and the credential fields required for issuing cards.

This endpoint is publicly accessible and does not require authentication.

## Parameters

No parameters required.

<RequestExample>
  ```javascript Node.js theme={null}
  const response = await fetch('https://service.pcibooking.net/api/VirtualCard');

  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://service.pcibooking.net/api/VirtualCard'
  )

  print(response.json())
  ```
</RequestExample>

## Response

The response contains an array of virtual card provider descriptions.

<ResponseExample>
  ```json 200 theme={null}
  [
      {
          "Name": "WEX",
          "CredentialsNames": [
              "MerchantID",
              "SharedSecret",
              "Account",
              "RebatePWD"
          ],
          "ProviderUrl": "https://www.wexinc.com"
      },
      {
          "Name": "Rapyd",
          "CredentialsNames": [
              "AccessKey",
              "SecretKey"
          ],
          "ProviderUrl": "https://www.rapyd.net"
      }
  ]
  ```
</ResponseExample>


# Network Tokenize a Card
Source: https://developers.pcibooking.net/api-reference/additional/network-tokenize-card

POST https://service.pcibooking.net/api/networkToken
Create a network token (Visa, Mastercard, or Amex) from raw card data and store it as a PCI Booking token.

Submits raw card details to the card network (Visa, Mastercard, or Amex) for network tokenization. On success, the resulting network token is stored as a PCI Booking token and the token URI is returned in the `Location` header.

<Note>
  Network tokenization replaces the real card number with a network-issued token that is bound to your merchant. The network token receives automatic card-on-file updates from the issuer, reducing declines from expired or replaced cards.
</Note>

## Error Responses

| Code    | HTTP Status | Condition                                                                                         |
| ------- | ----------- | ------------------------------------------------------------------------------------------------- |
| `-1003` | `401`       | API key is missing or invalid.                                                                    |
| `-125`  | `400`       | Request body validation failed (missing required fields, invalid card number, etc.).              |
| `-150`  | `500`       | Network tokenization failed (card cannot be network-tokenized, or the network returned an error). |

## Parameter Constraints

* **Card.Number**: Valid card number (Visa, Mastercard, or Amex).
* **Card.ExpirationMonth**: Range 1-12.
* **Card.SecurityCode**: 3-4 digits (regex `^\d{3,4}$`).
* **TokenizationRequest.ConsumerLanguage**: Exactly 2 characters, ISO 639-1 language code. Defaults to `en`.
* **TokenizationRequest.CardHolder.CountryCode**: Exactly 2 uppercase letters (ISO 3166-1 alpha-2).
* **TokenizationRequest.DeviceScore**: Range 1-5, defaults to 5.
* **TokenizationRequest.AccountScore**: Range 1-5, defaults to 5.
* **TokenizationRequest.DeviceLocationLat**: Range -90 to 90.
* **TokenizationRequest.DeviceLocationLon**: Range -180 to 180.

## Parameters

### Headers

<ParamField type="string">
  Your API key prefixed with `APIKEY`. Example: `APIKEY your-api-key`. See the [Authentication guide](/getting-started/authentication).
</ParamField>

### Query String

<ParamField type="string">
  Token storage region. One of: `US`, `IN`, `AU`, `JP`, `CA`, `IE`, `GB`, `BR`. If omitted, uses the account default.
</ParamField>

### Request Body

<ParamField type="object">
  The card details to network-tokenize.

  <Expandable title="Properties">
    <ParamField type="string">
      The full card number.
    </ParamField>

    <ParamField type="integer">
      Four-digit expiration year (e.g. `2028`).
    </ParamField>

    <ParamField type="integer">
      Expiration month (1-12).
    </ParamField>

    <ParamField type="string">
      The card CVV (3-4 digits).
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="object">
  Network tokenization parameters including cardholder and device information.

  <Expandable title="Properties">
    <ParamField type="string">
      ISO 639-1 language code (exactly 2 characters).
    </ParamField>

    <ParamField type="object">
      Cardholder details required by the card network.

      <Expandable title="Properties">
        <ParamField type="string">
          Cardholder first name.
        </ParamField>

        <ParamField type="string">
          Cardholder last name.
        </ParamField>

        <ParamField type="string">
          Cardholder email address.
        </ParamField>

        <ParamField type="string">
          Cardholder phone number.
        </ParamField>

        <ParamField type="string">
          Cardholder's IP address.
        </ParamField>

        <ParamField type="string">
          ISO 3166-1 alpha-2 country code (e.g. `US`, `GB`).
        </ParamField>

        <ParamField type="string">
          Billing address line 1.
        </ParamField>

        <ParamField type="string">
          Billing city.
        </ParamField>

        <ParamField type="string">
          Billing state or province.
        </ParamField>

        <ParamField type="string">
          Billing postal code.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="integer">
      Device trust score (1-5). Higher values indicate higher trust.
    </ParamField>

    <ParamField type="integer">
      Account trust score (1-5). Higher values indicate higher trust.
    </ParamField>

    <ParamField type="number">
      Device latitude (-90 to 90).
    </ParamField>

    <ParamField type="number">
      Device longitude (-180 to 180).
    </ParamField>

    <ParamField type="string">
      Device IP address (if different from cardholder IP).
    </ParamField>

    <ParamField type="string">
      Source of the card data (network-specific enum).
    </ParamField>
  </Expandable>
</ParamField>

<RequestExample>
  ```javascript Node.js theme={null}
  const response = await fetch('https://service.pcibooking.net/api/networkToken?loc=IE', {
    method: 'POST',
    headers: {
      'Authorization': 'APIKEY your-api-key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      Card: {
        Number: '4111111111111111',
        ExpirationYear: 2028,
        ExpirationMonth: 12,
        SecurityCode: '123'
      },
      TokenizationRequest: {
        ConsumerLanguage: 'en',
        CardHolder: {
          FirstName: 'John',
          LastName: 'Doe',
          Email: 'john.doe@example.com',
          ClientIPAddress: '203.0.113.42',
          CountryCode: 'US',
          Address1: '123 Main St',
          City: 'New York',
          StateProvince: 'NY',
          PostCode: '10001'
        },
        DeviceScore: 5,
        AccountScore: 5
      }
    })
  });

  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://service.pcibooking.net/api/networkToken',
      headers={
          'Authorization': 'APIKEY your-api-key',
          'Content-Type': 'application/json'
      },
      params={
          'loc': 'IE'
      },
      json={
          'Card': {
              'Number': '4111111111111111',
              'ExpirationYear': 2028,
              'ExpirationMonth': 12,
              'SecurityCode': '123'
          },
          'TokenizationRequest': {
              'ConsumerLanguage': 'en',
              'CardHolder': {
                  'FirstName': 'John',
                  'LastName': 'Doe',
                  'Email': 'john.doe@example.com',
                  'ClientIPAddress': '203.0.113.42',
                  'CountryCode': 'US',
                  'Address1': '123 Main St',
                  'City': 'New York',
                  'StateProvince': 'NY',
                  'PostCode': '10001'
              },
              'DeviceScore': 5,
              'AccountScore': 5
          }
      }
  )

  print(response.json())
  ```
</RequestExample>

## Response

**201** - Network token created. The `Location` header contains the PCI Booking token URI for the network-tokenized card.

<ResponseExample>
  ```json 201 theme={null}
  {
      "ResultCode": "Success",
      "Brand": "Visa",
      "TokenId": "4895370012003478",
      "TokenizedCard": {
          "Number": "489537******3478",
          "ExpirationMonth": 12,
          "ExpirationYear": 2028
      }
  }
  ```

  ```json 400 theme={null}
  {
      "code": -125,
      "message": "Bad input data",
      "moreInfo": "...",
      "errorList": null
  }
  ```

  ```json 401 theme={null}
  {
      "code": -1003,
      "message": "Not authorized to access this resource",
      "moreInfo": "Bad or missing authorization data, expected APIKEY",
      "errorList": null
  }
  ```
</ResponseExample>


# Network Tokenize from Existing Token
Source: https://developers.pcibooking.net/api-reference/additional/network-tokenize-from-token

POST https://service.pcibooking.net/api/networkToken/token
Create a network token from an existing PCI Booking card token.

Network-tokenizes a card that is already stored as a PCI Booking token. The card data is retrieved from the existing token, submitted to the card network, and the resulting network token is stored as a new PCI Booking token.

Optionally, the original token can be deleted after successful network tokenization by setting `deleteExisting=true`.

## Error Responses

| Code    | HTTP Status | Condition                                                 |
| ------- | ----------- | --------------------------------------------------------- |
| `-1003` | `401`       | API key is missing or invalid.                            |
| `-1003` | `401`       | Authenticated user does not own the specified card token. |
| `-160`  | `404`       | The `cardUri` does not resolve to a valid stored card.    |
| `-125`  | `400`       | Request body validation failed.                           |
| `-150`  | `500`       | Network tokenization failed.                              |

## Parameters

### Headers

<ParamField type="string">
  Your API key prefixed with `APIKEY`. Example: `APIKEY your-api-key`. See the [Authentication guide](/getting-started/authentication).
</ParamField>

### Query String

<ParamField type="string">
  The full URI of the existing PCI Booking token to network-tokenize (e.g. `https://service.pcibooking.net/api/payments/paycard/tok_abc123`).
</ParamField>

<ParamField type="boolean">
  When `true`, the original PCI Booking token is deleted after successful network tokenization.
</ParamField>

<ParamField type="string">
  Token storage region for the new network token. One of: `US`, `IN`, `AU`, `JP`, `CA`, `IE`, `GB`, `BR`. If omitted, uses the account default.
</ParamField>

### Request Body

The request body contains the same `TokenizationRequest` fields as [Network Tokenize a Card](/api-reference/additional/network-tokenize-card), excluding the `Card` object (since card data comes from the existing token).

<ParamField type="string">
  ISO 639-1 language code (exactly 2 characters).
</ParamField>

<ParamField type="object">
  Cardholder details required by the card network. See [Network Tokenize a Card](/api-reference/additional/network-tokenize-card) for the full field reference.
</ParamField>

<ParamField type="integer">
  Device trust score (1-5).
</ParamField>

<ParamField type="integer">
  Account trust score (1-5).
</ParamField>

<ParamField type="number">
  Device latitude (-90 to 90).
</ParamField>

<ParamField type="number">
  Device longitude (-180 to 180).
</ParamField>

<ParamField type="string">
  Device IP address.
</ParamField>

<ParamField type="string">
  Source of the card data.
</ParamField>

<RequestExample>
  ```javascript Node.js theme={null}
  const params = new URLSearchParams({
    cardUri: 'https://service.pcibooking.net/api/payments/paycard/tok_abc123',
    deleteExisting: 'false',
    loc: 'IE'
  });

  const response = await fetch(`https://service.pcibooking.net/api/networkToken/token?${params}`, {
    method: 'POST',
    headers: {
      'Authorization': 'APIKEY your-api-key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      ConsumerLanguage: 'en',
      CardHolder: {
        FirstName: 'John',
        LastName: 'Doe',
        Email: 'john.doe@example.com',
        ClientIPAddress: '203.0.113.42',
        CountryCode: 'US'
      },
      DeviceScore: 5,
      AccountScore: 5
    })
  });

  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://service.pcibooking.net/api/networkToken/token',
      headers={
          'Authorization': 'APIKEY your-api-key',
          'Content-Type': 'application/json'
      },
      params={
          'cardUri': 'https://service.pcibooking.net/api/payments/paycard/tok_abc123',
          'deleteExisting': 'false',
          'loc': 'IE'
      },
      json={
          'ConsumerLanguage': 'en',
          'CardHolder': {
              'FirstName': 'John',
              'LastName': 'Doe',
              'Email': 'john.doe@example.com',
              'ClientIPAddress': '203.0.113.42',
              'CountryCode': 'US'
          },
          'DeviceScore': 5,
          'AccountScore': 5
      }
  )

  print(response.json())
  ```
</RequestExample>

## Response

**201** - Network token created. The `Location` header contains the new PCI Booking token URI. If `deleteExisting=true` was set, the original token is deleted.

<ResponseExample>
  ```json 201 theme={null}
  {
      "ResultCode": "Success",
      "Brand": "MasterCard",
      "TokenId": "5412750012003478",
      "TokenizedCard": {
          "Number": "541275******3478",
          "ExpirationMonth": 6,
          "ExpirationYear": 2029
      }
  }
  ```

  ```json 404 theme={null}
  {
      "code": -160,
      "message": "Resource not found",
      "moreInfo": "Invalid Card Uri value",
      "errorList": null
  }
  ```

  ```json 401 theme={null}
  {
      "code": -1003,
      "message": "Not authorized to access this resource",
      "moreInfo": "User is not the owner of this bank card",
      "errorList": null
  }
  ```
</ResponseExample>


# Receive Result Notification
Source: https://developers.pcibooking.net/api-reference/additional/receive-result-notification

Callback payload sent by PCI Booking when a contact verification session completes.

<Card title="Contact Verification Guide" icon="book" href="/additional-functions/contact-verification">
  How the email + OTP verification flow works end-to-end
</Card>

If a `callbackUrl` was provided when [creating the verification](/api-reference/additional/create-verification), PCI Booking sends a POST request to that URL when the session reaches a terminal state (`Verified`, `Failed`, or `Expired`).

Your endpoint must be publicly accessible and should return a `2xx` HTTP status code to acknowledge receipt.

<Info>
  The callback payload uses the same structure as the [Get Verification Status](/api-reference/additional/get-verification-status) response.
</Info>

<Info>
  The `metadata` field contains the value provided in the original Create request, making it easy to correlate the notification with your internal records.
</Info>

<Warning>
  Callback delivery is best-effort. If your endpoint is unreachable or returns a non-2xx status, the failure is logged but does not affect the verification outcome. Use [Get Verification Status](/api-reference/additional/get-verification-status) or [Get Verification Results](/api-reference/additional/get-verification-results) as a fallback.
</Warning>

## Callback Payload

| Field         | Type     | Description                                                                   |
| ------------- | -------- | ----------------------------------------------------------------------------- |
| `verifyId`    | string   | The unique ID of the verification session.                                    |
| `status`      | string   | The terminal status. Possible values: `Verified`, `Failed`, `Expired`.        |
| `completedAt` | datetime | The UTC datetime at which the session reached its terminal status.            |
| `metadata`    | string   | The metadata string provided in the original request. `null` if not provided. |

```json theme={null}
{
    "verifyId": "xLoat3F385vvFRbgI2usOeuXKXQoB8kv",
    "status": "Verified",
    "completedAt": "2026-03-15T18:47:10Z",
    "metadata": "MY-REFERENCE_098"
}
```


# Retrieve VCP Credential Structure
Source: https://developers.pcibooking.net/api-reference/additional/retrieve-vcp-credential-structure

GET https://service.pcibooking.net/api/credentials/virtualCardProvider/{name}
Get the list of required credential fields for a specific virtual card provider.

Returns the credential field names required when [storing credentials](/api-reference/process-cards/store-credentials) for a specific virtual card provider. Use this to determine the correct structure before storing VCP credentials.

This endpoint is publicly accessible and does not require authentication.

## Error Responses

| Code   | HTTP Status | Condition                                                    |
| ------ | ----------- | ------------------------------------------------------------ |
| `-160` | `404`       | Virtual card provider with the specified name was not found. |

## Parameters

### Path Parameters

<ParamField type="string">
  The name of the virtual card provider (e.g. `WEX`, `Rapyd`). See [List Virtual Card Providers](/api-reference/additional/list-virtual-card-providers) for available names.
</ParamField>

<RequestExample>
  ```javascript Node.js theme={null}
  const providerName = 'WEX';

  const response = await fetch(`https://service.pcibooking.net/api/credentials/virtualCardProvider/${providerName}`);

  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={null}
  import requests

  provider_name = 'WEX'

  response = requests.get(
      f'https://service.pcibooking.net/api/credentials/virtualCardProvider/{provider_name}'
  )

  print(response.json())
  ```
</RequestExample>

## Response

Returns an array of credential field name strings.

<ResponseExample>
  ```json 200 theme={null}
  [
      "MerchantID",
      "SharedSecret",
      "Account",
      "RebatePWD"
  ]
  ```

  ```json 404 theme={null}
  {
      "code": -160,
      "message": "Resource not found",
      "moreInfo": "The selected Virtual Card Provider [InvalidName] is not valid",
      "errorList": null
  }
  ```
</ResponseExample>


# Search Data Blocks
Source: https://developers.pcibooking.net/api-reference/additional/search-data-blocks

GET https://service.pcibooking.net/api/dataBlock
Search for data blocks by reference, with pagination support.

<Card title="Data Block Tokenization Guide" icon="book" href="/additional-functions/data-blocks">
  Store and manage arbitrary data securely with GDPR-compliant storage locations
</Card>

Searches for data blocks by their reference value, with pagination support. Use this to find specific data blocks when you know the reference you assigned at creation, or omit the reference to list all data blocks in your account.

## Error Responses

| HTTP Status | Error Code | Description                                                                                                                             |
| ----------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| 400         | -125       | Validation error. A query parameter is out of range or has an invalid format (e.g. `maxItems` above 50 or invalid `reference` pattern). |
| 401         | -1003      | Not authenticated. The API key is missing or invalid.                                                                                   |
| 403         | -1003      | Not authorized. The API key does not have the `CanRetrieveData` permission.                                                             |
| 500         | -150       | Internal system error.                                                                                                                  |

## Parameter Constraints

| Parameter   | Constraint                                                                                                      |
| ----------- | --------------------------------------------------------------------------------------------------------------- |
| `reference` | Must match the pattern `[a-zA-Z0-9_\-@#=\"']{0,64}` with an optional trailing `*` wildcard for prefix matching. |
| `maxItems`  | Integer from 1 to 50. Defaults to 20 if omitted.                                                                |
| `offset`    | Integer from 0 upward. Zero-based index of the first result to return.                                          |

<Info title="Sort order">
  The list of items returned to you will be sorted by the `create date` of the data block.
</Info>

## Parameters

### Headers

<ParamField type="string">
  Your API key prefixed with `APIKEY`. Example: `APIKEY your-api-key`. See the [Authentication guide](/getting-started/authentication).
</ParamField>

### Query String

<ParamField type="string">
  The `reference` value provided in the [create method](/api-reference/additional/create-data-block) or [update method](/api-reference/additional/update-data-block-details). If omitted, all data blocks in the system are returned.
</ParamField>

<ParamField type="integer">
  The maximum number of items to return. Maximum allowed value is `50`.
</ParamField>

<ParamField type="string">
  The zero-based offset from the first item ID to return (item IDs in PCI Booking are sequential).
</ParamField>

<RequestExample>
  ```javascript Node.js theme={null}
  const params = new URLSearchParams({
    reference: 'booking_*',
    maxItems: '10',
    offset: '0'
  });

  const response = await fetch(`https://service.pcibooking.net/api/dataBlock?${params}`, {
    headers: {
      'Authorization': 'APIKEY your-api-key'
    }
  });

  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://service.pcibooking.net/api/dataBlock',
      headers={
          'Authorization': 'APIKEY your-api-key'
      },
      params={
          'reference': 'booking_*',
          'maxItems': 10,
          'offset': 0
      }
  )

  print(response.json())
  ```
</RequestExample>

## Response

<ResponseExample>
  ```json 200 theme={null}
  [
      {
          "UserId": "Nadya",
          "OwnerId": "Frodo",
          "Id": "12345678",
          "Reference": "ref1",
          "ContentType": "application/json",
          "DataSize": 140415,
          "CreationTime": "2019-01-16T15:17:38.4483995Z",
          "LastAccessedTime": "2019-01-17T14:17:38.4493958Z",
          "LastModifiedTime": "2019-01-17T10:17:38.4493958Z",
          "DataBlockLocation": "IE"
      },
      {
          "UserId": "Nadya",
          "OwnerId": "Frodo",
          "Id": "11111111",
          "Reference": "ref2",
          "ContentType": "application/xml",
          "DataSize": 2524,
          "CreationTime": "2019-01-16T15:17:38.4493958Z",
          "LastAccessedTime": "2019-01-17T14:17:38.4493958Z",
          "LastModifiedTime": "2019-01-17T10:17:38.4493958Z",
          "DataBlockLocation": "US"
      },
      {
          "UserId": "Nadya",
          "OwnerId": "Frodo",
          "Id": "22222222",
          "Reference": "ref1",
          "ContentType": "image/png",
          "DataSize": 5413,
          "CreationTime": "2019-01-16T15:17:38.4493958Z",
          "LastAccessedTime": "2019-01-17T14:17:38.4493958Z",
          "LastModifiedTime": "2019-01-17T10:17:38.4493958Z",
          "DataBlockLocation": "IE"
      }
  ]
  ```

  ```json 400 theme={null}
  {
      "code": -125,
      "message": "Bad input data",
      "moreInfo": "...",
      "errorList": null
  }
  ```

  ```json 401 theme={null}
  {
      "code": -1003,
      "message": "Not authorized to access this resource",
      "moreInfo": "Bad or missing authorization data, expected APIKEY",
      "errorList": null
  }
  ```
</ResponseExample>


# Update Data Block Details
Source: https://developers.pcibooking.net/api-reference/additional/update-data-block-details

PUT https://service.pcibooking.net/api/dataBlock/{id}
Update the details and metadata of an existing data block.

<Card title="Data Block Tokenization Guide" icon="book" href="/additional-functions/data-blocks">
  Store and manage arbitrary data securely with GDPR-compliant storage locations
</Card>

Updates the metadata of an existing data block, such as its reference value or storage location. Use this when you need to change the region where the data is stored (for GDPR compliance) or update the reference used for searching.

## Error Responses

| HTTP Status | Error Code | Description                                                                                                 |
| ----------- | ---------- | ----------------------------------------------------------------------------------------------------------- |
| 400         | -125       | Validation error. The request body is missing or contains invalid fields.                                   |
| 401         | -1003      | Not authenticated. The API key is missing or invalid.                                                       |
| 403         | -1003      | Not authorized. The authenticated user does not own this data block or lacks the `CanWriteData` permission. |
| 404         | -160       | Data block not found. No data block exists with the specified ID.                                           |
| 500         | -150       | Internal system error.                                                                                      |

## Parameter Constraints

| Parameter           | Constraint                                                                                                                                                               |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `Reference`         | Must match the pattern `[a-zA-Z0-9_\-@#=\"']{0,64}`. Letters, digits, underscore, hyphen, at-sign, hash, equals, double-quote, and single-quote only. Max 64 characters. |
| `DataBlockLocation` | One of: `US`, `IN`, `KR`, `SG`, `AU`, `JP`, `CA`, `DE`, `IE`, `GB`, `FR`, `BR`.                                                                                          |

## Parameters

### Headers

<ParamField type="string">
  Your API key prefixed with `APIKEY`. Example: `APIKEY your-api-key`. See the [Authentication guide](/getting-started/authentication).
</ParamField>

### Path Parameters

<ParamField type="string">
  The ID of the data block returned in the [create method](/api-reference/additional/create-data-block).
</ParamField>

### Request Body

<ParamField type="string">
  A reference value which can then be used to query for this card token.
</ParamField>

<ParamField type="string">
  The location to store this data block. Available locations: **US**, **IN**, **KR**, **SG**, **AU**, **JP**, **CA**, **CN**, **DE**, **IE**, **GB**, **FR**, **BR**. For the default location (Ireland), enter `null`.
</ParamField>

<RequestExample>
  ```javascript Node.js theme={null}
  const dataBlockId = '22222222';

  const response = await fetch(`https://service.pcibooking.net/api/dataBlock/${dataBlockId}`, {
    method: 'PUT',
    headers: {
      'Authorization': 'APIKEY your-api-key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      Reference: 'updated_ref_001',
      DataBlockLocation: 'US'
    })
  });

  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={null}
  import requests

  data_block_id = '22222222'

  response = requests.put(
      f'https://service.pcibooking.net/api/dataBlock/{data_block_id}',
      headers={
          'Authorization': 'APIKEY your-api-key',
          'Content-Type': 'application/json'
      },
      json={
          'Reference': 'updated_ref_001',
          'DataBlockLocation': 'US'
      }
  )

  print(response.json())
  ```
</RequestExample>

## Response

<ResponseExample>
  ```json 200 theme={null}
  {
      "UserId": "Nadya",
      "OwnerId": "Frodo",
      "Id": "22222222",
      "Reference": "my reference",
      "ContentType": null,
      "DataSize": null,
      "CreationTime": "2019-01-16T11:21:25.3241104Z",
      "LastAccessedTime": null,
      "LastModifiedTime": null,
      "DataBlockLocation": "DE"
  }
  ```

  ```json 400 theme={null}
  {
      "code": -125,
      "message": "Bad input data",
      "moreInfo": "...",
      "errorList": null
  }
  ```

  ```json 401 theme={null}
  {
      "code": -1003,
      "message": "Not authorized to access this resource",
      "moreInfo": "Bad or missing authorization data, expected APIKEY",
      "errorList": null
  }
  ```
</ResponseExample>


# Upload Data Block Content
Source: https://developers.pcibooking.net/api-reference/additional/upload-data-block-content

PUT https://service.pcibooking.net/api/datablock/{id}/data
Upload content to an existing data block (up to 50MB).

<Card title="Data Block Tokenization Guide" icon="book" href="/additional-functions/data-blocks">
  Store and manage arbitrary data securely with GDPR-compliant storage locations
</Card>

Uploads content to an existing data block. Use this after [creating a data block](/api-reference/additional/create-data-block) to store the actual sensitive data (files, documents, or any binary content). Uploading to a data block that already has content replaces the previous content.

## Error Responses

| HTTP Status | Error Code | Description                                                                                                 |
| ----------- | ---------- | ----------------------------------------------------------------------------------------------------------- |
| 401         | -1003      | Not authenticated. The API key is missing or invalid.                                                       |
| 403         | -1003      | Not authorized. The authenticated user does not own this data block or lacks the `CanWriteData` permission. |
| 404         | -160       | Data block not found. No data block exists with the specified ID.                                           |
| 413         | -126       | Payload too large. The `Content-Length` header exceeds the 50 MB limit.                                     |
| 500         | -150       | Internal system error.                                                                                      |

## Parameter Constraints

| Parameter        | Constraint                                                                                                                                            |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Content-Length` | Required. Must not exceed 52,428,800 bytes (50 MB).                                                                                                   |
| `Content-Type`   | Required. Specifies the MIME type of the uploaded content (e.g. `application/json`, `image/png`). This value is stored and returned when downloading. |

<Info title="50MB file size">
  Each data block can hold up to 50MB of content.
</Info>

## Parameters

### Path Parameters

<ParamField type="string">
  The ID of the data block returned in the [create method](/api-reference/additional/create-data-block).
</ParamField>

### Headers

<ParamField type="string">
  Your API key prefixed with `APIKEY`. Example: `APIKEY your-api-key`. See the [Authentication guide](/getting-started/authentication).
</ParamField>

<ParamField type="string">
  The content type of the body provided.
</ParamField>

### Request Body

<ParamField type="string">
  The content of the data block to upload.
</ParamField>

<RequestExample>
  ```javascript Node.js theme={null}
  const dataBlockId = '22222222';
  const content = JSON.stringify({ name: 'John Doe', passport: 'AB1234567' });

  const response = await fetch(`https://service.pcibooking.net/api/datablock/${dataBlockId}/data`, {
    method: 'PUT',
    headers: {
      'Authorization': 'APIKEY your-api-key',
      'Content-Type': 'application/json'
    },
    body: content
  });

  console.log(response.status); // 204 on success
  ```

  ```python Python theme={null}
  import requests

  data_block_id = '22222222'
  content = '{"name": "John Doe", "passport": "AB1234567"}'

  response = requests.put(
      f'https://service.pcibooking.net/api/datablock/{data_block_id}/data',
      headers={
          'Authorization': 'APIKEY your-api-key',
          'Content-Type': 'application/json'
      },
      data=content
  )

  print(response.status_code)  # 204 on success
  ```
</RequestExample>

## Response

<ResponseExample>
  ```text 204 theme={null}
  No content returned.
  ```

  ```json 400 theme={null}
  {
      "code": -125,
      "message": "Bad input data",
      "moreInfo": "...",
      "errorList": null
  }
  ```

  ```json 401 theme={null}
  {
      "code": -1003,
      "message": "Not authorized to access this resource",
      "moreInfo": "Bad or missing authorization data, expected APIKEY",
      "errorList": null
  }
  ```

  ```text 413 theme={null}
  Payload Too Large. Content exceeds the 50 MB limit.
  ```
</ResponseExample>


# Add or update CSS
Source: https://developers.pcibooking.net/api-reference/general/add-update-css

PUT https://service.pcibooking.net/api/resources/stylesheet/{ResourceName}
Create a new CSS record or update an existing one by replacing its content.

<Card title="Stylesheets Guide" icon="book" href="/account-setup/stylesheets">
  Customize the appearance of hosted forms
</Card>

Creates a new CSS stylesheet resource or replaces an existing one. Use this to customize the look and feel of PCI Booking's hosted card entry and card display forms to match your brand.

## Error Responses

| HTTP Status | Error Code | Description                                                                                                                           |
| ----------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| 400         |            | Missing required fields. One or more required properties (`ContentLTR`, `ContentRTL`, `IsDefault`) are missing from the request body. |
| 400         |            | No CSS content. Both `ContentLTR` and `ContentRTL` are empty. At least one must contain valid CSS.                                    |
| 400         |            | Invalid CSS syntax. The provided CSS content could not be parsed. The response includes the line number and error details.            |
| 401         | -1003      | Not authenticated. The API key is missing or invalid.                                                                                 |
| 403         | -1003      | Not authorized. The API key does not have the `CanConfigureSettings` permission.                                                      |
| 500         |            | Internal server error. The resource could not be saved.                                                                               |

## Parameter Constraints

| Parameter      | Constraint                                                                                           |
| -------------- | ---------------------------------------------------------------------------------------------------- |
| `ResourceName` | Required. Must contain only alphanumeric characters (`[a-zA-Z0-9]+`).                                |
| `ContentLTR`   | Required (may be empty string). At least one of `ContentLTR` or `ContentRTL` must contain valid CSS. |
| `ContentRTL`   | Required (may be empty string). At least one of `ContentLTR` or `ContentRTL` must contain valid CSS. |

<Info title="Same method is used for creating a new CSS resource and updating an existing CSS resource">
  Please be aware that the same method is used for both creating a new CSS and updating an existing one.
  If you update an existing CSS, the content of it will be replaced with the uploaded content and this action **cannot be undone**.
</Info>

## Parameters

### Headers

<ParamField type="string">
  Your API key prefixed with `APIKEY`. Example: `APIKEY your-api-key`. See the [Authentication guide](/getting-started/authentication).
</ParamField>

### Path Parameters

<ParamField type="string">
  The resource name to assign to this CSS record.
</ParamField>

### Request Body

<ParamField type="string">
  Description of this CSS resource, displayed in the user's site.
</ParamField>

<ParamField type="string">
  Stylesheet configuration for LTR content. At least one of `ContentLTR` or `ContentRTL` must contain valid CSS.
</ParamField>

<ParamField type="string">
  Stylesheet configuration for RTL content. At least one of `ContentLTR` or `ContentRTL` must contain valid CSS. Typically left blank unless you use RTL pages.
</ParamField>

<ParamField type="boolean">
  Sets this CSS resource as the default CSS for your account.
</ParamField>

<RequestExample>
  ```javascript Node.js theme={null}
  const response = await fetch('https://service.pcibooking.net/api/resources/stylesheet/BrandCSS', {
    method: 'PUT',
    headers: {
      'Authorization': 'APIKEY your-api-key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      Description: 'Brand-specific card form styles',
      ContentLTR: 'body { background-color: #f5f5f5; } h1 { color: #333; }',
      ContentRTL: '',
      IsDefault: false
    })
  });

  console.log(response.status); // 201 created, 200 updated
  ```

  ```python Python theme={null}
  import requests

  response = requests.put(
      'https://service.pcibooking.net/api/resources/stylesheet/BrandCSS',
      headers={
          'Authorization': 'APIKEY your-api-key',
          'Content-Type': 'application/json'
      },
      json={
          'Description': 'Brand-specific card form styles',
          'ContentLTR': 'body { background-color: #f5f5f5; } h1 { color: #333; }',
          'ContentRTL': '',
          'IsDefault': False
      }
  )

  print(response.status_code)  # 201 created, 200 updated
  ```
</RequestExample>

## Response

<ResponseExample>
  ```json 201 theme={null}
  // Empty body. Returned when a new CSS resource is created (the ResourceName did not exist before).
  ```

  ```json 200 theme={null}
  // Empty body. Returned when an existing CSS resource is updated (the ResourceName already existed).
  ```

  ```json 400 Missing required fields theme={null}
  {
      "Message": "The request is invalid.",
      "ModelState": {
          "model": [
              "Required property 'IsDefault' not found in JSON. Path '', line 6, position 1."
          ],
          "model.ContentLTR": [
              "The ContentLTR field is required."
          ]
      }
  }
  ```

  ```json 400 No CSS content provided theme={null}
  {
      "Message": "The request is invalid.",
      "ModelState": {
          "ContentError": [
              "At least one of the fields, ContentLTR or ContentRTL, must have valid CSS content"
          ]
      }
  }
  ```

  ```json 400 Invalid CSS syntax theme={null}
  {
      "Message": "Invalid CSS: Line number: 1<br />Error: invalid selector after \n"
  }
  ```

  ```json 401 theme={null}
  {
      "code": -1003,
      "message": "Not authorized to access this resource",
      "moreInfo": "Bad or missing authorization data, expected APIKEY",
      "errorList": null
  }
  ```
</ResponseExample>


# Authenticate API Key
Source: https://developers.pcibooking.net/api-reference/general/authenticate

POST https://service.pcibooking.net/api/accounts/authenticate/
Verify that the PCI Booking service is available and your API key is valid.

This method lets you verify that the PCI Booking service is available and that your API key is valid.

<Card title="Authentication Guide" icon="book" href="/getting-started/authentication#api-key">
  Learn about API key authentication
</Card>

## Error Responses

| HTTP Status | Error Code | Description                                                                  |
| ----------- | ---------- | ---------------------------------------------------------------------------- |
| 401         | -1003      | Not authenticated. The API key is missing, malformed, or invalid.            |
| 401         | -1005      | User suspended. The account associated with this API key has been suspended. |
| 401         | -1006      | User closed. The account associated with this API key has been closed.       |
| 429         |            | Rate limited. Too many authentication requests in a short period.            |

Both `POST` and `GET` methods are supported:

```text theme={null}
GET https://service.pcibooking.net/api/accounts/authenticate/
```

## Parameters

### Headers

<ParamField type="string">
  Your API key prefixed with `APIKEY`. Example: `APIKEY your-api-key`. See the [Authentication guide](/getting-started/authentication).
</ParamField>

<RequestExample>
  ```javascript Node.js theme={null}
  const response = await fetch('https://service.pcibooking.net/api/accounts/authenticate/', {
    method: 'POST',
    headers: {
      'Authorization': 'APIKEY your-api-key'
    }
  });

  console.log(response.status); // 200 if valid
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://service.pcibooking.net/api/accounts/authenticate/',
      headers={
          'Authorization': 'APIKEY your-api-key'
      }
  )

  print(response.status_code)  # 200 if valid
  ```
</RequestExample>

## Response

<ResponseExample>
  ```json 200 theme={null}
  // Empty body. The API key is valid and the service is available.
  ```

  ```json 401 theme={null}
  {
      "code": -1003,
      "message": "Not authorized to access this resource",
      "moreInfo": "Bad or missing authorization data, expected APIKEY",
      "errorList": null
  }
  ```
</ResponseExample>


# Delete CSS Record
Source: https://developers.pcibooking.net/api-reference/general/delete-css-record

DELETE https://service.pcibooking.net/api/resources/stylesheet/{ResourceName}
Delete a CSS record from your PCI Booking account.

<Card title="Stylesheets Guide" icon="book" href="/account-setup/stylesheets">
  Customize the appearance of hosted forms
</Card>

Deletes the specified CSS resource from your account.

## Error Responses

| HTTP Status | Error Code | Description                                                                      |
| ----------- | ---------- | -------------------------------------------------------------------------------- |
| 401         | -1003      | Not authenticated. The API key is missing or invalid.                            |
| 403         | -1003      | Not authorized. The API key does not have the `CanConfigureSettings` permission. |
| 404         |            | Resource not found. No CSS record exists with the specified `ResourceName`.      |

## Parameter Constraints

| Parameter      | Constraint                                                            |
| -------------- | --------------------------------------------------------------------- |
| `ResourceName` | Required. Must contain only alphanumeric characters (`[a-zA-Z0-9]+`). |

## Parameters

### Headers

<ParamField type="string">
  Your API key prefixed with `APIKEY`. Example: `APIKEY your-api-key`. See the [Authentication guide](/getting-started/authentication).
</ParamField>

### Path Parameters

<ParamField type="string">
  The resource name assigned to this CSS record. You can view the list of CSS records in the user's site or [retrieve the full list](/api-reference/general/list-css-records) via the API.
</ParamField>

<RequestExample>
  ```javascript Node.js theme={null}
  const response = await fetch('https://service.pcibooking.net/api/resources/stylesheet/BrandCSS', {
    method: 'DELETE',
    headers: {
      'Authorization': 'APIKEY your-api-key'
    }
  });

  console.log(response.status); // 204 on success
  ```

  ```python Python theme={null}
  import requests

  response = requests.delete(
      'https://service.pcibooking.net/api/resources/stylesheet/BrandCSS',
      headers={
          'Authorization': 'APIKEY your-api-key'
      }
  )

  print(response.status_code)  # 204 on success
  ```
</RequestExample>

## Response

<ResponseExample>
  ```json 204 theme={null}
  // Empty body. Returned on successful deletion.
  ```

  ```json 404 theme={null}
  // Empty body. The specified ResourceName does not exist in your account.
  ```

  ```json 401 theme={null}
  {
      "code": -1003,
      "message": "Not authorized to access this resource",
      "moreInfo": "Bad or missing authorization data, expected APIKEY",
      "errorList": null
  }
  ```
</ResponseExample>


# Get Supported Credit Cards
Source: https://developers.pcibooking.net/api-reference/general/get-supported-cards

GET https://service.pcibooking.net/api/payments/paycard/supportedCards
Retrieve the list of supported credit card type codes.

For the full list of card brands with their codes, see the [Supported Card Types](/reference/card-types) reference page.

This method returns the list of supported credit card type codes. You can use this to validate or filter card types in your integration.

**Authentication:** Not required (public endpoint). This endpoint has no error responses.

<RequestExample>
  ```javascript Node.js theme={null}
  const response = await fetch('https://service.pcibooking.net/api/payments/paycard/supportedCards');

  const cards = await response.json();
  console.log(cards);
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://service.pcibooking.net/api/payments/paycard/supportedCards'
  )

  cards = response.json()
  print(cards)
  ```
</RequestExample>

## Response

Returns an alphabetically sorted JSON array of card type code strings. See [Supported Card Types](/reference/card-types) for what each code represents.

<ResponseExample>
  ```json 200 theme={null}
  [
    "AMEX",
    "BC",
    "CartaSi",
    "Dankort",
    "Delta",
    "DinersClub",
    "Discover",
    "Electron",
    "Elo",
    "Hipercard",
    "JCB",
    "Maestro",
    "MasterCard",
    "MC_Alaska",
    "MC_Canada",
    "Switch",
    "Troy",
    "UATP",
    "UnionPay",
    "Visa",
    "enRoute"
  ]
  ```
</ResponseExample>


# List All CSS Records
Source: https://developers.pcibooking.net/api-reference/general/list-css-records

GET https://service.pcibooking.net/api/resources/stylesheet
Retrieve a list of all CSS records in your account.

<Card title="Stylesheets Guide" icon="book" href="/account-setup/stylesheets">
  Customize the appearance of hosted forms
</Card>

The response is an array of CSS resource summaries in your account. Each item includes the resource name, description, content type, and whether it is the default. To retrieve the full CSS content, use the [Retrieve CSS Record](/api-reference/general/retrieve-css-record) endpoint.

## Error Responses

| HTTP Status | Error Code | Description                                           |
| ----------- | ---------- | ----------------------------------------------------- |
| 401         | -1003      | Not authenticated. The API key is missing or invalid. |

## Parameters

### Headers

<ParamField type="string">
  Your API key prefixed with `APIKEY`. Example: `APIKEY your-api-key`. See the [Authentication guide](/getting-started/authentication).
</ParamField>

<RequestExample>
  ```javascript Node.js theme={null}
  const response = await fetch('https://service.pcibooking.net/api/resources/stylesheet', {
    headers: {
      'Authorization': 'APIKEY your-api-key'
    }
  });

  const cssRecords = await response.json();
  console.log(cssRecords);
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://service.pcibooking.net/api/resources/stylesheet',
      headers={
          'Authorization': 'APIKEY your-api-key'
      }
  )

  css_records = response.json()
  print(css_records)
  ```
</RequestExample>

## Response

<ResponseExample>
  ```json 200 theme={null}
  [
    {
      "ResourceName": "DefaultCSS",
      "Description": "The default CSS",
      "IsDefault": true,
      "ContentType": "text/css"
    },
    {
      "ResourceName": "ArabicCSS",
      "Description": "CSS for Arabic pages",
      "IsDefault": false,
      "ContentType": "text/css"
    }
  ]
  ```

  ```json 401 theme={null}
  {
      "code": -1003,
      "message": "Not authorized to access this resource",
      "moreInfo": "Bad or missing authorization data, expected APIKEY",
      "errorList": null
  }
  ```
</ResponseExample>


# Retrieve CSS Record
Source: https://developers.pcibooking.net/api-reference/general/retrieve-css-record

GET https://service.pcibooking.net/api/resources/stylesheet/{ResourceName}
Retrieve the content of a particular CSS record stored in PCI Booking.

<Card title="Stylesheets Guide" icon="book" href="/account-setup/stylesheets">
  Customize the appearance of hosted forms
</Card>

The response is a single CSS resource item including its full CSS content.

## Error Responses

| HTTP Status | Error Code | Description                                                                 |
| ----------- | ---------- | --------------------------------------------------------------------------- |
| 401         | -1003      | Not authenticated. The API key is missing or invalid.                       |
| 404         |            | Resource not found. No CSS record exists with the specified `ResourceName`. |

## Parameter Constraints

| Parameter      | Constraint                                                            |
| -------------- | --------------------------------------------------------------------- |
| `ResourceName` | Required. Must contain only alphanumeric characters (`[a-zA-Z0-9]+`). |

## Parameters

### Headers

<ParamField type="string">
  Your API key prefixed with `APIKEY`. Example: `APIKEY your-api-key`. See the [Authentication guide](/getting-started/authentication).
</ParamField>

### Path Parameters

<ParamField type="string">
  The resource name assigned to this CSS record. You can view the list of CSS records in the user's site or [retrieve the full list](/api-reference/general/list-css-records) via the API.
</ParamField>

<RequestExample>
  ```javascript Node.js theme={null}
  const response = await fetch('https://service.pcibooking.net/api/resources/stylesheet/DefaultCSS', {
    headers: {
      'Authorization': 'APIKEY your-api-key'
    }
  });

  const cssRecord = await response.json();
  console.log(cssRecord);
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://service.pcibooking.net/api/resources/stylesheet/DefaultCSS',
      headers={
          'Authorization': 'APIKEY your-api-key'
      }
  )

  css_record = response.json()
  print(css_record)
  ```
</RequestExample>

## Response

<ResponseExample>
  ```json 200 theme={null}
  {
      "ResourceName": "DefaultCSS",
      "Description": "The default CSS",
      "ContentLTR": "body { background-color: powderblue; } h1 { color: blue; }",
      "ContentRTL": "",
      "IsDefault": true,
      "ContentType": "text/css"
  }
  ```

  ```json 404 theme={null}
  // Empty body. The specified ResourceName does not exist in your account.
  ```

  ```json 401 theme={null}
  {
      "code": -1003,
      "message": "Not authorized to access this resource",
      "moreInfo": "Bad or missing authorization data, expected APIKEY",
      "errorList": null
  }
  ```
</ResponseExample>


# Start a Temporary Session
Source: https://developers.pcibooking.net/api-reference/general/start-temporary-session

POST https://service.pcibooking.net/api/payments/paycard/tempsession
Start a new session for capturing a customer's payment card.

<Card title="Authentication Guide" icon="book" href="/getting-started/authentication#session-token">
  Learn about session token authentication
</Card>

Creates a short-lived session token from your API key credentials. Use this when you need to authenticate client-side operations (such as card capture forms) without exposing your API key to the browser. The returned token is valid for a single session and expires automatically.

## Error Responses

| Code | HTTP Status | Condition                  |
| ---- | ----------- | -------------------------- |
| -150 | 500         | Memory cache insert failed |

## Parameters

### Headers

<ParamField type="string">
  Your API key prefixed with `APIKEY`. Example: `APIKEY your-api-key`. See the [Authentication guide](/getting-started/authentication).
</ParamField>

<RequestExample>
  ```javascript Node.js theme={null}
  const response = await fetch('https://service.pcibooking.net/api/payments/paycard/tempsession', {
    method: 'POST',
    headers: {
      'Authorization': 'APIKEY your-api-key'
    }
  });

  const sessionToken = await response.json();
  console.log(sessionToken);
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://service.pcibooking.net/api/payments/paycard/tempsession',
      headers={
          'Authorization': 'APIKEY your-api-key'
      }
  )

  session_token = response.json()
  print(session_token)
  ```
</RequestExample>

## Response

<ResponseExample>
  ```json 200 theme={null}
  "1a75885fabe443588488de7d7e7f9980"
  ```

  ```json 401 theme={null}
  {
      "code": -1003,
      "message": "Not authorized to access this resource",
      "moreInfo": "Bad or missing authorization data, expected APIKEY",
      "errorList": null
  }
  ```
</ResponseExample>


# Associate with Customer
Source: https://developers.pcibooking.net/api-reference/manage-tokens/associate-with-customer

PUT https://service.pcibooking.net/api/payments/paycard/{cardToken}/user/{userID}
Associate a token with another PCI Booking customer, allowing them to perform actions on this token.

<Card title="Third-Party Permissions Guide" icon="book" href="/manage-tokens/third-party-permissions">
  Learn how to share tokens with other PCI Booking customers
</Card>

Associates a token with another PCI Booking customer (sub-account), granting them permission to use the token in their own API calls. This is useful in marketplace or platform scenarios where multiple parties need access to the same stored card.

## Error Responses

| Code  | HTTP Status | Condition             |
| ----- | ----------- | --------------------- |
| -1003 | 401         | User is not the owner |
| -179  | 400         | userId is empty       |

## Parameters

### Headers

<ParamField type="string">
  Your API key prefixed with `APIKEY`. Example: `APIKEY your-api-key`. See the [Authentication guide](/getting-started/authentication).
</ParamField>

### Path Parameters

<ParamField type="string">
  The token ID as returned by one of the tokenization methods.
</ParamField>

<ParamField type="string">
  The user ID of a PCI Booking customer ("Booker") that the token should be associated with. You will need to collect this userID from the booker you wish to associate the card with.
</ParamField>

<RequestExample>
  ```javascript Node.js theme={null}
  const response = await fetch(
    'https://service.pcibooking.net/api/payments/paycard/2821a46d80e14d1b96a7f18f1b81926d/user/booker-user-123',
    {
      method: 'PUT',
      headers: {
        'Authorization': 'APIKEY your-api-key'
      }
    }
  );

  console.log(response.status);
  ```

  ```python Python theme={null}
  import requests

  response = requests.put(
      'https://service.pcibooking.net/api/payments/paycard/2821a46d80e14d1b96a7f18f1b81926d/user/booker-user-123',
      headers={'Authorization': 'APIKEY your-api-key'}
  )

  print(response.status_code)
  ```
</RequestExample>

## Response

**200** - Association created. Empty response body.

<ResponseExample>
  ```text 200 theme={null}
  Empty response body. Association created successfully.
  ```

  ```json 400 theme={null}
  {
      "code": -125,
      "message": "Bad input data",
      "moreInfo": "Could not find a valid user",
      "errorList": null
  }
  ```

  ```json 401 theme={null}
  {
      "code": -1003,
      "message": "Not authorized to access this resource",
      "moreInfo": "Bad or missing authorization data, expected APIKEY",
      "errorList": null
  }
  ```
</ResponseExample>


# Clear CVV
Source: https://developers.pcibooking.net/api-reference/manage-tokens/clear-cvv

POST https://service.pcibooking.net/api/payments/paycard/{cardToken}/op/clearcvv
Immediately delete the CVV stored on a token.

Immediately removes the CVV from a token. The card data itself is not affected.

<Card title="CVV Retention Policy Guide" icon="book" href="/capture-cards/cvv-retention-policy">
  Control how long CVV data is retained and who can use it
</Card>

## Error Responses

| Code  | HTTP Status | Condition                                                       |
| ----- | ----------- | --------------------------------------------------------------- |
| -1003 | 401         | User is not the owner of this token                             |
| -125  | 400         | Card not found (when `postponeUntilDate` is provided)           |
| -168  | 409         | Card has no CVV to clear (when `postponeUntilDate` is provided) |
| -179  | 400         | Failed to update CVV retention date                             |
| -150  | 500         | Could not clear CVV (immediate clear operation)                 |

## Parameter Constraints

| Parameter         | Type     | Required | Constraints                                                                                           |
| ----------------- | -------- | -------- | ----------------------------------------------------------------------------------------------------- |
| postponeUntilDate | DateTime | No       | Optional. When provided, defers CVV clearing until the specified date instead of clearing immediately |
| Auth              | string   | Yes      | Basic, ApiKey, AccessToken, or SessionToken                                                           |

## Parameters

### Headers

<ParamField type="string">
  Your API key prefixed with `APIKEY`. Example: `APIKEY your-api-key`. For server-to-server calls.
</ParamField>

<Accordion title="Alternative: Browser-Side Authentication">
  This endpoint also accepts token-based authentication via query parameters:

  | Method                         | Details                                                                                                             |
  | ------------------------------ | ------------------------------------------------------------------------------------------------------------------- |
  | **Access Token** (recommended) | `accessToken` query param. [How to generate](/getting-started/authentication#access-token).                         |
  | **Session Token**              | `sessionToken` query param. [How to generate](/api-reference/general/start-temporary-session). Valid for 5 minutes. |

  If multiple methods are provided, precedence: Session Token > Access Token > API Key.
</Accordion>

### Path Parameters

<ParamField type="string">
  The token ID as returned by one of the tokenization methods.
</ParamField>

<RequestExample>
  ```javascript Node.js theme={null}
  const response = await fetch(
    'https://service.pcibooking.net/api/payments/paycard/2821a46d80e14d1b96a7f18f1b81926d/op/clearcvv',
    {
      method: 'POST',
      headers: {
        'Authorization': 'APIKEY your-api-key'
      }
    }
  );

  console.log(response.status);
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://service.pcibooking.net/api/payments/paycard/2821a46d80e14d1b96a7f18f1b81926d/op/clearcvv',
      headers={'Authorization': 'APIKEY your-api-key'}
  )

  print(response.status_code)
  ```
</RequestExample>

## Response

**200** - CVV cleared. Empty response body.

<ResponseExample>
  ```text 200 theme={null}
  Empty response body. CVV cleared successfully.
  ```

  ```json 401 theme={null}
  {
      "code": -1003,
      "message": "Not authorized to access this resource",
      "moreInfo": "Bad or missing authorization data, expected APIKEY or Temp Session or HTTP Basic or One-Time Accesss Token",
      "errorList": null
  }
  ```
</ResponseExample>


# Delete 3D Secure Data
Source: https://developers.pcibooking.net/api-reference/manage-tokens/delete-3d-token

DELETE https://service.pcibooking.net/api/payments/paycard/{cardToken}/3dToken
Delete the 3D Secure authentication data stored on a token. This does not affect the token itself.

<Card title="3DS Authentication Guide" icon="book" href="/manage-tokens/3ds-auth-management">
  Store and manage 3D Secure authentication data
</Card>

Removes the 3D Secure authentication data from a token. The token itself and all other card data remain intact. Use this when the stored 3DS results have expired or are no longer valid for upcoming transactions.

## Error Responses

| Code  | HTTP Status | Condition                 |
| ----- | ----------- | ------------------------- |
| -1003 | 401         | User is not the owner     |
| -150  | 500         | Failed to delete 3DS data |

## Parameters

### Headers

<ParamField type="string">
  Your API key prefixed with `APIKEY`. Example: `APIKEY your-api-key`. See the [Authentication guide](/getting-started/authentication).
</ParamField>

### Path Parameters

<ParamField type="string">
  The token ID as returned by one of the tokenization methods. For example, `2821a46d80e14d1b96a7f18f1b81926d`.
</ParamField>

<RequestExample>
  ```javascript Node.js theme={null}
  const response = await fetch(
    'https://service.pcibooking.net/api/payments/paycard/2821a46d80e14d1b96a7f18f1b81926d/3dToken',
    {
      method: 'DELETE',
      headers: {
        'Authorization': 'APIKEY your-api-key'
      }
    }
  );

  console.log(response.status);
  ```

  ```python Python theme={null}
  import requests

  response = requests.delete(
      'https://service.pcibooking.net/api/payments/paycard/2821a46d80e14d1b96a7f18f1b81926d/3dToken',
      headers={'Authorization': 'APIKEY your-api-key'}
  )

  print(response.status_code)
  ```
</RequestExample>

## Response

**200** - 3D Secure data deleted. Empty response body.

<ResponseExample>
  ```text 200 theme={null}
  Empty response body. 3D Secure data deleted successfully.
  ```

  ```json 401 theme={null}
  {
      "code": -1003,
      "message": "Not authorized to access this resource",
      "moreInfo": "Bad or missing authorization data, expected APIKEY",
      "errorList": null
  }
  ```
</ResponseExample>


# Delete Creator Reference
Source: https://developers.pcibooking.net/api-reference/manage-tokens/delete-creator-reference

DELETE https://service.pcibooking.net/api/payments/paycard/{token}/creatorReference
Remove the creator reference value from an existing token.

<Card title="Update Card Data Guide" icon="book" href="/manage-tokens/update-card-data">
  Modify expiration dates and creator references on tokens
</Card>

Removes the creator reference label from a token. After deletion, the token can no longer be found via creator reference queries, though the token itself remains intact.

## Error Responses

| Code  | HTTP Status | Condition                         |
| ----- | ----------- | --------------------------------- |
| -1003 | 401         | User is not the owner             |
| -125  | 400         | Removing creator reference failed |

## Parameters

### Headers

<ParamField type="string">
  Your API key prefixed with `APIKEY`. Example: `APIKEY your-api-key`. See the [Authentication guide](/getting-started/authentication).
</ParamField>

### Path Parameters

<ParamField type="string">
  The token ID as returned by one of the tokenization methods. For example, `2821a46d80e14d1b96a7f18f1b81926d`.
</ParamField>

<RequestExample>
  ```javascript Node.js theme={null}
  const response = await fetch(
    'https://service.pcibooking.net/api/payments/paycard/2821a46d80e14d1b96a7f18f1b81926d/creatorReference',
    {
      method: 'DELETE',
      headers: {
        'Authorization': 'APIKEY your-api-key'
      }
    }
  );

  console.log(response.status);
  ```

  ```python Python theme={null}
  import requests

  response = requests.delete(
      'https://service.pcibooking.net/api/payments/paycard/2821a46d80e14d1b96a7f18f1b81926d/creatorReference',
      headers={'Authorization': 'APIKEY your-api-key'}
  )

  print(response.status_code)
  ```
</RequestExample>

## Response

**200** - Creator reference removed successfully.

<ResponseExample>
  ```text 200 theme={null}
  Creator reference deleted successfully. No content returned.
  ```

  ```json 401 theme={null}
  {
      "code": -1003,
      "message": "Not authorized to access this resource",
      "moreInfo": "Bad or missing authorization data, expected APIKEY",
      "errorList": null
  }
  ```

  ```json 404 theme={null}
  {
      "code": -160,
      "message": "Uri not found",
      "moreInfo": "Uri to Bank card not found",
      "errorList": null
  }
  ```
</ResponseExample>


# Delete CVV Retention Policy
Source: https://developers.pcibooking.net/api-reference/manage-tokens/delete-cvv-retention-policy

DELETE https://service.pcibooking.net/api/payments/paycard/{cardToken}/cvv/Restriction
Delete the entire CVV retention policy for a token, reverting to the system-wide default.

Deletes all destination restrictions for this token. The token will revert to the [system-wide default retention policy](/capture-cards/cvv-retention-policy#setting-the-account-wide-default).

<Card title="CVV Retention Policy Guide" icon="book" href="/capture-cards/cvv-retention-policy">
  Control how long CVV data is retained and who can use it
</Card>

## Error Responses

| Code    | HTTP Status | Condition                                                                                                        |
| ------- | ----------- | ---------------------------------------------------------------------------------------------------------------- |
| `-1003` | `401`       | API key is missing or invalid.                                                                                   |
| `-1003` | `401`       | Authenticated user does not have `ForceCVVRetentionPolicy` permission.                                           |
| `-1003` | `401`       | Token does not belong to the authenticated user.                                                                 |
| `-125`  | `400`       | The token does not have a CVV stored.                                                                            |
| `-1010` | `423`       | The retention policy is locked. Either the 60-minute update window has passed, or the CVV has already been used. |
| `-150`  | `500`       | An internal system error occurred.                                                                               |

## Parameters

### Headers

<ParamField type="string">
  Your API key prefixed with `APIKEY`. Example: `APIKEY your-api-key`. See the [Authentication guide](/getting-started/authentication).
</ParamField>

### Path Parameters

<ParamField type="string">
  The token ID as returned by one of the tokenization methods.
</ParamField>

<RequestExample>
  ```javascript Node.js theme={null}
  const response = await fetch(
    'https://service.pcibooking.net/api/payments/paycard/2821a46d80e14d1b96a7f18f1b81926d/cvv/Restriction',
    {
      method: 'DELETE',
      headers: {
        'Authorization': 'APIKEY your-api-key'
      }
    }
  );

  console.log(response.status);
  ```

  ```python Python theme={null}
  import requests

  response = requests.delete(
      'https://service.pcibooking.net/api/payments/paycard/2821a46d80e14d1b96a7f18f1b81926d/cvv/Restriction',
      headers={'Authorization': 'APIKEY your-api-key'}
  )

  print(response.status_code)
  ```
</RequestExample>

## Response

**200** - Policy deleted. Empty JSON object.

<ResponseExample>
  ```text 200 theme={null}
  CVV retention policy deleted successfully. No content returned.
  ```

  ```json 401 theme={null}
  {
      "code": -1003,
      "message": "Not authorized to access this resource",
      "moreInfo": "Bad or missing authorization data, expected APIKEY",
      "errorList": null
  }
  ```
</ResponseExample>


# Delete CVV Retention Policy by Destination Type
Source: https://developers.pcibooking.net/api-reference/manage-tokens/delete-cvv-retention-policy-type

DELETE https://service.pcibooking.net/api/payments/paycard/{cardToken}/cvv/Restriction/{DestinationType}
Remove all destinations of a specific type from the CVV retention policy.

Removes all destinations matching the given type from this token's retention policy. Other destination types remain unaffected. If no destinations remain, the token follows the [system-wide default](/capture-cards/cvv-retention-policy#setting-the-account-wide-default).

<Card title="CVV Retention Policy Guide" icon="book" href="/capture-cards/cvv-retention-policy">
  Control how long CVV data is retained and who can use it
</Card>

## Error Responses

| Code    | HTTP Status | Condition                                                                                                        |
| ------- | ----------- | ---------------------------------------------------------------------------------------------------------------- |
| `-1003` | `401`       | API key is missing or invalid.                                                                                   |
| `-1003` | `401`       | Authenticated user does not have `ForceCVVRetentionPolicy` permission.                                           |
| `-1003` | `401`       | Token does not belong to the authenticated user.                                                                 |
| `-125`  | `400`       | The token does not have a CVV stored.                                                                            |
| `-1010` | `423`       | The retention policy is locked. Either the 60-minute update window has passed, or the CVV has already been used. |
| `-150`  | `500`       | An internal system error occurred.                                                                               |

## Parameters

### Headers

<ParamField type="string">
  Your API key prefixed with `APIKEY`. Example: `APIKEY your-api-key`. See the [Authentication guide](/getting-started/authentication).
</ParamField>

### Path Parameters

<ParamField type="string">
  The token ID as returned by one of the tokenization methods.
</ParamField>

<ParamField type="string">
  One of: `HostName`, `Owner`, `OtherMerchant`, `SFTP`, `OtherUser`. See [destination types](/capture-cards/cvv-retention-policy#destination-types).
</ParamField>

<RequestExample>
  ```javascript Node.js theme={null}
  const response = await fetch(
    'https://service.pcibooking.net/api/payments/paycard/2821a46d80e14d1b96a7f18f1b81926d/cvv/Restriction/HostName',
    {
      method: 'DELETE',
      headers: {
        'Authorization': 'APIKEY your-api-key'
      }
    }
  );

  console.log(response.status);
  ```

  ```python Python theme={null}
  import requests

  response = requests.delete(
      'https://service.pcibooking.net/api/payments/paycard/2821a46d80e14d1b96a7f18f1b81926d/cvv/Restriction/HostName',
      headers={'Authorization': 'APIKEY your-api-key'}
  )

  print(response.status_code)
  ```
</RequestExample>

## Response

**200** - Destinations removed. Empty JSON object.

<ResponseExample>
  ```text 200 theme={null}
  CVV retention policy type deleted successfully. No content returned.
  ```

  ```json 401 theme={null}
  {
      "code": -1003,
      "message": "Not authorized to access this resource",
      "moreInfo": "Bad or missing authorization data, expected APIKEY",
      "errorList": null
  }
  ```
</ResponseExample>


# Delete CVV Retention Policy by Destination
Source: https://developers.pcibooking.net/api-reference/manage-tokens/delete-cvv-retention-policy-type-data

DELETE https://service.pcibooking.net/api/payments/paycard/{cardToken}/cvv/Restriction/{DestinationType}/{DestinationData}
Remove a single destination from the CVV retention policy.

Removes a single destination (matching both type and data) from this token's retention policy. Other destinations remain unaffected. If no destinations remain, the token follows the [system-wide default](/capture-cards/cvv-retention-policy#setting-the-account-wide-default).

<Card title="CVV Retention Policy Guide" icon="book" href="/capture-cards/cvv-retention-policy">
  Control how long CVV data is retained and who can use it
</Card>

## Error Responses

| Code    | HTTP Status | Condition                                                                                                        |
| ------- | ----------- | ---------------------------------------------------------------------------------------------------------------- |
| `-1003` | `401`       | API key is missing or invalid.                                                                                   |
| `-1003` | `401`       | Authenticated user does not have `ForceCVVRetentionPolicy` permission.                                           |
| `-1003` | `401`       | Token does not belong to the authenticated user.                                                                 |
| `-125`  | `400`       | The token does not have a CVV stored.                                                                            |
| `-1010` | `423`       | The retention policy is locked. Either the 60-minute update window has passed, or the CVV has already been used. |
| `-150`  | `500`       | An internal system error occurred.                                                                               |

## Parameters

### Headers

<ParamField type="string">
  Your API key prefixed with `APIKEY`. Example: `APIKEY your-api-key`. See the [Authentication guide](/getting-started/authentication).
</ParamField>

### Path Parameters

<ParamField type="string">
  The token ID as returned by one of the tokenization methods.
</ParamField>

<ParamField type="string">
  One of: `HostName`, `Owner`, `OtherMerchant`, `SFTP`, `OtherUser`. See [destination types](/capture-cards/cvv-retention-policy#destination-types).
</ParamField>

<ParamField type="string">
  The target identifier for this destination (e.g. hostname, user ID, IP address).
</ParamField>

<RequestExample>
  ```javascript Node.js theme={null}
  const response = await fetch(
    'https://service.pcibooking.net/api/payments/paycard/2821a46d80e14d1b96a7f18f1b81926d/cvv/Restriction/HostName/gateway.example.com',
    {
      method: 'DELETE',
      headers: {
        'Authorization': 'APIKEY your-api-key'
      }
    }
  );

  console.log(response.status);
  ```

  ```python Python theme={null}
  import requests

  response = requests.delete(
      'https://service.pcibooking.net/api/payments/paycard/2821a46d80e14d1b96a7f18f1b81926d/cvv/Restriction/HostName/gateway.example.com',
      headers={'Authorization': 'APIKEY your-api-key'}
  )

  print(response.status_code)
  ```
</RequestExample>

## Response

**200** - Destination removed. Empty JSON object.

<ResponseExample>
  ```text 200 theme={null}
  CVV retention policy type data deleted successfully. No content returned.
  ```

  ```json 401 theme={null}
  {
      "code": -1003,
      "message": "Not authorized to access this resource",
      "moreInfo": "Bad or missing authorization data, expected APIKEY",
      "errorList": null
  }
  ```
</ResponseExample>


# Delete Token
Source: https://developers.pcibooking.net/api-reference/manage-tokens/delete-token

DELETE https://service.pcibooking.net/api/payments/paycard/{cardToken}
Permanently delete a token and its associated card data from PCI Booking.

<Card title="Delete Tokens Guide" icon="book" href="/manage-tokens/delete-tokens">
  Permanently remove tokens from the system
</Card>

<Warning>
  Deleting a token is permanent and cannot be undone.
</Warning>

Permanently deletes a token and all associated card data from PCI Booking. Use this to remove cards that are no longer needed, such as expired reservations or cancelled bookings, to stop incurring monthly storage fees.

## Error Responses

| Code  | HTTP Status | Condition                           |
| ----- | ----------- | ----------------------------------- |
| -160  | 404         | Token not found or already deleted  |
| -1003 | 401         | User is not the owner of this token |
| -125  | 400         | Delete operation failed             |

## Parameters

### Headers

<ParamField type="string">
  Your API key prefixed with `APIKEY`. Example: `APIKEY your-api-key`. See the [Authentication guide](/getting-started/authentication).
</ParamField>

### Path Parameters

<ParamField type="string">
  The token ID as returned by one of the tokenization methods. For example, `2821a46d80e14d1b96a7f18f1b81926d`.
</ParamField>

<RequestExample>
  ```javascript Node.js theme={null}
  const response = await fetch(
    'https://service.pcibooking.net/api/payments/paycard/2821a46d80e14d1b96a7f18f1b81926d',
    {
      method: 'DELETE',
      headers: {
        'Authorization': 'APIKEY your-api-key'
      }
    }
  );

  console.log(response.status);
  ```

  ```python Python theme={null}
  import requests

  response = requests.delete(
      'https://service.pcibooking.net/api/payments/paycard/2821a46d80e14d1b96a7f18f1b81926d',
      headers={'Authorization': 'APIKEY your-api-key'}
  )

  print(response.status_code)
  ```
</RequestExample>

## Response

**200** - Token deleted. Empty response body.

<ResponseExample>
  ```text 200 theme={null}
  Token deleted successfully. No content returned.
  ```

  ```json 401 theme={null}
  {
      "code": -1003,
      "message": "Not authorized to access this resource",
      "moreInfo": "Bad or missing authorization data, expected APIKEY",
      "errorList": null
  }
  ```
</ResponseExample>


# Disassociate from Customer
Source: https://developers.pcibooking.net/api-reference/manage-tokens/disassociate-from-customer

DELETE https://service.pcibooking.net/api/payments/paycard/{cardToken}/user/{userID}
Remove a customer association from a token. The customer will no longer have access to perform actions on this token.

<Card title="Third-Party Permissions Guide" icon="book" href="/manage-tokens/third-party-permissions">
  Learn how to share tokens with other PCI Booking customers
</Card>

Removes a customer association from a token, revoking that customer's access to use it. The token itself is not deleted and remains available to its owner and any other associated customers.

## Error Responses

| Code  | HTTP Status | Condition             |
| ----- | ----------- | --------------------- |
| -1003 | 401         | User is not the owner |
| -125  | 400         | UserId not found      |
| -150  | 500         | Disassociation failed |

## Parameters

### Headers

<ParamField type="string">
  Your API key prefixed with `APIKEY`. Example: `APIKEY your-api-key`. See the [Authentication guide](/getting-started/authentication).
</ParamField>

### Path Parameters

<ParamField type="string">
  The token ID as returned by one of the tokenization methods.
</ParamField>

<ParamField type="string">
  The user ID of the PCI Booking customer ("Booker") that the token should be disassociated from. You will need to collect this userID from the booker you wish to disassociate.
</ParamField>

<RequestExample>
  ```javascript Node.js theme={null}
  const response = await fetch(
    'https://service.pcibooking.net/api/payments/paycard/2821a46d80e14d1b96a7f18f1b81926d/user/booker-user-123',
    {
      method: 'DELETE',
      headers: {
        'Authorization': 'APIKEY your-api-key'
      }
    }
  );

  console.log(response.status);
  ```

  ```python Python theme={null}
  import requests

  response = requests.delete(
      'https://service.pcibooking.net/api/payments/paycard/2821a46d80e14d1b96a7f18f1b81926d/user/booker-user-123',
      headers={'Authorization': 'APIKEY your-api-key'}
  )

  print(response.status_code)
  ```
</RequestExample>

## Response

**200** - Association removed. Empty response body.

<ResponseExample>
  ```text 200 theme={null}
  Empty response body. Association removed successfully.
  ```

  ```json 400 theme={null}
  {
      "code": -125,
      "message": "Bad input data",
      "moreInfo": "Could not find a valid user",
      "errorList": null
  }
  ```

  ```json 401 theme={null}
  {
      "code": -1003,
      "message": "Not authorized to access this resource",
      "moreInfo": "Bad or missing authorization data, expected APIKEY",
      "errorList": null
  }
  ```
</ResponseExample>


# Duplicate Token
Source: https://developers.pcibooking.net/api-reference/manage-tokens/duplicate-token

POST https://service.pcibooking.net/api/payments/paycard/duplicate
Create a copy of an existing token, optionally adding a CVV and specifying property association and creator reference.

<Card title="Update Card Data Guide" icon="book" href="/manage-tokens/update-card-data">
  Modify expiration dates and creator references on tokens
</Card>

Once the `Duplicate Token` method has been completed successfully, a new card token will be created and the token URI will be returned in the response header `Location`.

The result of this process would be that there are two card tokens in PCI Booking for the same card.
**It is your responsibility** to [delete](/api-reference/manage-tokens/delete-token) one of them to avoid getting charged for storage on both tokens.

## Error Responses

| Code  | HTTP Status | Condition                                                  |
| ----- | ----------- | ---------------------------------------------------------- |
| -179  | 400         | CVV provided but does not match `^\d{3,4}$`                |
| -160  | 404         | Card URI is invalid or card not found                      |
| -1003 | 401         | User is not the owner and is not associated with this card |

## Parameter Constraints

| Parameter | Type   | Required | Constraints                                         |
| --------- | ------ | -------- | --------------------------------------------------- |
| cardUri   | string | Yes      | Must contain a valid 32-character hexadecimal token |
| cvv       | string | No       | If provided, must match `^\d{3,4}$` (3 or 4 digits) |

<Note>This endpoint is rate limited.</Note>

## Parameters

### Headers

<ParamField type="string">
  Your API key prefixed with `APIKEY`. Example: `APIKEY your-api-key`. For server-to-server calls.
</ParamField>

<Accordion title="Alternative: Browser-Side Authentication">
  This endpoint also accepts token-based authentication via query parameters:

  | Method                         | Details                                                                                                             |
  | ------------------------------ | ------------------------------------------------------------------------------------------------------------------- |
  | **Access Token** (recommended) | `accessToken` query param. [How to generate](/getting-started/authentication#access-token).                         |
  | **Session Token**              | `sessionToken` query param. [How to generate](/api-reference/general/start-temporary-session). Valid for 5 minutes. |

  If multiple methods are provided, precedence: Session Token > Access Token > API Key.
</Accordion>

### Query String

<ParamField type="string">
  The card URI (resource identifier for the card location within PCI Booking). For example, `https://service.pcibooking.net/api/payments/paycard/865ed8bec1f84366b97112a69cdbf915`. The card URI should be URL encoded.
</ParamField>

<ParamField type="string">
  Security code, as returned from the iFrame or other sources. If not provided, the new token will not contain any CVV.
</ParamField>

<ParamField type="string">
  A reference value that can be used to query for this card token.
</ParamField>

<ParamField type="string">
  The Property's Username (user ID) found within PCI Booking (under "Property settings") which has been given permission to view the card. The owner (Booker) always has permission to view the card.
</ParamField>

<RequestExample>
  ```javascript Node.js theme={null}
  const params = new URLSearchParams({
    cardUri: 'https://service.pcibooking.net/api/payments/paycard/865ed8bec1f84366b97112a69cdbf915',
    cvv: '123',
    ref: 'booking-12345',
    merchant: 'hotel-sunrise'
  });

  const response = await fetch(
    `https://service.pcibooking.net/api/payments/paycard/duplicate?${params}`,
    {
      method: 'POST',
      headers: {
        'Authorization': 'APIKEY your-api-key'
      }
    }
  );

  const newTokenUri = response.headers.get('Location');
  console.log('New token URI:', newTokenUri);
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://service.pcibooking.net/api/payments/paycard/duplicate',
      headers={'Authorization': 'APIKEY your-api-key'},
      params={
          'cardUri': 'https://service.pcibooking.net/api/payments/paycard/865ed8bec1f84366b97112a69cdbf915',
          'cvv': '123',
          'ref': 'booking-12345',
          'merchant': 'hotel-sunrise'
      }
  )

  new_token_uri = response.headers.get('Location')
  print('New token URI:', new_token_uri)
  ```
</RequestExample>

## Response

**200** - Card duplicated. A `Location` header is returned with the new token URI.

<Info>
  Remember to set the [CVV Retention Policy](/capture-cards/cvv-retention-policy) on the new token if it includes a CVV.
</Info>

<ResponseExample>
  ```xml 200 theme={null}
  <?xml version='1.0' encoding='utf-8'?>
  <BankCard>
      <Type>Visa</Type>
      <Number>491891******5005</Number>
      <NameOnCard>Juan Dela Cruz</NameOnCard>
      <ExpirationDate>
          <Month>07</Month>
          <Year>2020</Year>
      </ExpirationDate>
      <IssueNumber>2</IssueNumber>
  </BankCard>
  ```

  ```json 401 theme={null}
  {
      "code": -1003,
      "message": "Not authorized to access this resource",
      "moreInfo": "Bad or missing authorization data, expected APIKEY or Temp Session or One-Time Accesss Token",
      "errorList": null
  }
  ```
</ResponseExample>


# Get CVV Retention Policy
Source: https://developers.pcibooking.net/api-reference/manage-tokens/get-cvv-retention-policy

GET https://service.pcibooking.net/api/payments/paycard/{cardToken}/cvv/Restriction
Retrieve the full CVV retention policy for a token, including per-destination usage counts.

Returns the retention policy for this token, including how many times the CVV has been sent to each destination.

<Card title="CVV Retention Policy Guide" icon="book" href="/capture-cards/cvv-retention-policy">
  Control how long CVV data is retained and who can use it
</Card>

## Error Responses

| Code    | HTTP Status | Condition                                                              |
| ------- | ----------- | ---------------------------------------------------------------------- |
| `-1003` | `401`       | API key is missing or invalid.                                         |
| `-1003` | `401`       | Authenticated user does not have `ForceCVVRetentionPolicy` permission. |
| `-1003` | `401`       | Token does not belong to the authenticated user.                       |
| `-125`  | `400`       | The token does not have a CVV stored.                                  |
| `-160`  | `404`       | No CVV retention policy has been set on this token.                    |
| `-150`  | `500`       | An internal system error occurred while retrieving the policy.         |

## Parameters

### Path Parameters

<ParamField type="string">
  The token ID as returned by one of the tokenization methods.
</ParamField>

### Headers

<ParamField type="string">
  Your API key prefixed with `APIKEY`. Example: `APIKEY your-api-key`. See the [Authentication guide](/getting-started/authentication).
</ParamField>

<ParamField type="string">
  Set to `application/xml` to receive the response in XML format.
</ParamField>

<RequestExample>
  ```javascript Node.js theme={null}
  const response = await fetch(
    'https://service.pcibooking.net/api/payments/paycard/2821a46d80e14d1b96a7f18f1b81926d/cvv/Restriction',
    {
      headers: {
        'Authorization': 'APIKEY your-api-key'
      }
    }
  );

  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://service.pcibooking.net/api/payments/paycard/2821a46d80e14d1b96a7f18f1b81926d/cvv/Restriction',
      headers={'Authorization': 'APIKEY your-api-key'}
  )

  print(response.json())
  ```
</RequestExample>

## Response

The response mirrors the structure of the [Set CVV Retention Policy](/api-reference/manage-tokens/set-cvv-retention-policy) request body, with an additional `CvvDestinationUsage` field per destination showing how many times the CVV has already been sent there.

<ResponseExample>
  ```json 200 Custom policy theme={null}
  {
      "CvvEndRetentionDate": "2025-12-12T12:32:45",
      "DeleteCardUponCvvCleanup": "true",
      "CvvRetentionPolicyList": [
          {
              "CvvDestinationUsage": 3,
              "DestinationType": "HostName",
              "DestinationData": "gateway.example.com",
              "Quota": 10
          }
      ]
  }
  ```

  ```json 200 System default theme={null}
  {
      "CvvEndRetentionDate": "2025-01-12T20:02:26",
      "CvvRetentionPolicyList": []
  }
  ```

  ```json 401 theme={null}
  {
      "code": -1003,
      "message": "Not authorized to access this resource",
      "moreInfo": "Bad or missing authorization data, expected APIKEY",
      "errorList": null
  }
  ```
</ResponseExample>


# Get CVV Retention Policy for Specific Destination
Source: https://developers.pcibooking.net/api-reference/manage-tokens/get-cvv-retention-policy-specific

GET https://service.pcibooking.net/api/payments/paycard/{cardToken}/cvv/Restriction/{DestinationType}/{DestinationData}
Retrieve the CVV retention policy for a single destination, including its usage count.

Returns the retention policy for a single destination on this token, including how many times the CVV has been sent there.

<Card title="CVV Retention Policy Guide" icon="book" href="/capture-cards/cvv-retention-policy">
  Control how long CVV data is retained and who can use it
</Card>

## Error Responses

| Code    | HTTP Status | Condition                                                                 |
| ------- | ----------- | ------------------------------------------------------------------------- |
| `-1003` | `401`       | API key is missing or invalid.                                            |
| `-1003` | `401`       | Authenticated user does not have `ForceCVVRetentionPolicy` permission.    |
| `-1003` | `401`       | Token does not belong to the authenticated user.                          |
| `-125`  | `400`       | The token does not have a CVV stored.                                     |
| `-160`  | `404`       | The specified destination does not exist in the token's retention policy. |
| `-150`  | `500`       | An internal system error occurred while retrieving the destination.       |

## Parameter Constraints

* **DestinationType**: Must be a valid destination type. Accepted values: `HostName`, `Owner`, `OtherMerchant`, `SFTP`, `OtherUser`, `Upg`, `IpAddress`, `GeneralProperty`, `OtpCardView`, `Any`.
* **DestinationData**: The format depends on the `DestinationType` (e.g. a valid hostname, IP address, or user ID).

## Parameters

### Headers

<ParamField type="string">
  Your API key prefixed with `APIKEY`. Example: `APIKEY your-api-key`. See the [Authentication guide](/getting-started/authentication).
</ParamField>

### Path Parameters

<ParamField type="string">
  The token ID as returned by one of the tokenization methods.
</ParamField>

<ParamField type="string">
  One of: `HostName`, `Owner`, `OtherMerchant`, `SFTP`, `OtherUser`. See [destination types](/capture-cards/cvv-retention-policy#destination-types).
</ParamField>

<ParamField type="string">
  The target identifier for this destination type (e.g. hostname, user ID, IP address).
</ParamField>

<RequestExample>
  ```javascript Node.js theme={null}
  const response = await fetch(
    'https://service.pcibooking.net/api/payments/paycard/2821a46d80e14d1b96a7f18f1b81926d/cvv/Restriction/HostName/gateway.example.com',
    {
      headers: {
        'Authorization': 'APIKEY your-api-key'
      }
    }
  );

  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://service.pcibooking.net/api/payments/paycard/2821a46d80e14d1b96a7f18f1b81926d/cvv/Restriction/HostName/gateway.example.com',
      headers={'Authorization': 'APIKEY your-api-key'}
  )

  print(response.json())
  ```
</RequestExample>

## Response

<ResponseExample>
  ```json 200 theme={null}
  {
      "CvvDestinationUsage": 3,
      "DestinationType": "HostName",
      "DestinationData": "gateway.example.com",
      "Quota": 10
  }
  ```

  ```json 401 theme={null}
  {
      "code": -1003,
      "message": "Not authorized to access this resource",
      "moreInfo": "Bad or missing authorization data, expected APIKEY",
      "errorList": null
  }
  ```
</ResponseExample>


# List Customer Associations
Source: https://developers.pcibooking.net/api-reference/manage-tokens/list-customer-associations

GET https://service.pcibooking.net/api/payments/paycard/{cardToken}/users
Retrieve a list of all PCI Booking customers associated with this token.

<Card title="Third-Party Permissions Guide" icon="book" href="/manage-tokens/third-party-permissions">
  Learn how to share tokens with other PCI Booking customers
</Card>

The successful response to this request will include an array of IDs that are associated with this token.

## Error Responses

| Code  | HTTP Status | Condition             |
| ----- | ----------- | --------------------- |
| -1003 | 401         | User is not the owner |

## Parameters

### Headers

<ParamField type="string">
  Your API key prefixed with `APIKEY`. Example: `APIKEY your-api-key`. See the [Authentication guide](/getting-started/authentication).
</ParamField>

### Path Parameters

<ParamField type="string">
  The token ID as returned by one of the tokenization methods.
</ParamField>

<RequestExample>
  ```javascript Node.js theme={null}
  const response = await fetch(
    'https://service.pcibooking.net/api/payments/paycard/2821a46d80e14d1b96a7f18f1b81926d/users',
    {
      headers: {
        'Authorization': 'APIKEY your-api-key'
      }
    }
  );

  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://service.pcibooking.net/api/payments/paycard/2821a46d80e14d1b96a7f18f1b81926d/users',
      headers={'Authorization': 'APIKEY your-api-key'}
  )

  print(response.json())
  ```
</RequestExample>

## Response

<ResponseExample>
  ```json 200 theme={null}
  [
      "tpPMiFSB"
  ]
  ```

  ```json 401 theme={null}
  {
      "code": -1003,
      "message": "Not authorized to access this resource",
      "moreInfo": "Bad or missing authorization data, expected APIKEY",
      "errorList": null
  }
  ```
</ResponseExample>


# Manage Tokens API Reference
Source: https://developers.pcibooking.net/api-reference/manage-tokens/overview

API endpoints for token management: query, update, duplicate, delete tokens, CVV retention policies, and customer/property associations

API endpoints for managing card tokens stored in PCI Booking. For concepts and guidance, see the [Manage Tokens guide](/manage-tokens/overview).

## Query & Update

| Endpoint                                                                          | Description                                                                                                               |
| --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| [Query Tokens](/api-reference/manage-tokens/query-tokens)                         | Search for tokens by reference or associated property.                                                                    |
| [Retrieve Token Metadata](/api-reference/manage-tokens/retrieve-token-metadata)   | Get non-sensitive metadata for a single token (card type, masked number, expiration, CVV status, 3DS data, associations). |
| [Update Expiration](/api-reference/manage-tokens/update-expiration)               | Update the expiration date on a stored card.                                                                              |
| [Update Creator Reference](/api-reference/manage-tokens/update-creator-reference) | Set or update the reference value on a token.                                                                             |
| [Delete Creator Reference](/api-reference/manage-tokens/delete-creator-reference) | Remove the reference value from a token.                                                                                  |
| [Transfer Ownership](/api-reference/manage-tokens/transfer-ownership)             | Transfer a token to another PCI Booking account.                                                                          |
| [Duplicate Token](/api-reference/manage-tokens/duplicate-token)                   | Create a copy of an existing token.                                                                                       |
| [Delete Token](/api-reference/manage-tokens/delete-token)                         | Permanently delete a token from the vault.                                                                                |

## CVV Management

| Endpoint                                                                      | Description                                               |
| ----------------------------------------------------------------------------- | --------------------------------------------------------- |
| [CVV Management Guide](/manage-tokens/cvv-management)                         | Overview of CVV operations.                               |
| [Request CVV Entry Form](/api-reference/manage-tokens/request-cvv-entry-form) | Generate a secure CVV capture form for an existing token. |
| [Clear CVV](/api-reference/manage-tokens/clear-cvv)                           | Remove CVV data from a token.                             |

## CVV Retention Policy

| Endpoint                                                                                                        | Description                                        |
| --------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
| [CVV Retention Policy Guide](/capture-cards/cvv-retention-policy)                                               | Overview of CVV retention policy management.       |
| [Set CVV Retention Policy](/api-reference/manage-tokens/set-cvv-retention-policy)                               | Create or update a CVV retention policy.           |
| [Get CVV Retention Policy](/api-reference/manage-tokens/get-cvv-retention-policy)                               | Retrieve all CVV retention policies.               |
| [Get CVV Retention Policy (Specific)](/api-reference/manage-tokens/get-cvv-retention-policy-specific)           | Retrieve a specific CVV retention policy.          |
| [Delete CVV Retention Policy](/api-reference/manage-tokens/delete-cvv-retention-policy)                         | Delete all CVV retention policies.                 |
| [Delete CVV Retention Policy (Type)](/api-reference/manage-tokens/delete-cvv-retention-policy-type)             | Delete CVV retention policies for a specific type. |
| [Delete CVV Retention Policy (Type + Data)](/api-reference/manage-tokens/delete-cvv-retention-policy-type-data) | Delete a specific CVV retention policy entry.      |

## 3D Secure

| Endpoint                                                             | Description                                    |
| -------------------------------------------------------------------- | ---------------------------------------------- |
| [3D Secure Authentication Guide](/manage-tokens/3ds-auth-management) | Overview of 3DS data management.               |
| [Store 3D Token](/api-reference/manage-tokens/store-3d-token)        | Store 3DS authentication data on a token.      |
| [Retrieve 3D Token](/api-reference/manage-tokens/retrieve-3d-token)  | Retrieve 3DS authentication data from a token. |
| [Delete 3D Token](/api-reference/manage-tokens/delete-3d-token)      | Remove 3DS authentication data from a token.   |

## Customer Associations

| Endpoint                                                                              | Description                                    |
| ------------------------------------------------------------------------------------- | ---------------------------------------------- |
| [Customer Associations](/manage-tokens/third-party-permissions)                       | Overview of token-to-customer associations.    |
| [Associate with Customer](/api-reference/manage-tokens/associate-with-customer)       | Associate a token with a PCI Booking customer. |
| [Disassociate from Customer](/api-reference/manage-tokens/disassociate-from-customer) | Remove a customer association from a token.    |
| [List Customer Associations](/api-reference/manage-tokens/list-customer-associations) | List all customers associated with a token.    |


# Query Tokens
Source: https://developers.pcibooking.net/api-reference/manage-tokens/query-tokens

GET https://service.pcibooking.net/api/payments/paycard/meta
Search for tokens by creator reference. Returns metadata for up to 100 matching tokens, with pagination support.

<Card title="Query & Retrieve Guide" icon="book" href="/manage-tokens/query-retrieve">
  Search for tokens and retrieve their metadata
</Card>

Use this endpoint to search for stored card tokens by the reference value you assigned during tokenization. It returns metadata (card type, last digits, expiration, associations) for up to 100 matching tokens per request, with pagination support for larger result sets.

## Parameter Constraints

| Parameter | Type    | Required | Constraints                                                |
| --------- | ------- | -------- | ---------------------------------------------------------- |
| to        | integer | No       | Maximum number of results to return. Defaults to `100`     |
| from      | integer | No       | Pagination offset (chronological counter). Defaults to `0` |
| ref       | string  | No       | Filter by creator reference value (exact match)            |
| property  | string  | No       | Filter by associated property ID                           |

<Note>This endpoint is rate limited. Standard authentication errors apply (code -1003, HTTP 401).</Note>

## Parameters

### Headers

<ParamField type="string">
  Your API key prefixed with `APIKEY`. Example: `APIKEY your-api-key`. See the [Authentication guide](/getting-started/authentication).
</ParamField>

### Query String

<ParamField type="string">
  The reference value provided during tokenization to locate this token. Exact match only.
</ParamField>

<ParamField type="integer">
  Chronological counter of tokens from which to start retrieving.
</ParamField>

<ParamField type="integer">
  The number of tokens to return in the response.
</ParamField>

<ParamField type="string">
  The property ID of the hotel the tokens were associated with. You would have used [this method](/api-reference/manage-tokens/associate-with-customer) to set up the association first.
</ParamField>

## Request Example

Query all tokens created with the reference `booking-12345`, returning the first 10 results:

<Tabs>
  <Tab title="curl">
    ```bash theme={null}
    curl -G "https://service.pcibooking.net/api/payments/paycard/meta" \
      -H "Authorization: APIKEY your-api-key" \
      --data-urlencode "ref=booking-12345" \
      --data-urlencode "from=0" \
      --data-urlencode "to=10"
    ```
  </Tab>

  <Tab title="Node.js">
    ```javascript theme={null}
    const params = new URLSearchParams({
      ref: "booking-12345",
      from: "0",
      to: "10"
    });

    const response = await fetch(
      `https://service.pcibooking.net/api/payments/paycard/meta?${params}`,
      {
        headers: {
          "Authorization": "APIKEY your-api-key"
        }
      }
    );

    const data = await response.json();
    console.log(data);
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import requests

    response = requests.get(
        "https://service.pcibooking.net/api/payments/paycard/meta",
        headers={"Authorization": "APIKEY your-api-key"},
        params={
            "ref": "booking-12345",
            "from": 0,
            "to": 10
        }
    )

    print(response.json())
    ```
  </Tab>
</Tabs>

To filter by property, add the `property` parameter:

<Tabs>
  <Tab title="curl">
    ```bash theme={null}
    curl -G "https://service.pcibooking.net/api/payments/paycard/meta" \
      -H "Authorization: APIKEY your-api-key" \
      --data-urlencode "ref=booking-12345" \
      --data-urlencode "property=hotel-sunrise"
    ```
  </Tab>

  <Tab title="Node.js">
    ```javascript theme={null}
    const params = new URLSearchParams({
      ref: "booking-12345",
      property: "hotel-sunrise"
    });

    const response = await fetch(
      `https://service.pcibooking.net/api/payments/paycard/meta?${params}`,
      {
        headers: {
          "Authorization": "APIKEY your-api-key"
        }
      }
    );

    const data = await response.json();
    console.log(data);
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import requests

    response = requests.get(
        "https://service.pcibooking.net/api/payments/paycard/meta",
        headers={"Authorization": "APIKEY your-api-key"},
        params={
            "ref": "booking-12345",
            "property": "hotel-sunrise"
        }
    )

    print(response.json())
    ```
  </Tab>
</Tabs>

<RequestExample>
  ```javascript Node.js theme={null}
  const params = new URLSearchParams({
    ref: 'booking-12345',
    from: '0',
    to: '10'
  });

  const response = await fetch(
    `https://service.pcibooking.net/api/payments/paycard/meta?${params}`,
    {
      headers: {
        'Authorization': 'APIKEY your-api-key'
      }
    }
  );

  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://service.pcibooking.net/api/payments/paycard/meta',
      headers={'Authorization': 'APIKEY your-api-key'},
      params={
          'ref': 'booking-12345',
          'from': 0,
          'to': 10
      }
  )

  print(response.json())
  ```
</RequestExample>

## Response

**200** - An array of token metadata objects. Each item contains the fields below. For the single-token equivalent (which also returns `CreatorReference` and `VirtualInfo`), see [Retrieve Token Metadata](/api-reference/manage-tokens/retrieve-token-metadata).

<ParamField type="string">
  The date and time the token was created (ISO 8601).
</ParamField>

<ParamField type="string">
  The card brand (e.g. `Visa`, `Mastercard`, `Amex`). See [supported card types](/reference/card-types).
</ParamField>

<ParamField type="string">
  The first 6 digits (BIN) of the card number.
</ParamField>

<ParamField type="string">
  The last 4 digits of the card number.
</ParamField>

<ParamField type="integer">
  The card expiration year.
</ParamField>

<ParamField type="integer">
  The card expiration month.
</ParamField>

<ParamField type="string">
  The cardholder ID, if provided at tokenization time.
</ParamField>

<ParamField type="string">
  The name on the card, if provided at tokenization time.
</ParamField>

<ParamField type="string">
  The PCI Booking user ID that owns this token.
</ParamField>

<ParamField type="string">
  The card issue number (used by some card schemes).
</ParamField>

<ParamField type="string">
  The full token URI for use in API calls.
</ParamField>

<ParamField type="boolean">
  Whether CVV data is currently stored on this token.
</ParamField>

<ParamField type="string">
  The date after which the CVV will be automatically deleted (ISO 8601). Reflects the [CVV retention policy](/capture-cards/cvv-retention-policy).
</ParamField>

<ParamField type="string[]">
  List of PCI Booking customer (booker) user IDs associated with this token.
</ParamField>

<ParamField type="string[]">
  List of property user IDs associated with this token.
</ParamField>

<ParamField type="object">
  3D Secure authentication data, if stored on this token. See [3D Secure Authentication](/manage-tokens/3ds-auth-management) for field details.
</ParamField>

<ParamField type="string">
  The card network scheme if this is a network token (e.g. `Visa`, `Mastercard`). `null` for regular cards.
</ParamField>

<ParamField type="string">
  The network token identifier assigned by the card scheme. `null` for regular cards.
</ParamField>

<ParamField type="string">
  The geographic storage location of the token data. `null` for default (in-table) storage.
</ParamField>

<ResponseExample>
  ```json 200 theme={null}
  [
      {
          "CreateDate": "2020-05-19T16:51:00",
          "CardType": "Visa",
          "LastDigits": "5005",
          "LeadingDigits": "491891",
          "ExpirationYear": 2020,
          "ExpirationMonth": 7,
          "OwnerID": "",
          "OwnerName": "Juan Dela Cruz",
          "UserID": "myUser",
          "IssueNumber": "2",
          "URI": "https://service.pcibooking.net/api/payments/paycard/eb454e0462d548ddbc6e6c2193b749a9",
          "EndRetentionDate": "2017-07-08T00:00:00",
          "CvvExists": true,
          "AssociatedMerchants": ["userID1", "userID2"],
          "AssociatedProperties": ["hotel1", "hotel2"],
          "ThreeDSecureInfo": {
              "Token": "42c775efa8b04b1d8bf14ef49a9e45e5",
              "ThreeDSSessionID": "uOrDbh0dEimUDmB3Vvn2f5CAM9B1bMQX",
              "Indication": "Authenticated",
              "AuthenticationValue": "AJkBAoEREQAAAAB4hABwcAAAAAA=",
              "Eci": "05",
              "XID": "861433f4-abff-4c40-b2fd-fea208856a33",
              "AcsTransactionId": "e7a46959-9630-413e-ab56-4e399b96244a",
              "Version": "2.1.0",
              "MerchantName": "PCI Booking * Hotelreservation"
          },
          "NetworkTokenScheme": null,
          "NetworkTokenId": null,
          "TokenLocation": null
      }
  ]
  ```

  ```json 401 theme={null}
  {
      "code": -1003,
      "message": "Not authorized to access this resource",
      "moreInfo": "Bad or missing authorization data, expected APIKEY",
      "errorList": null
  }
  ```
</ResponseExample>


# Request a Card Security Code Entry Form
Source: https://developers.pcibooking.net/api-reference/manage-tokens/request-cvv-entry-form

GET https://service.pcibooking.net/api/payments/cvvcapturecard
Create a PCI Booking CVV capture form for use in an iFrame.

<Card title="CVV Capture Guide" icon="book" href="/capture-cards/cvv-capture">
  Collect CVV from cardholders via hosted forms
</Card>

The response is the HTML content of the CVV capture form itself. You can use the request URL either as the page URL that a customer is directed to or as the source URL of an iframe element on your page.

<Warning>
  Submitting this form creates a **new token** that is a full copy of the original card details plus the captured CVV. The original token is not modified and does not contain the CVV. You are responsible for [deleting](/api-reference/manage-tokens/delete-token) the original token if it is no longer needed, otherwise it will continue to incur monthly storage fees. Remember to set the [CVV Retention Policy](/capture-cards/cvv-retention-policy) on the new token.
</Warning>

## Parameters

### Authentication

<Warning>
  This is a browser-facing endpoint. Use one of the authentication methods below instead of the API key shown above.
</Warning>

<ParamField type="string">
  Recommended. A long-lived token for browser-side calls. [How to generate](/getting-started/authentication#access-token).
</ParamField>

<ParamField type="string">
  Alternative. Valid for 5 minutes. [How to generate](/api-reference/general/start-temporary-session).
</ParamField>

If both are provided, the session token takes precedence.

### Form Configuration

<ParamField type="string">
  Your PCI Booking username, used to identify your account.
</ParamField>

<ParamField type="string">
  The resource identifier (URI) for the card location within PCI Booking.
</ParamField>

<ParamField type="string">
  The form's language in ISO 639-1 (2-letter) format - [see here](/account-setup/custom-translations). If an unsupported language is provided, English will be displayed. To add languages, [contact support](mailto:support@pcibooking.net).
</ParamField>

<ParamField type="string">
  The CSS resource name. See the guide on [managing stylesheets](/account-setup/stylesheets). If omitted, the [default CSS](/account-setup/stylesheets) is applied.
</ParamField>

<ParamField type="boolean">
  Whether to remove the PCI Booking base CSS. The base CSS does not collide with the host site's CSS. **true**: remove base CSS. **false**: use base CSS.
</ParamField>

<ParamField type="string">
  URL to redirect to on successful submission. See [success/failure redirection pages](/account-setup/success-and-failure-urls).
</ParamField>

<ParamField type="string">
  URL to redirect to on failed submission. See [success/failure redirection pages](/account-setup/success-and-failure-urls).
</ParamField>

<ParamField type="boolean">
  Whether to exclude the PCI Booking submit button, allowing the host site to use its own button. **true**: exclude submit button. **false**: include submit button. See [postMessage integration](/account-setup/success-and-failure-urls).
</ParamField>

<ParamField type="boolean">
  Whether the card security code field receives focus when the parent page loads.
</ParamField>

<ParamField type="string">
  The domain name of the host site where the iframe is displayed.
</ParamField>

<ParamField type="string">
  A reference value that can be used to query for this card token later.
</ParamField>

### 3D Secure

<Note>
  **Visa requirement (Aug 2024):** You **must** provide at least the cardholder's `email` or `phone` for 3DS authentication.
</Note>

<ParamField type="boolean">
  Whether to perform 3D Secure authentication after card entry. If enabled with Access Token authorization, provide two access tokens.
</ParamField>

<ParamField type="string">
  Action to take if a technical problem occurs during 3DS processing. **Accept**: ignore 3DS failure and proceed with tokenization. **Reject**: do not tokenize the card; redirect to the failure URL.
</ParamField>

<ParamField type="string">
  The merchant name for 3D Secure authentication. Must be URL-encoded and unique per 3DS merchant account. See [3DS merchant setup](/account-setup/3ds-merchant-setup).
</ParamField>

<ParamField type="integer">
  Transaction amount for the 3D Secure challenge screen. Must be provided together with `currencyCode`. If omitted, authentication uses a 0 EUR amount.
</ParamField>

<ParamField type="string">
  Currency code for the 3D Secure challenge screen amount. Must be provided together with `amount`. If omitted, authentication uses a 0 EUR amount.
</ParamField>

<ParamField type="string">
  Cardholder's email address for 3D Secure authentication. Must be a valid email format, e.g. `joe@bloggs.com`.
</ParamField>

<ParamField type="string">
  Cardholder's telephone number for 3D Secure authentication. May only contain digits \[0-9], e.g. `00353112223344`.
</ParamField>

<RequestExample>
  ```javascript Node.js theme={null}
  const params = new URLSearchParams({
    brand: 'your-username',
    cardUri: 'https://service.pcibooking.net/api/payments/paycard/865ed8bec1f84366b97112a69cdbf915',
    language: 'en',
    success: 'https://example.com/success',
    failure: 'https://example.com/failure'
  });

  const response = await fetch(
    `https://service.pcibooking.net/api/payments/cvvcapturecard?${params}`,
    {
      headers: {
        'Authorization': 'Bearer your-access-token'
      }
    }
  );

  const html = await response.text();
  console.log(html);
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://service.pcibooking.net/api/payments/cvvcapturecard',
      headers={'Authorization': 'Bearer your-access-token'},
      params={
          'brand': 'your-username',
          'cardUri': 'https://service.pcibooking.net/api/payments/paycard/865ed8bec1f84366b97112a69cdbf915',
          'language': 'en',
          'success': 'https://example.com/success',
          'failure': 'https://example.com/failure'
      }
  )

  print(response.text)
  ```
</RequestExample>

## Response

**200** - HTML content of the CVV capture form.

<ResponseExample>
  ```html 200 theme={null}
  HTML content of form
  ```
</ResponseExample>


# Retrieve 3D Secure Data
Source: https://developers.pcibooking.net/api-reference/manage-tokens/retrieve-3d-token

GET https://service.pcibooking.net/api/payments/paycard/{cardToken}/3dToken
Retrieve the 3D Secure authentication data stored on a token.

<Card title="3DS Authentication Guide" icon="book" href="/manage-tokens/3ds-auth-management">
  Store and manage 3D Secure authentication data
</Card>

This data can also be retrieved via the [Retrieve Token Metadata](/api-reference/manage-tokens/retrieve-token-metadata) endpoint.

## Error Responses

| Code   | HTTP Status | Condition                          |
| ------ | ----------- | ---------------------------------- |
| -1003  | 401         | User not owner or associated       |
| (none) | 404         | No 3DS data exists for this card   |
| -150   | 500         | Internal error retrieving 3DS data |

## Parameters

### Headers

<ParamField type="string">
  Your API key prefixed with `APIKEY`. Example: `APIKEY your-api-key`. See the [Authentication guide](/getting-started/authentication).
</ParamField>

### Path Parameters

<ParamField type="string">
  The token ID as returned by one of the tokenization methods. For example, `2821a46d80e14d1b96a7f18f1b81926d`.
</ParamField>

<RequestExample>
  ```javascript Node.js theme={null}
  const response = await fetch(
    'https://service.pcibooking.net/api/payments/paycard/2821a46d80e14d1b96a7f18f1b81926d/3dToken',
    {
      headers: {
        'Authorization': 'APIKEY your-api-key'
      }
    }
  );

  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://service.pcibooking.net/api/payments/paycard/2821a46d80e14d1b96a7f18f1b81926d/3dToken',
      headers={'Authorization': 'APIKEY your-api-key'}
  )

  print(response.json())
  ```
</RequestExample>

## Response

<ResponseExample>
  ```json 200 theme={null}
  {
      "Token": "e13448f6255a496f960d215852f9ccc4",
      "ThreeDSSessionID": null,
      "ThreeDSecIndication": "Authenticated",
      "AuthenticationValue": "AJkBAoEREQAAAAB4hABwcAAAAAA=",
      "Eci": "05",
      "XID": "f0688d0b-6081-4879-9713-e7237d1fddfd",
      "AcsTransactionId": null,
      "Version": "2.1.0",
      "MerchantName": null,
      "SLI": null
  }
  ```

  ```json 401 theme={null}
  {
      "code": -1003,
      "message": "Not authorized to access this resource",
      "moreInfo": "Bad or missing authorization data, expected APIKEY",
      "errorList": null
  }
  ```

  ```json 404 theme={null}
  {
      "code": -160,
      "message": "Uri not found",
      "moreInfo": "No 3D Secure data exists for this card",
      "errorList": null
  }
  ```

  ```json 500 theme={null}
  {
      "code": -150,
      "message": "Internal error",
      "moreInfo": "Failed to retrieve 3D Secure data",
      "errorList": null
  }
  ```
</ResponseExample>


# Retrieve Card Details
Source: https://developers.pcibooking.net/api-reference/manage-tokens/retrieve-card-details

GET https://service.pcibooking.net/api/payments/paycard/{cardToken}
Retrieve the full, unmasked card details for a token. This endpoint returns raw card data, putting your system in PCI DSS scope.

<Card title="Query & Retrieve Guide" icon="book" href="/manage-tokens/query-retrieve">
  Search for tokens and retrieve their metadata
</Card>

<Warning title="PCI compliance">
  Please note that the response to this method will be the **full and unmasked** card details. Processing this response will put the system, network and all connected components into PCI scope.
  Before using this method, we recommend that you review the need for using it and setting up the proper environment to run it in.
</Warning>

Retrieves the full, unmasked card number and all associated card details for a token. This endpoint is intended for PCI DSS-compliant environments that need raw card data, such as for manual payment processing or migration to another vault.

## Error Responses

| Code  | HTTP Status | Condition                                                  |
| ----- | ----------- | ---------------------------------------------------------- |
| -1003 | 401         | User is not the owner and is not associated with this card |
| -160  | 404         | Card not found for the given token                         |

## Parameter Constraints

| Parameter   | Type   | Required | Constraints                                                         |
| ----------- | ------ | -------- | ------------------------------------------------------------------- |
| cardToken   | string | Yes      | Must be a 32-character hexadecimal string                           |
| retrieveCVV | string | No       | Accepts `yes`, `no`, or `mask`. Defaults to `no` (CVV not returned) |
| Auth        | string | Yes      | ApiKey with `CanReplaceToken` or `CanRetrieveCard` permission       |

## Parameters

### Headers

<ParamField type="string">
  Your API key prefixed with `APIKEY`. Example: `APIKEY your-api-key`. See the [Authentication guide](/getting-started/authentication).
</ParamField>

### Path Parameters

<ParamField type="string">
  The token ID as returned by one of the tokenization methods. For example, `2821a46d80e14d1b96a7f18f1b81926d`.
</ParamField>

### Query String

<ParamField type="string">
  Specifies how the CVV should be handled in the response: **Yes**: the CVV will be retrieved. **No**: the CVV will not be retrieved. **Mask**: the CVV will return masked.
</ParamField>

<RequestExample>
  ```javascript Node.js theme={null}
  const response = await fetch(
    'https://service.pcibooking.net/api/payments/paycard/2821a46d80e14d1b96a7f18f1b81926d?retrieveCVV=yes',
    {
      headers: {
        'Authorization': 'APIKEY your-api-key'
      }
    }
  );

  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://service.pcibooking.net/api/payments/paycard/2821a46d80e14d1b96a7f18f1b81926d',
      headers={'Authorization': 'APIKEY your-api-key'},
      params={'retrieveCVV': 'yes'}
  )

  print(response.json())
  ```
</RequestExample>

## Response

<ResponseExample>
  ```json 200 Without CVV theme={null}
  {
      "@xmlns": "http://www.pcibooking.net/reservation",
      "@schemaVersion": "1.0",
      "BankCard": {
          "Type": "Visa",
          "Number": "4918914107195005",
          "NameOnCard": "Juan Dela Cruz",
          "ExpirationDate": {
              "Month": "07",
              "Year": "2020"
          },
          "IssueNumber": "2"
      }
  }
  ```

  ```json 200 With CVV theme={null}
  {
      "@xmlns": "http://www.pcibooking.net/reservation",
      "@schemaVersion": "1.0",
      "BankCard": {
          "Type": "Visa",
          "Number": "4918914107195005",
          "NameOnCard": "Juan Dela Cruz",
          "ExpirationDate": {
              "Month": "07",
              "Year": "2020"
          },
          "IssueNumber": "2",
          "CVV": "123"
      }
  }
  ```

  ```json 401 theme={null}
  {
      "code": -1003,
      "message": "Not authorized to access this resource",
      "moreInfo": "Bad or missing authorization data, expected APIKEY or HTTP Basic",
      "errorList": null
  }
  ```

  ```json 404 theme={null}
  {
      "code": -160,
      "message": "Uri not found",
      "moreInfo": "Uri to Bank card not found",
      "errorList": null
  }
  ```
</ResponseExample>


# Retrieve Token Metadata
Source: https://developers.pcibooking.net/api-reference/manage-tokens/retrieve-token-metadata

GET https://service.pcibooking.net/api/payments/paycard/{cardtoken}/meta
Returns non-sensitive metadata for a single token, including card type, masked card number, expiration, CVV status, 3DS data, and associations.

<Card title="Query & Retrieve Guide" icon="book" href="/manage-tokens/query-retrieve#retrieve-token-metadata">
  Search for tokens and retrieve their metadata
</Card>

Returns non-sensitive metadata for a single token, including the card type, masked card number, expiration date, CVV status, and 3D Secure data. Use this endpoint to inspect token details without exposing the full card number or entering PCI DSS scope.

## Error Responses

| Code  | HTTP Status | Condition                                                   |
| ----- | ----------- | ----------------------------------------------------------- |
| -1003 | 401         | User is not the owner and is not associated with this token |
| -125  | 400         | Token value is not valid                                    |
| -160  | 404         | Token not found                                             |
| -150  | 500         | Internal system error                                       |

<Note>This endpoint is rate limited.</Note>

## Parameters

### Headers

<ParamField type="string">
  Your API key prefixed with `APIKEY`. Example: `APIKEY your-api-key`. See the [Authentication guide](/getting-started/authentication).
</ParamField>

### Path Parameters

<ParamField type="string">
  The token ID as returned by one of the tokenization methods. For example, `2821a46d80e14d1b96a7f18f1b81926d`.
</ParamField>

<RequestExample>
  ```javascript Node.js theme={null}
  const response = await fetch(
    'https://service.pcibooking.net/api/payments/paycard/2821a46d80e14d1b96a7f18f1b81926d/meta',
    {
      headers: {
        'Authorization': 'APIKEY your-api-key'
      }
    }
  );

  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://service.pcibooking.net/api/payments/paycard/2821a46d80e14d1b96a7f18f1b81926d/meta',
      headers={'Authorization': 'APIKEY your-api-key'}
  )

  print(response.json())
  ```
</RequestExample>

## Response

**200**

<ParamField type="string">
  The reference value set when the card was tokenized.
</ParamField>

<ParamField type="string">
  The date and time the token was created (ISO 8601).
</ParamField>

<ParamField type="string">
  The card brand (e.g. `Visa`, `Mastercard`, `Amex`). See [supported card types](/reference/card-types).
</ParamField>

<ParamField type="string">
  The first 6 digits (BIN) of the card number.
</ParamField>

<ParamField type="string">
  The last 4 digits of the card number.
</ParamField>

<ParamField type="integer">
  The card expiration year.
</ParamField>

<ParamField type="integer">
  The card expiration month.
</ParamField>

<ParamField type="string">
  The cardholder ID, if provided at tokenization time.
</ParamField>

<ParamField type="string">
  The name on the card, if provided at tokenization time.
</ParamField>

<ParamField type="string">
  The PCI Booking user ID that owns this token.
</ParamField>

<ParamField type="string">
  The card issue number (used by some card schemes).
</ParamField>

<ParamField type="string">
  The full token URI for use in API calls.
</ParamField>

<ParamField type="boolean">
  Whether CVV data is currently stored on this token.
</ParamField>

<ParamField type="string">
  The date after which the CVV will be automatically deleted (ISO 8601). Reflects the [CVV retention policy](/capture-cards/cvv-retention-policy).
</ParamField>

<ParamField type="string[]">
  List of PCI Booking customer (booker) user IDs associated with this token.
</ParamField>

<ParamField type="string[]">
  List of property user IDs associated with this token.
</ParamField>

<ParamField type="object">
  3D Secure authentication data, if stored on this token. See [3D Secure Authentication](/manage-tokens/3ds-auth-management) for field details.
</ParamField>

<ParamField type="string">
  The card network scheme if this is a network token (e.g. `Visa`, `Mastercard`). `null` for regular cards.
</ParamField>

<ParamField type="string">
  The network token identifier assigned by the card scheme. `null` for regular cards.
</ParamField>

<ParamField type="string">
  The geographic storage location of the token data. `null` for default (in-table) storage.
</ParamField>

<ParamField type="object">
  Virtual card metadata, if this token was created from a virtual card. Contains `IsMultiUse`, `Currency`, `MaxAmount`, `CardRules`, and validity date fields. `null` for regular cards.
</ParamField>

<ResponseExample>
  ```json 200 theme={null}
  {
      "CreatorReference": "myRef",
      "VirtualInfo": null,
      "CreateDate": "2020-05-19T16:51:00",
      "CardType": "Visa",
      "LastDigits": "5005",
      "LeadingDigits": "491891",
      "ExpirationYear": 2020,
      "ExpirationMonth": 7,
      "OwnerID": "",
      "OwnerName": "Juan Dela Cruz",
      "UserID": "myUser",
      "IssueNumber": "2",
      "URI": "https://service.pcibooking.net/api/payments/paycard/eb454e0462d548ddbc6e6c2193b749a9",
      "EndRetentionDate": "2017-07-08T00:00:00",
      "CvvExists": true,
      "AssociatedMerchants": ["userID1", "userID2"],
      "AssociatedProperties": ["hotel1", "hotel2"],
      "ThreeDSecureInfo": {
          "Token": "42c775efa8b04b1d8bf14ef49a9e45e5",
          "ThreeDSSessionID": "uOrDbh0dEimUDmB3Vvn2f5CAM9B1bMQX",
          "Indication": "Authenticated",
          "AuthenticationValue": "AJkBAoEREQAAAAB4hABwcAAAAAA=",
          "Eci": "05",
          "XID": "861433f4-abff-4c40-b2fd-fea208856a33",
          "AcsTransactionId": "e7a46959-9630-413e-ab56-4e399b96244a",
          "Version": "2.1.0",
          "MerchantName": "PCI Booking * Hotelreservation"
      },
      "NetworkTokenScheme": null,
      "NetworkTokenId": null,
      "TokenLocation": null
  }
  ```

  ```json 401 theme={null}
  {
      "code": -1003,
      "message": "Not authorized to access this resource",
      "moreInfo": "Bad or missing authorization data, expected APIKEY",
      "errorList": null
  }
  ```

  ```json 404 theme={null}
  {
      "code": -160,
      "message": "Uri not found",
      "moreInfo": "Uri to Bank card not found",
      "errorList": null
  }
  ```
</ResponseExample>


# Risk Assessment
Source: https://developers.pcibooking.net/api-reference/manage-tokens/risk-assessment

POST https://service.pcibooking.net/api/payments/paycard/{cardToken}/op/validate
Assess the risk level of a tokenized card by cross-referencing billing address, card issuer country, and client IP address.

<Card title="Risk Assessment Guide" icon="book" href="/use-tokens/risk-assessment">
  Evaluate transaction risk before processing payments
</Card>

Performs a fraud risk assessment on a tokenized card by cross-referencing the billing address, card issuer country, and client IP address. Use this before processing a payment to detect mismatches that may indicate fraudulent activity, such as anonymous proxies or country discrepancies.

## Error Responses

| Code  | HTTP Status | Condition                         |
| ----- | ----------- | --------------------------------- |
| -125  | 400         | Payer details missing (null body) |
| -125  | 400         | CountryCode is empty              |
| -1003 | 401         | User is not the owner             |

## Parameter Constraints

* **CountryCode** is required and must be a 2-letter ISO country code.
* **ClientIPAddress**, **City**, and **StateProvince** are used for geo-validation against the card issuer country.
* **FirstName** and **LastName** are compared against the card owner name.

## Parameters

### Headers

<ParamField type="string">
  Your API key prefixed with `APIKEY`. Example: `APIKEY your-api-key`. See the [Authentication guide](/getting-started/authentication).
</ParamField>

### Path Parameters

<ParamField type="string">
  The token ID as returned by one of the tokenization methods.
</ParamField>

### Payer Information

<ParamField type="string">
  Payer's first name.
</ParamField>

<ParamField type="string">
  Payer's last name.
</ParamField>

<ParamField type="string">
  Payer's email address.
</ParamField>

<ParamField type="string">
  Payer's phone number.
</ParamField>

### Billing Address

<ParamField type="string">
  Primary billing address line.
</ParamField>

<ParamField type="string">
  Secondary billing address line.
</ParamField>

<ParamField type="string">
  Tertiary billing address line.
</ParamField>

<ParamField type="string">
  Billing postal/ZIP code.
</ParamField>

<ParamField type="string">
  Billing city.
</ParamField>

<ParamField type="string">
  Billing state or province.
</ParamField>

<ParamField type="string">
  2-letter country code.
</ParamField>

### Client Details

<ParamField type="string">
  Client's IP address. Both IPv6 and IPv4 formats are supported.
</ParamField>

<RequestExample>
  ```javascript Node.js theme={null}
  const response = await fetch(
    'https://service.pcibooking.net/api/payments/paycard/2821a46d80e14d1b96a7f18f1b81926d/op/validate',
    {
      method: 'POST',
      headers: {
        'Authorization': 'APIKEY your-api-key',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        FirstName: 'Juan',
        LastName: 'Dela Cruz',
        Email: 'juan@example.com',
        Phone: '14155551234',
        Address1: '123 Main Street',
        PoseCode: '10001',
        City: 'New York',
        StateProvince: 'NY',
        CountryCode: 'US',
        clientIPAddress: '203.0.113.42'
      })
    }
  );

  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://service.pcibooking.net/api/payments/paycard/2821a46d80e14d1b96a7f18f1b81926d/op/validate',
      headers={
          'Authorization': 'APIKEY your-api-key',
          'Content-Type': 'application/json'
      },
      json={
          'FirstName': 'Juan',
          'LastName': 'Dela Cruz',
          'Email': 'juan@example.com',
          'Phone': '14155551234',
          'Address1': '123 Main Street',
          'PoseCode': '10001',
          'City': 'New York',
          'StateProvince': 'NY',
          'CountryCode': 'US',
          'clientIPAddress': '203.0.113.42'
      }
  )

  print(response.json())
  ```
</RequestExample>

## Response

<ResponseExample>
  ```json 200 theme={null}
  {
      "RiskLevel": "High",
      "Description": "Mismatch between billing address and credit card issuer country",
      "CountryByIP": "US",
      "IssuerCountry": "HK",
      "IssuerName": "CITIC BANK INTERNATIONAL, LTD.",
      "CardBrand": "VISA",
      "CardType": "CREDIT",
      "CardCategory": "CLASSIC",
      "CountryFromBillingAddress": "US",
      "AnonymousProxyUsed": false
  }
  ```

  ```json 400 theme={null}
  {
      "code": -125,
      "message": "Bad input data",
      "moreInfo": "Missing Payer details",
      "errorList": null
  }
  ```

  ```json 401 theme={null}
  {
      "code": -1003,
      "message": "Not authorized to access this resource",
      "moreInfo": "Bad or missing authorization data, expected APIKEY or Temp Session or One-Time Accesss Token",
      "errorList": null
  }
  ```

  ```json 404 theme={null}
  {
      "code": -160,
      "message": "Uri not found",
      "moreInfo": "Uri to Bank card not found",
      "errorList": null
  }
  ```
</ResponseExample>


# Set CVV Retention Policy
Source: https://developers.pcibooking.net/api-reference/manage-tokens/set-cvv-retention-policy

PUT https://service.pcibooking.net/api/payments/paycard/{cardToken}/cvv/Restriction
Define when and how the CVV on a token expires, and which destinations may consume it.

Define how long the CVV is retained and which destinations may use it.

<Card title="CVV Retention Policy Guide" icon="book" href="/capture-cards/cvv-retention-policy">
  Control how long CVV data is retained and who can use it
</Card>

## Error Responses

| Code    | HTTP Status | Condition                                                                                                        |
| ------- | ----------- | ---------------------------------------------------------------------------------------------------------------- |
| `-1003` | `401`       | API key is missing or invalid.                                                                                   |
| `-1003` | `401`       | Authenticated user does not have `ForceCVVRetentionPolicy` permission.                                           |
| `-1003` | `401`       | Token does not belong to the authenticated user.                                                                 |
| `-125`  | `400`       | The token does not have a CVV stored.                                                                            |
| `-179`  | `400`       | Request body validation failed (e.g. unrecognized `DestinationType`, invalid `DestinationData`).                 |
| `-1010` | `423`       | The retention policy is locked and cannot be modified. This happens when the 60-minute update window has passed. |
| `-160`  | `404`       | Token not found.                                                                                                 |
| `-150`  | `500`       | An internal system error occurred.                                                                               |

## Parameter Constraints

* **CvvEndRetentionDate**: If provided, must be between the current time and 4 years from now. If omitted, `CvvRetentionPolicyList` must be non-empty.
* **CvvRetentionPolicyList**: Maximum 50 entries.
* **Quota**: Must be between 1 and 50 (inclusive).
* **DestinationData** validation depends on `DestinationType`:

| DestinationType | DestinationData Rules                                                        |
| --------------- | ---------------------------------------------------------------------------- |
| `HostName`      | Valid hostname with 2-3 dot-separated parts. Optional port number (0-65535). |
| `IpAddress`     | Valid IPv4 address. Optional port number (0-65535).                          |
| `OtherMerchant` | Non-empty, valid property user ID.                                           |
| `OtherUser`     | Non-empty, valid booker user ID.                                             |
| `SFTP`          | Valid hostname or IPv4 address. Optional port number.                        |
| `Owner`         | Leave empty.                                                                 |

## Parameters

### Path Parameters

<ParamField type="string">
  The token ID as returned by one of the tokenization methods.
</ParamField>

### Headers

<ParamField type="string">
  Your API key prefixed with `APIKEY`. Example: `APIKEY your-api-key`. See the [Authentication guide](/getting-started/authentication).
</ParamField>

<ParamField type="string">
  Set to `application/xml` to submit the request body in XML format.
</ParamField>

### Request Body

<ParamField type="string">
  Date and time when the CVV expires. Format: `YYYY-MM-DD HH:MM:SS`. Must not exceed 48 months from the token creation date.
</ParamField>

<ParamField type="array">
  Destination whitelist (up to 50 entries). Each entry specifies a destination type, its data, and the number of times the CVV may be sent to it. Pass an empty array to use time-based retention only. See [destination types](/capture-cards/cvv-retention-policy#destination-types).
</ParamField>

<ParamField type="string">
  One of: `HostName`, `Owner`, `OtherMerchant`, `SFTP`, `OtherUser`.
</ParamField>

<ParamField type="string">
  The target identifier for this destination type (e.g. hostname, user ID, IP address). Leave empty for `Owner`.
</ParamField>

<ParamField type="integer">
  Maximum number of times the CVV may be sent to this destination.
</ParamField>

<ParamField type="boolean">
  If `true`, the entire token (not just the CVV) is deleted when the retention period ends.
</ParamField>

## Request Examples

<Tabs>
  <Tab title="JSON (minimal)">
    ```json theme={null}
    {
      "CvvEndRetentionDate": "2025-12-12 12:32:45",
      "CvvRetentionPolicyList": []
    }
    ```
  </Tab>

  <Tab title="JSON (with destinations)">
    ```json theme={null}
    {
      "CvvEndRetentionDate": "2025-12-12 12:32:45",
      "DeleteCardUponCvvCleanup": true,
      "CvvRetentionPolicyList": [
        {
          "DestinationType": "HostName",
          "DestinationData": "gateway.example.com",
          "Quota": 10
        },
        {
          "DestinationType": "Owner",
          "DestinationData": "",
          "Quota": 5
        }
      ]
    }
    ```
  </Tab>

  <Tab title="XML">
    ```xml theme={null}
    <?xml version="1.0"?>
    <CardCvvRetentionPolicy>
        <CvvEndRetentionDate>2025-12-12T12:32:45</CvvEndRetentionDate>
        <DeleteCardUponCvvCleanup>true</DeleteCardUponCvvCleanup>
        <CvvRetentionPolicyList>
            <CvvRetentionPolicyDestination>
                <DestinationType>HostName</DestinationType>
                <DestinationData>gateway.example.com</DestinationData>
                <Quota>10</Quota>
            </CvvRetentionPolicyDestination>
        </CvvRetentionPolicyList>
    </CardCvvRetentionPolicy>
    ```
  </Tab>
</Tabs>

<RequestExample>
  ```javascript Node.js theme={null}
  const response = await fetch(
    'https://service.pcibooking.net/api/payments/paycard/2821a46d80e14d1b96a7f18f1b81926d/cvv/Restriction',
    {
      method: 'PUT',
      headers: {
        'Authorization': 'APIKEY your-api-key',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        CvvEndRetentionDate: '2027-12-12 12:32:45',
        DeleteCardUponCVVCleanup: false,
        CvvRetentionPolicyList: [
          {
            DestinationType: 'HostName',
            DestinationData: 'gateway.example.com',
            Quota: 10
          }
        ]
      })
    }
  );

  console.log(response.status);
  ```

  ```python Python theme={null}
  import requests

  response = requests.put(
      'https://service.pcibooking.net/api/payments/paycard/2821a46d80e14d1b96a7f18f1b81926d/cvv/Restriction',
      headers={
          'Authorization': 'APIKEY your-api-key',
          'Content-Type': 'application/json'
      },
      json={
          'CvvEndRetentionDate': '2027-12-12 12:32:45',
          'DeleteCardUponCVVCleanup': False,
          'CvvRetentionPolicyList': [
              {
                  'DestinationType': 'HostName',
                  'DestinationData': 'gateway.example.com',
                  'Quota': 10
              }
          ]
      }
  )

  print(response.status_code)
  ```
</RequestExample>

## Response

**200** - Policy set successfully.

<ResponseExample>
  ```text 200 theme={null}
  CVV retention policy set successfully. No content returned.
  ```

  ```json 400 theme={null}
  {
      "code": -179,
      "message": "Bad input parameter",
      "moreInfo": "Bad input data",
      "errorList": [
          "Unrecognized DestinationType in json request"
      ]
  }
  ```

  ```json 401 theme={null}
  {
      "code": -1003,
      "message": "Not authorized to access this resource",
      "moreInfo": "Bad or missing authorization data, expected APIKEY",
      "errorList": null
  }
  ```

  ```json 423 theme={null}
  {
      "code": -1010,
      "message": "Resource is locked for updates",
      "moreInfo": "This card does not have a Cvv",
      "errorList": null
  }
  ```
</ResponseExample>


# Store 3D Secure Data
Source: https://developers.pcibooking.net/api-reference/manage-tokens/store-3d-token

PUT https://service.pcibooking.net/api/payments/paycard/{cardToken}/3dToken
Store 3D Secure authentication data on a token.

<Card title="3DS Authentication Guide" icon="book" href="/manage-tokens/3ds-auth-management">
  Store and manage 3D Secure authentication data
</Card>

Stores 3D Secure authentication results on an existing token. Use this when you have performed 3DS authentication outside of PCI Booking and need to attach the authentication data (CAVV, ECI, XID) to the token for use in subsequent payment transactions.

## Error Responses

| Code  | HTTP Status | Condition                                                            |
| ----- | ----------- | -------------------------------------------------------------------- |
| -179  | 400         | ThreeDSecureInfo is null or Version does not start with "1." or "2." |
| -1003 | 401         | User is not the owner                                                |
| -150  | 500         | Failed to store 3DS data                                             |

## Parameter Constraints

* **ThreeDSecIndication** is required and must be `Authenticated` or `TechnicalProblem`.
* **AuthenticationValue** has a max length of 256 characters and is required when ThreeDSecIndication is `Authenticated`.
* **Eci** has a max length of 2 characters.
* **Version** must start with "1." or "2.".

## Parameters

### Headers

<ParamField type="string">
  Your API key prefixed with `APIKEY`. Example: `APIKEY your-api-key`. See the [Authentication guide](/getting-started/authentication).
</ParamField>

### Path Parameters

<ParamField type="string">
  The token ID as returned by one of the tokenization methods. For example, `2821a46d80e14d1b96a7f18f1b81926d`.
</ParamField>

### Request Body

<ParamField type="string">
  The cardholder's Authentication Verification Value (AVV). e.g. `1234567890`. Max 256 characters.
</ParamField>

<ParamField type="string">
  The version of 3DS authentication used. Should start with either "1" or "2". Max 5 characters.
</ParamField>

<ParamField type="string">
  The Electronic Commerce Indicator (ECI) value. e.g. `12`.
</ParamField>

<ParamField type="string">
  The 3D Secure authentication decision. Accepted values: **Authenticated**, **TechnicalProblem**, **CardNotEnrolled**.
</ParamField>

<ParamField type="string">
  The 3DS transaction ID for 3DS version 1.0 (`XID`) and version 2.0 (`3DS_Trans_ID`). Max 40 characters.
</ParamField>

<ParamField type="string">
  Unique transaction identifier assigned by the Access Control Server (ACS) to identify a single 3D Secure transaction.
</ParamField>

<RequestExample>
  ```javascript Node.js theme={null}
  const response = await fetch(
    'https://service.pcibooking.net/api/payments/paycard/2821a46d80e14d1b96a7f18f1b81926d/3dToken',
    {
      method: 'PUT',
      headers: {
        'Authorization': 'APIKEY your-api-key',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        AuthenticationValue: 'AJkBAoEREQAAAAB4hABwcAAAAAA=',
        Version: '2.1.0',
        eci: '05',
        ThreeDSeciIndication: 'Authenticated',
        XID: '861433f4-abff-4c40-b2fd-fea208856a33',
        AcsTransactionId: 'e7a46959-9630-413e-ab56-4e399b96244a'
      })
    }
  );

  console.log(response.status);
  ```

  ```python Python theme={null}
  import requests

  response = requests.put(
      'https://service.pcibooking.net/api/payments/paycard/2821a46d80e14d1b96a7f18f1b81926d/3dToken',
      headers={
          'Authorization': 'APIKEY your-api-key',
          'Content-Type': 'application/json'
      },
      json={
          'AuthenticationValue': 'AJkBAoEREQAAAAB4hABwcAAAAAA=',
          'Version': '2.1.0',
          'eci': '05',
          'ThreeDSeciIndication': 'Authenticated',
          'XID': '861433f4-abff-4c40-b2fd-fea208856a33',
          'AcsTransactionId': 'e7a46959-9630-413e-ab56-4e399b96244a'
      }
  )

  print(response.status_code)
  ```
</RequestExample>

## Response

**201** - 3D Secure data stored successfully.

<ResponseExample>
  ```text 201 theme={null}
  Empty response body. 3D Secure data stored successfully.
  ```

  ```json 401 theme={null}
  {
      "code": -1003,
      "message": "Not authorized to access this resource",
      "moreInfo": "Bad or missing authorization data, expected APIKEY or Temp Session or One-Time Accesss Token",
      "errorList": null
  }
  ```
</ResponseExample>


# Transfer Ownership
Source: https://developers.pcibooking.net/api-reference/manage-tokens/transfer-ownership

PUT https://service.pcibooking.net/api/payments/paycard/{cardToken}/externalUser/{AltCustomer}
Transfer ownership of a token to another PCI Booking customer.

<Card title="Third-Party Permissions Guide" icon="book" href="/manage-tokens/third-party-permissions">
  Learn how to share tokens with other PCI Booking customers
</Card>

Permanently transfers ownership of a token from your PCI Booking account to another customer's account. After the transfer, the original owner loses all access to the token and the new owner gains full control.

## Error Responses

| Code  | HTTP Status | Condition                       |
| ----- | ----------- | ------------------------------- |
| -1003 | 401         | User is not the owner           |
| -179  | 400         | externalUserId is empty         |
| -179  | 400         | Recipient user does not exist   |
| -179  | 400         | Cannot transfer to same account |

## Parameters

### Headers

<ParamField type="string">
  Your API key prefixed with `APIKEY`. Example: `APIKEY your-api-key`. See the [Authentication guide](/getting-started/authentication).
</ParamField>

### Path Parameters

<ParamField type="string">
  The token ID as returned by one of the tokenization methods.
</ParamField>

<ParamField type="string">
  The user ID in PCI Booking of the customer to transfer ownership to.
</ParamField>

<RequestExample>
  ```javascript Node.js theme={null}
  const response = await fetch(
    'https://service.pcibooking.net/api/payments/paycard/2821a46d80e14d1b96a7f18f1b81926d/externalUser/recipient-user-456',
    {
      method: 'PUT',
      headers: {
        'Authorization': 'APIKEY your-api-key'
      }
    }
  );

  console.log(response.status);
  ```

  ```python Python theme={null}
  import requests

  response = requests.put(
      'https://service.pcibooking.net/api/payments/paycard/2821a46d80e14d1b96a7f18f1b81926d/externalUser/recipient-user-456',
      headers={'Authorization': 'APIKEY your-api-key'}
  )

  print(response.status_code)
  ```
</RequestExample>

## Response

<ResponseExample>
  ```text 200 theme={null}
  Ownership transferred successfully. No content returned.
  ```

  ```json 400 theme={null}
  {
      "code": -125,
      "message": "Bad input data",
      "moreInfo": "Could not find a valid user",
      "errorList": null
  }
  ```

  ```json 401 theme={null}
  {
      "code": -1003,
      "message": "Not authorized to access this resource",
      "moreInfo": "User is not the owner of this bank card",
      "errorList": null
  }
  ```
</ResponseExample>


# Update Creator Reference
Source: https://developers.pcibooking.net/api-reference/manage-tokens/update-creator-reference

PUT https://service.pcibooking.net/api/payments/paycard/{token}/creatorReference/{creatorReference}
Set or update the creator reference value on an existing token.

<Card title="Update Card Data Guide" icon="book" href="/manage-tokens/update-card-data">
  Modify expiration dates and creator references on tokens
</Card>

Sets or updates the creator reference label on an existing token. The creator reference is a merchant-defined string that lets you look up tokens by your own identifiers, such as a booking or reservation number.

## Error Responses

| Code  | HTTP Status | Condition                        |
| ----- | ----------- | -------------------------------- |
| -1003 | 401         | User is not the owner            |
| -179  | 400         | creatorReference is empty        |
| -125  | 400         | Setting creator reference failed |

## Parameters

### Headers

<ParamField type="string">
  Your API key prefixed with `APIKEY`. Example: `APIKEY your-api-key`. See the [Authentication guide](/getting-started/authentication).
</ParamField>

### Path Parameters

<ParamField type="string">
  The token ID as returned by one of the tokenization methods. For example, `2821a46d80e14d1b96a7f18f1b81926d`.
</ParamField>

<ParamField type="string">
  The new creator reference value to assign to this token. Can be used later to [query for tokens](/api-reference/manage-tokens/query-tokens) by reference.
</ParamField>

<RequestExample>
  ```javascript Node.js theme={null}
  const response = await fetch(
    'https://service.pcibooking.net/api/payments/paycard/2821a46d80e14d1b96a7f18f1b81926d/creatorReference/booking-12345',
    {
      method: 'PUT',
      headers: {
        'Authorization': 'APIKEY your-api-key'
      }
    }
  );

  console.log(response.status);
  ```

  ```python Python theme={null}
  import requests

  response = requests.put(
      'https://service.pcibooking.net/api/payments/paycard/2821a46d80e14d1b96a7f18f1b81926d/creatorReference/booking-12345',
      headers={'Authorization': 'APIKEY your-api-key'}
  )

  print(response.status_code)
  ```
</RequestExample>

## Response

**200** - Creator reference updated successfully.

<ResponseExample>
  ```text 200 theme={null}
  Creator reference updated successfully. No content returned.
  ```

  ```json 400 theme={null}
  {
      "code": -125,
      "message": "Bad input data",
      "moreInfo": "Invalid token or creator reference",
      "errorList": null
  }
  ```

  ```json 401 theme={null}
  {
      "code": -1003,
      "message": "Not authorized to access this resource",
      "moreInfo": "Bad or missing authorization data, expected APIKEY",
      "errorList": null
  }
  ```

  ```json 404 theme={null}
  {
      "code": -160,
      "message": "Uri not found",
      "moreInfo": "Uri to Bank card not found",
      "errorList": null
  }
  ```
</ResponseExample>


# Update Card Expiration Date
Source: https://developers.pcibooking.net/api-reference/manage-tokens/update-expiration

PUT https://service.pcibooking.net/api/payments/paycard/{cardToken}/UpdateExpiration
Update the expiration date on a stored token. Only the expiration date is changed; all other card data remains unchanged.

<Card title="Update Card Data Guide" icon="book" href="/manage-tokens/update-card-data">
  Modify expiration dates and creator references on tokens
</Card>

Updates the expiration date on a stored token without affecting any other card data. Use this when a cardholder's card has been renewed with a new expiration date and you need to keep the token current.

## Error Responses

| Code  | HTTP Status | Condition                            |
| ----- | ----------- | ------------------------------------ |
| -125  | 400         | Year or Month value is not numeric   |
| -125  | 400         | Expiration date is in the past       |
| -1003 | 401         | User is not the owner of this token  |
| -160  | 404         | Card not found for the given token   |
| -150  | 500         | Update transaction failed (rollback) |

## Parameter Constraints

| Parameter | Type   | Required | Constraints                                                           |
| --------- | ------ | -------- | --------------------------------------------------------------------- |
| Month     | string | Yes      | Numeric string, valid range 1 to 12                                   |
| Year      | string | Yes      | Numeric string, must be greater than or equal to the current UTC year |

<Note>This endpoint is rate limited.</Note>

## Parameters

### Headers

<ParamField type="string">
  Your API key prefixed with `APIKEY`. Example: `APIKEY your-api-key`. See the [Authentication guide](/getting-started/authentication).
</ParamField>

### Path Parameters

<ParamField type="string">
  The token ID as returned by one of the tokenization methods. For example, `2821a46d80e14d1b96a7f18f1b81926d`.
</ParamField>

### Request Body

<ParamField type="integer">
  New expiration year. Format **YYYY**.
</ParamField>

<ParamField type="integer">
  New expiration month. Format **MM**.
</ParamField>

<RequestExample>
  ```javascript Node.js theme={null}
  const response = await fetch(
    'https://service.pcibooking.net/api/payments/paycard/2821a46d80e14d1b96a7f18f1b81926d/UpdateExpiration',
    {
      method: 'PUT',
      headers: {
        'Authorization': 'APIKEY your-api-key',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        Year: 2027,
        Month: 12
      })
    }
  );

  console.log(response.status);
  ```

  ```python Python theme={null}
  import requests

  response = requests.put(
      'https://service.pcibooking.net/api/payments/paycard/2821a46d80e14d1b96a7f18f1b81926d/UpdateExpiration',
      headers={
          'Authorization': 'APIKEY your-api-key',
          'Content-Type': 'application/json'
      },
      json={
          'Year': 2027,
          'Month': 12
      }
  )

  print(response.status_code)
  ```
</RequestExample>

## Response

**200** - Expiration updated successfully. Empty response body.

<ResponseExample>
  ```text 200 theme={null}
  Expiration date updated successfully. No content returned.
  ```

  ```json 400 theme={null}
  {
      "code": -125,
      "message": "Bad input data",
      "moreInfo": "Expiration year/month error",
      "errorList": null
  }
  ```

  ```json 401 theme={null}
  {
      "code": -1003,
      "message": "Not authorized to access this resource",
      "moreInfo": "Bad or missing authorization data, expected APIKEY",
      "errorList": null
  }
  ```
</ResponseExample>


# API Reference Overview
Source: https://developers.pcibooking.net/api-reference/overview

PCI Booking REST API reference. Base URL, authentication, response format, and a map of all available endpoints.

This reference documents every endpoint in the PCI Booking API. If you are new to PCI Booking, start with the guides:

* [Introduction](/start-here/introduction). What PCI Booking does and how the platform works.
* [Create an Account](/getting-started/create-account). How to get sandbox and production API keys.
* [Quickstart](/start-here/quickstart). Tokenize a card and process a payment in minutes.

## Base URL

All API calls use a single base URL for both sandbox and production:

```text theme={null}
https://service.pcibooking.net/api
```

The only difference between sandbox and production is your API key. See [Testing and Going Live](/getting-started/testing-and-going-live) for details.

## Authentication

Most endpoints require an API key passed in the `Authorization` header:

```http theme={null}
Authorization: APIKEY your-api-key
```

For browser-side calls (card entry forms, payments library), generate a temporary session token first. See the [Authentication guide](/getting-started/authentication) for full details on API keys, session tokens, and access tokens.

## Response Format

Responses are JSON. Successful calls return `200` with the result in the body. Errors return a standard error object:

```json theme={null}
{
  "code": -1003,
  "message": "Not authorized to access this resource",
  "moreInfo": "Bad or missing authorization data, expected APIKEY",
  "errorList": null
}
```

## Endpoint Sections

| Section                                                                | What It Covers                                                                                                     |
| ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| **[Capture Cards](/api-reference/tokenize-cards/overview)**            | Tokenize cards from hosted forms, email/SMS links, third-party API responses, file transfers, or direct migration. |
| **[Manage Tokens](/api-reference/manage-tokens/overview)**             | Query, update, delete tokens. CVV management, 3D Secure storage, customer associations, risk assessment.           |
| **[Use Tokens](/api-reference/process-cards/overview)**                | Process payments via 100+ gateways, replace tokens in HTTP requests and files, display card details securely.      |
| **[Data Blocks](/additional-functions/data-blocks)**                   | Store and retrieve arbitrary data blocks associated with tokens.                                                   |
| **[Contact Verification](/additional-functions/contact-verification)** | Verify cardholder contact details (email, phone).                                                                  |
| **[Payments Library](/api-reference/payments-library/create-session)** | Server-side session management for the client-side Payments Library.                                               |


# Delete Digital Wallet Credentials
Source: https://developers.pcibooking.net/api-reference/payments-library-accounts/delete-credentials

DELETE https://service.pcibooking.net/api/eWalletAccounts/{credentialsId}
Delete stored digital wallet credentials by their ID.

<Card title="Payments Library Credentials Guide" icon="book" href="/account-setup/payments-library-credentials">
  Configure credentials for Payments Library integrations
</Card>

Deletes a stored set of digital wallet credentials. Any Payments Library sessions referencing this credential ID will no longer work.

## Error Responses

| Code    | HTTP Status | Condition                                                    |
| ------- | ----------- | ------------------------------------------------------------ |
| `-1003` | `401`       | API key is missing or invalid, or user type is not `Booker`. |
| `-1`    | `404`       | No credentials found with the specified ID.                  |

## Parameters

### Headers

<ParamField type="string">
  Your API key prefixed with `APIKEY`. Example: `APIKEY your-api-key`. See the [Authentication guide](/getting-started/authentication).
</ParamField>

### Path Parameters

<ParamField type="string">
  The ID assigned to the credentials when they were [stored](/api-reference/payments-library-accounts/store-credentials).
</ParamField>

<RequestExample>
  ```javascript Node.js theme={null}
  const credentialsId = 'my-googlepay';
  const response = await fetch(`https://service.pcibooking.net/api/eWalletAccounts/${credentialsId}`, {
    method: 'DELETE',
    headers: {
      'Authorization': 'APIKEY your-api-key'
    }
  });
  console.log(response.status); // 204 on success
  ```

  ```python Python theme={null}
  import requests

  credentials_id = 'my-googlepay'
  response = requests.delete(
      f'https://service.pcibooking.net/api/eWalletAccounts/{credentials_id}',
      headers={'Authorization': 'APIKEY your-api-key'}
  )
  print(response.status_code)  # 204 on success
  ```
</RequestExample>

## Response

<ResponseExample>
  ```text 204 theme={null}
  Credentials deleted successfully. No content returned.
  ```

  ```json 400 theme={null}
  {
      "code": -125,
      "message": "Bad input data",
      "moreInfo": "...",
      "errorList": null
  }
  ```

  ```json 404 theme={null}
  {
      "code": -1,
      "message": "Credentials not found"
  }
  ```
</ResponseExample>


# List Digital Wallet Credentials
Source: https://developers.pcibooking.net/api-reference/payments-library-accounts/list-credentials

GET https://service.pcibooking.net/api/eWalletAccounts
Retrieve a list of all stored digital wallet credential IDs.

<Card title="Payments Library Credentials Guide" icon="book" href="/account-setup/payments-library-credentials">
  Configure credentials for Payments Library integrations
</Card>

Returns a list of all digital wallet credential IDs stored in your account.

## Error Responses

| Code    | HTTP Status | Condition                                                    |
| ------- | ----------- | ------------------------------------------------------------ |
| `-1003` | `401`       | API key is missing or invalid, or user type is not `Booker`. |

## Parameters

### Headers

<ParamField type="string">
  Your API key prefixed with `APIKEY`. Example: `APIKEY your-api-key`. See the [Authentication guide](/getting-started/authentication).
</ParamField>

<RequestExample>
  ```javascript Node.js theme={null}
  const response = await fetch('https://service.pcibooking.net/api/eWalletAccounts', {
    method: 'GET',
    headers: {
      'Authorization': 'APIKEY your-api-key'
    }
  });
  const credentials = await response.json();
  credentials.forEach(cred => {
    console.log(cred.credentialsId, cred.name);
  });
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://service.pcibooking.net/api/eWalletAccounts',
      headers={'Authorization': 'APIKEY your-api-key'}
  )
  credentials = response.json()
  for cred in credentials:
      print(cred['credentialsId'], cred['name'])
  ```
</RequestExample>

## Response

<ResponseExample>
  ```json 200 theme={null}
  [
      {
          "credentialsId": "my-googlepay",
          "name": "GooglePay"
      },
      {
          "credentialsId": "my-applepay",
          "name": "ApplePay"
      }
  ]
  ```

  ```json 400 theme={null}
  {
      "code": -125,
      "message": "Bad input data",
      "moreInfo": "...",
      "errorList": null
  }
  ```
</ResponseExample>


# Retrieve Digital Wallet Credential Structure
Source: https://developers.pcibooking.net/api-reference/payments-library-accounts/retrieve-credential-structure

GET https://service.pcibooking.net/api/eWalletOperation
Retrieve the list of supported digital wallets and the required credential format for each.

<Card title="Payments Library Credentials Guide" icon="book" href="/account-setup/payments-library-credentials">
  Configure credentials for Payments Library integrations
</Card>

Returns the list of supported digital wallet payment methods and the credential fields required for each. Use this to determine the correct structure when [storing credentials](/api-reference/payments-library-accounts/store-credentials).

## Error Responses

| Code    | HTTP Status | Condition                      |
| ------- | ----------- | ------------------------------ |
| `-1003` | `401`       | API key is missing or invalid. |

## Parameters

### Headers

<ParamField type="string">
  Your API key prefixed with `APIKEY`. Example: `APIKEY your-api-key`. See the [Authentication guide](/getting-started/authentication).
</ParamField>

<RequestExample>
  ```javascript Node.js theme={null}
  const response = await fetch('https://service.pcibooking.net/api/eWalletOperation', {
    method: 'GET',
    headers: {
      'Authorization': 'APIKEY your-api-key'
    }
  });
  const wallets = await response.json();
  wallets.forEach(wallet => {
    console.log(wallet.Name, wallet.MerchantAccountPropertyNames);
  });
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://service.pcibooking.net/api/eWalletOperation',
      headers={'Authorization': 'APIKEY your-api-key'}
  )
  wallets = response.json()
  for wallet in wallets:
      print(wallet['Name'], wallet['MerchantAccountPropertyNames'])
  ```
</RequestExample>

## Response

The response contains an object for each supported digital wallet, listing the required credential fields in `MerchantAccountPropertyNames`.

<ResponseExample>
  ```json 200 theme={null}
  [
      {
          "Name": "GooglePay",
          "MerchantAccountPropertyNames": [
              "MerchantId",
              "MerchantName"
          ]
      },
      {
          "Name": "ApplePay",
          "MerchantAccountPropertyNames": [
              "MerchantId",
              "DomainName",
              "DisplayName"
          ]
      }
  ]
  ```

  ```json 400 theme={null}
  {
      "code": -125,
      "message": "Bad input data",
      "moreInfo": "...",
      "errorList": null
  }
  ```
</ResponseExample>


# Store Digital Wallet Credentials
Source: https://developers.pcibooking.net/api-reference/payments-library-accounts/store-credentials

PUT https://service.pcibooking.net/api/eWalletAccounts/{credentialsId}
Store credentials for a digital wallet payment method.

<Card title="Payments Library Credentials Guide" icon="book" href="/account-setup/payments-library-credentials">
  Configure credentials for Payments Library integrations
</Card>

Stores a set of credentials for a digital wallet under the specified ID. You reference this ID in the `AllowedeWalletAccountIds` field when [creating a session](/api-reference/payments-library/create-session).

<Warning>
  If you store credentials with an ID that already exists, the new credentials overwrite the existing ones. This cannot be undone.
</Warning>

## Error Responses

| Code    | HTTP Status | Condition                                                                                                |
| ------- | ----------- | -------------------------------------------------------------------------------------------------------- |
| `-1003` | `401`       | API key is missing or invalid, or user type is not `Booker`.                                             |
| `-125`  | `400`       | Request body failed validation (e.g. invalid or missing digital wallet name, malformed credential data). |

## Parameters

### Headers

<ParamField type="string">
  Your API key prefixed with `APIKEY`. Example: `APIKEY your-api-key`. See the [Authentication guide](/getting-started/authentication).
</ParamField>

### Path Parameters

<ParamField type="string">
  The unique ID to assign to this set of credentials. You reference this ID when [creating a Payments Library session](/api-reference/payments-library/create-session).
</ParamField>

### Request Body

<ParamField type="string">
  The digital wallet name (e.g. `GooglePay`, `ApplePay`). Retrieve the full list of supported names using the [Retrieve Credential Structure](/api-reference/payments-library-accounts/retrieve-credential-structure) endpoint.
</ParamField>

The remaining body fields are the credential key-value pairs required for the chosen digital wallet. Retrieve the required fields for each wallet using the [Retrieve Credential Structure](/api-reference/payments-library-accounts/retrieve-credential-structure) endpoint.

<RequestExample>
  ```javascript Node.js theme={null}
  const credentialsId = 'my-googlepay';
  const response = await fetch(`https://service.pcibooking.net/api/eWalletAccounts/${credentialsId}`, {
    method: 'PUT',
    headers: {
      'Authorization': 'APIKEY your-api-key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'GooglePay',
      MerchantId: 'BCR2DN4T7654321',
      MerchantName: 'My Store'
    })
  });
  console.log(response.status); // 200 on success
  ```

  ```python Python theme={null}
  import requests

  credentials_id = 'my-googlepay'
  response = requests.put(
      f'https://service.pcibooking.net/api/eWalletAccounts/{credentials_id}',
      headers={
          'Authorization': 'APIKEY your-api-key',
          'Content-Type': 'application/json'
      },
      json={
          'name': 'GooglePay',
          'MerchantId': 'BCR2DN4T7654321',
          'MerchantName': 'My Store'
      }
  )
  print(response.status_code)  # 200 on success
  ```
</RequestExample>

## Response

<ResponseExample>
  ```text 200 theme={null}
  Credentials stored successfully. No content returned.
  ```

  ```json 400 theme={null}
  {
      "code": -125,
      "message": "Bad input data",
      "moreInfo": "...",
      "errorList": null
  }
  ```
</ResponseExample>


# Create Payments Library Session
Source: https://developers.pcibooking.net/api-reference/payments-library/create-session

POST https://service.pcibooking.net/api/eWalletOperation
Create a new Payments Library session for tokenization or charge operations using digital wallets.

<Card title="Payments Library Setup Guide" icon="book" href="/payments-library/setup">
  Get started with the Payments Library
</Card>

Creates a session for a digital wallet operation. The session ID returned is used by the client-side Payments Library to present the payment UI to the payer.

## Error Responses

| Code    | HTTP Status | Condition                                                                                                     |
| ------- | ----------- | ------------------------------------------------------------------------------------------------------------- |
| `-1003` | `401`       | API key is missing or invalid.                                                                                |
| `-125`  | `400`       | A sandbox user attempted a `LIVE` mode operation. Sandbox users can only use `TEST` mode.                     |
| `-125`  | `400`       | Session creation failed due to invalid parameters (e.g. missing required fields, invalid wallet account IDs). |

## Parameter Constraints

* **operation**: Must be `TOKENIZE` or `CHARGE`.
* **mode**: Must be `TEST` or `LIVE`. Sandbox users are restricted to `TEST` only.
* **PaymentGatewayAccountId**: Must reference a valid stored credential ID.
* **AllowedeWalletAccountIds**: Comma-separated list of stored digital wallet credential IDs.
* **CurrencyCode**: Must be a valid ISO 4217 currency code.
* **CountryCode**: Must be a valid ISO 3166-1 alpha-2 country code.
* **CustomerEmail**: Must be a valid email format (when provided for 3DS).
* **CustomerPhone**: Digits only (when provided for 3DS).

<Info title="Tokenization and 3D Secure support by payment method">
  **Tokenization** (`TOKENIZE` operation) is only available for card pay, Apple Pay, and Google Pay. Other payment methods support charge only.

  **3D Secure** behavior varies by method:

  * **Apple Pay:** 3DS is always performed by Apple when the cardholder interacts with their device. The card always includes 3DS authentication results.
  * **Google Pay:** 3DS depends on cardholder interaction and device. If Google Pay performed two-factor authentication, the card includes the 3DS result.
  * **Card pay:** You choose whether to perform 3DS after the cardholder enters their card details. If enabled, PCI Booking performs 3DS and only proceeds if successful.
</Info>

## Parameters

### Headers

<ParamField type="string">
  Your API key prefixed with `APIKEY`. Example: `APIKEY your-api-key`. See the [Authentication guide](/getting-started/authentication).
</ParamField>

### Operation

<ParamField type="string">
  The type of operation to perform:

  * `TOKENIZE`: Retrieve card details from the digital wallet and store them as a token in PCI Booking's vault.
  * `CHARGE`: Retrieve card details from the digital wallet and submit a charge to the payment gateway.
</ParamField>

### Payment Gateway

<ParamField type="string">
  The `credentialsId` of your payment gateway credentials, stored using the [Store Gateway Credentials](/api-reference/process-cards/store-credentials) method.
</ParamField>

<ParamField type="string">
  A comma-separated list of digital wallet credential IDs stored using the [Store Digital Wallet Credentials](/api-reference/payments-library-accounts/store-credentials) method.
</ParamField>

<ParamField type="array">
  Fallback payment gateway accounts to try if the primary gateway fails. Each object contains the fallback gateway account details.
</ParamField>

### Transaction

<ParamField type="string">
  The environment. Possible values: `TEST`, `LIVE`.
</ParamField>

<ParamField type="string">
  ISO 4217 currency code (e.g. `USD`, `EUR`).
</ParamField>

<ParamField type="number">
  The transaction amount.
</ParamField>

<ParamField type="string">
  ISO 3166-1 alpha-2 country code of the payer (e.g. `US`, `GB`).
</ParamField>

<ParamField type="string">
  Comma-separated list of accepted card brands. If the payer's card does not match, they are prompted to enter a different card.
</ParamField>

<ParamField type="string">
  A note sent to and recorded by the payment processor.
</ParamField>

<ParamField type="string">
  Your own reference for this transaction (e.g. booking number, order ID).
</ParamField>

### 3D Secure

<ParamField type="string">
  The cardholder's email address for 3D Secure authentication. Must be a valid email format. Either `CustomerEmail` or `CustomerPhone` is required when performing 3DS.
</ParamField>

<ParamField type="string">
  The cardholder's phone number for 3D Secure authentication. Digits only (e.g. `00353112223344`). Either `CustomerEmail` or `CustomerPhone` is required when performing 3DS.
</ParamField>

<RequestExample>
  ```javascript Node.js theme={null}
  const response = await fetch('https://service.pcibooking.net/api/eWalletOperation', {
    method: 'POST',
    headers: {
      'Authorization': 'APIKEY your-api-key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      operation: 'CHARGE',
      mode: 'LIVE',
      PaymentGatewayAccountId: 'my-gateway-credentials',
      AllowedeWalletAccountIds: 'my-applepay,my-googlepay',
      CurrencyCode: 'USD',
      Amount: 99.99,
      CountryCode: 'US',
      AllowedBrands: 'visa,mastercard,amex',
      CustomerEmail: 'customer@example.com',
      merchantReference: 'ORDER-12345'
    })
  });
  const data = await response.json();
  console.log(data.sessionId);
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://service.pcibooking.net/api/eWalletOperation',
      headers={
          'Authorization': 'APIKEY your-api-key',
          'Content-Type': 'application/json'
      },
      json={
          'operation': 'CHARGE',
          'mode': 'LIVE',
          'PaymentGatewayAccountId': 'my-gateway-credentials',
          'AllowedeWalletAccountIds': 'my-applepay,my-googlepay',
          'CurrencyCode': 'USD',
          'Amount': 99.99,
          'CountryCode': 'US',
          'AllowedBrands': 'visa,mastercard,amex',
          'CustomerEmail': 'customer@example.com',
          'merchantReference': 'ORDER-12345'
      }
  )
  data = response.json()
  print(data['sessionId'])
  ```
</RequestExample>

## Response

The response contains the session details needed by the client-side Payments Library.

<ResponseExample>
  ```json 200 theme={null}
  {
      "sessionId": "abc123def456",
      "status": "Created"
  }
  ```

  ```json 400 theme={null}
  {
      "code": -125,
      "message": "Bad input data",
      "moreInfo": "...",
      "errorList": null
  }
  ```
</ResponseExample>


# Validate Operation Result
Source: https://developers.pcibooking.net/api-reference/payments-library/validate-operation

POST https://service.pcibooking.net/api/eWalletOperation/validateResults
Validate the data returned to the client after a Payments Library operation to ensure it was not altered.

<Card title="Payments Library Reference" icon="book" href="/payments-library/reference">
  Complete reference for Payments Library operations
</Card>

After a charge or tokenization operation completes, the client-side Payments Library returns a payment token to your callback function. Call this endpoint from your server to verify the token is authentic and has not been tampered with.

## Error Responses

| Code    | HTTP Status | Condition                                              |
| ------- | ----------- | ------------------------------------------------------ |
| `-1003` | `401`       | API key is missing or invalid.                         |
| `-125`  | `400`       | The results token is invalid or could not be verified. |

## Parameters

### Headers

<ParamField type="string">
  Your API key prefixed with `APIKEY`. Example: `APIKEY your-api-key`. See the [Authentication guide](/getting-started/authentication).
</ParamField>

### Request Body

<ParamField type="string">
  The payment token string received in the client-side callback function. Pass it as the raw request body.
</ParamField>

<RequestExample>
  ```javascript Node.js theme={null}
  const response = await fetch('https://service.pcibooking.net/api/eWalletOperation/validateResults', {
    method: 'POST',
    headers: {
      'Authorization': 'APIKEY your-api-key',
      'Content-Type': 'text/plain'
    },
    body: resultTokenFromClient
  });
  const data = await response.json();
  console.log(data.valid); // true if token is authentic
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://service.pcibooking.net/api/eWalletOperation/validateResults',
      headers={
          'Authorization': 'APIKEY your-api-key',
          'Content-Type': 'text/plain'
      },
      data=result_token_from_client
  )
  data = response.json()
  print(data['valid'])  # True if token is authentic
  ```
</RequestExample>

## Response

<ResponseExample>
  ```json 200 theme={null}
  {
      "valid": true
  }
  ```

  ```json 400 theme={null}
  {
      "code": -125,
      "message": "Bad input data",
      "moreInfo": "...",
      "errorList": null
  }
  ```
</ResponseExample>


# Initiate Card Display with OTP
Source: https://developers.pcibooking.net/api-reference/process-cards/card-display-otp

POST https://service.pcibooking.net/api/card-view-request/initView
Send a secure card viewing link with OTP verification to a cardholder.

<Card title="Card Display with OTP Guide" icon="book" href="/use-tokens/card-display-otp">
  How the OTP verification flow works end-to-end
</Card>

Sends an email containing a secure link to the specified viewer. When the viewer clicks the link and verifies their phone number via OTP, PCI Booking displays the card details on a hosted page.

## Error Responses

| Code  | HTTP Status | Condition                                                                 |
| ----- | ----------- | ------------------------------------------------------------------------- |
| -179  | 400         | Validation error: missing required fields, invalid email or phone format. |
| -1003 | 401         | Missing or invalid API key in the `Authorization` header.                 |
| -1003 | 401         | No valid identity found for the authenticated user.                       |
| -160  | 404         | Session incorrect or expired (when validating or retrieving OTP session). |

## Parameter Constraints

| Parameter         | Constraint                                                      |
| ----------------- | --------------------------------------------------------------- |
| `ViewerPhone`     | Required. Digits only, 8 to 20 characters. Regex: `^\d{8,20}$`. |
| `ViewerEmail`     | Required. Must be a valid email address.                        |
| `ViewerName`      | Max 100 characters.                                             |
| `TtlMinutes`      | Integer, range 1 to 30 (minutes). Default: 10.                  |
| `Language`        | 2-letter ISO 639-1 language code. Default: `en`.                |
| OTP code          | 6-digit numeric code. Regex: `^\d{6}$`.                         |
| Session ID (CVRT) | 32-character alphanumeric string. Regex: `^[a-zA-Z0-9]{32}$`.   |

## Parameters

### Headers

<ParamField type="string">
  Your API key prefixed with `APIKEY`. Example: `APIKEY your-api-key`. See the [Authentication guide](/getting-started/authentication).
</ParamField>

### Request Body

<ParamField type="string">
  The PCI Booking card token to display.
</ParamField>

<ParamField type="string">
  Email address to send the secure viewing link to.
</ParamField>

<ParamField type="string">
  Phone number for SMS verification. Format: country code + number, no `+` prefix (e.g. `1555123456` for US, `353858622255` for Ireland).
</ParamField>

<ParamField type="string">
  Full name of the viewer. Shown in the email and verification screens.
</ParamField>

<ParamField type="number">
  How long the email link stays valid, in minutes.
</ParamField>

<ParamField type="string">
  Two-letter language code (ISO 639-1) for the email and verification screens.
</ParamField>

<RequestExample>
  ```javascript Node.js theme={null}
  const response = await fetch('https://service.pcibooking.net/api/card-view-request/initView', {
    method: 'POST',
    headers: {
      'Authorization': 'APIKEY your-api-key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      Card_token: 'tok_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4',
      ViewerEmail: 'customer@example.com',
      ViewerPhone: '353858622255',
      ViewerName: 'Jane Smith',
      TtlMinutes: 15,
      Language: 'en'
    })
  });

  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://service.pcibooking.net/api/card-view-request/initView',
      headers={
          'Authorization': 'APIKEY your-api-key',
          'Content-Type': 'application/json'
      },
      json={
          'Card_token': 'tok_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4',
          'ViewerEmail': 'customer@example.com',
          'ViewerPhone': '353858622255',
          'ViewerName': 'Jane Smith',
          'TtlMinutes': 15,
          'Language': 'en'
      }
  )

  print(response.json())
  ```
</RequestExample>

## Response

<ResponseExample>
  ```json 200 theme={null}
  {
    "success": true,
    "message": "Card view request created successfully",
    "data": {
      "requestId": "s4iMrBQioE0JBCJIMN9kjnsLNDeGZUmG",
      "viewUrl": "https://static.pcibooking.net/card-view/s4iMrBQioE0JBCJIMN9kjnsLNDeGZUmG?language=en",
      "email": "customer@example.com",
      "expiresAt": "2026-01-12T14:30:00Z",
      "createdAt": "2026-01-12T14:00:00Z"
    }
  }
  ```

  ```json 400 Invalid Card Token theme={null}
  {
    "success": false,
    "error": {
      "code": "INVALID_CARD_TOKEN",
      "message": "The provided card token does not exist or is invalid"
    }
  }
  ```

  ```json 400 Invalid Email theme={null}
  {
    "success": false,
    "error": {
      "code": "INVALID_EMAIL",
      "message": "The provided email address is invalid"
    }
  }
  ```
</ResponseExample>


# Delete Payment Gateway Credentials
Source: https://developers.pcibooking.net/api-reference/process-cards/delete-credentials

DELETE https://service.pcibooking.net/api/credentials/{credentialsId}
Delete a stored set of payment gateway credentials.

<Card title="Gateway Credentials Guide" icon="book" href="/account-setup/gateway-credentials">
  Store and manage payment gateway credentials
</Card>

Permanently removes a stored set of payment gateway credentials from your account. Use this when you no longer need a particular gateway integration or want to rotate credentials by deleting the old set and storing a new one.

## Error Responses

| Code    | HTTP Status | Condition                                                    |
| ------- | ----------- | ------------------------------------------------------------ |
| `-1003` | `401`       | API key is missing or invalid, or user type is not `Booker`. |
| `-125`  | `400`       | Bad input data.                                              |

## Parameters

### Headers

<ParamField type="string">
  Your API key prefixed with `APIKEY`. Example: `APIKEY your-api-key`. See the [Authentication guide](/getting-started/authentication).
</ParamField>

### Path Parameters

<ParamField type="string">
  The ID given to the credentials for the payment gateway when they were [stored in PCI Booking](/api-reference/process-cards/store-credentials).
</ParamField>

<RequestExample>
  ```javascript Node.js theme={null}
  const response = await fetch(
    'https://service.pcibooking.net/api/credentials/my-stripe-credentials',
    {
      method: 'DELETE',
      headers: {
        'Authorization': 'APIKEY your-api-key'
      }
    }
  );

  console.log(response.status);
  ```

  ```python Python theme={null}
  import requests

  response = requests.delete(
      'https://service.pcibooking.net/api/credentials/my-stripe-credentials',
      headers={
          'Authorization': 'APIKEY your-api-key'
      }
  )

  print(response.status_code)
  ```
</RequestExample>

## Response

<ResponseExample>
  ```text 200 theme={null}
  Credentials deleted successfully. No content returned.
  ```

  ```json 400 theme={null}
  {
      "code": -125,
      "message": "Bad input data",
      "moreInfo": "...",
      "errorList": null
  }
  ```
</ResponseExample>


# Additional Guidance for Specific Payment Gateways
Source: https://developers.pcibooking.net/api-reference/process-cards/gateway-guidance

PSP-specific parameter requirements, quirks, and configuration notes for each payment gateway supported by PCI Booking.

<Card title="Gateway Guidance Guide" icon="book" href="/use-tokens/gateway-guidance">
  Get routing recommendations for payment processing
</Card>

Some of the payment gateways require additional parameters to be sent, or they offer optional functionality. The list below highlights the specific requirements of each such payment gateway. Any gateway not listed here uses the standard request.

## Unique Requirements Per Payment Gateway

### 3GDirectPay

* `CompanyID` and `ServiceType` credentials are required; the Company Token also selects sandbox vs production.
* `isDigitalGoods` sets the service description sent to the processor.
* No real-time Void. An authorisation can only be cancelled before its Payment Time Limit lapses, and a paid transaction cannot be cancelled. Refunds are testable in production only.

### Adyen

* The `ShopperInteraction` parameter specifies the sales channel through which the shopper provides their card details, and whether they are a returning customer. For POS accounts set this to `Ecommerce` (also the default).

### AdyenCheckout

* `ShopperInteraction` and `RecurringProcessingModel` may be supplied; `Currency` acts as the fallback currency for stand-alone tokenization.

### Airwallex

* `OrderDesc` sets the statement descriptor.
* Any keys in the `Parameters` object are passed through to the gateway as `metadata`.
* The `CustomerID` credential is required in order to tokenize.

### AMEX

* The `myRef` parameter is required and must contain 6 or more characters (only the first 6 are used as the trace number).
* No Charge and no Refund operations. Use PreAuth + Capture, and Void to reverse.

### Authorize.Net

* The `ECCenabled` parameter is only relevant to refund requests; it indicates whether PCI Booking sends the full card details with the request. When set to False, customers cannot perform refunds later than 120 days after the original charge.

### Azul

* A **client certificate** must be configured on the account.

### BAC

* `TerminalID`, `Username` and `Password` credentials are required (Live also needs the service API URL).
* CVV is mandatory (manual-entry mode). Integration documentation is private; you must be a BAC Credomatic bank customer.

### Better

* Credentials: `APIKey`, `PartnerId`, `MerchantId`.
* `OrderDesc` may be supplied.
* Tokenisation only happens within a Charge/PreAuth. There is no stand-alone Tokenize call.

### BML

* Only Charge and Void operations are supported.

### Bold

* `OrderDesc` sets the payment description.
* No PreAuth / Capture.
* Partial refund is not supported.

### Borgun

* The `myRef` parameter must be exactly **12 characters**, using A-Z and 0-9 only.

### BorgunBGateway

* The `myRef` parameter must be exactly **12 characters**, using A-Z and 0-9 only.

### CardNet

* Only Charge and Void operations are supported.
* Partial refund is not supported.

### CardStream

* `OrderDesc` provides an additional description / order reference for the payment.
* Set `TransactionType` to `MOTO` to allow charging without CVV.
* Refund is only possible after the transaction has settled (ACCEPTED).

### CaterPay

* `OrderDesc` provides an additional description related to the order the payment is for (CardStream white-label).
* Set `TransactionType` to `MOTO` to allow charging without CVV.

### CCV

* The `Language` credential must be one of `eng`, `nld`, `deu`, `fra`.
* `OrderDesc` may be supplied; the `AuthExemption` credential is also available.

### Checkout

* Credentials: `SecretKey`, `PublicKey`, `URLPrefix` (acquirer URL prefix); `ProcessingChannelId` is optional.
* `OrderDesc` may be supplied.

### Credorax

* `OrderDesc` is sent only when longer than 4 characters.
* `VoidType` may be AuthVoid (default), CaptureVoid or SaleVoid.
* PCI Booking's integration is certified with Credorax, so no extra certification step is required of you.

### Datatrans

* Tokens are created only via a dedicated Tokenize call, not within a Charge/PreAuth.

### DECTA

* Refund is only possible within 30 days of payment; partial refund is not supported.

### DLocal

* `SplitAccounts` (marketplace split payments) and `NotificationURL` may be supplied.

### Easebuzz

* `SURL` and `FURL` credentials (success/failure return URLs) are used by the form-charge flow.
* Hosted OTP/redirect (form-charge) flow; supports UPI.

### Eigen

* `APPID`, `EPAKey` and `NodeID` credentials are required.

### Elavon

* The PaymentGateway object must include the `RebatePWD` parameter containing the rebate (refund) password.
* Refund is allowed up to 115% of the original; the original currency must match.

### ElavonConvergePay

* Do **not** send a currency. The account is single-currency and supplying a currency value will error.

### ElavonFusebox

* Credentials: `ClientId`, `ClientSecret`, `Chain`, `Location`, `Terminal` (OAuth).
* `OrderDesc` may be supplied.

### ePDQ

* The merchant IP must be whitelisted in the ePDQ back-office.
* A sale cannot be voided (refund only), and partial refund is not supported.

### eWAY

* `PayerDetails.ClientIPAddress` is required.

### FatZebra

* `Username` and `APIToken` credentials are required.
* Payer details are required on Charge/PreAuth. `PayerDetails.ClientIPAddress` is sent as the customer IP.

### FirstData

* Payeezy / Fiserv REST gateway, distinct from **FirstDataIPG** (the SOAP IPG gateway that needs a client certificate).
* Credentials: `APIKey`, `Token`, `APISecret`.
* Refund re-sends the full card details.

### FirstDataIPG

* First Data (FirstDataIPG) requires authentication by **client certificate**. You must upload the certificate to the account. This gateway is not the same as Payzee.
* `PayerDetails.ClientIPAddress` (cardholder IP) is forwarded, falling back to a default if not supplied.

### Gateline

* Gateline requires authentication by **client certificate**. You must upload the certificate to the account.
* The `myRef` parameter must be numeric only.
* Gateline requires that the card owner's IP address be provided in the `ClientIPAddress` parameter of the PayerDetails object.

### GPWebPay

* The `myRef` parameter must be a 15-digit numeric value.
* `PayerDetails.Email` is mandatory.

### Heartland

* The `myRef` parameter must be numeric only.
* Set `CertiMode` to `1` for certification mode, which then also requires the `DeveloperID` and `VersionNumber` credentials.
* PCI Booking's integration is certified with Heartland, so no extra certification step is required of you.

### Ingenico

* `SkipAuthentication` may be supplied.
* Refund is only possible after the transaction is COMPLETED.

### KortaPay

* The `OriginalAmount` credential is mandatory for Void or Refund operations.
* `myRef` has a maximum of 15 characters.
* Partial refund is not supported.

### LianLianPay

* Product credentials are required: `ProductID`, `ProductName`, `ProductSKU`, `ProductURL`, `ProductShippingProvider` (plus optional shipping fields).
* No PreAuth / Capture.

### MaksuPay

* Credentials: `MerchantId`, `PrivateKey`, `PublicKeyHash`.
* `OrderDesc` may be supplied.

### Monek

* No real-time Void. Reverse via Refund; a pre-auth lapses after 28 days.

### Moneris

* The `ProcessingCountry` credential is required.
* Void is only possible after completion.

### MyPOS

* Credentials include `PrivateKey` and `PublicKey` (used to sign requests and encrypt card / CVV data), plus `SID`, `WalletNumber`, `KeyIndex`, `IPCVersion`, `Language`.
* `isDigitalGoods` sets the cart item description.

### NETS

* A Sale can only be refunded (not voided); only an Auth can be voided.

### Network.ae

* `APIKey` and `OutletReference` credentials are required.

### NEXI

* `OrderDesc` may be supplied.

### NMI

* Authenticate with either an `APIKey` credential, or `Username` + `Password`.

### NomuPay

* The `Region` credential is required; `AuthorizationType` and `CaptureType` credentials are also available.
* Tokenisation is not available in Turkey.

### OpenPay

* `MerchantID` and `PrivateKey` credentials are required.
* The cardholder device IP is forwarded as `X-Forwarded-For` (required by Mexican anti-fraud rules).
* `OrderDesc` sets the payment description.
* Void is processed as a Refund and works cleanly with MXN.

### PayArc

* `OrderDesc` must be under 25 characters; address fields must be at least 5 characters.

### PayDollar

* Credentials: `MerchantId`, `LoginId`, `Password`, `SecureHashSecretKey` (AsiaPay secure-hash signing).

### PayGate

* You must ensure that your merchant account in PayGate is configured with the "auto-settle" flag set to **OFF**; the payer country must be a 3-letter code.

### PayPalPaymentsPro

* Credentials: `Username`, `Password`, `Vendor`, `Partner` (PayPal Payflow Pro).
* The billing country must be a **3-digit numeric** country code; cardholder IP is forwarded when present.
* For a **full** refund omit the amount. Distinct from **PayPalWebsitePaymentsPro**.

### PayPalWebsitePaymentsPro

* Credentials: `Username`, `Password`, `Signature`, `Version` (PayPal NVP DoDirectPayment).
* US / UK / CA only. For a **full** refund omit the amount. Distinct from **PayPalPaymentsPro** (Payflow Pro).

### Payplug

* `OrderDesc` may be supplied.
* Do not send a currency. The account is single-currency.

### Paystack

* `Pin` (optional card PIN) may be supplied.
* Capture / Void are not supported.

### Paystation

* `OrderDesc` may be supplied.
* No Void.

### PayULatam

* `OrderDesc` may be supplied.
* The `Country` credential drives behaviour.
* In Panama only Charge is supported (no PreAuth/Capture).

### PayZen

* The `CaptureDelayDays` credential sets the capture delay at authorization (0 = same-night); there is no separate Capture call.

### Payzone

* `OrderDesc` and `PayerDetails.Email` are mandatory.
* No Authorization Code is returned.

### PCIBookingEU

* NomuPay white-label. Same behaviour as **NomuPay**.
* The `Region` credential is required.

### PCIBookingUSA

* `OrderDesc`, `CaptureSeq` + `CaptureTotal` (partial capture) may be supplied.
* `SendReceipt` (Yes/No) may be supplied.

### PeleCard

* A PreAuth cannot be voided online.

### PesoPay

* The `myRef` parameter must be unique on every submission.
* A Void operation must be performed with the `GatewayReference` returned from PreAuth, and not from Capture.

### PomeloPay

* Only Charge and Void operations are supported.

### PXP

* `MerchantID`, `StoreID`, `UserID` and `Password` credentials are required.
* `VoidType` may be `reversalSale` or `reversalPreAuthorization` (defaults to pre-auth reversal).
* An `amount` is required on every operation, including Void / Capture / Refund.

### Quickpay

* The `APIKey` credential is required.
* Card tokenisation is rejected for EEA cards.

### RapydCardPayments

* `AccessKey` and `SecretKey` credentials (HMAC request signing) are required.
* The card brand is currently sent as Visa regardless of the actual card. Confirm with support before use.

### RedDotPayment

* Only PreAuth and Charge operations are supported.
* Partial refund is not supported.

### Ryft

* `OrderDesc` sets the statement descriptor.

### SaferPay

* `OrderDesc` (payer note) may be supplied.
* Merchant IP allow-listing is required.

### SagePay

* US / CA / GB only.

### Shift4

* The `myRef` parameter must be numeric (10 digits).

### Shift4Clone

* The `myRef` parameter must be numeric (10 digits).

### SiamPay

* An Auth cannot be voided (charges only); Refund is only possible after settlement (\~1 day).

### Stripe

* Void is performed as a full Refund.

### StripeConnect

* `ConnectedAccount`, `ApplicationFeeAmount` (platform fee), and `HotelID`/`SiteName`/`ReservationID` (metadata) may be supplied.
* Void is performed as a full Refund.

### StripePaymentIntent

* To enable 3DS transaction support, contact Stripe and ask them to enable the 3DS Import (`payment_method_options.card.request_three_d_secure`) option on your test/live account.
* `SetupFutureUsage` lets you use Stripe Subscriptions with the PaymentIntents integration. It is provided in the credential object and the value can be `on_session` or `off_session`.
* `ApplicationFeeAmount` lets your platform take an application fee on direct charges. Provide it in the credential object together with `ConnectedAccount` data, and include a `ConnectionType` of `standardconnect` or `connect`.
* A captured charge cannot be voided.

### StripeStandardConnect

* `OrderDesc` may be supplied.
* `ConnectedAccount` and `ApplicationFeeAmount` may be supplied.

### TotalProcessing

* Authorization Code is only returned on live captures (not on PreAuth or test).

### Trust

* Tokenize is performed as an **ACCOUNTCHECK** (zero-amount) request.
* `TokenCurrency` sets the tokenize currency (default GBP).

### Tyro

* `MerchantID` and `APIPassword` credentials (Mastercard MPGS platform) are required.
* `myRef` is used as the order id, transaction id and reference. It must be unique and URL-safe per transaction.

### USAePay

* Credentials: `SourceKey`, `PIN`, `EndpointID`.
* `OrderDesc` may be supplied.

### Valitor

* `ServiceType` may be ONLINEPAYMENT, TELEPHONEPAYMENT or MAILORDER (MOTO modes suppress CVV).
* Refunds are not allowed on debit cards.

### ValitorPay

* Tokenisation creates a virtual card.
* `MCCCode` (a travel/hotel MCC switches to PreAuthorization), `TransactionType`, and `DefaultClearingDays`/`DefaultClearingAction` may be supplied.

### Verifone

* `PayerDetails` first and last name are required.
* `TokenScope` may be supplied (for tokenize).

### VersioPay

* The `Crypto` credential (account secret) is required.

### Viva

* `GroupId` can be set on Tokenize.
* Separate token-client credentials (`TokenClientId`, `TokenClientSecret`) are used for tokenize / refund / void.

### Windcave

* `EnableAddBillCard` may be supplied.

### Wirecard

* `OrderDesc` provides a payment reason for the payment gateway. The field is optional for Charge and PreAuth operations and is sent as false by default.

### Worldline TravelHub

* `OrderDesc` may be supplied.

### WorldPay

* The `isDigitalGoods` parameter sets the goods type (DIGITAL/PHYSICAL) and is sent as digital (`true`) by default.
* PCI Booking's integration is certified with WorldPay (SecureNet), so no extra certification step is required of you.

### WorldPayOnline

* The `ServiceKey` credential is used as the authorization header.
* `isDigitalGoods` overwrites the order description (the gateway has no free-text descriptor); amounts are in the smallest currency unit.

### WorldPayVantiv

* Only the first 6 characters of `myRef` are used (ticket number).

### WorldPayWPG

* `OrderDesc` may be supplied.

### WSPay

* One account does either Charge or PreAuth→Capture, not both.

### Xendit

* The `Country` credential (2-letter, default PH) may be supplied.

### YeePay

* Hosted SMS-OTP (form-charge) flow.

### Zeamster

* `OrderDesc` provides an additional description related to the order the payment is for.

### Zoop

* The `NoOfInstallments` parameter lets you use an installment plan and split the cost into multiple credit-card payments (micro credit). The value must be between 1 and 12.

### ZoozPaymentsOS

* `AppID`, `PublicKey`, `PrivateKey` and `APIVersion` credentials are required.
* Amounts are in the smallest currency unit.


# Get Payment Gateways
Source: https://developers.pcibooking.net/api-reference/process-cards/get-payment-gateways

GET https://service.pcibooking.net/api/paymentGateway
Retrieve a list of supported payment gateways and their credential descriptions.

<Card title="Universal Payment Gateway Guide" icon="book" href="/use-tokens/universal-payment-gateway">
  Route payments through any supported gateway
</Card>

Returns the full list of payment gateways supported by PCI Booking, along with the credential fields each gateway requires. Use this to discover available gateways and determine what credentials you need to store before routing transactions through a specific gateway.

## Error Responses

| Code   | HTTP Status | Condition                                                 |
| ------ | ----------- | --------------------------------------------------------- |
| `-160` | `404`       | A specific gateway name was requested but does not exist. |

<Note>
  This is a public endpoint. No authentication is required.
</Note>

## Parameters

### Headers

<ParamField type="string">
  Your API key prefixed with `APIKEY`. Example: `APIKEY your-api-key`. See the [Authentication guide](/getting-started/authentication).
</ParamField>

<RequestExample>
  ```javascript Node.js theme={null}
  const response = await fetch('https://service.pcibooking.net/api/paymentGateway', {
    headers: {
      'Authorization': 'APIKEY your-api-key'
    }
  });

  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://service.pcibooking.net/api/paymentGateway',
      headers={
          'Authorization': 'APIKEY your-api-key'
      }
  )

  print(response.json())
  ```
</RequestExample>

## Response

<ResponseExample>
  ```json 200 theme={null}
  [
      {
          "Name": "The name of the payment gateway",
          "Description": "A description of the payment gateway",
          "CredentialsNames": [
              "An array of parameters required by the specific payment gateway for authentication"
          ]
      },
      {
          "Name": "The name of the payment gateway",
          "Description": "A description of the payment gateway",
          "CredentialsNames": [
              "An array of parameters required by the specific payment gateway for authentication"
          ]
      },
    {...}
  ]
  ```

  ```json 404 theme={null}
  {
      "code": -160,
      "message": "Uri not found",
      "moreInfo": "Payment gateway not found",
      "errorList": null
  }
  ```
</ResponseExample>


# List Payment Gateway Credentials
Source: https://developers.pcibooking.net/api-reference/process-cards/list-credentials

GET https://service.pcibooking.net/api/credentials
Retrieve a list of all stored payment gateway credentials.

<Card title="Gateway Credentials Guide" icon="book" href="/account-setup/gateway-credentials">
  Store and manage payment gateway credentials
</Card>

Returns all credential set IDs stored in your PCI Booking account. Use this to see which payment gateway credentials you have on file, for example before creating a token replacement request or when auditing your stored credential sets.

## Error Responses

| Code    | HTTP Status | Condition                      |
| ------- | ----------- | ------------------------------ |
| `-1003` | `401`       | API key is missing or invalid. |
| `-1003` | `401`       | User type is not `Booker`.     |
| `-125`  | `400`       | Bad input data.                |

## Parameters

### Headers

<ParamField type="string">
  Your API key prefixed with `APIKEY`. Example: `APIKEY your-api-key`. See the [Authentication guide](/getting-started/authentication).
</ParamField>

<RequestExample>
  ```javascript Node.js theme={null}
  const response = await fetch('https://service.pcibooking.net/api/credentials', {
    headers: {
      'Authorization': 'APIKEY your-api-key'
    }
  });

  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://service.pcibooking.net/api/credentials',
      headers={
          'Authorization': 'APIKEY your-api-key'
      }
  )

  print(response.json())
  ```
</RequestExample>

## Response

<ResponseExample>
  ```json 200 theme={null}
  [
      "my-stripe-credentials",
      "my-adyen-credentials",
      "hotel-booking-gateway"
  ]
  ```

  ```json 400 theme={null}
  {
      "code": -125,
      "message": "Bad input data",
      "moreInfo": "...",
      "errorList": null
  }
  ```
</ResponseExample>


# Use Tokens API Reference
Source: https://developers.pcibooking.net/api-reference/process-cards/overview

API endpoints for processing cards: Universal Payment Gateway transactions, token replacement, card display, and FTPS/sFTP file transfer

API endpoints for using stored card tokens. For concepts and guidance, see the [Use Tokens guide](/use-tokens/overview).

## Token Replacement

| Endpoint                                                                          | Description                                                        |
| --------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| [Token Replacement](/api-reference/process-cards/token-replacement)               | Replace tokens with card data in HTTP requests to any third party. |
| [Token Replacement via SFTP](/api-reference/process-cards/token-replacement-sftp) | Replace tokens in batch files uploaded via SFTP.                   |
| [Token Replacement via FTPS](/api-reference/process-cards/token-replacement-ftps) | Replace tokens in batch files uploaded via FTPS.                   |

## Payment Gateway

| Endpoint                                                                  | Description                                                  |
| ------------------------------------------------------------------------- | ------------------------------------------------------------ |
| [Universal Payment Gateway](/use-tokens/universal-payment-gateway)        | Overview of gateway processing through PCI Booking.          |
| [Process Transaction](/api-reference/process-cards/process-transaction)   | Submit a charge, pre-auth, capture, refund, or void.         |
| [Get Payment Gateways](/api-reference/process-cards/get-payment-gateways) | List all supported payment gateways.                         |
| [Gateway Guidance](/api-reference/process-cards/gateway-guidance)         | Troubleshooting and best practices for gateway integrations. |

## Gateway Credentials

| Endpoint                                                                                    | Description                                     |
| ------------------------------------------------------------------------------------------- | ----------------------------------------------- |
| [Credentials Management](/account-setup/gateway-credentials)                                | Overview of gateway credential operations.      |
| [Retrieve Credential Structure](/api-reference/process-cards/retrieve-credential-structure) | Get the required fields for a specific gateway. |
| [Store Credentials](/api-reference/process-cards/store-credentials)                         | Save gateway credentials to your account.       |
| [List Credentials](/api-reference/process-cards/list-credentials)                           | List all stored gateway credentials.            |
| [Delete Credentials](/api-reference/process-cards/delete-credentials)                       | Remove gateway credentials from your account.   |

## Card Display

| Endpoint                                                                    | Description                                         |
| --------------------------------------------------------------------------- | --------------------------------------------------- |
| [Card Display Form](/api-reference/process-cards/request-card-display-form) | Render card details in a secure iframe.             |
| [Card Display with OTP](/api-reference/process-cards/card-display-otp)      | Send a secure card view link with OTP verification. |

## Retrieve Raw Card Data

| Endpoint                                                                    | Description                                                                   |
| --------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| [Retrieve Card Details](/api-reference/manage-tokens/retrieve-card-details) | Retrieve full, unmasked card data via API. Puts your system in PCI DSS scope. |
| [Risk Assessment](/api-reference/manage-tokens/risk-assessment)             | Analyze a card for fraud risk indicators before using the token.              |


# Process Transaction
Source: https://developers.pcibooking.net/api-reference/process-cards/process-transaction

POST https://service.pcibooking.net/api/paymentGateway
Process a payment gateway transaction using a stored card token.

<Card title="Processing Charges Guide" icon="book" href="/use-tokens/charge">
  Process payments using stored tokens
</Card>

PCI Booking retrieves the real card data from the token, constructs a PSP-specific request, sends it to your configured payment gateway, and returns the gateway's response.

<Note>
  Some payment gateways have additional requirements. Review the [gateway-specific guidance](/api-reference/process-cards/gateway-guidance) before sending your first transaction.
</Note>

## Error Responses

| Code    | HTTP Status | Condition                                                                                    |
| ------- | ----------- | -------------------------------------------------------------------------------------------- |
| `-1003` | `401`       | API key is missing or invalid.                                                               |
| `-1003` | `401`       | The token does not belong to the authenticated user.                                         |
| `-125`  | `400`       | Request body could not be parsed as JSON.                                                    |
| `-125`  | `400`       | Missing `cardToken` when the operation requires card data and no `GatewayToken` is provided. |
| `-125`  | `400`       | Invalid or malformed `cardToken` URI.                                                        |
| `-125`  | `400`       | Missing `Amount` for operations other than `Void` and `Tokenize`.                            |
| `-125`  | `400`       | Missing `GatewayReference` when `OperationType` is `Refund`.                                 |
| `-125`  | `400`       | The `credentialsId` was provided but the credentials were not found or could not be parsed.  |
| `-125`  | `400`       | The `PaymentGateway` JSON section could not be parsed.                                       |
| `-125`  | `400`       | The payment gateway does not support network tokens, but a network token brand was provided. |
| `-125`  | `400`       | Client certificate name was provided but the certificate could not be retrieved.             |
| `-150`  | `500`       | Failed to retrieve the bank card data from the vault.                                        |

## Parameter Constraints

* **OperationType**: Must be one of `Charge`, `PreAuth`, `Capture`, `Void`, `Refund`, `Tokenize`.
* **Amount**: Required for all operations except `Void` and `Tokenize`.
* **GatewayReference**: Required for `Refund` operations.
* **cardToken**: Required when the operation needs card data and no `GatewayToken` is provided. Must be a valid PCI Booking token URI containing a 32-character hex token.
* **credentialsId** or **PaymentGateway** object: One must be provided. If using `credentialsId`, the credentials must already be stored.

## Parameters

### Headers

<ParamField type="string">
  Your API key prefixed with `APIKEY`. Example: `APIKEY your-api-key`. See the [Authentication guide](/getting-started/authentication).
</ParamField>

### Query String

<ParamField type="string">
  The ID of credentials [stored in PCI Booking](/api-reference/process-cards/store-credentials). When provided, omit the `PaymentGateway` object from the request body.
</ParamField>

<ParamField type="string">
  The name of a [client certificate](/account-setup/client-certificates) to use for gateway authentication, if required by the gateway.
</ParamField>

### Request Body

<ParamField type="string">
  The PCI Booking card token URI, received during tokenization.
</ParamField>

<ParamField type="string">
  The operation to perform. One of: `Charge`, `PreAuth`, `Capture`, `Void`, `Refund`, `Tokenize`.
</ParamField>

<ParamField type="number">
  The transaction amount. Required for all operations except `Void` and `Tokenize`.
</ParamField>

<ParamField type="string">
  ISO 4217 currency code (e.g. `USD`, `EUR`). Required for all operations except `Void` and `Tokenize`.
</ParamField>

<ParamField type="object">
  The payment gateway name and credentials. Not required if `credentialsId` is provided.

  <Expandable title="Properties">
    <ParamField type="string">
      The payment gateway name (e.g. `Stripe`, `Adyen`, `Worldpay`). See [supported gateways](/api-reference/process-cards/get-payment-gateways).
    </ParamField>

    <ParamField type="object">
      Gateway-specific credential key-value pairs. See [gateway guidance](/api-reference/process-cards/gateway-guidance) for required credentials per gateway.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="string">
  The transaction ID of a prior operation. Required for `Capture` (reference the PreAuth), `Refund` (reference the Charge or Capture), and `Void` (reference the operation to void).
</ParamField>

<ParamField type="string">
  A token previously generated by the payment gateway. When provided, PCI Booking uses this gateway token instead of the card token for the transaction.
</ParamField>

<ParamField type="string">
  Your own reference for this transaction. Some gateways have specific format requirements. See [gateway guidance](/api-reference/process-cards/gateway-guidance).
</ParamField>

<ParamField type="boolean">
  For `Charge` and `PreAuth` operations, additionally generates a token from the payment gateway. The gateway token is returned in the response.
</ParamField>

<ParamField type="boolean">
  Whether to use 3D Secure authentication for this transaction.
</ParamField>

<ParamField type="object">
  Gateway-specific parameters as key-value pairs. These are passed through to the payment gateway. See [gateway guidance](/api-reference/process-cards/gateway-guidance) for supported parameters per gateway.
</ParamField>

### Payer and Order Details

<ParamField type="object">
  Details about the customer being charged. Some gateways require specific payer fields.

  <Expandable title="Properties">
    <ParamField type="string">
      Customer's first name.
    </ParamField>

    <ParamField type="string">
      Customer's last name.
    </ParamField>

    <ParamField type="string">
      Customer's email address.
    </ParamField>

    <ParamField type="string">
      Customer's phone number.
    </ParamField>

    <ParamField type="string">
      Billing address line 1.
    </ParamField>

    <ParamField type="string">
      Billing address line 2.
    </ParamField>

    <ParamField type="string">
      Billing address line 3.
    </ParamField>

    <ParamField type="string">
      Billing city.
    </ParamField>

    <ParamField type="string">
      Billing state or province.
    </ParamField>

    <ParamField type="string">
      Billing postal code.
    </ParamField>

    <ParamField type="string">
      ISO 3166-1 alpha-2 country code (e.g. `US`, `GB`).
    </ParamField>

    <ParamField type="string">
      Customer's IP address. Required by some gateways for fraud screening.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="string">
  Order description. Used by specific payment gateways. See [gateway guidance](/api-reference/process-cards/gateway-guidance) for details.
</ParamField>

<ParamField type="boolean">
  Indicates digital goods. Used by specific gateways (e.g. WorldPay).
</ParamField>

### Fallback Routing

<ParamField type="array">
  A list of fallback payment gateway accounts. If the primary gateway fails, PCI Booking tries each fallback in order.

  <Expandable title="Properties">
    <ParamField type="string">
      The stored credentials ID for the fallback gateway.
    </ParamField>

    <ParamField type="string">
      The client certificate name for the fallback gateway, if required.
    </ParamField>
  </Expandable>
</ParamField>

## Request Example

A `Charge` operation for \$150.00 USD, using inline gateway credentials:

<Tabs>
  <Tab title="curl">
    ```bash theme={null}
    curl -X POST "https://service.pcibooking.net/api/paymentGateway" \
      -H "Authorization: APIKEY your-api-key" \
      -H "Content-Type: application/json" \
      -d '{
        "cardToken": "https://service.pcibooking.net/api/payments/paycard/tok_abc123",
        "OperationType": "Charge",
        "Amount": 150.00,
        "Currency": "USD",
        "PaymentGateway": {
          "Name": "Stripe",
          "Credentials": {
            "SecretKey": "sk_test_abc123"
          }
        },
        "myRef": "order-98765",
        "PayerDetails": {
          "FirstName": "Jane",
          "LastName": "Smith",
          "Email": "jane.smith@example.com"
        }
      }'
    ```
  </Tab>

  <Tab title="Node.js">
    ```javascript theme={null}
    const response = await fetch("https://service.pcibooking.net/api/paymentGateway", {
      method: "POST",
      headers: {
        "Authorization": "APIKEY your-api-key",
        "Content-Type": "application/json"
      },
      body: JSON.stringify({
        cardToken: "https://service.pcibooking.net/api/payments/paycard/tok_abc123",
        OperationType: "Charge",
        Amount: 150.00,
        Currency: "USD",
        PaymentGateway: {
          Name: "Stripe",
          Credentials: {
            SecretKey: "sk_test_abc123"
          }
        },
        myRef: "order-98765",
        PayerDetails: {
          FirstName: "Jane",
          LastName: "Smith",
          Email: "jane.smith@example.com"
        }
      })
    });

    const data = await response.json();
    console.log(data);
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import requests

    response = requests.post(
        "https://service.pcibooking.net/api/paymentGateway",
        headers={
            "Authorization": "APIKEY your-api-key",
            "Content-Type": "application/json"
        },
        json={
            "cardToken": "https://service.pcibooking.net/api/payments/paycard/tok_abc123",
            "OperationType": "Charge",
            "Amount": 150.00,
            "Currency": "USD",
            "PaymentGateway": {
                "Name": "Stripe",
                "Credentials": {
                    "SecretKey": "sk_test_abc123"
                }
            },
            "myRef": "order-98765",
            "PayerDetails": {
                "FirstName": "Jane",
                "LastName": "Smith",
                "Email": "jane.smith@example.com"
            }
        }
    )

    print(response.json())
    ```
  </Tab>
</Tabs>

To use stored credentials instead of inline ones, pass the `credentialsId` query parameter and omit the `PaymentGateway` object:

<Tabs>
  <Tab title="curl">
    ```bash theme={null}
    curl -X POST "https://service.pcibooking.net/api/paymentGateway?credentialsId=my-stripe-prod" \
      -H "Authorization: APIKEY your-api-key" \
      -H "Content-Type: application/json" \
      -d '{
        "cardToken": "https://service.pcibooking.net/api/payments/paycard/tok_abc123",
        "OperationType": "Charge",
        "Amount": 150.00,
        "Currency": "USD",
        "myRef": "order-98765"
      }'
    ```
  </Tab>

  <Tab title="Node.js">
    ```javascript theme={null}
    const response = await fetch(
      "https://service.pcibooking.net/api/paymentGateway?credentialsId=my-stripe-prod",
      {
        method: "POST",
        headers: {
          "Authorization": "APIKEY your-api-key",
          "Content-Type": "application/json"
        },
        body: JSON.stringify({
          cardToken: "https://service.pcibooking.net/api/payments/paycard/tok_abc123",
          OperationType: "Charge",
          Amount: 150.00,
          Currency: "USD",
          myRef: "order-98765"
        })
      }
    );

    const data = await response.json();
    console.log(data);
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import requests

    response = requests.post(
        "https://service.pcibooking.net/api/paymentGateway",
        params={"credentialsId": "my-stripe-prod"},
        headers={
            "Authorization": "APIKEY your-api-key",
            "Content-Type": "application/json"
        },
        json={
            "cardToken": "https://service.pcibooking.net/api/payments/paycard/tok_abc123",
            "OperationType": "Charge",
            "Amount": 150.00,
            "Currency": "USD",
            "myRef": "order-98765"
        }
    )

    print(response.json())
    ```
  </Tab>
</Tabs>

## Response

The response contains the gateway's transaction result.

### Response Fields

<ParamField type="string">
  The outcome of the operation. See the status table below.
</ParamField>

<ParamField type="string">
  PCI Booking's internal transaction identifier.
</ParamField>

<ParamField type="string">
  The authorization code returned by the payment gateway. Only present on successful authorizations and charges.
</ParamField>

<ParamField type="string">
  The gateway's own transaction reference. Use this value for subsequent Capture, Void, or Refund operations on the same transaction.
</ParamField>

<ParamField type="string">
  Human-readable message from the payment gateway describing the result.
</ParamField>

<ParamField type="string">
  Raw response description from the acquirer/processor.
</ParamField>

### Operation Statuses

| Status             | Description                                                                                         |
| ------------------ | --------------------------------------------------------------------------------------------------- |
| `Accepted`         | The payment gateway accepted the request.                                                           |
| `Success`          | The operation completed successfully.                                                               |
| `Rejected`         | The gateway rejected the operation. See `GatewayDescription` and `AcquirerDescription` for details. |
| `TemporaryFailure` | The operation failed but can be retried.                                                            |
| `FatalFailure`     | The operation failed permanently.                                                                   |

<Info>
  Consider adding business logic based on the [CVV retention policy](/capture-cards/cvv-retention-policy) status after a transaction.
</Info>

<ResponseExample>
  ```json 200 Success theme={null}
  {
      "Status": "Success",
      "TransactionID": "txn_abc123",
      "AuthorizationCode": "AUTH456",
      "GatewayDescription": "Approved",
      "AcquirerDescription": "Transaction approved"
  }
  ```

  ```json 200 Rejected theme={null}
  {
      "Status": "Rejected",
      "TransactionID": "txn_abc123",
      "GatewayDescription": "Insufficient funds",
      "AcquirerDescription": "51 - Insufficient Funds"
  }
  ```

  ```json 400 theme={null}
  {
      "code": -125,
      "message": "Bad input data",
      "moreInfo": "...",
      "errorList": null
  }
  ```

  ```json 401 theme={null}
  {
      "code": -1003,
      "message": "Not authorized to access this resource",
      "moreInfo": "Bad or missing authorization data, expected APIKEY",
      "errorList": null
  }
  ```
</ResponseExample>


# Request a Card Display Form
Source: https://developers.pcibooking.net/api-reference/process-cards/request-card-display-form

GET https://service.pcibooking.net/api/payments/paycard/{cardtoken}/display
Create a Card Display form for displaying stored credit card data within an e-commerce site.

<Card title="Card Display Guide" icon="book" href="/use-tokens/card-display">
  Display stored card details to authorized users
</Card>

The response is the HTML content of the Card Display Form. You can use the request URL as the page URL that a customer is directed to, or as the source URL of an iframe element on your page.

## Parameters

### Authentication

<Warning>
  This is a browser-facing endpoint. Use one of the authentication methods below instead of the API key shown above.
</Warning>

<ParamField type="string">
  Recommended. A long-lived token for browser-side calls. [How to generate](/getting-started/authentication#access-token).
</ParamField>

<ParamField type="string">
  Alternative. Valid for 5 minutes. [How to generate](/api-reference/general/start-temporary-session).
</ParamField>

If both are provided, the session token takes precedence.

### Path Parameters

<ParamField type="string">
  The token ID as returned by one of the tokenization methods.
</ParamField>

### Query String

<ParamField type="string">
  A second Access Token, required when the card includes a CVV. Used for the "[Clear CVV](/api-reference/manage-tokens/clear-cvv)" method.
</ParamField>

### Display Options

<ParamField type="string">
  The form's language in ISO 639-1 (2-letter) format. [See here](/account-setup/custom-translations). If an unsupported language is received, English will be displayed. To add languages, [contact our support team](mailto:support@pcibooking.net).
</ParamField>

<ParamField type="string">
  The CSS resource name. See our guide on [managing stylesheets](/account-setup/stylesheets). If omitted, PCI Booking uses the [default CSS](/account-setup/stylesheets).
</ParamField>

<ParamField type="string">
  The domain name of the host site where the iframe is displayed. Read more on [setting up the postMessage mechanism](/capture-cards/postmessage-notifications).
</ParamField>

<ParamField type="boolean">
  Whether to display the card number in blocks of digits or as a single string of numbers.
</ParamField>

<RequestExample>
  ```javascript Node.js theme={null}
  const params = new URLSearchParams({
    language: 'en',
    formatCardNumber: 'true',
    postMessageHost: 'https://www.yoursite.com'
  });

  const response = await fetch(
    `https://service.pcibooking.net/api/payments/paycard/tok_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4/display?${params}`,
    {
      headers: {
        'Authorization': 'APIKEY your-api-key'
      }
    }
  );

  const html = await response.text();
  console.log(html);
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://service.pcibooking.net/api/payments/paycard/tok_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4/display',
      params={
          'language': 'en',
          'formatCardNumber': 'true',
          'postMessageHost': 'https://www.yoursite.com'
      },
      headers={
          'Authorization': 'APIKEY your-api-key'
      }
  )

  print(response.text)
  ```
</RequestExample>

## Response

<ResponseExample>
  ```html 200 theme={null}
  HTML content of form
  ```
</ResponseExample>


# Retrieve Payment Gateway Credential Structure
Source: https://developers.pcibooking.net/api-reference/process-cards/retrieve-credential-structure

GET https://service.pcibooking.net/api/credentials/paymentGateway/{name}
Retrieve the credential structure for a specific payment gateway.

<Card title="Gateway Credentials Guide" icon="book" href="/account-setup/gateway-credentials">
  Store and manage payment gateway credentials
</Card>

Returns the list of credential field names required by a specific payment gateway. Use this before [storing credentials](/api-reference/process-cards/store-credentials) to determine exactly which fields (such as merchant ID, API key, or shared secret) the gateway expects.

## Error Responses

| Code   | HTTP Status | Condition                                                         |
| ------ | ----------- | ----------------------------------------------------------------- |
| `-160` | `404`       | The specified payment gateway name is not valid or not supported. |

## Parameters

### Headers

<ParamField type="string">
  Your API key prefixed with `APIKEY`. Example: `APIKEY your-api-key`. See the [Authentication guide](/getting-started/authentication).
</ParamField>

### Path Parameters

<ParamField type="string">
  The name of the payment gateway. See the full list using the [Get Payment Gateways](/api-reference/process-cards/get-payment-gateways) method.
</ParamField>

<RequestExample>
  ```javascript Node.js theme={null}
  const response = await fetch(
    'https://service.pcibooking.net/api/credentials/paymentGateway/Stripe',
    {
      headers: {
        'Authorization': 'APIKEY your-api-key'
      }
    }
  );

  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://service.pcibooking.net/api/credentials/paymentGateway/Stripe',
      headers={
          'Authorization': 'APIKEY your-api-key'
      }
  )

  print(response.json())
  ```
</RequestExample>

## Response

<ResponseExample>
  ```json 200 theme={null}
  [
      "MerchantId",
      "ApiKey",
      "SharedSecret"
  ]
  ```

  ```json 400 theme={null}
  {
      "code": -125,
      "message": "Bad input data",
      "moreInfo": "...",
      "errorList": null
  }
  ```
</ResponseExample>


# Store Payment Gateway Credentials
Source: https://developers.pcibooking.net/api-reference/process-cards/store-credentials

PUT https://service.pcibooking.net/api/credentials/{credentialsId}
Store credentials for a payment gateway.

<Card title="Gateway Credentials Guide" icon="book" href="/account-setup/gateway-credentials">
  Store and manage payment gateway credentials
</Card>

<Warning title="Using the same ID would overwrite stored credentials">
  If you try to store credentials with an ID that already exists in your user in PCI Booking, the new set of credentials will overwrite the stored ones.
  This cannot be undone.
</Warning>

## Error Responses

| Code    | HTTP Status | Condition                                                                        |
| ------- | ----------- | -------------------------------------------------------------------------------- |
| `-1003` | `401`       | API key is missing or invalid, or user type is not `Booker`.                     |
| `-125`  | `400`       | Request body could not be parsed as JSON.                                        |
| `-125`  | `400`       | Request body is missing the `paymentGateway` (or `virtualCardProvider`) section. |
| `-125`  | `400`       | The `Name` property is missing from the provider section.                        |
| `-125`  | `400`       | The specified payment gateway name is not valid.                                 |
| `-125`  | `400`       | No credentials were provided, but the gateway requires them.                     |
| `-125`  | `400`       | One or more credential field names do not match the gateway's expected fields.   |

## Parameter Constraints

* **credentialsId**: Required string. Used as the unique identifier for this credential set.
* **Request body**: Must be valid JSON containing either a `paymentGateway` or `virtualCardProvider` top-level key.
* **Name** (inside provider object): Required, non-empty string matching a supported gateway.
* **Credentials** (inside provider object): All property names must match the gateway's expected credential field names (see [Retrieve Credential Structure](/api-reference/process-cards/retrieve-credential-structure)).

## Parameters

### Headers

<ParamField type="string">
  Your API key prefixed with `APIKEY`. Example: `APIKEY your-api-key`. See the [Authentication guide](/getting-started/authentication).
</ParamField>

### Path Parameters

<ParamField type="string">
  The unique ID for this set of credentials. You will reference this ID when sending a [request through the Universal Payment Gateway](/api-reference/process-cards/process-transaction).
</ParamField>

### Request Body

<ParamField type="object">
  A custom object specifying the name of the payment gateway and its credentials.
</ParamField>

<RequestExample>
  ```javascript Node.js theme={null}
  const response = await fetch(
    'https://service.pcibooking.net/api/credentials/my-stripe-credentials',
    {
      method: 'PUT',
      headers: {
        'Authorization': 'APIKEY your-api-key',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        paymentGateway: {
          Name: 'Stripe',
          Credentials: {
            SecretKey: 'sk_live_abc123'
          }
        }
      })
    }
  );

  console.log(response.status);
  ```

  ```python Python theme={null}
  import requests

  response = requests.put(
      'https://service.pcibooking.net/api/credentials/my-stripe-credentials',
      headers={
          'Authorization': 'APIKEY your-api-key',
          'Content-Type': 'application/json'
      },
      json={
          'paymentGateway': {
              'Name': 'Stripe',
              'Credentials': {
                  'SecretKey': 'sk_live_abc123'
              }
          }
      }
  )

  print(response.status_code)
  ```
</RequestExample>

## Response

<ResponseExample>
  ```text 200 theme={null}
  Credentials stored successfully. No content returned.
  ```

  ```json 400 theme={null}
  {
      "code": -125,
      "message": "Bad input data",
      "moreInfo": "...",
      "errorList": null
  }
  ```
</ResponseExample>


# Token Replacement in Request
Source: https://developers.pcibooking.net/api-reference/process-cards/token-replacement

POST https://service.pcibooking.net/api/payments/paycard/relay
Replace card tokens with real card data and relay the request to a third-party API.

<Card title="Token Replacement Guide" icon="book" href="/use-tokens/token-replacement-in-request">
  Replace tokens with card data in API requests
</Card>

This is PCI Booking's core proxy feature. Instead of processing payments through PCI Booking's gateway integrations, you send the exact API request your third-party system expects, with token placeholders where card data should go. PCI Booking swaps in the real card data and forwards the request transparently, so the third party receives a normal API call with real card details while you never handle sensitive data.

## Error Responses

| Code  | HTTP Status | Condition                                   |
| ----- | ----------- | ------------------------------------------- |
| -125  | 400         | httpMethod not POST/GET/PUT/PATCH/DELETE    |
| -160  | 404         | Card not found                              |
| -150  | 500         | Card retrieval failed                       |
| -125  | 400         | Profile name provided but profile not found |
| -125  | 400         | Content replacement failed                  |
| -125  | 400         | Empty content body                          |
| -125  | 400         | Missing Content-Type header                 |
| -125  | 400         | Target URI invalid                          |
| -1003 | 401         | User not owner and not associated           |

## Parameter Constraints

* **cardToken** must contain a valid card URI with a 32-hex token.
* **targetUri** is required.
* **httpMethod** defaults to POST. Accepted values: POST, GET, PUT, PATCH, DELETE.
* **postResponseAction** accepts `ClearCVV` or `DeleteToken`.

<Note>
  All URLs must be HTTPS. URL-encode all query string components.
</Note>

## Parameters

### Authentication

<Warning>
  This is a browser-facing endpoint. Use one of the authentication methods below instead of the API key shown above.
</Warning>

<ParamField type="string">
  Recommended. A long-lived token for browser-side calls. [How to generate](/getting-started/authentication#access-token).
</ParamField>

<ParamField type="string">
  Alternative. Valid for 5 minutes. [How to generate](/api-reference/general/start-temporary-session).
</ParamField>

If both are provided, the session token takes precedence.

### Query String

<ParamField type="string">
  The token URI identifying the card in PCI Booking.
</ParamField>

<ParamField type="string">
  The HTTPS URL of the third party to relay the request to.
</ParamField>

<ParamField type="string">
  The HTTP method to use when calling the target URI. One of: `POST`, `GET`, `PUT`, `PATCH`, `DELETE`.
</ParamField>

<ParamField type="string">
  The ID of a [target profile](/account-setup/target-profiles) configured for this request. If omitted, PCI Booking uses [placeholder-based replacement](/use-tokens/token-replacement-in-request#how-it-works) instead.
</ParamField>

<ParamField type="string">
  For placeholder-based replacement: the key containing card data in form-data or query string. Ignored if `profileName` is provided. If omitted, PCI Booking searches the request body for [placeholders](/use-tokens/token-replacement-in-request#supported-content-types).
</ParamField>

<ParamField type="string">
  Action to perform after a successful relay. `ClearCVV` clears the CVV from the token. `DeleteToken` deletes the token entirely. If omitted, no action is taken.
</ParamField>

<ParamField type="int">
  Seconds to wait for the third-party response before timing out.
</ParamField>

### Headers

<ParamField type="string">
  Compression format: `gzip` or `deflate`. Omit if no compression is needed.
</ParamField>

### Request Body

The request body is relayed to the third party as-is, with token placeholders replaced by real card data. Structure it as required by the third party's API.

## Request Example

Send a JSON payment request to a third-party API, with PCI Booking replacing the card placeholders with real data before forwarding:

<Tabs>
  <Tab title="curl">
    ```bash theme={null}
    curl -X POST "https://service.pcibooking.net/api/payments/paycard/relay?cardToken=https%3A%2F%2Fservice.pcibooking.net%2Fapi%2Fpayments%2Fpaycard%2Ftok_abc123&targetURI=https%3A%2F%2Fapi.thirdparty.com%2Fv1%2Fpayments&httpMethod=POST" \
      -H "Authorization: APIKEY your-api-key" \
      -H "Content-Type: application/json" \
      -d '{
        "amount": 250.00,
        "currency": "USD",
        "card": {
          "number": "{{CardNo}}",
          "expMonth": "{{ExpMonth}}",
          "expYear": "{{ExpYear}}",
          "cvv": "{{Cvv}}",
          "holderName": "{{NameOnCard}}"
        },
        "reference": "order-98765"
      }'
    ```
  </Tab>

  <Tab title="Node.js">
    ```javascript theme={null}
    const params = new URLSearchParams({
      cardToken: "https://service.pcibooking.net/api/payments/paycard/tok_abc123",
      targetURI: "https://api.thirdparty.com/v1/payments",
      httpMethod: "POST"
    });

    const response = await fetch(
      `https://service.pcibooking.net/api/payments/paycard/relay?${params}`,
      {
        method: "POST",
        headers: {
          "Authorization": "APIKEY your-api-key",
          "Content-Type": "application/json"
        },
        body: JSON.stringify({
          amount: 250.00,
          currency: "USD",
          card: {
            number: "{{CardNo}}",
            expMonth: "{{ExpMonth}}",
            expYear: "{{ExpYear}}",
            cvv: "{{Cvv}}",
            holderName: "{{NameOnCard}}"
          },
          reference: "order-98765"
        })
      }
    );

    const data = await response.text();
    console.log(data);
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import requests

    response = requests.post(
        "https://service.pcibooking.net/api/payments/paycard/relay",
        params={
            "cardToken": "https://service.pcibooking.net/api/payments/paycard/tok_abc123",
            "targetURI": "https://api.thirdparty.com/v1/payments",
            "httpMethod": "POST"
        },
        headers={
            "Authorization": "APIKEY your-api-key",
            "Content-Type": "application/json"
        },
        json={
            "amount": 250.00,
            "currency": "USD",
            "card": {
                "number": "{{CardNo}}",
                "expMonth": "{{ExpMonth}}",
                "expYear": "{{ExpYear}}",
                "cvv": "{{Cvv}}",
                "holderName": "{{NameOnCard}}"
            },
            "reference": "order-98765"
        }
    )

    print(response.text)
    ```
  </Tab>
</Tabs>

PCI Booking replaces the `{{CardNo}}`, `{{ExpMonth}}`, `{{ExpYear}}`, `{{Cvv}}`, and `{{NameOnCard}}` placeholders with the actual card data from the token before forwarding the request to `api.thirdparty.com`.

To use a target profile (pre-configured replacement rules) instead of inline placeholders:

<Tabs>
  <Tab title="curl">
    ```bash theme={null}
    curl -X POST "https://service.pcibooking.net/api/payments/paycard/relay?cardToken=https%3A%2F%2Fservice.pcibooking.net%2Fapi%2Fpayments%2Fpaycard%2Ftok_abc123&targetURI=https%3A%2F%2Fapi.thirdparty.com%2Fv1%2Fpayments&httpMethod=POST&profileName=my-thirdparty-profile" \
      -H "Authorization: APIKEY your-api-key" \
      -H "Content-Type: application/json" \
      -d '{
        "amount": 250.00,
        "currency": "USD",
        "reference": "order-98765"
      }'
    ```
  </Tab>

  <Tab title="Node.js">
    ```javascript theme={null}
    const params = new URLSearchParams({
      cardToken: "https://service.pcibooking.net/api/payments/paycard/tok_abc123",
      targetURI: "https://api.thirdparty.com/v1/payments",
      httpMethod: "POST",
      profileName: "my-thirdparty-profile"
    });

    const response = await fetch(
      `https://service.pcibooking.net/api/payments/paycard/relay?${params}`,
      {
        method: "POST",
        headers: {
          "Authorization": "APIKEY your-api-key",
          "Content-Type": "application/json"
        },
        body: JSON.stringify({
          amount: 250.00,
          currency: "USD",
          reference: "order-98765"
        })
      }
    );

    const data = await response.text();
    console.log(data);
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import requests

    response = requests.post(
        "https://service.pcibooking.net/api/payments/paycard/relay",
        params={
            "cardToken": "https://service.pcibooking.net/api/payments/paycard/tok_abc123",
            "targetURI": "https://api.thirdparty.com/v1/payments",
            "httpMethod": "POST",
            "profileName": "my-thirdparty-profile"
        },
        headers={
            "Authorization": "APIKEY your-api-key",
            "Content-Type": "application/json"
        },
        json={
            "amount": 250.00,
            "currency": "USD",
            "reference": "order-98765"
        }
    )

    print(response.text)
    ```
  </Tab>
</Tabs>

## Response

**200** - The third-party response, relayed back as-is.

<Info>
  Consider adding business logic based on the [CVV retention policy status](/capture-cards/cvv-retention-policy) after a token replacement request.
</Info>

<ResponseExample>
  ```text 200 theme={null}
  The third-party response is returned as-is. The format and content depend entirely on the destination API.
  ```

  ```json 401 theme={null}
  {
      "code": -1003,
      "message": "Not authorized to access this resource",
      "moreInfo": "Bad or missing authorization data, expected Temp Session or One-Time Accesss Token",
      "errorList": null
  }
  ```

  ```json 400 Invalid profile theme={null}
  {
      "code": -125,
      "message": "Bad input data",
      "moreInfo": "Couldn't fetch a valid pciShield profile:: wsc",
      "errorList": null
  }
  ```

  ```json 400 Invalid URI theme={null}
  {
      "code": -125,
      "message": "Bad input data",
      "moreInfo": "Invalid target Uri::",
      "errorList": null
  }
  ```
</ResponseExample>


# Token Replacement to FTPS
Source: https://developers.pcibooking.net/api-reference/process-cards/token-replacement-ftps

PUT https://service.pcibooking.net/api/ftps/{serverAddress}/{folderPath}/{fileName}
Replace card tokens in a document and upload the result to an FTPS server.

<Card title="File Transfer Token Replacement Guide" icon="book" href="/use-tokens/file-transfer-token-replacement">
  Replace tokens with card data in FTPS file transfers
</Card>

Performs token replacement on a file and uploads the result directly to an FTPS server. Use this when your payment processor or partner requires batch file delivery over FTPS (FTP over TLS). PCI Booking replaces all card tokens in the file body with real card data before uploading.

## Error Responses

| Code    | HTTP Status | Condition                                                              |
| ------- | ----------- | ---------------------------------------------------------------------- |
| `-1003` | `401`       | Authorization token is missing or invalid.                             |
| `-125`  | `400`       | Invalid host format (e.g. multiple colons in the server address).      |
| `-125`  | `400`       | Invalid or missing Basic Auth credentials in the Authorization header. |
| `-125`  | `400`       | The requested filter name is not recognized.                           |
| `-125`  | `400`       | Token replacement could not be applied to the file content.            |
| `-1003` | `401`       | FTPS login failed (invalid server credentials).                        |
| `-160`  | `404`       | File upload failed on the remote server.                               |

## Parameter Constraints

* **serverAddress**: Format is `hostname` or `hostname:port`. Only one colon is allowed. Default port is 22.
* **filter**: Must be one of: `GBT`, `SIMPLECSV`, `SIMPLEJSON`, `AIR`, `IUR`, `TADC`, `CSV`. Case-insensitive.
* **Authorization header**: Must contain valid Basic Auth credentials (`username:password`) for the FTPS server.

## Parameters

### Authentication

<Warning>
  This is a browser-facing endpoint. Use one of the authentication methods below instead of the API key shown above.
</Warning>

<ParamField type="string">
  Recommended. A long-lived token for browser-side calls. [How to generate](/getting-started/authentication#access-token).
</ParamField>

<ParamField type="string">
  Alternative. Valid for 5 minutes. [How to generate](/api-reference/general/start-temporary-session).
</ParamField>

If both are provided, the session token takes precedence.

### Path Parameters

<ParamField type="string">
  The FTPS server address. This can be an IP address or domain name. Add the port number with a colon if required. For example: `fsgatewaytest.aexp.com:22` or `10.200.1.10`.
</ParamField>

<ParamField type="string">
  The folder path where the file should be uploaded to. This can be an individual folder or a full path.
</ParamField>

<ParamField type="string">
  The file name for the content being uploaded, including extension. For example: `PCIBTST.xml`.
</ParamField>

### Query String

<ParamField type="string">
  Indicates the format of the file being sent. Read more on [Supported Formats](/reference/api-conventions).
</ParamField>

<ParamField type="string">
  The timeout, in seconds, for the FTPS server to respond.
</ParamField>

### Headers

<ParamField type="string">
  Comma-separated token values to insert into the file. Tokens should be listed in the order of their appearance. For tokens appearing multiple times, include the number of occurrences in square brackets.
</ParamField>

<ParamField type="string">
  The authorization parameter used to authenticate to the FTPS server.
</ParamField>

<ParamField type="string">
  Supported compression formats: `gzip` and `deflate`. Omit this header if no compression is needed.
</ParamField>

### Request Body

The request body contains the raw file content as text. PCI Booking replaces any token placeholders with real card data (based on the `filter` format), then uploads the result to the FTPS server.

<RequestExample>
  ```javascript Node.js theme={null}
  const response = await fetch(
    'https://service.pcibooking.net/api/ftps/ftps.gateway.com:990/uploads/batch/PCIBTST.xml?filter=GBT',
    {
      method: 'PUT',
      headers: {
        'Authorization': 'Basic dXNlcm5hbWU6cGFzc3dvcmQ=',
        'X-PciBooking-carduri': 'tok_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4,tok_f6e5d4c3b2a1f6e5d4c3b2a1f6e5d4c3[2]',
        'Content-Type': 'text/plain'
      },
      body: '<CardData>\n  <Card1>{{CardNo}}</Card1>\n  <Card2>{{CardNo}}</Card2>\n</CardData>'
    }
  );

  console.log(response.status);
  ```

  ```python Python theme={null}
  import requests

  response = requests.put(
      'https://service.pcibooking.net/api/ftps/ftps.gateway.com:990/uploads/batch/PCIBTST.xml',
      params={'filter': 'GBT'},
      headers={
          'Authorization': 'Basic dXNlcm5hbWU6cGFzc3dvcmQ=',
          'X-PciBooking-carduri': 'tok_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4,tok_f6e5d4c3b2a1f6e5d4c3b2a1f6e5d4c3[2]',
          'Content-Type': 'text/plain'
      },
      data='<CardData>\n  <Card1>{{CardNo}}</Card1>\n  <Card2>{{CardNo}}</Card2>\n</CardData>'
  )

  print(response.status_code)
  ```
</RequestExample>

## Response

<ResponseExample>
  ```text 204 theme={null}
  File uploaded successfully. No content returned.
  ```

  ```json 400 theme={null}
  {
      "code": -125,
      "message": "Bad input data",
      "moreInfo": "...",
      "errorList": null
  }
  ```

  ```json 401 theme={null}
  {
      "code": -1003,
      "message": "Not authorized to access this resource",
      "moreInfo": "Bad or missing authorization data, expected Temp Session or One-Time Access Token",
      "errorList": null
  }
  ```
</ResponseExample>


# Token Replacement to sFTP
Source: https://developers.pcibooking.net/api-reference/process-cards/token-replacement-sftp

PUT https://service.pcibooking.net/api/sftp/{serverAddress}/{folderPath}/{fileName}
Replace card tokens in a document and upload the result to an sFTP server.

<Card title="File Transfer Token Replacement Guide" icon="book" href="/use-tokens/file-transfer-token-replacement">
  Replace tokens with card data in SFTP file transfers
</Card>

Performs token replacement on a file and uploads the result directly to an SFTP server. Use this when you need to send batch files containing card data to a payment processor or partner that accepts SFTP delivery. PCI Booking replaces all card tokens in the file body with the real card data before uploading.

## Error Responses

| Code    | HTTP Status | Condition                                                              |
| ------- | ----------- | ---------------------------------------------------------------------- |
| `-1003` | `401`       | Authorization token is missing or invalid.                             |
| `-125`  | `400`       | Invalid host format (e.g. multiple colons in the server address).      |
| `-125`  | `400`       | Invalid or missing Basic Auth credentials in the Authorization header. |
| `-125`  | `400`       | The requested filter name is not recognized.                           |
| `-125`  | `400`       | Token replacement could not be applied to the file content.            |
| `-1003` | `401`       | SFTP login failed (invalid server credentials).                        |
| `-160`  | `404`       | File upload failed on the remote server.                               |

## Parameter Constraints

* **serverAddress**: Format is `hostname` or `hostname:port`. Only one colon is allowed. Default port is 22.
* **filter**: Must be one of: `GBT`, `SIMPLECSV`, `SIMPLEJSON`, `AIR`, `IUR`, `TADC`, `CSV`. Case-insensitive.
* **Authorization header**: Must contain valid Basic Auth credentials (`username:password`) for the SFTP server.

## Parameters

### Authentication

<Warning>
  This is a browser-facing endpoint. Use one of the authentication methods below instead of the API key shown above.
</Warning>

<ParamField type="string">
  Recommended. A long-lived token for browser-side calls. [How to generate](/getting-started/authentication#access-token).
</ParamField>

<ParamField type="string">
  Alternative. Valid for 5 minutes. [How to generate](/api-reference/general/start-temporary-session).
</ParamField>

If both are provided, the session token takes precedence.

### Path Parameters

<ParamField type="string">
  The sFTP server address. This can be an IP address or domain name. Add the port number with a colon if required. For example: `fsgatewaytest.aexp.com:22` or `10.200.1.10`.
</ParamField>

<ParamField type="string">
  The folder path where the file should be uploaded to. This can be an individual folder or a full path.
</ParamField>

<ParamField type="string">
  The file name for the content being uploaded, including extension. For example: `PCIBTST.xml`.
</ParamField>

### Query String

<ParamField type="string">
  Indicates the format of the file being sent. Read more on [Supported Formats](/reference/api-conventions).
</ParamField>

<ParamField type="string">
  The timeout, in seconds, for the sFTP server to respond.
</ParamField>

### Headers

<ParamField type="string">
  Comma-separated token values to insert into the file. Tokens should be listed in the order of their appearance. For tokens appearing multiple times, include the number of occurrences in square brackets.
</ParamField>

<ParamField type="string">
  The authorization parameter used to authenticate to the sFTP server.
</ParamField>

<ParamField type="string">
  Supported compression formats: `gzip` and `deflate`. Omit this header if no compression is needed.
</ParamField>

### Request Body

The request body contains the raw file content as text. PCI Booking replaces any token placeholders with real card data (based on the `filter` format), then uploads the result to the sFTP server.

<RequestExample>
  ```javascript Node.js theme={null}
  const response = await fetch(
    'https://service.pcibooking.net/api/sftp/sftp.gateway.com:22/uploads/batch/PCIBTST.xml?filter=GBT',
    {
      method: 'PUT',
      headers: {
        'Authorization': 'Basic dXNlcm5hbWU6cGFzc3dvcmQ=',
        'X-PciBooking-carduri': 'tok_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4,tok_f6e5d4c3b2a1f6e5d4c3b2a1f6e5d4c3[2]',
        'Content-Type': 'text/plain'
      },
      body: '<CardData>\n  <Card1>{{CardNo}}</Card1>\n  <Card2>{{CardNo}}</Card2>\n</CardData>'
    }
  );

  console.log(response.status);
  ```

  ```python Python theme={null}
  import requests

  response = requests.put(
      'https://service.pcibooking.net/api/sftp/sftp.gateway.com:22/uploads/batch/PCIBTST.xml',
      params={'filter': 'GBT'},
      headers={
          'Authorization': 'Basic dXNlcm5hbWU6cGFzc3dvcmQ=',
          'X-PciBooking-carduri': 'tok_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4,tok_f6e5d4c3b2a1f6e5d4c3b2a1f6e5d4c3[2]',
          'Content-Type': 'text/plain'
      },
      data='<CardData>\n  <Card1>{{CardNo}}</Card1>\n  <Card2>{{CardNo}}</Card2>\n</CardData>'
  )

  print(response.status_code)
  ```
</RequestExample>

## Response

<ResponseExample>
  ```text 204 theme={null}
  File uploaded successfully. No content returned.
  ```

  ```json 400 theme={null}
  {
      "code": -125,
      "message": "Bad input data",
      "moreInfo": "...",
      "errorList": null
  }
  ```

  ```json 401 theme={null}
  {
      "code": -1003,
      "message": "Not authorized to access this resource",
      "moreInfo": "Bad or missing authorization data, expected Temp Session or One-Time Access Token",
      "errorList": null
  }
  ```
</ResponseExample>


# Card Entry Form Webhook
Source: https://developers.pcibooking.net/api-reference/tokenize-cards/card-entry-form-callback

PCI Booking sends a POST request to your callback URL each time the status of a card entry form session changes.

<Card title="Hosted Card Entry Form Guide" icon="book" href="/capture-cards/hosted-card-entry-form#option-2-api-session">
  API session approach for embedded card capture
</Card>

When you create a session-based card entry form with a `CallBackURL`, PCI Booking sends a POST request to that URL each time the session status changes. Your endpoint must accept the following payload.

## Webhook Payload

```json theme={null}
{
  "CaptureCardRequestID": "uC1efRTOpU4p3hmhH7fbY3J6A9LYL3j5",
  "CaptureCardRequestStatus": "OK",
  "CardUri": "https://service.pcibooking.net/api/payments/paycard/G54Cvv0GZddE4TTr44mHj12DssAzb5Dp"
}
```

<ParamField type="string">
  The ID of the card entry form session. Matches the `RequestID` returned by [Create Card Entry Form Session](/api-reference/tokenize-cards/create-card-entry-form-session).
</ParamField>

<ParamField type="string">
  The current status of the session. Possible values:

  | Status       | Value     | Description                                                                                                   |
  | ------------ | --------- | ------------------------------------------------------------------------------------------------------------- |
  | Card stored  | `OK`      | Card was tokenized successfully. The `CardUri` field contains the token URL.                                  |
  | Store failed | `Failure` | Card storage failed due to a general error.                                                                   |
  | Bad data     | `BadData` | Card storage failed because the cardholder entered invalid data (e.g. a card type not in the supported list). |
  | Expired      | `Expired` | The session exceeded its `TTL` without a successful submission.                                               |
</ParamField>

<ParamField type="string">
  The PCI Booking token URL for the stored card. Only present when `CaptureCardRequestStatus` is `OK`.
</ParamField>

## Expected Response

Your callback endpoint must return **200 OK** to acknowledge receipt. If PCI Booking does not receive a 200 response, the notification is not retried.


# Card By Link Webhook
Source: https://developers.pcibooking.net/api-reference/tokenize-cards/cotp-callback

PCI Booking sends a POST request to your callback URL each time the status of a Card By Link request changes.

<Card title="Card By Link Guide" icon="book" href="/capture-cards/card-by-link">
  Send secure card capture links via email or SMS
</Card>

When you create a Card By Link request with a `CallBackURL`, PCI Booking sends a POST request to that URL each time the request status changes. Your endpoint must accept the following payload.

## Callback Payload

```json theme={null}
{
  "RequestID": "uC1efRTOpU4p3hmhH7fbY3J6A9LYL3j5",
  "LastNotifiedStatus": "CardStored",
  "LastNotifiedTime": "2017-12-19T20:07:32"
}
```

<ParamField type="string">
  The unique identifier for the Card By Link request.
</ParamField>

<ParamField type="string">
  The current status of the request. Possible values:

  | Channel     | Value              | Description                                          |
  | ----------- | ------------------ | ---------------------------------------------------- |
  | Email / SMS | `MessageQueued`    | Message was added to the PCI Booking queue.          |
  | SMS only    | `MessageSent`      | The message was sent to the recipient.               |
  | SMS only    | `MessageFailed`    | Message delivery to the recipient failed.            |
  | SMS only    | `MessageDelivered` | Message was successfully delivered to the recipient. |
  | Email / SMS | `FormViewed`       | Recipient viewed the capture form.                   |
  | Email / SMS | `CardStored`       | Card was captured and tokenized successfully.        |
  | Email / SMS | `LinkExpired`      | The link to the capture form has expired.            |
  | Email / SMS | `StoreFailed`      | Capture form submission failed.                      |
</ParamField>

<ParamField type="string">
  Timestamp of the status change (ISO 8601 format).
</ParamField>

## What to Do on `CardStored`

Once you receive a callback with `LastNotifiedStatus: CardStored`, call [Retrieve Request](/api-reference/tokenize-cards/cotp-retrieve-request) to get the full request details including the `CardUri` (token URL).

<Warning title="CVV capture requests">
  For CVV-only requests, PCI Booking creates a **new token** that is a full copy of the original card details plus the captured CVV. The original token is not modified and does not contain the CVV. You should delete the original token if it is no longer needed, otherwise it will continue to incur monthly storage fees.
</Warning>

<Info>
  Remember to set the [CVV Retention Policy](/capture-cards/cvv-retention-policy) on the token once `CardStored` is received.
</Info>

## Expected Response

Your callback endpoint must return **200 OK** to acknowledge receipt.


# Delete Card By Link Request
Source: https://developers.pcibooking.net/api-reference/tokenize-cards/cotp-delete-request

DELETE https://service.pcibooking.net/api/cardrequest/{requestID}
Delete a Card By Link request. Clicking a deleted request's link shows an 'invalid link' message.

<Card title="Card By Link Guide" icon="book" href="/capture-cards/card-by-link">
  Send secure card capture links via email or SMS
</Card>

Use this endpoint to cancel an active Card By Link request. Once deleted, the capture link becomes invalid and the cardholder sees an "invalid link" message if they try to open it. Delete requests that are no longer needed or that were sent in error.

## Error Responses

| Code  | HTTP Status | Condition                                                                |
| ----- | ----------- | ------------------------------------------------------------------------ |
| -1003 | 401         | Missing or invalid API key in the `Authorization` header.                |
| -160  | 404         | Card request not found, or request has already been deleted or archived. |

## Parameters

### Headers

<ParamField type="string">
  Your API key prefixed with `APIKEY`. Example: `APIKEY your-api-key`. See the [Authentication guide](/getting-started/authentication).
</ParamField>

### Path Parameters

<ParamField type="string">
  The request ID received from sending the card form to the customer.
</ParamField>

<RequestExample>
  ```javascript Node.js theme={null}
  const requestID = 'SULqe7pa22gghYDnX6O3J7QDMhyyUzNb';

  const response = await fetch(
    `https://service.pcibooking.net/api/cardrequest/${requestID}`,
    {
      method: 'DELETE',
      headers: {
        'Authorization': 'APIKEY your-api-key'
      }
    }
  );

  console.log('Deleted:', response.status === 200);
  ```

  ```python Python theme={null}
  import requests

  request_id = 'SULqe7pa22gghYDnX6O3J7QDMhyyUzNb'

  response = requests.delete(
      f'https://service.pcibooking.net/api/cardrequest/{request_id}',
      headers={
          'Authorization': 'APIKEY your-api-key'
      }
  )

  print('Deleted:', response.status_code == 200)
  ```
</RequestExample>

## Response

**200** - Empty body. The card request has been deleted.

<ResponseExample>
  ```text 200 theme={null}
  Empty response body. Card request deleted successfully.
  ```

  ```json 401 theme={null}
  {
      "code": -1003,
      "message": "Not authorized to access this resource",
      "moreInfo": "Bad or missing authorization data, expected APIKEY",
      "errorList": null
  }
  ```

  ```json 404 theme={null}
  {
      "code": -160,
      "message": "Uri not found",
      "moreInfo": "Card request not found",
      "errorList": null
  }
  ```
</ResponseExample>


# Retrieve Card By Link Request
Source: https://developers.pcibooking.net/api-reference/tokenize-cards/cotp-retrieve-request

GET https://service.pcibooking.net/api/cardrequest/{requestID}
Retrieve the status and details of a Card By Link request.

<Card title="Card By Link Guide" icon="book" href="/capture-cards/card-by-link">
  Send secure card capture links via email or SMS
</Card>

Use this endpoint to check the current status and configuration of a Card By Link request. The response includes the request parameters, delivery status, and the card token URI if the cardholder has already submitted their card details.

## Error Responses

| Code  | HTTP Status | Condition                                                  |
| ----- | ----------- | ---------------------------------------------------------- |
| -1003 | 401         | Missing or invalid API key in the `Authorization` header.  |
| -160  | 404         | Card request with the specified `requestID` was not found. |

## Parameters

### Headers

<ParamField type="string">
  Your API key prefixed with `APIKEY`. Example: `APIKEY your-api-key`. See the [Authentication guide](/getting-started/authentication).
</ParamField>

### Path Parameters

<ParamField type="string">
  The request ID returned from sending a [card capture link](/api-reference/tokenize-cards/cotp-send-card-form) or [CVV capture link](/api-reference/tokenize-cards/cotp-send-cvv-form).
</ParamField>

<RequestExample>
  ```javascript Node.js theme={null}
  const requestID = 'SULqe7pa22gghYDnX6O3J7QDMhyyUzNb';

  const response = await fetch(
    `https://service.pcibooking.net/api/cardrequest/${requestID}`,
    {
      headers: {
        'Authorization': 'APIKEY your-api-key'
      }
    }
  );

  const data = await response.json();
  console.log('Status:', data.Status);
  console.log('Card URI:', data.CardUri);
  ```

  ```python Python theme={null}
  import requests

  request_id = 'SULqe7pa22gghYDnX6O3J7QDMhyyUzNb'

  response = requests.get(
      f'https://service.pcibooking.net/api/cardrequest/{request_id}',
      headers={
          'Authorization': 'APIKEY your-api-key'
      }
  )

  data = response.json()
  print('Status:', data['Status'])
  print('Card URI:', data['CardUri'])
  ```
</RequestExample>

## Response

**200**

Returns the full request configuration and its current status.

<ParamField type="string">
  The current status of the request. Possible values:

  | Channel     | Value              | Description                                                                  |
  | ----------- | ------------------ | ---------------------------------------------------------------------------- |
  | Email / SMS | `MessageQueued`    | Message was added to the PCI Booking queue.                                  |
  | SMS only    | `MessageSent`      | The message was sent to the recipient.                                       |
  | SMS only    | `MessageFailed`    | Message delivery to the recipient failed.                                    |
  | SMS only    | `MessageDelivered` | Message was successfully delivered to the recipient.                         |
  | Email / SMS | `FormViewed`       | Recipient viewed the capture form.                                           |
  | Email / SMS | `CardStored`       | Card was captured and tokenized. The `CardUri` field contains the token URL. |
  | Email / SMS | `LinkExpired`      | The link to the capture form has expired.                                    |
  | Email / SMS | `StoreFailed`      | Capture form submission failed.                                              |
</ParamField>

<ParamField type="string">
  The unique identifier for this request.
</ParamField>

<ParamField type="string">
  The type of request: `Card` for card capture, `CVV` for CVV-only capture.
</ParamField>

<ParamField type="string">
  The PCI Booking token URL for the stored card. Only populated when `Status` is `CardStored`.
</ParamField>

<ParamField type="string">
  Timestamp of the last status change (ISO 8601 format).
</ParamField>

<ParamField type="string">
  The original token URL. Only present for CVV-only requests (`RequestType: CVV`).
</ParamField>

<Warning title="CVV capture requests">
  For CVV-only requests, PCI Booking creates a **new token** that is a full copy of the original card details plus the captured CVV (returned in `CardUri`). The original token (`OriginCardUri`) is not modified and does not contain the CVV. You should delete the original token if it is no longer needed, otherwise it will continue to incur monthly storage fees.
</Warning>

<Info>
  Once `Status` is `CardStored`, remember to set the [CVV Retention Policy](/capture-cards/cvv-retention-policy) on the token.
</Info>

<ResponseExample>
  ```json Card - Queued 200 theme={null}
  {
    "RequestID": "SULqe7pa22gghYDnX6O3J7QDMhyyUzNb",
    "RequestType": "Card",
    "Status": "MessageQueued",
    "StatusTime": "2018-03-21T13:28:38",
    "CardUri": null,
    "SenderID": "Frodo",
    "SenderReference": "Refererfe",
    "CallBackURL": "https://httpbin.org/post",
    "RequestTTL": 22,
    "Destination": "nadya@recipientDomain.com",
    "DestinationType": "Email",
    "RecipientName": "Mr. Roee Dayan",
    "Description": "Request for Roee's reservation in Bora Bora",
    "Amount": 999.65,
    "Currency": "USD",
    "Language": "en",
    "CardTypes": "Visa,MasterCard,AMEX",
    "DefaultCardType": "AMEX",
    "AutoDetectCardType": true,
    "ShowOwnerID": false,
    "MinExpiration": "082018",
    "CVV": true,
    "ShortUrl": "SULqe7",
    "Css": "TEst CSS"
  }
  ```

  ```json Card - Stored 200 theme={null}
  {
    "RequestID": "UPzpUmAj2NIRbciQCim3tHS0hZk7b2HE",
    "RequestType": "Card",
    "Status": "CardStored",
    "StatusTime": "2018-03-21T12:53:28",
    "CardUri": "https://service.pcibooking.net/api/payments/paycard/d919fe8ee51c4adbbbc22cef85e736a6",
    "SenderID": "Frodo",
    "SenderReference": "Refererfe",
    "CallBackURL": "https://httpbin.org/post",
    "RequestTTL": 22,
    "Destination": "nadya@recipientDomain.com",
    "DestinationType": "Email",
    "RecipientName": "Mr. Roee Dayan",
    "Description": "Request for Roee's reservation in Bora Bora",
    "Amount": 999.65,
    "Currency": "USD",
    "Language": "en",
    "CardTypes": "Visa,MasterCard,AMEX",
    "DefaultCardType": "AMEX",
    "AutoDetectCardType": true,
    "ShowOwnerID": false,
    "MinExpiration": "082018",
    "CVV": true,
    "ShortUrl": "7inQGn",
    "Css": "TEst CSS"
  }
  ```

  ```json CVV - Queued 200 theme={null}
  {
    "RequestID": "pMdsvukESyaUIFuSBmvIufYtKjI0vOrj",
    "RequestType": "CVV",
    "Status": "MessageSent",
    "StatusTime": "2018-03-21T12:56:00",
    "CardUri": null,
    "OriginCardUri": "https://service.pcibooking.net/api/payments/paycard/7175f98744434ca89615b1cc86c69a45",
    "SenderID": "Frodo",
    "SenderReference": "Refererfe",
    "CallBackURL": "https://httpbin.org/post",
    "RequestTTL": 22,
    "Destination": null,
    "DestinationType": "SMS",
    "RecipientName": "Mr. Roee Dayan",
    "Description": "Request for Roee's reservation in Bora Bora",
    "Amount": 999.65,
    "Currency": "USD",
    "Language": "en",
    "ShortUrl": "pMdsvu",
    "Css": "TEst CSS"
  }
  ```

  ```json CVV - Stored 200 theme={null}
  {
    "RequestID": "pMdsvukESyaUIFuSBmvIufYtKjI0vOrj",
    "RequestType": "CVV",
    "Status": "CardStored",
    "StatusTime": "2018-03-21T13:26:29",
    "CardUri": "https://service.pcibooking.net/api/payments/paycard/d4ffa09028a044d2ac0d8bada49b6502",
    "OriginCardUri": "https://service.pcibooking.net/api/payments/paycard/7175f98744434ca89615b1cc86c69a45",
    "SenderID": "Frodo",
    "SenderReference": "Refererfe",
    "CallBackURL": "https://httpbin.org/post",
    "RequestTTL": 22,
    "Destination": null,
    "DestinationType": "SMS",
    "RecipientName": "Mr. Roee Dayan",
    "Description": "Request for Roee's reservation in Bora Bora",
    "Amount": 999.65,
    "Currency": "USD",
    "Language": "en",
    "ShortUrl": "pMdsvu",
    "Css": "TEst CSS"
  }
  ```

  ```json 401 theme={null}
  {
      "code": -1003,
      "message": "Not authorized to access this resource",
      "moreInfo": "Bad or missing authorization data, expected APIKEY",
      "errorList": null
  }
  ```

  ```json 404 theme={null}
  {
      "code": -160,
      "message": "Uri not found",
      "moreInfo": "Card request not found",
      "errorList": null
  }
  ```
</ResponseExample>


# Send Card Capture Link
Source: https://developers.pcibooking.net/api-reference/tokenize-cards/cotp-send-card-form

POST https://service.pcibooking.net/api/cardrequest
Send a Card By Link request via email or SMS with a link to a secure card capture form.

<Card title="Card By Link Guide" icon="book" href="/capture-cards/card-by-link">
  Send secure card capture links via email or SMS
</Card>

Use this endpoint to send a secure card capture link to a cardholder via email or SMS. The recipient clicks the link to open a PCI-compliant form where they enter their card details, which are tokenized and stored by PCI Booking. This is ideal for scenarios like phone bookings or back-office operations where you need to collect card data without handling it directly.

## Error Responses

| Code  | HTTP Status | Condition                                                                                |
| ----- | ----------- | ---------------------------------------------------------------------------------------- |
| -179  | 400         | Validation error: missing required fields, invalid field format, or malformed JSON body. |
| -112  | 400         | Destination phone number exceeds maximum length (SMS delivery).                          |
| -1003 | 401         | Missing or invalid API key in the `Authorization` header.                                |
| -1003 | 401         | `SenderID` does not match the identity associated with the API key.                      |
| -150  | 500         | Internal system error while creating the card request.                                   |

## Parameter Constraints

| Parameter                 | Constraint                                                                                                                                         |                       |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- |
| `RequestTTL`              | Integer, range 1 to 24 (hours).                                                                                                                    |                       |
| `Destination`             | Max 255 characters. For SMS, phone number is sanitized (non-digit characters and leading `+`/`0` removed) then validated against a maximum length. |                       |
| `RecipientName`           | Required. Max 70 characters.                                                                                                                       |                       |
| `SenderReference`         | Max 50 characters.                                                                                                                                 |                       |
| `Description`             | Max 50 characters.                                                                                                                                 |                       |
| `CompanyName`             | Max 20 characters. Required when `DestinationType` is `sms`.                                                                                       |                       |
| `CustomHeaderText`        | Max 1000 characters.                                                                                                                               |                       |
| `CustomFooterText`        | Max 1000 characters.                                                                                                                               |                       |
| `CustomerSupportPhone`    | Max 20 characters.                                                                                                                                 |                       |
| `CustomerSupportEmail`    | Max 50 characters.                                                                                                                                 |                       |
| `CustomerSupportLink`     | Max 255 characters. Must be a valid URL.                                                                                                           |                       |
| `CustomerSupportLinkText` | Max 100 characters.                                                                                                                                |                       |
| `LogoTitle`               | Max 100 characters.                                                                                                                                |                       |
| `SiteTitle`               | Max 40 characters.                                                                                                                                 |                       |
| `ClientLogoUrl`           | Must be a valid fully-qualified HTTP, HTTPS, or FTP URL (if provided).                                                                             |                       |
| `MinExpiration`           | Format `mmyyyy`, regex \`^(1\[0-2]                                                                                                                 | 0\[1-9])(20\d\d)\$\`. |

## Parameters

### Headers

<ParamField type="string">
  Your API key prefixed with `APIKEY`. Example: `APIKEY your-api-key`. See the [Authentication guide](/getting-started/authentication).
</ParamField>

### Request Configuration

<ParamField type="string">
  The user ID of the booker.
</ParamField>

<ParamField type="string">
  The form's language in ISO 639-1 (2-letter) format. See [supported languages](/account-setup/custom-translations#supported-languages). If an unsupported language is received, English will be displayed.
</ParamField>

<ParamField type="string">
  The CSS resource name. Follow the guide on [managing stylesheets](/account-setup/stylesheets). If not provided, PCI Booking will use the [default CSS](/account-setup/stylesheets).
</ParamField>

<ParamField type="string">
  A URL where the status of the request will be pushed to by PCI Booking.
</ParamField>

<ParamField type="integer">
  The number of hours the request will be valid for. Minimum 1 hour, maximum 24 hours.
</ParamField>

### Card Form Settings

<ParamField type="string[]">
  Limits the list of card types. If omitted or no valid card types are found, all types will be displayed. Separate card types by comma. Read more on [supported card types](/api-reference/general/get-supported-cards).
</ParamField>

<ParamField type="boolean">
  Whether to display the Owner ID field in the form (required in some countries). `true`: include the field. `false`: exclude the field.
</ParamField>

<ParamField type="string">
  Which card type will be set as default in the card drop down menu. Read more on [supported card types](/api-reference/general/get-supported-cards).
</ParamField>

<ParamField type="boolean">
  Whether to use card detection according to card number. `true`: use card detection. `false`: show a drop down menu for card type selection.
</ParamField>

<ParamField type="string">
  Minimum expiration month/year. Format: **mmyyyy**. The expiration validation will be checked against this date. Must be a valid date in the specified format. Use case: when the card expiration should be later than a check-in date.
</ParamField>

<ParamField type="boolean">
  Whether to add the CVV field. `true`: include the CVV and save it in the database. `false`: exclude the field.
</ParamField>

<ParamField type="string">
  Additional input validation on the `Name On Card` field. Possible values: `NO_DIGITS` - the field cannot contain digits.
</ParamField>

<ParamField type="boolean">
  Whether PCI Booking should look up this card in previously stored cards and return the existing token (if found) or always return a new token. `True`: look up in existing cards. `False`: always create new tokens. If not specified, the default behavior is taken from the account settings.
</ParamField>

### Delivery

<ParamField type="string">
  How to send the link to the card capture form. Values: `email` or `sms`.
</ParamField>

<ParamField type="string">
  The destination of the message - email address or phone number. For phone numbers, format as international dial number: `Country code + area code + phone number`.
</ParamField>

<ParamField type="string">
  The recipient's name. Max 70 characters.
</ParamField>

<ParamField type="string">
  Free text description of this request. Max 50 characters.
</ParamField>

<ParamField type="string">
  A reference value that can be used to query for this card token later.
</ParamField>

### Branding

<Info>
  `CustomerSupportLink`, `CustomerSupportLinkText`, `CustomerSupportEmail`, and `CustomerSupportPhone` can also be set in your [account settings](https://users.pcibooking.net/booker/Login). Values provided in the request override the account defaults.
</Info>

<Note>
  URLs in the request body (e.g. `ClientLogoURL`, `Success`, `Failure`) should **not** be URL-encoded, since they are sent in JSON, not as query parameters.
</Note>

<ParamField type="string">
  The name of the company sending the message. Required when sending via SMS.
</ParamField>

<ParamField type="string">
  URL to the logo displayed in the Card By Link email and landing page. Submit with a null value to hide the logo. If not supplied, the logo from the Booker information in the portal is used. Images must be publicly accessible, HTTPS URL.
</ParamField>

<ParamField type="string">
  The title of the logo. If not provided, the booker name (as set in the portal) is used. Submit with a null value for no title. Max 100 characters.
</ParamField>

<ParamField type="string">
  URL to the favicon displayed in the Card By Link landing page. If not supplied, the browser default is used. Images must be publicly accessible, HTTPS URL in ico or png format, size 16x16 or 32x32.
</ParamField>

<ParamField type="string">
  The page title to be displayed. Max 40 characters.
</ParamField>

<ParamField type="string">
  Text displayed in the header of the message to the recipient. Max 1000 characters. If `RecipientName`, `Amount` and `Currency` placeholders are not listed here or in the [portal customizations](/account-setup/card-by-link-templates), but are provided in other request parameters, they will not be displayed.
</ParamField>

<ParamField type="string">
  Text displayed in the footer of the message to the recipient. Max 1000 characters. If `CustomerSupportEmail` and `CustomerSupportPhone` placeholders are not listed here or in the [portal customizations](/account-setup/card-by-link-templates), but are provided in other request parameters, they will not be displayed.
</ParamField>

<ParamField type="string">
  Phone number displayed in the email message and landing page. Max 20 characters.
</ParamField>

<ParamField type="string">
  Email address displayed in the email message and landing page. Max 50 characters.
</ParamField>

<ParamField type="string">
  URL for customer support displayed in the email message and landing page. Max 255 characters. Required if `CustomerSupportLinkText` is provided.
</ParamField>

<ParamField type="string">
  Display name for the customer support URL in the email message and landing page. Max 100 characters. Required if `CustomerSupportLink` is provided.
</ParamField>

### Redirect URLs

<ParamField type="string">
  URL where a successful response will be redirected to. Read more on [setting up success / failure redirection pages](/account-setup/success-and-failure-urls).
</ParamField>

<ParamField type="string">
  URL where a failed response will be redirected to. Read more on [setting up success / failure redirection pages](/account-setup/success-and-failure-urls).
</ParamField>

### 3D Secure

<Warning>
  * The 3DS challenge window has a **5 minute timeout**. If the cardholder does not respond in time, authentication is rejected.
  * Do not use `merchantName` unless you have configured your [3DS merchant information](/account-setup/3ds-merchant-setup). To use PCI Booking's merchant, set `ThreeDS` to `True` and leave `merchantName` blank (Visa and Mastercard only).
  * **Visa requirement (Aug 2024):** You **must** provide at least the cardholder's `email` or `phone` for 3DS authentication.
</Warning>

<ParamField type="boolean">
  Whether to perform 3D Secure authentication following card entry. If enabled with access token authorization, provide two access tokens.
</ParamField>

<ParamField type="string">
  What to do if there is a technical problem with the 3DS process. **Accept** - ignore 3DS and proceed with tokenizing the card. **Reject** - do not continue or tokenize; the card owner will be directed to the failure page URL.
</ParamField>

<ParamField type="string">
  The merchant to use for 3D Secure authentication. Must match a merchant name registered in your [3DS merchant setup](/account-setup/3ds-merchant-setup).
</ParamField>

<ParamField type="double">
  The transaction amount, also displayed in the 3DS challenge screen. Required if `Currency` is provided.
</ParamField>

<ParamField type="string">
  The transaction currency in ISO 4217 (3-letter) format, also displayed in the 3DS challenge screen. Required if `Amount` is provided.
</ParamField>

<ParamField type="string">
  Cardholder's email address for 3D Secure authentication. Must be in a valid email format, e.g. [joe@bloggs.com](mailto:joe@bloggs.com).
</ParamField>

<ParamField type="string">
  Cardholder's telephone number for 3D Secure authentication. May only contain digits \[0-9], e.g.: 00353112223344.
</ParamField>

<RequestExample>
  ```javascript Node.js theme={null}
  const response = await fetch('https://service.pcibooking.net/api/cardrequest', {
    method: 'POST',
    headers: {
      'Authorization': 'APIKEY your-api-key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      SenderID: 'myhotel',
      DestinationType: 'email',
      Destination: 'guest@example.com',
      RecipientName: 'Jane Smith',
      RequestTTL: 12,
      Language: 'en',
      AutoDetectCardType: true,
      CVV: true,
      SenderReference: 'booking-12345',
      Description: 'Card for reservation #12345',
      CompanyName: 'Sunrise Hotel',
      Success: 'https://yoursite.com/success',
      Failure: 'https://yoursite.com/failure',
      CallBackURL: 'https://yoursite.com/webhook/card-status'
    })
  });

  const requestUri = response.headers.get('Location');
  console.log('Request URI:', requestUri);
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://service.pcibooking.net/api/cardrequest',
      headers={
          'Authorization': 'APIKEY your-api-key',
          'Content-Type': 'application/json'
      },
      json={
          'SenderID': 'myhotel',
          'DestinationType': 'email',
          'Destination': 'guest@example.com',
          'RecipientName': 'Jane Smith',
          'RequestTTL': 12,
          'Language': 'en',
          'AutoDetectCardType': True,
          'CVV': True,
          'SenderReference': 'booking-12345',
          'Description': 'Card for reservation #12345',
          'CompanyName': 'Sunrise Hotel',
          'Success': 'https://yoursite.com/success',
          'Failure': 'https://yoursite.com/failure',
          'CallBackURL': 'https://yoursite.com/webhook/card-status'
      }
  )

  request_uri = response.headers.get('Location')
  print('Request URI:', request_uri)
  ```
</RequestExample>

## Response

**201** - Empty body. A `Location` header is returned with the URI for this card request. Use this URI to [retrieve the request status](/api-reference/tokenize-cards/cotp-retrieve-request) or [delete the request](/api-reference/tokenize-cards/cotp-delete-request).

<Info>
  Remember to set the [CVV Retention Policy](/capture-cards/cvv-retention-policy) on the token once the card is captured.
</Info>

<ResponseExample>
  ```text 201 theme={null}
  Empty response body. The Location header contains the request URI:
  Location: https://service.pcibooking.net/api/payments/paycard/CardForm/SULqe7pa22gghYDnX6O3J7QDMhyyUzNb
  ```

  ```json 400 theme={null}
  {
      "code": -179,
      "message": "Bad input parameter",
      "moreInfo": "Bad input data",
      "errorList": [
          "Bad json format"
      ]
  }
  ```

  ```json 401 theme={null}
  {
      "code": -1003,
      "message": "Not authorized to access this resource",
      "moreInfo": "Bad or missing authorization data, expected APIKEY",
      "errorList": null
  }
  ```
</ResponseExample>


# Send CVV Capture Link
Source: https://developers.pcibooking.net/api-reference/tokenize-cards/cotp-send-cvv-form

POST https://service.pcibooking.net/api/cardrequest/duplicate
Send a Card By Link request via email or SMS with a link to a secure CVV capture form.

<Card title="CVV Capture Guide" icon="book" href="/capture-cards/cvv-capture">
  Collect CVV from cardholders via hosted forms
</Card>

Use this endpoint to send a secure CVV capture link to a cardholder who has already provided their card details. The cardholder clicks the link to enter only their CVV, which PCI Booking combines with the original card data to create a new token. This is useful when you already have a stored card token but need the CVV for a subsequent transaction.

<Warning>
  This operation **duplicates** the original token. Once the cardholder enters the CVV, PCI Booking creates a new token with the original card details plus the captured CVV. The original token remains unchanged. Delete it if no longer needed, otherwise it will continue to incur monthly storage fees.
</Warning>

## Error Responses

| Code  | HTTP Status | Condition                                                                                |
| ----- | ----------- | ---------------------------------------------------------------------------------------- |
| -179  | 400         | Validation error: missing required fields, invalid field format, or malformed JSON body. |
| -1003 | 401         | Missing or invalid API key in the `Authorization` header.                                |
| -1003 | 401         | `SenderID` does not match the identity associated with the API key.                      |
| -150  | 500         | Internal system error while creating the CVV request.                                    |

## Parameter Constraints

| Parameter                 | Constraint                               |
| ------------------------- | ---------------------------------------- |
| `RequestTTL`              | Integer, range 1 to 24 (hours).          |
| `Destination`             | Required. Max 255 characters.            |
| `RecipientName`           | Required. Max 70 characters.             |
| `SenderReference`         | Max 50 characters.                       |
| `Description`             | Max 50 characters.                       |
| `CustomHeaderText`        | Max 1000 characters.                     |
| `CustomFooterText`        | Max 1000 characters.                     |
| `CustomerSupportPhone`    | Max 20 characters.                       |
| `CustomerSupportEmail`    | Max 50 characters.                       |
| `CustomerSupportLink`     | Max 255 characters. Must be a valid URL. |
| `CustomerSupportLinkText` | Max 100 characters.                      |
| `LogoTitle`               | Max 100 characters.                      |
| `SiteTitle`               | Max 40 characters.                       |

## Parameters

### Headers

<ParamField type="string">
  Your API key prefixed with `APIKEY`. Example: `APIKEY your-api-key`. See the [Authentication guide](/getting-started/authentication).
</ParamField>

### Request Configuration

<ParamField type="string">
  The user ID of the booker.
</ParamField>

<ParamField type="string">
  The card URI is the resource identifier for the card location within PCI Booking.
</ParamField>

<ParamField type="string">
  The form's language in ISO 639-1 (2-letter) format. See [supported languages](/account-setup/custom-translations#supported-languages). If an unsupported language is received, English will be displayed. Languages can be added through the user's control panel.
</ParamField>

<ParamField type="string">
  The CSS resource name. Follow the guide on [managing stylesheets](/account-setup/stylesheets). If not provided, PCI Booking will apply the [default CSS](/account-setup/stylesheets).
</ParamField>

<ParamField type="string">
  A URL where PCI Booking will push the status of the request.
</ParamField>

<ParamField type="integer">
  The number of hours the request will be valid for. Minimum 1 hour, maximum 24 hours.
</ParamField>

### Delivery

<ParamField type="string">
  How to send the link to the card capture form. Values: `email` or `sms`.
</ParamField>

<ParamField type="string">
  The destination email address or phone number. Phone numbers should be formatted as international dial numbers: `Country code + area code + phone number`.
</ParamField>

<ParamField type="string">
  The recipient's name. Max 70 characters.
</ParamField>

<ParamField type="string">
  Free text description of this request. Max 50 characters.
</ParamField>

<ParamField type="string">
  A reference value that can be used to query for this card token.
</ParamField>

### Transaction Details

<ParamField type="double">
  The transaction amount. Required if `Currency` is provided.
</ParamField>

<ParamField type="string">
  The transaction currency in ISO 4217 (3-letter) format. Required if `Amount` is provided. An incorrect value returns error code `401 BAD DATA`.
</ParamField>

### Branding

<Info>
  `CustomerSupportLink`, `CustomerSupportLinkText`, `CustomerSupportEmail`, and `CustomerSupportPhone` can also be set in your [account settings](https://users.pcibooking.net/booker/Login). Values provided in the request override the account defaults.
</Info>

<Note>
  URLs in the request body (e.g. `ClientLogoURL`, `Success`, `Failure`) should **not** be URL-encoded, since they are sent in JSON, not as query parameters.
</Note>

<ParamField type="string">
  URL to the logo displayed in the Card By Link email and landing page. Submit with a null value to hide the logo. If not supplied, the logo from your Booker profile in the portal is used. Images must be publicly accessible via HTTPS URL.
</ParamField>

<ParamField type="string">
  The title of the logo. If not provided, the booker name from the portal is used. Submit with a null value to hide the logo title. Max 100 characters.
</ParamField>

<ParamField type="string">
  URL to the favicon displayed in the Card By Link landing page. If not supplied, the browser default favicon is used. Images must be publicly accessible via HTTPS URL in ico or png format, size 16x16 or 32x32.
</ParamField>

<ParamField type="string">
  The page title to be displayed. Max 40 characters.
</ParamField>

<ParamField type="string">
  Text displayed in the header of the message to the recipient. Max 1000 characters. If `RecipientName`, `Amount`, and `Currency` placeholders are not listed in the `CustomHeaderText` or in the [portal customizations](/account-setup/card-by-link-templates) but are provided in the request parameters, they will still be displayed in the email.
</ParamField>

<ParamField type="string">
  Text displayed in the footer of the message to the recipient. Max 1000 characters. If `CustomerSupportEmail` and `CustomerSupportPhone` placeholders are not listed in the `CustomFooterText` or in the [portal customizations](/account-setup/card-by-link-templates) but are provided in the request parameters, they will still be displayed in the email.
</ParamField>

<ParamField type="string">
  Phone number displayed in the email and landing page. Max 20 characters.
</ParamField>

<ParamField type="string">
  Email address displayed in the email and landing page. Max 50 characters.
</ParamField>

<ParamField type="string">
  URL for customer support displayed in the email and landing page. Max 255 characters. Required if `CustomerSupportLinkText` is provided.
</ParamField>

<ParamField type="string">
  Display name for the customer support URL in the email and landing page. Max 100 characters. Required if `CustomerSupportLink` is provided.
</ParamField>

### Redirect URLs

<ParamField type="string">
  URL where a successful response will be redirected to. See [setting up success/failure redirection pages](/account-setup/success-and-failure-urls).
</ParamField>

<ParamField type="string">
  URL where a failed response will be redirected to. See [setting up success/failure redirection pages](/account-setup/success-and-failure-urls).
</ParamField>

<RequestExample>
  ```javascript Node.js theme={null}
  const response = await fetch('https://service.pcibooking.net/api/cardrequest/duplicate', {
    method: 'POST',
    headers: {
      'Authorization': 'APIKEY your-api-key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      SenderID: 'myhotel',
      OriginCardUri: 'https://service.pcibooking.net/api/payments/paycard/d919fe8ee51c4adbbbc22cef85e736a6',
      DestinationType: 'email',
      Destination: 'guest@example.com',
      RecipientName: 'Jane Smith',
      RequestTTL: 12,
      Language: 'en',
      SenderReference: 'booking-12345',
      Description: 'CVV for reservation #12345',
      Amount: 250.00,
      Currency: 'USD',
      Success: 'https://yoursite.com/success',
      Failure: 'https://yoursite.com/failure'
    })
  });

  const requestUri = response.headers.get('Location');
  console.log('Request URI:', requestUri);
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://service.pcibooking.net/api/cardrequest/duplicate',
      headers={
          'Authorization': 'APIKEY your-api-key',
          'Content-Type': 'application/json'
      },
      json={
          'SenderID': 'myhotel',
          'OriginCardUri': 'https://service.pcibooking.net/api/payments/paycard/d919fe8ee51c4adbbbc22cef85e736a6',
          'DestinationType': 'email',
          'Destination': 'guest@example.com',
          'RecipientName': 'Jane Smith',
          'RequestTTL': 12,
          'Language': 'en',
          'SenderReference': 'booking-12345',
          'Description': 'CVV for reservation #12345',
          'Amount': 250.00,
          'Currency': 'USD',
          'Success': 'https://yoursite.com/success',
          'Failure': 'https://yoursite.com/failure'
      }
  )

  request_uri = response.headers.get('Location')
  print('Request URI:', request_uri)
  ```
</RequestExample>

## Response

**201** - Empty body. A `Location` header is returned with the URI for this card request. Use this URI to [retrieve the request status](/api-reference/tokenize-cards/cotp-retrieve-request) or [delete the request](/api-reference/tokenize-cards/cotp-delete-request).

<Info>
  Remember to set the [CVV Retention Policy](/capture-cards/cvv-retention-policy) on the new token once the CVV is captured.
</Info>

<ResponseExample>
  ```text 201 theme={null}
  Empty response body. The Location header contains the request URI:
  Location: https://service.pcibooking.net/api/payments/paycard/CardForm/xLoat3F385vvFRbgI2usOeuXKXQoB8kv
  ```

  ```json 400 theme={null}
  {
      "code": -179,
      "message": "Bad input parameter",
      "moreInfo": "Bad input data",
      "errorList": [
          "Bad json format"
      ]
  }
  ```

  ```json 401 theme={null}
  {
      "code": -1003,
      "message": "Not authorized to access this resource",
      "moreInfo": "Bad or missing authorization data, expected APIKEY",
      "errorList": null
  }
  ```
</ResponseExample>


# Create Card Entry Form Session
Source: https://developers.pcibooking.net/api-reference/tokenize-cards/create-card-entry-form-session

POST https://service.pcibooking.net/api/capturecard
Create a new session for the card entry form. Parameters are sent in the request body instead of as URL query strings. Returns a Location header with the card form URL.

<Card title="Hosted Card Entry Form Guide" icon="book" href="/capture-cards/hosted-card-entry-form#option-2-api-session">
  API session approach for embedded card capture
</Card>

The successful response of this method will include the following:

* `RequestID` for this Card Entry Form session. You will need to use this request ID in future requests relating to this Card Entry Form session.
* `Location` header for the URL of the card form. You will need to set this URL as the value of the `SRC` attribute of your iframe in your webpage.

All URLs should be HTTPS.

## Error Responses

| Code  | HTTP Status | Condition                                                                                |
| ----- | ----------- | ---------------------------------------------------------------------------------------- |
| -179  | 400         | Validation error: missing required fields, invalid field format, or malformed JSON body. |
| -125  | 400         | Invalid credentials ID provided via the `credentialsId` query parameter.                 |
| -1003 | 401         | Missing or invalid API key in the `Authorization` header.                                |
| -160  | 404         | Resource not matching request (e.g. wrong capture type).                                 |

## Parameter Constraints

| Parameter                    | Constraint                                                                         |                                                                            |
| ---------------------------- | ---------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| `TTL`                        | Integer, range 30 to 600 (seconds). Default: 120.                                  |                                                                            |
| `CreatorReference`           | Max 50 characters.                                                                 |                                                                            |
| `CallBackURL`                | Must be a valid URL.                                                               |                                                                            |
| `Properties.MinExpiration`   | Format `mmyyyy`, regex \`^(1\[0-2]                                                 | 0\[1-9])(20\d\d)\$\`. Cards with expiration before this date are rejected. |
| `Properties.Language`        | 2-letter ISO 639-1 language code. `zh` is automatically mapped to `cn` internally. |                                                                            |
| `Properties.CardCaptureType` | One of `Tokenize`, `Charge`, or `ChargeToken`. Default: `Tokenize`.                |                                                                            |

## Parameters

### Headers

<ParamField type="string">
  Your API key prefixed with `APIKEY`. Example: `APIKEY your-api-key`. See the [Authentication guide](/getting-started/authentication).
</ParamField>

### Request Body

<ParamField type="string">
  URL where PCI Booking will push the status of the request.
</ParamField>

<ParamField type="integer">
  Number of seconds the request will be valid for. Minimum 30, maximum 600.
</ParamField>

<ParamField type="string">
  A reference value that can be used to query for this card token.
</ParamField>

<ParamField type="object">
  The set of properties defining the card entry form. See the 201 response example below for the full list of available properties.
</ParamField>

<Warning title="3D Secure">
  * The 3DS challenge window has a **5 minute timeout**. If the cardholder does not respond in time, authentication is rejected.
  * Do not use `merchantName` unless you have configured your [3DS merchant information](/account-setup/3ds-merchant-setup). To use PCI Booking's merchant, set `ThreeDs` to `True` and leave `merchantName` blank (Visa and Mastercard only).
  * **Visa requirement (Aug 2024):** You **must** provide at least the cardholder's email address or phone number for 3DS authentication.
</Warning>

<RequestExample>
  ```javascript Node.js theme={null}
  const response = await fetch('https://service.pcibooking.net/api/capturecard', {
    method: 'POST',
    headers: {
      'Authorization': 'APIKEY your-api-key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      TTL: 300,
      creatorReference: 'booking-12345',
      CallBackURL: 'https://yoursite.com/webhook/card-captured',
      Properties: {
        Language: 'en',
        AutoDetectCardType: true,
        ShowCVV: true,
        Success: 'https://yoursite.com/success?cardToken={cardToken}',
        Failure: 'https://yoursite.com/failure',
        postMessageHost: 'yoursite.com',
        CardTypes: ['Visa', 'MasterCard', 'AMEX']
      }
    })
  });

  const formUrl = response.headers.get('Location');
  const data = await response.json();
  console.log('Request ID:', data.RequestID);
  console.log('Form URL:', formUrl);
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://service.pcibooking.net/api/capturecard',
      headers={
          'Authorization': 'APIKEY your-api-key',
          'Content-Type': 'application/json'
      },
      json={
          'TTL': 300,
          'creatorReference': 'booking-12345',
          'CallBackURL': 'https://yoursite.com/webhook/card-captured',
          'Properties': {
              'Language': 'en',
              'AutoDetectCardType': True,
              'ShowCVV': True,
              'Success': 'https://yoursite.com/success?cardToken={cardToken}',
              'Failure': 'https://yoursite.com/failure',
              'postMessageHost': 'yoursite.com',
              'CardTypes': ['Visa', 'MasterCard', 'AMEX']
          }
      }
  )

  form_url = response.headers.get('Location')
  data = response.json()
  print('Request ID:', data['RequestID'])
  print('Form URL:', form_url)
  ```
</RequestExample>

## Response

**201** - Session created. A `Location` header is returned with the card form URL. Set this URL as the `src` of your iframe.

<Info>
  Remember to set the [CVV Retention Policy](/capture-cards/cvv-retention-policy) on the token once the card is captured.
</Info>

<ResponseExample>
  ```json 201 theme={null}
  {
    "RequestID": "ITGdnzZuR7hQOI583EUB8U9vC3aPjuoV",
    "SenderId": "RoeeSandbox",
    "CreatorReference": "Card capture request",
    "TTL": 600,
    "CallBackURL": "http://httpbin.org/post",
    "CreateTime": "2019-11-20T11:36:46.8062564Z",
    "Properties": {
      "Language": "en",
      "Css": "test",
      "removeBaseCss": false,
      "CardTypes": [
        "Visa",
        "electron",
        "mastercard",
        "maestro",
        "UnionPay"
      ],
      "DefaultCardType": "Visa",
      "AutoDetectCardType": true,
      "ShowOwnerID": false,
      "MinExpiration": "082020",
      "ShowCVV": true,
      "Success": "https://www.google.com?cardToken={cardToken}",
      "Failure": "https://www.pcibooking.net",
      "autoFocus": true,
      "submitWithPostMessage": false,
      "postMessageHost": "https://www.example.com",
      "ThreeDS": true,
      "UnavailThreeDSAuth": "Accept",
      "ExpirationMonths": "Names"
    }
  }
  ```

  ```json 400 theme={null}
  {
      "code": -179,
      "message": "Bad input parameter",
      "moreInfo": "Bad input data",
      "errorList": [
          "Bad json format"
      ]
  }
  ```

  ```json 401 theme={null}
  {
      "code": -1003,
      "message": "Not authorized to access this resource",
      "moreInfo": "Bad or missing authorization data, expected APIKEY",
      "errorList": null
  }
  ```
</ResponseExample>


# Delete Card Entry Form
Source: https://developers.pcibooking.net/api-reference/tokenize-cards/delete-card-entry-form

DELETE https://service.pcibooking.net/api/capturecard/{RequestID}
Delete a card entry form session created via the API.

<Card title="Hosted Card Entry Form Guide" icon="book" href="/capture-cards/hosted-card-entry-form#option-2-api-session">
  API session approach for embedded card capture
</Card>

Use this endpoint to delete a card entry form session that is no longer needed. Once deleted, the form URL becomes invalid and the cardholder can no longer submit card details through it. Delete sessions that have expired or been completed to keep your active sessions clean.

## Error Responses

| Code  | HTTP Status | Condition                                                               |
| ----- | ----------- | ----------------------------------------------------------------------- |
| -1003 | 401         | Missing or invalid API key in the `Authorization` header.               |
| N/A   | 403         | The session belongs to a different user than the authenticated API key. |
| N/A   | 404         | Card entry form session with the specified `RequestID` was not found.   |

## Parameters

### Headers

<ParamField type="string">
  Your API key prefixed with `APIKEY`. Example: `APIKEY your-api-key`. See the [Authentication guide](/getting-started/authentication).
</ParamField>

### Path Parameters

<ParamField type="string">
  The request ID returned from [Create Card Entry Form session](/api-reference/tokenize-cards/create-card-entry-form-session).
</ParamField>

<RequestExample>
  ```javascript Node.js theme={null}
  const requestID = 'ITGdnzZuR7hQOI583EUB8U9vC3aPjuoV';

  const response = await fetch(
    `https://service.pcibooking.net/api/capturecard/${requestID}`,
    {
      method: 'DELETE',
      headers: {
        'Authorization': 'APIKEY your-api-key'
      }
    }
  );

  console.log('Deleted:', response.status === 200);
  ```

  ```python Python theme={null}
  import requests

  request_id = 'ITGdnzZuR7hQOI583EUB8U9vC3aPjuoV'

  response = requests.delete(
      f'https://service.pcibooking.net/api/capturecard/{request_id}',
      headers={
          'Authorization': 'APIKEY your-api-key'
      }
  )

  print('Deleted:', response.status_code == 200)
  ```
</RequestExample>

## Response

**200** - Session deleted successfully.

**404** - Session not found.

<ResponseExample>
  ```text 200 theme={null}
  Card entry form deleted successfully. No content returned.
  ```

  ```json 401 theme={null}
  {
      "code": -1003,
      "message": "Not authorized to access this resource",
      "moreInfo": "Bad or missing authorization data, expected APIKEY",
      "errorList": null
  }
  ```
</ResponseExample>


# Get Tokenization Profiles
Source: https://developers.pcibooking.net/api-reference/tokenize-cards/get-tokenization-profiles

GET https://service.pcibooking.net/api/booker
Returns a list of pre-configured tokenization profiles. Use the profile name when calling the Tokenize on Response Using Preset Profiles endpoint.

<Card title="Universal Tokenization Guide" icon="book" href="/capture-cards/universal-tokenization">
  Tokenize cards from any source using preset profiles
</Card>

Use this endpoint to retrieve the list of pre-configured tokenization profiles available for your account. Each profile defines a target URL and extraction rules for a specific third-party integration. You need the profile name from this response when calling the [Tokenize on Response Using Preset Profiles](/api-reference/tokenize-cards/tokenize-on-response-using-preset-profiles) endpoint.

**Authentication:** Not required (public endpoint).

## Error Responses

| Code   | HTTP Status | Condition                                                           |
| ------ | ----------- | ------------------------------------------------------------------- |
| `-150` | `500`       | Failed to retrieve the list of available profiles (internal error). |

<RequestExample>
  ```javascript Node.js theme={null}
  const response = await fetch('https://service.pcibooking.net/api/booker');

  const profiles = await response.json();
  profiles.forEach(profile => {
    console.log(`${profile.Name}: ${profile.Description}`);
    if (profile.PathSegmentNames.length > 0) {
      console.log('  Path segments:', profile.PathSegmentNames.join(', '));
    }
  });
  ```

  ```python Python theme={null}
  import requests

  response = requests.get('https://service.pcibooking.net/api/booker')

  profiles = response.json()
  for profile in profiles:
      print(f"{profile['Name']}: {profile['Description']}")
      if profile['PathSegmentNames']:
          print(f"  Path segments: {', '.join(profile['PathSegmentNames'])}")
  ```
</RequestExample>

## Response

**200** - An array of available profiles.

<ParamField type="string">
  The profile identifier. Use this value as the `ProfileName` path parameter when calling [Tokenize on Response Using Preset Profiles](/api-reference/tokenize-cards/tokenize-on-response-using-preset-profiles).
</ParamField>

<ParamField type="string">
  A description of the profile, including the target URL. If the URL contains dynamic path segments, they are shown as placeholders (e.g. `{SiteMinderCustID}`).
</ParamField>

<ParamField type="string[]">
  Dynamic path segment names that must be provided via the `pathSegments` query parameter when submitting a request. Empty array if the profile's URL has no dynamic segments.
</ParamField>

<ResponseExample>
  ```json 200 theme={null}
  [
      {
          "Name": "Agoda",
          "Description": "Request to https://supply.agoda.com/api",
          "PathSegmentNames": []
      },
      {
          "Name": "SiteMinder",
          "Description": "Request to https://ws.siteminder.com/pmsxchangev2/services/{SiteMinderCustID}",
          "PathSegmentNames": [
              "SiteMinderCustID"
          ]
      }
  ]
  ```

  ```json 500 theme={null}
  {
      "code": -150,
      "message": "Internal error",
      "moreInfo": "Failed to retrieve the list of available profiles",
      "errorList": null
  }
  ```
</ResponseExample>


# Capture Cards API Reference
Source: https://developers.pcibooking.net/api-reference/tokenize-cards/overview

API endpoints for card tokenization: hosted forms, Card By Link, card migration, response interception, and sFTP file tokenization

API endpoints for capturing and tokenizing cards. For concepts and guidance, see the [Capture Cards guide](/capture-cards/overview).

## Client-Side Tokenization

| Endpoint                                                                        | Description                                      |
| ------------------------------------------------------------------------------- | ------------------------------------------------ |
| [Hosted Card Entry Form](/api-reference/tokenize-cards/request-card-entry-form) | Embed a secure card form in your website or app. |
| [Card By Link](/api-reference/tokenize-cards/cotp-send-card-form)               | Send a secure capture link via email or SMS.     |

## Server-Side Tokenization

| Endpoint                                                                                                   | Description                                                       |
| ---------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| [Tokenization on Response](/api-reference/tokenize-cards/tokenization-in-response)                         | Intercept and tokenize card data from a third-party API response. |
| [Tokenize Using Preset Profiles](/api-reference/tokenize-cards/tokenize-on-response-using-preset-profiles) | Tokenize cards using pre-built profiles for common third parties. |
| [Tokenize from sFTP](/api-reference/tokenize-cards/tokenize-from-sftp)                                     | Tokenize card data from batch files on an sFTP server.            |

## Direct Storage

| Endpoint                                                    | Description                                                       |
| ----------------------------------------------------------- | ----------------------------------------------------------------- |
| [Migrate Card](/api-reference/tokenize-cards/store-paycard) | Store card details you already possess directly into PCI Booking. |


# Request a Card Entry Form
Source: https://developers.pcibooking.net/api-reference/tokenize-cards/request-card-entry-form

GET https://service.pcibooking.net/api/payments/capturecard
Build a URL that renders a PCI Booking card capture form. Use it as an iframe src or redirect the cardholder to it.

<Card title="Hosted Card Entry Form Guide" icon="book" href="/capture-cards/hosted-card-entry-form">
  Embed a secure card capture form in your website
</Card>

This is not a typical API call that you make from your server. Instead, you build a URL with query parameters and use it in one of two ways:

* **iframe**: set it as the `src` attribute of an iframe element on your page
* **Redirect**: redirect the cardholder's browser to this URL as a standalone page

The URL renders a secure card capture form hosted by PCI Booking. When the cardholder submits the form, PCI Booking tokenizes the card and redirects to your `success` URL with the token details, or to your `failure` URL if something goes wrong.

```
https://service.pcibooking.net/api/payments/capturecard?accessToken=YOUR_TOKEN&brand=YOUR_BRAND&language=en&autoDetectCardType=true&success=https://yoursite.com/success&failure=https://yoursite.com/failure&postMessageHost=yoursite.com
```

<Note title="URL building tips">
  * All parameter values must be URL-encoded.
  * All URLs you pass (success, failure, postMessageHost) must use HTTPS.
  * See the [Hosted Card Entry Form guide](/capture-cards/hosted-card-entry-form) for a visual preview of the rendered form.
</Note>

<Info>
  If you prefer a clean iframe URL without query parameters, use the [session-based card entry form](/capture-cards/hosted-card-entry-form#option-2-api-session) instead. That method sends parameters in a server-side POST and returns a ready-to-use iframe URL.
</Info>

## Parameters

### Authentication

<Warning>
  This is a browser-facing endpoint. Use one of the authentication methods below instead of the API key shown above.
</Warning>

<ParamField type="string">
  Recommended. A long-lived token for browser-side calls. [How to generate](/getting-started/authentication#access-token).
</ParamField>

<ParamField type="string">
  Alternative. Valid for 5 minutes. [How to generate](/api-reference/general/start-temporary-session).
</ParamField>

If both are provided, the session token takes precedence.

All parameters are passed as **query string** parameters in the URL.

### Core Parameters

<ParamField type="string">
  Access token for authentication. Recommended over session token.
</ParamField>

<ParamField type="string">
  Session token for authentication.
</ParamField>

<ParamField type="string">
  Your PCI Booking username, used to identify your account.
</ParamField>

<ParamField type="string">
  Form language in ISO 639-1 format (e.g. `en`, `fr`, `de`). Unsupported languages fall back to English. See [custom translations](/account-setup/custom-translations).
</ParamField>

<ParamField type="string">
  The domain of the host page where the iframe is displayed (e.g. `yoursite.com`). Required for postMessage communication between the form and your page.
</ParamField>

<ParamField type="string">
  URL to redirect to after successful card capture. The token details are appended as query parameters. Strongly recommended. See [success/failure URLs](/account-setup/success-and-failure-urls).
</ParamField>

<ParamField type="string">
  URL to redirect to if the card capture fails. See [success/failure URLs](/account-setup/success-and-failure-urls).
</ParamField>

<ParamField type="string">
  A reference value you define, which you can later use to [query for this token](/manage-tokens/query-retrieve).
</ParamField>

### Card Form Display

<ParamField type="boolean">
  When `true`, the form detects the card type from the card number automatically. When `false`, a dropdown menu is shown for manual card type selection.
</ParamField>

<ParamField type="string">
  Which card type is pre-selected in the dropdown menu (only relevant when `autoDetectCardType` is `false`).
</ParamField>

<ParamField type="string">
  Comma-separated list of accepted card types. If omitted or no valid types are found, all card types are shown.
</ParamField>

<ParamField type="boolean">
  Show an "Owner ID" field on the form. Required in some countries.
</ParamField>

<ParamField type="string">
  Format of the expiration month dropdown. `numbers` shows `01, 02, ...`, `names` shows `January, February, ...`
</ParamField>

<ParamField type="string">
  Minimum allowed expiration date in `mmyyyy` format (e.g. `012027`). Useful when the card must be valid past a check-in date.
</ParamField>

<ParamField type="string">
  Additional validation for the Name on Card field. `NO_DIGITS` prevents digits in the name.
</ParamField>

<ParamField type="boolean">
  Auto-focus the first form field when the page loads. Focuses the card number field if `autoDetectCardType` is `true`, or the card type dropdown otherwise.
</ParamField>

### Styling

<ParamField type="string">
  CSS resource name. See [managing stylesheets](/account-setup/stylesheets). If omitted, PCI Booking's default stylesheet is used.
</ParamField>

<ParamField type="boolean">
  When `true`, removes PCI Booking's base CSS entirely. The base CSS does not collide with your site's styles, so this is rarely needed.
</ParamField>

### CVV

<ParamField type="boolean">
  When `true`, saves the CVV in PCI Booking's vault alongside the card. Remember to set a [CVV Retention Policy](/capture-cards/cvv-retention-policy) to control how long the CVV is stored.
</ParamField>

### 3D Secure

<Warning>
  If you enable 3D Secure, the challenge window has a **5-minute timeout**. If the cardholder does not complete the challenge in time, the authentication is rejected.
</Warning>

<ParamField type="boolean">
  Enable 3D Secure authentication after card entry. If using access token auth, provide two access tokens (see Authentication section above).
</ParamField>

<ParamField type="string">
  What to do if the 3DS service is unavailable. `Accept`: skip 3DS and tokenize the card anyway. `Reject`: do not tokenize, redirect to the failure URL.
</ParamField>

<ParamField type="string">
  Merchant name for 3DS authentication. Must be URL-encoded and match a configured [3DS merchant](/account-setup/3ds-merchant-setup). Leave blank to use PCI Booking's merchant (Visa and Mastercard only).
</ParamField>

<ParamField type="integer">
  Transaction amount shown in the 3DS challenge screen. Must be paired with `currencyCode`. If omitted, authentication uses 0 EUR.
</ParamField>

<ParamField type="string">
  ISO 4217 currency code for the 3DS challenge amount. Must be paired with `amount`.
</ParamField>

<ParamField type="string">
  Cardholder email for 3DS authentication. Since August 2024, Visa requires either `email` or `phone` for all 3DS authentications.
</ParamField>

<ParamField type="string">
  Cardholder phone number for 3DS authentication (digits only, e.g. `00353112223344`). Required by Visa if `email` is not provided.
</ParamField>

<Warning title="Merchant name for 3DS">
  Do not use the `merchantName` parameter unless you have configured a [3DS merchant account](/account-setup/3ds-merchant-setup). Providing an unconfigured merchant name will cause 3DS processing to fail.
</Warning>

### Advanced

<ParamField type="boolean">
  When `true`, removes PCI Booking's submit button so you can trigger form submission from your own page via postMessage. See [postMessage setup](/capture-cards/postmessage-notifications).
</ParamField>

<ParamField type="boolean">
  When `true`, PCI Booking checks if this card was previously stored and returns the existing token instead of creating a new one.
</ParamField>

<ParamField type="boolean">
  When `true`, PCI Booking sends the non-sensitive form data to your server via [postMessage](/capture-cards/postmessage-notifications) for custom validation before tokenizing. Your server has 3 seconds to respond.
</ParamField>

## Request Example

Since this is a URL you build (not a server-side API call), the "request" is the fully constructed URL placed in an iframe or used as a redirect target. Here is an example using curl to test the URL directly:

<Tabs>
  <Tab title="curl">
    ```bash theme={null}
    curl -G "https://service.pcibooking.net/api/payments/capturecard" \
      --data-urlencode "accessToken=at_test_abc123" \
      --data-urlencode "brand=myhotel" \
      --data-urlencode "language=en" \
      --data-urlencode "autoDetectCardType=true" \
      --data-urlencode "success=https://yoursite.com/booking/success" \
      --data-urlencode "failure=https://yoursite.com/booking/failure" \
      --data-urlencode "postMessageHost=yoursite.com" \
      --data-urlencode "creatorReference=booking-12345" \
      --data-urlencode "cvv=true"
    ```
  </Tab>

  <Tab title="Node.js">
    ```javascript theme={null}
    const params = new URLSearchParams({
      accessToken: "at_test_abc123",
      brand: "myhotel",
      language: "en",
      autoDetectCardType: "true",
      success: "https://yoursite.com/booking/success",
      failure: "https://yoursite.com/booking/failure",
      postMessageHost: "yoursite.com",
      creatorReference: "booking-12345",
      cvv: "true"
    });

    const url = `https://service.pcibooking.net/api/payments/capturecard?${params}`;

    // Use this URL as an iframe src or redirect target
    console.log(url);

    // To test the URL directly:
    const response = await fetch(url);
    console.log(response.status);
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import requests

    params = {
        "accessToken": "at_test_abc123",
        "brand": "myhotel",
        "language": "en",
        "autoDetectCardType": "true",
        "success": "https://yoursite.com/booking/success",
        "failure": "https://yoursite.com/booking/failure",
        "postMessageHost": "yoursite.com",
        "creatorReference": "booking-12345",
        "cvv": "true"
    }

    # Build the URL for iframe src or redirect target
    prepared = requests.Request("GET",
        "https://service.pcibooking.net/api/payments/capturecard",
        params=params
    ).prepare()
    print(prepared.url)

    # To test the URL directly:
    response = requests.get(
        "https://service.pcibooking.net/api/payments/capturecard",
        params=params
    )
    print(response.status_code)
    ```
  </Tab>
</Tabs>

In production, you would set this URL as the `src` of an iframe element on your page:

```html theme={null}
<iframe src="https://service.pcibooking.net/api/payments/capturecard?accessToken=at_test_abc123&brand=myhotel&language=en&autoDetectCardType=true&success=https%3A%2F%2Fyoursite.com%2Fbooking%2Fsuccess&failure=https%3A%2F%2Fyoursite.com%2Fbooking%2Ffailure&postMessageHost=yoursite.com"></iframe>
```

## Success Response

On successful card capture, PCI Booking redirects the cardholder's browser to your `success` URL with the token details appended as query parameters:

```
https://yoursite.com/success?token=TOKEN_URI&last4Digits=1234&expirationDate=12/2028&cardType=Visa&nameOnCard=John+Doe
```

If you are using postMessage instead of redirect, the token details are sent via a [postMessage event](/capture-cards/postmessage-notifications).

## Errors

If the form cannot be rendered (invalid or missing parameters, authentication failure), PCI Booking redirects to your `failure` URL with error details. If no `failure` URL is configured, PCI Booking displays an error page.

| Error                                   | Cause                                                                                                                                                                  |
| --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Invalid or expired session/access token | The authentication token is missing, malformed, or has expired. Generate a new token and rebuild the URL.                                                              |
| Missing required parameters             | `brand`, `language`, or `postMessageHost` was not provided.                                                                                                            |
| Invalid language code                   | The `language` value is not a valid ISO 639-1 code. The form falls back to English.                                                                                    |
| 3DS challenge timeout                   | The cardholder did not complete the 3D Secure challenge within 5 minutes.                                                                                              |
| 3DS authentication rejected             | The cardholder failed 3D Secure authentication and `UnavailThreeDSAuth` is set to `Reject`.                                                                            |
| 3DS service unavailable                 | The 3DS provider is unreachable. If `UnavailThreeDSAuth` is `Accept`, the card is tokenized without 3DS. If `Reject`, the cardholder is redirected to the failure URL. |
| Invalid merchant name                   | The `merchantName` value does not match any configured 3DS merchant account.                                                                                           |

Errors delivered to the `failure` URL are appended as query parameters. See [success/failure URLs](/account-setup/success-and-failure-urls) for the format and available error fields.


# Retrieve Card Entry Session Details
Source: https://developers.pcibooking.net/api-reference/tokenize-cards/retrieve-card-entry-session

GET https://service.pcibooking.net/api/capturecard/{RequestID}
Retrieve the parameters configured for a card form session.

<Card title="Hosted Card Entry Form Guide" icon="book" href="/capture-cards/hosted-card-entry-form#option-2-api-session">
  API session approach for embedded card capture
</Card>

Use this endpoint to retrieve the configuration and current status of a card entry form session. The response includes all the original session parameters along with the capture result, letting you check whether the cardholder has submitted the form and whether tokenization succeeded.

## Error Responses

| Code  | HTTP Status | Condition                                                               |
| ----- | ----------- | ----------------------------------------------------------------------- |
| -1003 | 401         | Missing or invalid API key in the `Authorization` header.               |
| N/A   | 403         | The session belongs to a different user than the authenticated API key. |
| N/A   | 404         | Card entry form session with the specified `RequestID` was not found.   |

## Parameters

### Headers

<ParamField type="string">
  Your API key prefixed with `APIKEY`. Example: `APIKEY your-api-key`. See the [Authentication guide](/getting-started/authentication).
</ParamField>

### Path Parameters

<ParamField type="string">
  The request ID returned from [Create Card Entry Form session](/api-reference/tokenize-cards/create-card-entry-form-session).
</ParamField>

<RequestExample>
  ```javascript Node.js theme={null}
  const requestID = 'ITGdnzZuR7hQOI583EUB8U9vC3aPjuoV';

  const response = await fetch(
    `https://service.pcibooking.net/api/capturecard/${requestID}`,
    {
      headers: {
        'Authorization': 'APIKEY your-api-key'
      }
    }
  );

  const data = await response.json();
  console.log('Status:', data.FormChargeResult);
  console.log('Request ID:', data.RequestID);
  ```

  ```python Python theme={null}
  import requests

  request_id = 'ITGdnzZuR7hQOI583EUB8U9vC3aPjuoV'

  response = requests.get(
      f'https://service.pcibooking.net/api/capturecard/{request_id}',
      headers={
          'Authorization': 'APIKEY your-api-key'
      }
  )

  data = response.json()
  print('Status:', data['FormChargeResult'])
  print('Request ID:', data['RequestID'])
  ```
</RequestExample>

## Response

**200**

Returns the session configuration and its current status. The response includes all the fields from [Create Card Entry Form Session](/api-reference/tokenize-cards/create-card-entry-form-session), plus status fields that reflect what happened after the form was presented to the cardholder.

<ParamField type="string">
  The current status of the session. Possible values:

  | Value     | Meaning                                                          |
  | --------- | ---------------------------------------------------------------- |
  | `Pending` | Initial state. The cardholder has not yet submitted the form.    |
  | `Success` | Card was captured and tokenized successfully.                    |
  | `Reject`  | The card was rejected (e.g. failed validation or 3DS challenge). |
  | `Failure` | A technical error occurred during processing.                    |
</ParamField>

**404** - Session not found.

<ResponseExample>
  ```json 200 theme={null}
  {
    "RequestID": "ITGdnzZuR7hQOI583EUB8U9vC3aPjuoV",
    "SenderId": "RoeeSandbox",
    "CreatorReference": "Card capture request",
    "TTL": 600,
    "CallBackURL": "http://httpbin.org/post",
    "CreateTime": "2019-11-20T11:36:46.8062564Z",
    "FormChargeResult": "Success",
    "Properties": {
      "Language": "en",
      "AutoDetectCardType": true,
      "ShowCVV": true,
      "Success": "https://yoursite.com/success?cardToken={cardToken}",
      "Failure": "https://yoursite.com/failure"
    }
  }
  ```

  ```json 401 theme={null}
  {
      "code": -1003,
      "message": "Not authorized to access this resource",
      "moreInfo": "Bad or missing authorization data, expected APIKEY",
      "errorList": null
  }
  ```
</ResponseExample>


# Store Paycard (Card Migration)
Source: https://developers.pcibooking.net/api-reference/tokenize-cards/store-paycard

POST https://service.pcibooking.net/api/payments/paycard
Store card details in PCI Booking when migrating from local storage. The card data is sent in XML format.

<Card title="Card Migration Guide" icon="book" href="/capture-cards/store-card-migration">
  Migrate existing card data into PCI Booking tokens
</Card>

Use this endpoint to migrate card data you currently store on your own systems into PCI Booking tokens. Send the full card details in XML format, and PCI Booking returns a token URI you can use for all future operations. This is typically a one-time bulk migration step when onboarding with PCI Booking.

<Warning>
  This endpoint accepts card details in **XML format only**. Set `Content-Type: text/xml`.
</Warning>

## Error Responses

| Code  | HTTP Status | Condition                                                                                 |
| ----- | ----------- | ----------------------------------------------------------------------------------------- |
| -123  | 400         | Request body is not valid XML or is null                                                  |
| -123  | 400         | XML fails schema validation                                                               |
| -160  | 404         | Submitted data is PaymentInfo instead of BankCard                                         |
| -179  | 400         | Card validation failed (Luhn check, expiration, or CVV). Returns `errorList` with details |
| -125  | 400         | Card storage failed due to invalid data                                                   |
| -150  | 500         | Card storage failed due to a system error                                                 |
| -1003 | 401         | Missing `CanTokenize` permission                                                          |

## Parameter Constraints

| Parameter                | Type    | Required | Constraints                                                                     |
| ------------------------ | ------- | -------- | ------------------------------------------------------------------------------- |
| validateLuhn             | boolean | No       | Defaults to `true`. Validates card number with Luhn algorithm                   |
| validateExpiration       | boolean | No       | Defaults to `false`. When `true`, rejects expired cards                         |
| saveCVV                  | boolean | No       | Defaults to `false`. Requires CVV retention policy to be set after storage      |
| eliminateCardDuplication | boolean | No       | Defaults to `false`. When `true`, returns existing token if card already stored |
| Content-Type             | string  | Yes      | Must be `text/xml`                                                              |
| Auth                     | string  | Yes      | ApiKey, AccessToken, or SessionToken                                            |

The request body must contain a `BankCardDetails` XML document. See [Card Data XML Structure](/reference/card-data-xml-structure) for the full field reference.

```xml theme={null}
<BankCardDetails xmlns="http://www.pcibooking.net/reservation" schemaVersion="1.0">
  <BankCard>
    <Type>Visa</Type>
    <Number>4918914107195005</Number>
    <NameOnCard>Juan Dela Cruz</NameOnCard>
    <ExpirationDate>
      <Month>07</Month>
      <Year>2020</Year>
    </ExpirationDate>
    <IssueNumber>2</IssueNumber>
    <OwnerID>123456789</OwnerID>
    <CVV>123</CVV>
  </BankCard>
</BankCardDetails>
```

On success, a card token is created and the token URI is returned in the `Location` response header. The response body contains the submitted card details with sensitive data masked.

## Parameters

### Headers

<ParamField type="string">
  Your API key prefixed with `APIKEY`. Example: `APIKEY your-api-key`. For server-to-server calls.
</ParamField>

<Accordion title="Alternative: Browser-Side Authentication">
  This endpoint also accepts token-based authentication via query parameters:

  | Method                         | Details                                                                                                             |
  | ------------------------------ | ------------------------------------------------------------------------------------------------------------------- |
  | **Access Token** (recommended) | `accessToken` query param. [How to generate](/getting-started/authentication#access-token).                         |
  | **Session Token**              | `sessionToken` query param. [How to generate](/api-reference/general/start-temporary-session). Valid for 5 minutes. |

  If multiple methods are provided, precedence: Session Token > Access Token > API Key.
</Accordion>

<ParamField type="string">
  Must be `text/xml`. This endpoint accepts card details in XML format only.
</ParamField>

### Query String

<ParamField type="string">
  A reference value that can be used to query for this card token.
</ParamField>

<ParamField type="string">
  User ID of the property to associate the token with. Found under "Property settings" in the user's site.
</ParamField>

<ParamField type="string">
  User ID of the PCI Booking customer (booker ID) to associate the token with. The customer must share their PCI Booking user ID with you.
</ParamField>

<ParamField type="boolean">
  Whether to save the CVV in the database. **true** - save the CVV. **false** - do not save the CVV.
</ParamField>

<ParamField type="boolean">
  Whether to check if the expiration date is valid. `True` validates the expiration date and tokenization will fail if expired. `False` accepts the date as is, even if in the past.
</ParamField>

<ParamField type="boolean">
  Whether to check if the card number passes the Luhn algorithm. `True` validates using Luhn and tokenization will fail if the number does not pass. `False` accepts the number as is.
</ParamField>

### Request Body

<ParamField type="object">
  The BankCardDetails object. See the XML structure and example above.
</ParamField>

## Request Example

Store a Visa card and associate it with a reference and property:

<Tabs>
  <Tab title="curl">
    ```bash theme={null}
    curl -X POST "https://service.pcibooking.net/api/payments/paycard?ref=booking-12345&merchant=hotel-sunrise&saveCVV=true" \
      -H "Authorization: APIKEY your-api-key" \
      -H "Content-Type: text/xml" \
      -d '<?xml version="1.0" encoding="utf-8"?>
    <BankCardDetails xmlns="http://www.pcibooking.net/reservation" schemaVersion="1.0">
      <BankCard>
        <Type>Visa</Type>
        <Number>4111111111111111</Number>
        <NameOnCard>Jane Smith</NameOnCard>
        <ExpirationDate>
          <Month>12</Month>
          <Year>2028</Year>
        </ExpirationDate>
        <CVV>123</CVV>
      </BankCard>
    </BankCardDetails>'
    ```
  </Tab>

  <Tab title="Node.js">
    ```javascript theme={null}
    const xmlBody = `<?xml version="1.0" encoding="utf-8"?>
    <BankCardDetails xmlns="http://www.pcibooking.net/reservation" schemaVersion="1.0">
      <BankCard>
        <Type>Visa</Type>
        <Number>4111111111111111</Number>
        <NameOnCard>Jane Smith</NameOnCard>
        <ExpirationDate>
          <Month>12</Month>
          <Year>2028</Year>
        </ExpirationDate>
        <CVV>123</CVV>
      </BankCard>
    </BankCardDetails>`;

    const params = new URLSearchParams({
      ref: "booking-12345",
      merchant: "hotel-sunrise",
      saveCVV: "true"
    });

    const response = await fetch(
      `https://service.pcibooking.net/api/payments/paycard?${params}`,
      {
        method: "POST",
        headers: {
          "Authorization": "APIKEY your-api-key",
          "Content-Type": "text/xml"
        },
        body: xmlBody
      }
    );

    const tokenUri = response.headers.get("Location");
    console.log("Token URI:", tokenUri);

    const data = await response.json();
    console.log(data);
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import requests

    xml_body = """<?xml version="1.0" encoding="utf-8"?>
    <BankCardDetails xmlns="http://www.pcibooking.net/reservation" schemaVersion="1.0">
      <BankCard>
        <Type>Visa</Type>
        <Number>4111111111111111</Number>
        <NameOnCard>Jane Smith</NameOnCard>
        <ExpirationDate>
          <Month>12</Month>
          <Year>2028</Year>
        </ExpirationDate>
        <CVV>123</CVV>
      </BankCard>
    </BankCardDetails>"""

    response = requests.post(
        "https://service.pcibooking.net/api/payments/paycard",
        params={
            "ref": "booking-12345",
            "merchant": "hotel-sunrise",
            "saveCVV": "true"
        },
        headers={
            "Authorization": "APIKEY your-api-key",
            "Content-Type": "text/xml"
        },
        data=xml_body
    )

    token_uri = response.headers.get("Location")
    print("Token URI:", token_uri)
    print(response.json())
    ```
  </Tab>
</Tabs>

On success, the token URI is returned in the `Location` response header (e.g. `Location: https://service.pcibooking.net/api/payments/paycard/tok_abc123`).

## Response

**201** - Card stored. A `Location` header is returned with the token URI. The response body contains the card details with sensitive data masked.

<Info>
  Remember to set the [CVV Retention Policy](/capture-cards/cvv-retention-policy) on the token if you stored the CVV.
</Info>

<ResponseExample>
  ```json 201 theme={null}
  {
      "Type": "Visa",
      "Number": "491891******5005",
      "NameOnCard": "Juan Dela Cruz",
      "ExpirationDate": {
          "Month": "07",
          "Year": "2020"
      },
      "IssueNumber": "2"
  }
  ```

  ```json Unauthorized (bad credentials) 401 theme={null}
  {
      "code": -1003,
      "message": "Not authorized to access this resource",
      "moreInfo": "Bad or missing authorization data, expected APIKEY or Temp Session or One-Time Accesss Token",
      "errorList": null
  }
  ```

  ```json Unauthorized (no access) 401 theme={null}
  {
      "code": -1003,
      "message": "Not authorized to access this resource",
      "moreInfo": "Merchant or Owner are not associated with bank card [{{Token}] userID: SoBookIt",
      "errorList": null
  }
  ```
</ResponseExample>


# Tokenization in Response
Source: https://developers.pcibooking.net/api-reference/tokenize-cards/tokenization-in-response

POST https://service.pcibooking.net/api/payments/paycard/capture
Route a request through PCI Booking to a third party. PCI Booking intercepts the response, tokenizes card data, masks the details, and returns the sanitized response.

<Card title="Tokenization on Response Guide" icon="book" href="/capture-cards/tokenization-on-response">
  Automatically tokenize cards from gateway responses
</Card>

PCI Booking forwards your request to the third party, tokenizes any card data found in the response (using your [target profile](/account-setup/target-profiles)), and returns the sanitized response with the following custom headers:

| Header                               | Description                                                                                                         |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------- |
| `X-pciBooking-cardUri`               | Semicolon-separated list of token URIs for each card tokenized. The header name can be customized per profile.      |
| `X-pciBooking-Tokenization-Errors`   | Errors encountered during tokenization (e.g. invalid card number, missing fields). Present only if errors occurred. |
| `X-pciBooking-Tokenization-Warnings` | Warnings encountered during tokenization (e.g. expired card accepted). Present only if warnings occurred.           |

<Note>
  All URLs must be HTTPS and URL-encoded.
</Note>

## Error Responses

| Code  | HTTP Status | Condition                                  |
| ----- | ----------- | ------------------------------------------ |
| -125  | 400         | Empty relay message content (null body)    |
| -125  | 400         | Could not fetch a valid PCI Shield profile |
| -1003 | 401         | Missing `CanTokenize` permission           |

## Parameter Constraints

| Parameter   | Type    | Required | Constraints                                                                  |
| ----------- | ------- | -------- | ---------------------------------------------------------------------------- |
| targetURI   | string  | Yes      | Must be a valid HTTPS URL                                                    |
| profileName | string  | Yes      | Must match a configured target profile                                       |
| httpMethod  | string  | Yes      | Defaults to `POST`. Accepted values: `POST`, `GET`, `PUT`, `PATCH`, `DELETE` |
| timeout     | integer | No       | Number of seconds to wait for a response. Defaults to 0 (no timeout)         |
| Auth        | string  | Yes      | ApiKey, AccessToken, or SessionToken                                         |

## Parameters

### Authentication

<Warning>
  This is a browser-facing endpoint. Use one of the authentication methods below instead of the API key shown above.
</Warning>

<ParamField type="string">
  Recommended. A long-lived token for browser-side calls. [How to generate](/getting-started/authentication#access-token).
</ParamField>

<ParamField type="string">
  Alternative. Valid for 5 minutes. [How to generate](/api-reference/general/start-temporary-session).
</ParamField>

If both are provided, the session token takes precedence.

### Query String

<ParamField type="string">
  The unique ID for the profile set up for the response you will receive for this request. You can set up as many profiles as you require. Read more about [target profiles](/account-setup/target-profiles).
</ParamField>

<ParamField type="string">
  The URI of the third party to relay the request to. PCI Booking sends your request to this endpoint and intercepts the response.
</ParamField>

<ParamField type="string">
  The HTTP method that PCI Booking should use when calling the target URI. Possible values: `POST`, `GET`, `PUT`, `PATCH`, `DELETE`.
</ParamField>

<ParamField type="int">
  The number of seconds PCI Booking should wait for a response from the third party.
</ParamField>

<ParamField type="boolean">
  Whether to save the CVV in the database. `true`: save the CVV. `false`: discard the CVV.
</ParamField>

<ParamField type="string">
  A reference value which can be used to query for this card token.
</ParamField>

<ParamField type="string">
  The user ID of the property to associate the token with. Found under "Property settings" in the user's site.
</ParamField>

<ParamField type="string">
  The user ID of the PCI Booking customer (booker ID) to associate the token with. The PCI Booking customer must share their user ID with you.
</ParamField>

<ParamField type="boolean">
  Controls whether PCI Booking checks if the card already exists as a token in your account.

  * **`true`**: PCI Booking looks up the card in your stored tokens. If a match is found, the existing token URI is returned instead of creating a new one. The response status will be `200` instead of `201`.
  * **`false`** (default): A new token is always created, even if the same card was previously stored.
</ParamField>

### Request Body

<Note>
  The request body and headers are passed through to the third party as-is. Include any body content and headers that the third party requires.
</Note>

<RequestExample>
  ```javascript Node.js theme={null}
  const params = new URLSearchParams({
    profileName: 'MyOTAProfile',
    targetURI: 'https://api.thirdparty.com/reservations/12345',
    httpMethod: 'POST',
    saveCVV: 'true',
    ref: 'booking-12345'
  });

  const response = await fetch(
    `https://service.pcibooking.net/api/payments/paycard/capture?${params}`,
    {
      method: 'POST',
      headers: {
        'Authorization': 'APIKEY your-api-key',
        'Content-Type': 'application/xml'
      },
      body: '<ReservationRequest><ID>12345</ID></ReservationRequest>'
    }
  );

  const tokenUri = response.headers.get('X-pciBooking-cardUri');
  console.log('Token URI:', tokenUri);

  const data = await response.text();
  console.log('Sanitized response:', data);
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://service.pcibooking.net/api/payments/paycard/capture',
      params={
          'profileName': 'MyOTAProfile',
          'targetURI': 'https://api.thirdparty.com/reservations/12345',
          'httpMethod': 'POST',
          'saveCVV': 'true',
          'ref': 'booking-12345'
      },
      headers={
          'Authorization': 'APIKEY your-api-key',
          'Content-Type': 'application/xml'
      },
      data='<ReservationRequest><ID>12345</ID></ReservationRequest>'
  )

  token_uri = response.headers.get('X-pciBooking-cardUri')
  print('Token URI:', token_uri)
  print('Sanitized response:', response.text)
  ```
</RequestExample>

## Response

**200** - The card already exists in your account (when `eliminateCardDuplication` is `true`). The response body contains the third-party response with card details masked. The existing token URI is returned in the `X-pciBooking-cardUri` header.

**201** - A new card was tokenized. The response body contains the third-party response with card details masked. The new token URI is returned in the `X-pciBooking-cardUri` header.

<Info>
  Remember to set the [CVV Retention Policy](/capture-cards/cvv-retention-policy) on the token.
</Info>

<ResponseExample>
  ```text 201 theme={null}
  The third-party response body is returned with card details replaced by token placeholders.
  The X-pciBooking-cardUri header contains the new token URI.
  ```

  ```json Invalid profile 400 theme={null}
  {
      "code": -125,
      "message": "Bad input data",
      "moreInfo": "Couldn't fetch a valid pciShield profile:: wsc",
      "errorList": null
  }
  ```

  ```json Invalid target URI 400 theme={null}
  {
      "code": -125,
      "message": "Bad input data",
      "moreInfo": "Invalid target Uri::",
      "errorList": null
  }
  ```

  ```json 401 theme={null}
  {
      "code": -1003,
      "message": "Not authorized to access this resource",
      "moreInfo": "Bad or missing authorization data, expected Temp Session or One-Time Accesss Token",
      "errorList": null
  }
  ```
</ResponseExample>


# Tokenize from sFTP
Source: https://developers.pcibooking.net/api-reference/tokenize-cards/tokenize-from-sftp

GET https://service.pcibooking.net/api/sftp/{serverAddress}/{folderPath}/{fileName}
Download a file from an sFTP server through PCI Booking. Card data is extracted, tokenized, and the sanitized file content is returned.

<Card title="File Transfer Tokenization Guide" icon="book" href="/capture-cards/file-transfer-tokenization">
  Tokenize card data from SFTP file transfers
</Card>

Also available over FTPS:

```
GET https://service.pcibooking.net/api/ftps/{serverAddress}/{folderPath}/{fileName}
```

PCI Booking connects to the sFTP server, downloads the file, tokenizes any card data found in it (based on the specified filter), and returns the sanitized file content with the following custom headers:

| Header                               | Description                                                                                                         |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------- |
| `X-pciBooking-cardUri`               | Semicolon-separated list of token URIs for each card tokenized.                                                     |
| `X-pciBooking-Tokenization-Errors`   | Errors encountered during tokenization (e.g. invalid card number, missing fields). Present only if errors occurred. |
| `X-pciBooking-Tokenization-Warnings` | Warnings encountered during tokenization (e.g. expired card accepted). Present only if warnings occurred.           |

<Note>
  If the path ends with `/`, PCI Booking returns a directory listing instead of downloading a file.
</Note>

## Error Responses

| Code    | HTTP Status | Condition                                                              |
| ------- | ----------- | ---------------------------------------------------------------------- |
| `-1003` | `401`       | Authorization token is missing or invalid.                             |
| `-125`  | `400`       | Invalid host format (e.g. multiple colons in the server address).      |
| `-125`  | `400`       | Invalid or missing Basic Auth credentials in the Authorization header. |
| `-125`  | `400`       | The requested filter name is not recognized.                           |
| `-1003` | `401`       | SFTP/FTPS login failed (invalid server credentials).                   |
| `-160`  | `404`       | File download or directory listing failed on the remote server.        |

## Parameter Constraints

* **serverAddress**: Format is `hostname` or `hostname:port`. Only one colon is allowed. Default port is 22.
* **filter**: Must be one of: `GBT`, `SIMPLECSV`, `SIMPLEJSON`, `AIR`, `IUR`, `TADC`, `CSV`. Case-insensitive.
* **Authorization header**: Must contain valid Basic Auth credentials (`username:password`) for the SFTP/FTPS server.

## Parameters

### Authentication

<Warning>
  This is a browser-facing endpoint. Use one of the authentication methods below instead of the API key shown above.
</Warning>

<ParamField type="string">
  Recommended. A long-lived token for browser-side calls. [How to generate](/getting-started/authentication#access-token).
</ParamField>

<ParamField type="string">
  Alternative. Valid for 5 minutes. [How to generate](/api-reference/general/start-temporary-session).
</ParamField>

If both are provided, the session token takes precedence.

### Path Parameters

<ParamField type="string">
  The sFTP server address. This can be an IP address or domain name. If required, add the port number with a colon. For example: `fsgatewaytest.aexp.com:22` or `10.200.1.10`.
</ParamField>

<ParamField type="string">
  The folder path where the file should be downloaded from. This can be an individual folder or a full path.
</ParamField>

<ParamField type="string">
  The file name to download, including extension. For example: `PCIBTST.xml`.
</ParamField>

### Query String

<ParamField type="string">
  The file format filter that tells PCI Booking how to parse the file content and locate card data.
</ParamField>

<ParamField type="string">
  The number of seconds PCI Booking should wait for the sFTP server to respond.
</ParamField>

<ParamField type="string">
  A reference value which can be used to query for this card token.
</ParamField>

<ParamField type="string">
  The user ID of the property to associate the token with. Found under "Property settings" in the user's site.
</ParamField>

<ParamField type="boolean">
  Controls whether PCI Booking checks if the card already exists as a token in your account.

  * **`true`**: PCI Booking looks up the card in your stored tokens. If a match is found, the existing token URI is returned instead of creating a new one.
  * **`false`** (default): A new token is always created, even if the same card was previously stored.
</ParamField>

### Headers

<ParamField type="string">
  PCI Booking supports request compression in `gzip` and `deflate` formats. Set this header as needed. Omit if no compression is required.
</ParamField>

<RequestExample>
  ```javascript Node.js theme={null}
  const serverAddress = 'sftp.thirdparty.com:22';
  const folderPath = 'reports/daily';
  const fileName = 'reservations.xml';

  const params = new URLSearchParams({
    filter: 'GBT',
    ref: 'import-2024-01',
    timeout: '30'
  });

  const response = await fetch(
    `https://service.pcibooking.net/api/sftp/${serverAddress}/${folderPath}/${fileName}?${params}`,
    {
      headers: {
        'Authorization': 'APIKEY your-api-key'
      }
    }
  );

  const tokenUri = response.headers.get('X-pciBooking-cardUri');
  console.log('Token URI:', tokenUri);

  const data = await response.text();
  console.log('Sanitized file content:', data);
  ```

  ```python Python theme={null}
  import requests

  server_address = 'sftp.thirdparty.com:22'
  folder_path = 'reports/daily'
  file_name = 'reservations.xml'

  response = requests.get(
      f'https://service.pcibooking.net/api/sftp/{server_address}/{folder_path}/{file_name}',
      params={
          'filter': 'GBT',
          'ref': 'import-2024-01',
          'timeout': '30'
      },
      headers={
          'Authorization': 'APIKEY your-api-key'
      }
  )

  token_uri = response.headers.get('X-pciBooking-cardUri')
  print('Token URI:', token_uri)
  print('Sanitized file content:', response.text)
  ```
</RequestExample>

## Response

**200** - The file content with card details masked. Token URIs are returned in the `X-pciBooking-cardUri` header.

<Info>
  Remember to set the [CVV Retention Policy](/capture-cards/cvv-retention-policy) on the token.
</Info>

<ResponseExample>
  ```text 200 theme={null}
  The file content is returned with card details replaced by token placeholders.
  The X-pciBooking-cardUri header contains the token URI(s).
  ```

  ```json 400 theme={null}
  {
      "code": -125,
      "message": "Bad input data",
      "moreInfo": "...",
      "errorList": null
  }
  ```

  ```json 401 theme={null}
  {
      "code": -1003,
      "message": "Not authorized to access this resource",
      "moreInfo": "Bad or missing authorization data, expected Temp Session or One-Time Access Token",
      "errorList": null
  }
  ```
</ResponseExample>


# Tokenize on Response Using Preset Profiles
Source: https://developers.pcibooking.net/api-reference/tokenize-cards/tokenize-on-response-using-preset-profiles

POST https://service.pcibooking.net/api/booker/{ProfileName}/reservation
Send a request through a pre-configured PCI Booking profile to a third party. PCI Booking intercepts the response, tokenizes card data, and returns the sanitized response.

<Card title="Universal Tokenization Guide" icon="book" href="/capture-cards/universal-tokenization">
  Tokenize cards from any source using preset profiles
</Card>

PCI Booking forwards your request to the third party defined in the profile, tokenizes any card data found in the response, and returns the sanitized response with the following custom headers:

| Header                               | Description                                                                                                         |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------- |
| `X-pciBooking-cardUri`               | Semicolon-separated list of token URIs for each card tokenized. The header name can be customized per profile.      |
| `X-pciBooking-Tokenization-Errors`   | Errors encountered during tokenization (e.g. invalid card number, missing fields). Present only if errors occurred. |
| `X-pciBooking-Tokenization-Warnings` | Warnings encountered during tokenization (e.g. expired card accepted). Present only if warnings occurred.           |

## Error Responses

| Code    | HTTP Status | Condition                                                                           |
| ------- | ----------- | ----------------------------------------------------------------------------------- |
| `-1003` | `401`       | Authorization token is missing or invalid (requires Access Token or Session Token). |
| `-1003` | `401`       | User does not have `CanTokenize` permission.                                        |
| `-125`  | `400`       | The specified profile name was not found.                                           |
| `-150`  | `500`       | Failed to retrieve the profile configuration (internal error).                      |

## Parameter Constraints

* **ProfileName**: Must match an existing profile name (see [Get Tokenization Profiles](/api-reference/tokenize-cards/get-tokenization-profiles)).
* **pathSegments**: Required if the profile's target URL has dynamic path segments. Provide key-value pairs in query string format.
* **eliminateCardDuplication**: When `true`, a `200` status indicates the card already existed; `201` means a new token was created.

## Parameters

### Authentication

<Warning>
  This is a browser-facing endpoint. Use one of the authentication methods below instead of the API key shown above.
</Warning>

<ParamField type="string">
  Recommended. A long-lived token for browser-side calls. [How to generate](/getting-started/authentication#access-token).
</ParamField>

<ParamField type="string">
  Alternative. Valid for 5 minutes. [How to generate](/api-reference/general/start-temporary-session).
</ParamField>

If both are provided, the session token takes precedence.

### Path Parameters

<ParamField type="string">
  The name of the profile as returned from the [Get Tokenization Profiles](/api-reference/tokenize-cards/get-tokenization-profiles) method.
</ParamField>

### Query String

<ParamField type="string">
  Dynamic path segments to append to the profile's target URL. Some third-party endpoints include dynamic values in the URL path (e.g. `https://ws.mydomain.com/{customerName}`). The [Get Tokenization Profiles](/api-reference/tokenize-cards/get-tokenization-profiles) response lists the required path segments for each profile.
</ParamField>

<ParamField type="string">
  Query string parameters to append to the profile's target URL. Some third-party endpoints require additional parameters (e.g. `?param1=value1&param2=value2`). Provide the full query string as needed.
</ParamField>

<ParamField type="boolean">
  Whether to save the CVV in the database. `true`: save the CVV. `false`: discard the CVV.
</ParamField>

<ParamField type="string">
  A reference value which can be used to query for this card token.
</ParamField>

<ParamField type="string">
  The user ID of the property to associate the token with. Found under "Property settings" in the user's site.
</ParamField>

<ParamField type="boolean">
  Controls whether PCI Booking checks if the card already exists as a token in your account.

  * **`true`**: PCI Booking looks up the card in your stored tokens. If a match is found, the existing token URI is returned instead of creating a new one. The response status will be `200` instead of `201`.
  * **`false`** (default): A new token is always created, even if the same card was previously stored.
</ParamField>

### Request Body

<Note>
  The request body and headers are passed through to the third party as-is. Include any body content and headers that the third party requires.
</Note>

<RequestExample>
  ```javascript Node.js theme={null}
  const profileName = 'SiteMinder';
  const params = new URLSearchParams({
    pathSegments: 'SiteMinderCustID=CUST001',
    saveCVV: 'true',
    ref: 'booking-12345'
  });

  const response = await fetch(
    `https://service.pcibooking.net/api/booker/${profileName}/reservation?${params}`,
    {
      method: 'POST',
      headers: {
        'Authorization': 'APIKEY your-api-key',
        'Content-Type': 'application/xml'
      },
      body: '<ReservationRequest><HotelCode>HOTEL01</HotelCode></ReservationRequest>'
    }
  );

  const tokenUri = response.headers.get('X-pciBooking-cardUri');
  console.log('Token URI:', tokenUri);

  const data = await response.text();
  console.log('Sanitized response:', data);
  ```

  ```python Python theme={null}
  import requests

  profile_name = 'SiteMinder'

  response = requests.post(
      f'https://service.pcibooking.net/api/booker/{profile_name}/reservation',
      params={
          'pathSegments': 'SiteMinderCustID=CUST001',
          'saveCVV': 'true',
          'ref': 'booking-12345'
      },
      headers={
          'Authorization': 'APIKEY your-api-key',
          'Content-Type': 'application/xml'
      },
      data='<ReservationRequest><HotelCode>HOTEL01</HotelCode></ReservationRequest>'
  )

  token_uri = response.headers.get('X-pciBooking-cardUri')
  print('Token URI:', token_uri)
  print('Sanitized response:', response.text)
  ```
</RequestExample>

## Response

**200** - The card already exists in your account (when `eliminateCardDuplication` is `true`). The response body contains the third-party response with card details masked. The existing token URI is returned in the `X-pciBooking-cardUri` header.

**201** - A new card was tokenized. The response body contains the third-party response with card details masked. The new token URI is returned in the `X-pciBooking-cardUri` header.

<Info>
  Remember to set the [CVV Retention Policy](/capture-cards/cvv-retention-policy) on the token.
</Info>

<ResponseExample>
  ```text 201 theme={null}
  The third-party response body is returned with card details replaced by token placeholders.
  The X-pciBooking-cardUri header contains the new token URI.
  ```

  ```json Invalid profile 400 theme={null}
  {
      "code": -125,
      "message": "Bad input data",
      "moreInfo": "Couldn't fetch a valid pciShield profile:: wsc",
      "errorList": null
  }
  ```

  ```json Invalid target URI 400 theme={null}
  {
      "code": -125,
      "message": "Bad input data",
      "moreInfo": "Invalid target Uri::",
      "errorList": null
  }
  ```

  ```json 401 theme={null}
  {
      "code": -1003,
      "message": "Not authorized to access this resource",
      "moreInfo": "Bad or missing authorization data, expected Temp Session or One-Time Accesss Token",
      "errorList": null
  }
  ```
</ResponseExample>


# Card By Link
Source: https://developers.pcibooking.net/capture-cards/card-by-link

Send cardholders a secure link via email or SMS to enter card details. PCI Booking tokenizes so no card data touches your systems.

Card By Link lets you capture card details securely by sending a link to the cardholder via email or SMS. The cardholder enters their card on a PCI Booking-hosted page, customized by you, and PCI Booking tokenizes it. No card data passes through your systems.

## How It Works

1. **Initiate request**. Your system calls the [Send Card Form](/api-reference/tokenize-cards/cotp-send-card-form) API to create a Card By Link request, specifying the cardholder's email or phone number.
2. **Secure link sent**. PCI Booking sends a short-lived secure link to the cardholder.
3. **Cardholder enters card**. The cardholder clicks the link and enters their card details on the hosted form.
4. **Token created**. PCI Booking tokenizes the card and notifies your system via [callback](/api-reference/tokenize-cards/cotp-callback).

You can [check the request status](/api-reference/tokenize-cards/cotp-retrieve-request) at any time, or [cancel a pending request](/api-reference/tokenize-cards/cotp-delete-request) if needed.

## Key Features

* **Email and SMS delivery**. Send the capture link through either channel (or both).
* **Customizable templates**. Brand the email or SMS message with your own templates.
* **Status tracking**. Query the request status at any time to check if the cardholder has completed the form.
* **Callback notifications**. Receive a POST callback when the card is captured.
* **Short-lived links**. Links expire after a configurable period, ensuring security.
* **3D Secure**. 3DS verification is supported. When enabled, a 3DS challenge is presented to the cardholder after they enter their card. The cardholder has 5 minutes to complete the challenge before it expires. See [3DS Merchant Setup](/account-setup/3ds-merchant-setup) to configure your merchant details.

## Security

The cardholder enters card data directly into a PCI Booking-hosted page, customized by you. No one else sees or handles the card details. This is ideal for call centers, remote collection, and any scenario where the cardholder is not on your website.

<Info title="Common use case">
  An agent on the phone says: "I've just sent you a secure link to enter your card details." The cardholder receives the link, enters their card, and the agent sees confirmation that the token was created, without ever handling card data.
</Info>

<Warning title="Link expiration">
  Card By Link URLs are time-limited. If the cardholder doesn't complete the form before expiration, you'll need to generate a new request.
</Warning>

## CVV-Only Capture

Card By Link also supports collecting just the CVV on an existing token. Use the [Send CVV Form](/api-reference/tokenize-cards/cotp-send-cvv-form) endpoint instead of the card form endpoint. The cardholder receives a link, enters only their CVV, and PCI Booking creates a new token with the original card details plus the captured CVV.

<Warning>
  The CVV capture creates a **new token**. The original token remains unchanged. Delete the original token if it is no longer needed, otherwise it will continue to incur monthly storage fees.
</Warning>

Remember to set a [CVV retention policy](/capture-cards/cvv-retention-policy) on the new token within 60 minutes, or your account default will apply.

## White Label Emails

By default, Card By Link emails come from the `pcibooking.net` domain. To send them from your own domain instead, configure a [White Label Email Domain](/account-setup/white-label-email).

## Next Steps

<CardGroup>
  <Card title="Customize Card By Link Templates" icon="book" href="/account-setup/card-by-link-templates">
    Brand your Card By Link emails, SMS messages, and landing pages.
  </Card>

  <Card title="Card Validation Errors" icon="code" href="/reference/card-validation-errors">
    Error messages the cardholder may see when entering invalid card data.
  </Card>

  <Card title="Capture Cards Overview" icon="book" href="/capture-cards/overview">
    All available tokenization methods.
  </Card>
</CardGroup>


# CVV Capture Form
Source: https://developers.pcibooking.net/capture-cards/cvv-capture

Collect CVV codes securely using a PCI Booking hosted form. Works with existing card tokens, supports 3D Secure.

The CVV Capture Form is a PCI Booking-hosted form that collects only the card security code (CVV) from the cardholder. Use it when you already have a card token but need the CVV for a transaction.

## How It Works

1. Your system calls the [Request CVV Entry Form](/api-reference/manage-tokens/request-cvv-entry-form) endpoint, passing the existing card token.
2. PCI Booking returns a form URL that you embed as an iframe or redirect to.
3. The cardholder enters only their CVV.
4. PCI Booking duplicates the original card to a new token and attaches the captured CVV to the new token.
5. The cardholder is redirected to your success URL with the new token.

<Warning>
  The CVV capture form creates a **new token** with the card details copied from the original plus the captured CVV. The original token remains unchanged. It is your responsibility to delete the original token if it is no longer needed, otherwise it will continue to incur monthly storage fees.
</Warning>

## Setting the CVV Retention Policy

After the new token is created with CVV, you have 60 minutes to set a [CVV retention policy](/capture-cards/cvv-retention-policy) on it. If you don't, your account-wide default applies. If no account default exists, the system default applies (CVV can be used once and is then cleared).

## 3D Secure

The CVV capture form supports 3DS authentication. If enabled, a 3DS challenge is presented to the cardholder after they enter their CVV. The cardholder has 5 minutes to complete the challenge. See [3DS Merchant Setup](/account-setup/3ds-merchant-setup) to configure your merchant details for the challenge screen.

<Info>
  If you are using 3DS authentication, you must provide either the cardholder's email address or phone number in the request. This is required by Visa for all 3DS authentications.
</Info>

## Via Card By Link

You can also collect CVV remotely by sending the cardholder a link via email or SMS. See the [CVV-Only Capture section](/capture-cards/card-by-link#cvv-only-capture) in the Card By Link guide.

## Next Steps

<CardGroup>
  <Card title="CVV Retention Policy" icon="book" href="/capture-cards/cvv-retention-policy">
    Configure how long CVV is retained.
  </Card>

  <Card title="CVV Management" icon="book" href="/manage-tokens/cvv-management">
    Check CVV status, usage, or clear CVV on a token.
  </Card>

  <Card title="Capture Cards Overview" icon="book" href="/capture-cards/overview">
    All tokenization methods.
  </Card>
</CardGroup>


# CVV Retention Policy
Source: https://developers.pcibooking.net/capture-cards/cvv-retention-policy

Configure how long CVV data is retained and how many times it can be used. PCI DSS enforcement with per-token policies.

PCI DSS prohibits long-term storage of CVV data. When a card is tokenized with CVV, you need a retention policy that defines how long the CVV is kept and how many times it can be used before it is automatically cleared.

## How It Works

CVV retention is not part of the tokenization request itself. It is a separate step that happens after tokenization:

1. **Card is tokenized** (via any [tokenization method](/capture-cards/overview)) with CVV included.
2. **You have 60 minutes** to set a per-token CVV retention policy via the [Set CVV Retention Policy](/api-reference/manage-tokens/set-cvv-retention-policy) endpoint.
3. **If you don't set one**, the account-wide default policy is applied automatically. If no account-wide default exists, the system default applies: CVV can be used once and is then cleared.

This applies to every tokenization method that captures CVV.

## Policy Levels

| Level                    | Description                                                                                                         |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------- |
| **System default**       | CVV can be used once and is then cleared. Applies when no other policy is set.                                      |
| **Account-wide default** | Set by your account administrator. Applies automatically to all new tokens unless overridden by a per-token policy. |
| **Per-token**            | Set via the API within 60 minutes of tokenization. Overrides the account-wide default for that specific token.      |

## Policy Types

| Type                | How It Works                                                                                                                                                     |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Time-based**      | CVV is automatically cleared after a specified date/time (`CvvEndRetentionDate`).                                                                                |
| **Per-destination** | Different retention rules for different destinations. For example, keep CVV available for your primary PSP but clear it after one use for a secondary processor. |
| **Usage-based**     | CVV is cleared after it has been sent to a destination a specified number of times (quota).                                                                      |

## Destination Types

Per-destination policies support these destination types:

| Type              | Description                                                     |
| ----------------- | --------------------------------------------------------------- |
| **HostName**      | A specific host (e.g. `api.stripe.com`).                        |
| **Owner**         | The token owner account.                                        |
| **OtherMerchant** | Other merchant accounts that have permission to use this token. |
| **SFTP**          | An SFTP server by IP address.                                   |
| **OtherUser**     | Other users in the system.                                      |

## Auto-Delete Card on CVV Expiry

You can optionally configure the policy to delete the entire card token when its CVV is cleared, using the `DeleteCardUponCvvCleanup` option. Use this when a token without CVV has no value in your workflow.

## Setting the Account-Wide Default

To set a default CVV retention policy that applies automatically to all new tokens in your account:

1. Log in to the [PCI Booking portal](https://users.pcibooking.net).
2. Navigate to **Booker Settings** > **CVV Store Rules**.
3. Under **Storage Period**, set the duration that CVV is stored (e.g., 12 months). Maximum is 4 years / 48 months.
4. Under **Destinations**, define the approved list of destinations where CVV can be relayed. For each destination, specify:
   * **Destination type** (see [Destination Types](#destination-types) above)
   * **Destination value** (e.g., hostname, IP address)
   * **Quota** (number of times the CVV can be relayed to this destination)

<Info>
  You can configure up to 50 different destinations. Each destination allows a quota of up to 50 relays.
</Info>

<Warning>
  If you use destination-based retention with hostnames, make sure those hostnames are also included in your [relay restrictions](/account-setup/security-settings) (if configured).
</Warning>

Per-token policies set via the API override the account-wide default for that specific token.

## Managing Per-Token Policies

| Action                                        | API Endpoint                                                                                        |
| --------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| Set or update policy                          | [Set CVV Retention Policy](/api-reference/manage-tokens/set-cvv-retention-policy).                  |
| View current policy and usage                 | [Get CVV Retention Policy](/api-reference/manage-tokens/get-cvv-retention-policy).                  |
| View policy for a specific destination        | [Get Specific Policy](/api-reference/manage-tokens/get-cvv-retention-policy-specific).              |
| Remove policy (revert to account default)     | [Delete CVV Retention Policy](/api-reference/manage-tokens/delete-cvv-retention-policy).            |
| Remove policy for a specific destination type | [Delete Policy by Type](/api-reference/manage-tokens/delete-cvv-retention-policy-type).             |
| Remove policy for a specific destination      | [Delete Policy by Destination](/api-reference/manage-tokens/delete-cvv-retention-policy-type-data). |

## Next Steps

<CardGroup>
  <Card title="CVV Management" icon="book" href="/manage-tokens/cvv-management">
    Manage CVV data within a token: check status, capture separately, or clear manually.
  </Card>

  <Card title="Capture Cards Overview" icon="book" href="/capture-cards/overview">
    All tokenization methods.
  </Card>
</CardGroup>


# File Transfer Tokenization
Source: https://developers.pcibooking.net/capture-cards/file-transfer-tokenization

Tokenize card numbers in file transfers. PCI Booking acts as a secure SFTP/FTPS proxy, replacing card data with tokens.

PCI Booking acts as a secure file transfer proxy between you and a third party's file server. You make an [API call](/api-reference/tokenize-cards/tokenize-from-sftp) specifying the remote server, and PCI Booking connects, downloads the file, tokenizes all card numbers, and returns the tokenized content to you. Card data never touches your systems.

## Supported Protocols

| Protocol | Default Port | Description                 |
| -------- | ------------ | --------------------------- |
| **SFTP** | 22           | SSH File Transfer Protocol. |
| **FTPS** | 990          | FTP over TLS.               |

## How It Works

PCI Booking acts as a proxy between your system and the third party's file server. Your system never connects directly to the remote server, so card data never passes through your infrastructure.

1. You call [`GET /api/sftp/{host}/{path}`](/api-reference/tokenize-cards/tokenize-from-sftp) or `GET /api/ftps/{host}/{path}`, passing the third party's server credentials in the Authorization header along with a `fileFormat` parameter that tells PCI Booking which parser to apply.
2. PCI Booking establishes a secure connection to the third party's file server using the provided credentials and downloads the specified file.
3. PCI Booking applies the selected file format parser to locate all card numbers within the file content, tokenizes each card number, and stores the real card data in its PCI DSS Level 1 certified vault.
4. PCI Booking returns the modified file content to your system with all card numbers replaced by tokens. The file structure and all non-card data remain unchanged.

Your existing file processing logic continues to work without modification. The only difference is that card number fields now contain PCI Booking tokens instead of real card numbers.

To send tokenized data back to a third party via file transfer (the reverse direction), see [File Transfer Token Replacement](/use-tokens/file-transfer-token-replacement).

## Setup Requirements

Before using file transfer tokenization, you need:

* **A PCI Booking account** with API access. See [Create an Account](/getting-started/create-account) and [Authentication](/getting-started/authentication) for setup.
* **Third-party server credentials.** The SFTP or FTPS hostname, port, username, and password (or SSH key) for the remote file server. These are passed in the API call, not stored in PCI Booking.
* **File format identification.** Determine which file format parser matches your file structure (see the table below). If unsure, send a sample file to support.
* **Network access.** PCI Booking's servers must be able to reach the third party's file server. If the remote server has IP restrictions, contact support for the list of PCI Booking egress IPs to allowlist.

## Supported File Formats

PCI Booking supports several file format parsers to locate card data within different file structures:

| Format     | Description                                          |
| ---------- | ---------------------------------------------------- |
| GBT        | GBT travel industry format.                          |
| SIMPLECSV  | CSV files with card numbers in identifiable columns. |
| SIMPLEJSON | JSON files with card numbers in identifiable fields. |
| AIR        | Airline industry format.                             |
| IUR        | IUR format.                                          |
| TADC       | TADC XML travel industry card data format.           |
| CSV        | Generic CSV format.                                  |

<Info>
  Not sure if your file structure matches one of these formats? Contact [support@pcibooking.net](mailto:support@pcibooking.net) with a sample of the file. If your format is not yet supported, our team can enhance the system to handle it.
</Info>

## Use Cases

* Receiving card data from booking systems, GDS providers, or travel partners via file transfer.
* TADC-based integrations with travel industry systems.

## Next Steps

<CardGroup>
  <Card title="File Transfer Token Replacement" icon="book" href="/use-tokens/file-transfer-token-replacement">
    Send tokenized card data to a third party via SFTP/FTPS (the reverse direction).
  </Card>

  <Card title="Capture Cards Overview" icon="book" href="/capture-cards/overview">
    All available tokenization methods.
  </Card>

  <Card title="Target Profiles" icon="crosshairs" href="/account-setup/target-profiles">
    Configure target profiles for file transfer connections.
  </Card>
</CardGroup>

## Related

* [Tokenize from SFTP API](/api-reference/tokenize-cards/tokenize-from-sftp) - API reference for SFTP tokenization
* [Token Replacement via SFTP](/api-reference/process-cards/token-replacement-sftp) - Send card data to a third party's SFTP server


# Hosted Card Entry Form
Source: https://developers.pcibooking.net/capture-cards/hosted-card-entry-form

Embed a PCI-compliant hosted card entry form via iframe or standalone page. URL parameters and API sessions with 3D Secure.

The Hosted Card Entry Form is a PCI Booking-hosted page where cardholders enter their card details securely. You embed it as an iframe or redirect to it as a standalone page. Card data never touches your servers.

<iframe />

<Note>
  This is a non-functional preview showing the default card entry form. The form's appearance can be fully customized with your own [CSS stylesheet](/account-setup/stylesheets).
</Note>

There are two ways to create a card entry form: **URL with query parameters** or **API session**. Both produce the same form. The difference is how you configure it and how you receive the result.

## Option 1: URL with Query Parameters

Build the form URL directly by appending configuration as query parameters. This is the simpler approach and requires no server-side API call to set up the form.

```
https://service.pcibooking.net/api/payments/capturecard?sessionToken=YOUR_SESSION_TOKEN&language=en&autoDetectCardType=true&success=https://yoursite.com/success&failure=https://yoursite.com/failure
```

Embed it in your page:

```html theme={null}
<iframe
  src="https://service.pcibooking.net/api/payments/capturecard?sessionToken=YOUR_SESSION_TOKEN&language=en&autoDetectCardType=true&success=https://yoursite.com/success&failure=https://yoursite.com/failure"
  width="400"
  height="350"
  frameborder="0">
</iframe>
```

When the cardholder submits the form, PCI Booking redirects to your `success` URL with the token appended. You can also specify a `failure` URL for declined or cancelled submissions.

See the [full parameter reference](/api-reference/tokenize-cards/request-card-entry-form) for all available query parameters.

## Option 2: API Session

Create a card entry form session via a server-side API call. Configuration is set in the request body rather than in the URL, so nothing is exposed to the client. Results are delivered via a server-to-server callback.

<Steps>
  <Step title="Set up a callback endpoint">
    Create an endpoint on your server to receive tokenization results from PCI Booking. This is a one-time setup. See the [callback reference](/api-reference/tokenize-cards/card-entry-form-callback) for the payload format.
  </Step>

  <Step title="Create a card entry form session">
    Send a POST request to [create the session](/api-reference/tokenize-cards/create-card-entry-form-session):

    ```bash theme={null}
    curl -X POST https://service.pcibooking.net/api/capturecard \
      -H "Authorization: APIKEY your-api-key" \
      -H "Content-Type: application/json" \
      -d '{
        "TTL": 120,
        "CallBackURL": "https://your-server.com/card-captured",
        "Properties": {
          "CardCaptureType": "Tokenize",
          "Language": "en",
          "ShowCVV": true,
          "AutoDetectCardType": true
        }
      }'
    ```

    The response returns a `RequestID` and a `Location` header containing the form URL.
  </Step>

  <Step title="Embed the form">
    Take the URL from the `Location` header and set it as the iframe source in your page:

    ```html theme={null}
    <iframe src="{{Location-header-URL}}" width="400" height="300" frameborder="0"></iframe>
    ```
  </Step>

  <Step title="Receive the callback">
    When the cardholder submits the form, PCI Booking sends a POST to your `CallBackURL` with the token details. You can also [poll the session status](/api-reference/tokenize-cards/retrieve-card-entry-session) using the request ID:

    ```bash theme={null}
    curl -X GET https://service.pcibooking.net/api/capturecard/{requestId} \
      -H "Authorization: APIKEY your-api-key"
    ```
  </Step>

  <Step title="Clean up (optional)">
    [Delete the session](/api-reference/tokenize-cards/delete-card-entry-form) if the cardholder abandons the form or you no longer need it.
  </Step>
</Steps>

## Which Should I Use?

|                      | URL with Query Parameters                                                             | API Session                                                                                                                                              |
| -------------------- | ------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Setup**            | No server-side call needed. Build the URL directly.                                   | Requires a server-side API call to create the session.                                                                                                   |
| **Configuration**    | Query parameters in the URL.                                                          | JSON body in the API request.                                                                                                                            |
| **Result delivery**  | Redirect to success/failure URLs.                                                     | Callback POST to your server, plus session polling.                                                                                                      |
| **Session tracking** | No built-in tracking.                                                                 | Request ID for status queries.                                                                                                                           |
| **TTL control**      | No configurable TTL.                                                                  | Set session expiry via `TTL` parameter.                                                                                                                  |
| **Security**         | Parameters are visible in the iframe URL and could be manipulated on the client side. | Parameters are set server-side. The generated short URL contains no configuration, so there is nothing for an attacker to manipulate via site injection. |

For quick integrations and prototyping, the URL approach is fastest. For production use, the API session provides better security, callback support, and session management.

## Key Features

Both approaches support:

* **CSS customization**. Style the form to match your brand by storing a stylesheet. See the [Stylesheets guide](/account-setup/stylesheets) for details.
* **3D Secure**. 3DS verification is supported during card capture. When enabled, a 3DS challenge is presented to the cardholder automatically if required by the issuing bank. The cardholder has 5 minutes to complete the challenge before it expires. See the [3DS Merchant Setup](/account-setup/3ds-merchant-setup) page to configure your merchant details for 3DS.
* **[Multi-language](/account-setup/custom-translations)**. Set the form language via the `Language` parameter (ISO 639-1 two-letter code).

<Warning>
  When embedding in an iframe, ensure your Content Security Policy allows framing from `service.pcibooking.net`.
</Warning>

## Next Steps

<CardGroup>
  <Card title="Card Validation Errors" icon="code" href="/reference/card-validation-errors">
    Error messages the cardholder may see when entering invalid card data.
  </Card>

  <Card title="Stylesheets Guide" icon="book" href="/account-setup/stylesheets">
    Customize the look and feel of your card entry form.
  </Card>

  <Card title="Capture Cards Overview" icon="book" href="/capture-cards/overview">
    All available tokenization methods.
  </Card>
</CardGroup>


# Capture Cards Overview
Source: https://developers.pcibooking.net/capture-cards/overview

All ways to tokenize cards with PCI Booking: hosted form, email/SMS link, JavaScript library, file upload, API migration, and response interception

Tokenization is how card data enters PCI Booking. The method you use depends on where the card data comes from.

## Collecting Cards from the Cardholder

Use these methods when the cardholder enters their own card details. All three support 3D Secure natively in the UI with no additional development on your side.

| Method                                                       | How It Works                                                                                                                                                                                                                                                      |
| ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **[Card Entry Form](/capture-cards/hosted-card-entry-form)** | PCI Booking hosts a secure form that you embed via iframe or redirect. The cardholder enters their card and PCI Booking tokenizes it on submission. The simplest integration for web-based card capture.                                                          |
| **[Card By Link](/capture-cards/card-by-link)**              | Send a secure link to the cardholder via email or SMS. The cardholder clicks the link, enters their card on a hosted page, and PCI Booking tokenizes it. Ideal for call centers, remote collection, and any scenario where the cardholder is not on your website. |
| **[Payments Library](/capture-cards/payments-library)**      | Client-side JavaScript library (`@pcibooking/ewallet`) that renders a card form in your checkout page. Also supports alternative payment methods (Apple Pay, Google Pay, PayPal). The richest feature set for web and mobile checkout flows.                      |

## Receiving Cards from a Third Party via HTTP

Use these methods when card data flows through HTTP requests or responses between your system and a third party.

| Method                                                                          | How It Works                                                                                                                                                                                                                                                                                                                                                                       |
| ------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **[Tokenization on Response](/capture-cards/tokenization-on-response)**         | Route your outbound HTTP requests through PCI Booking as a proxy. When the third party responds with card data, PCI Booking parses the response using a profile you define (or a [universal profile](/capture-cards/universal-tokenization) for common third parties), tokenizes all card details, and forwards a sanitized response to you. Card data never reaches your systems. |
| **[Tokenization on Request (Gateway)](/capture-cards/tokenization-on-request)** | The reverse direction. When a third party sends card data to your API, PCI Booking sits as a gateway in front of your endpoint, tokenizes the card details in the inbound request, and forwards a sanitized version to you.                                                                                                                                                        |

## Receiving Cards from a Third Party via File

| Method                                                                     | How It Works                                                                                                                                                                                                                                                                    |
| -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **[File Transfer (SFTP/FTPS)](/capture-cards/file-transfer-tokenization)** | PCI Booking acts as a secure file transfer proxy. You call the API with the third party's SFTP or FTPS server details, and PCI Booking downloads the file, tokenizes all card numbers it finds, and returns the tokenized content to you. Card data never touches your systems. |

## Direct API (Card Migration)

| Method                                                    | How It Works                                                                                                                                                                                                                                                                                                                  |
| --------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **[Store Card API](/capture-cards/store-card-migration)** | POST card data directly to the PCI Booking API. Use this for migrating cards from another vault, provider, or internal storage. If your systems handle raw card data during the migration, you may be in PCI DSS scope for that period. Make sure to clear all card records from your systems once the migration is complete. |

## What Happens When a Card Is Tokenized

Regardless of the method, the outcome is the same:

1. Card data is captured through one of the methods above.
2. PCI Booking encrypts and stores the card in our PCI DSS Level 1 vault.
3. A token is returned to your system.
4. You use the token for all subsequent operations: manage, query, or detokenize.

## Next Steps

<CardGroup>
  <Card title="Manage Tokens" icon="sliders" href="/manage-tokens/overview">
    Query, update, and manage your stored tokens
  </Card>

  <Card title="Use Tokens" icon="arrow-right-arrow-left" href="/use-tokens/overview">
    Send card data to PSPs, partners, or display it
  </Card>
</CardGroup>


# Payments Library
Source: https://developers.pcibooking.net/capture-cards/payments-library

Render secure card forms and payment buttons with PCI Booking's client-side JavaScript library. Apple Pay, Google Pay, 3D Secure.

The Payments Library (`@pcibooking/ewallet`) is a client-side JavaScript library that renders a card form and payment buttons in your checkout page. The cardholder enters their card details or selects a digital wallet, and the library tokenizes the card through PCI Booking. Card data never touches your servers.

## How It Works

1. Your server creates a [payment session](/api-reference/payments-library/create-session) with PCI Booking, specifying the operation type (e.g. `TOKENIZE`).
2. Your page initializes the library with the session token.
3. The library renders the card form and available payment buttons.
4. The cardholder enters their card or selects a payment method.
5. The library sends the card data directly to PCI Booking, which tokenizes it and returns a token to the library.
6. Your page receives the token via callback and sends it to your server.

```javascript theme={null}
const engine = new eWallet.Engine(sessionToken);
const methods = await engine.checkAvailability();

engine.payBy(methods, function(result) {
  if (!result) return;

  const [data, success] = engine.parseResultToken(result.token);
  if (data.clientSuccess && success) {
    // Send result.token to your server
  }
}, {
  containerSelector: '#payment-buttons'
});
```

## Tokenization-Capable Methods

The following payment methods support tokenization through the library:

| Method         | What Happens                                                                                                      |
| -------------- | ----------------------------------------------------------------------------------------------------------------- |
| **CardPay**    | Cardholder enters card details in a form rendered by the library. Card is tokenized and stored in PCI Booking.    |
| **Apple Pay**  | Cardholder authorizes via Face ID / Touch ID. The Apple Pay token is tokenized and stored in PCI Booking.         |
| **Google Pay** | Cardholder selects a card from their Google account. The Google Pay token is tokenized and stored in PCI Booking. |

Other methods (PayPal, BankPay, UPI) process charges directly without tokenization. See [Supported Payment Methods](/payments-library/supported-methods) for the full list.

## 3D Secure

3DS is handled automatically based on the payment method:

* **CardPay**. When enabled, a 3DS challenge is presented to the cardholder if required by the issuing bank. The cardholder has 5 minutes to complete the challenge. If the challenge times out, the payment is cancelled and the callback receives `undefined`. See [3DS Merchant Setup](/account-setup/3ds-merchant-setup) to configure your merchant details for the challenge screen.
* **Apple Pay and Google Pay**. 3DS authentication is handled natively by the wallet provider. No additional configuration needed.
* **PayPal, BankPay, UPI**. 3DS does not apply. Each provider handles authentication through its own flow.

For tokenization operations (`TOKENIZE`, `CHARGE_AND_TOKENIZE`, `PREAUTH_AND_TOKENIZE`), the result token includes 3DS authentication data that can be stored with the token for subsequent transactions. See [3DS Auth Management](/manage-tokens/3ds-auth-management) for details.

## Next Steps

<CardGroup>
  <Card title="Payments Library Setup" icon="book" href="/payments-library/setup">
    Installation, configuration, and code examples.
  </Card>

  <Card title="Supported Payment Methods" icon="book" href="/payments-library/supported-methods">
    All payment methods with availability and supported operations.
  </Card>

  <Card title="Library Reference" icon="code" href="/payments-library/reference">
    Full API surface and configuration options.
  </Card>

  <Card title="Capture Cards Overview" icon="book" href="/capture-cards/overview">
    All available tokenization methods.
  </Card>
</CardGroup>


# PostMessage Notifications
Source: https://developers.pcibooking.net/capture-cards/postmessage-notifications

Control and receive events from the PCI Booking card entry iframe using postMessage. Form submission, validation, resizing.

The postMessage mechanism enables secure cross-domain communication between your page and the embedded PCI Booking iframe. It works with the [Card Entry Form](/capture-cards/hosted-card-entry-form), Card Display, and CVV capture forms.

Use postMessage to:

* Know when the iframe is ready.
* Validate the form programmatically from your page.
* Submit the form programmatically.
* Receive tokenization results without a page redirect.
* Resize the iframe dynamically based on form content.
* Intercept card details before tokenization for custom approval logic.

## Setup

Add the `postMessageHost` parameter to your iframe URL. Set it to your page's origin (URL-encoded):

```
https://service.pcibooking.net/api/payments/capturecard?sessionToken=YOUR_TOKEN&postMessageHost=https%3A%2F%2Fwww.yoursite.com
```

On your page, listen for messages from the iframe:

```javascript theme={null}
window.addEventListener('message', function(event) {
  if (event.origin !== 'https://service.pcibooking.net') return;
  console.log('Received:', event.data);
});
```

## Events from the Iframe

| Event                                     | Format      | Description                                                                        |
| ----------------------------------------- | ----------- | ---------------------------------------------------------------------------------- |
| `ready`                                   | String      | Iframe loaded and ready for input.                                                 |
| `valid`                                   | String      | Form passed validation.                                                            |
| `invalid`                                 | String      | Form has validation errors.                                                        |
| `frameDimensionsChanged:{width}:{height}` | String      | Iframe dimensions changed. Use this to resize the iframe element on your page.     |
| `CardSubmitSuccess`                       | JSON object | Card tokenized successfully. Contains card info (masked number, type, expiration). |
| `CardSubmitFailure`                       | JSON object | Tokenization failed. Contains error reason.                                        |
| `ThreeDsChallengeLoaded`                  | String      | 3DS challenge iframe loaded.                                                       |
| `OTPdisplayed`                            | JSON object | OTP entry form displayed (for 3DS or form charge).                                 |
| `OTPsubmitted`                            | JSON object | OTP submitted by the user.                                                         |

Field-level validation events are also sent as JSON objects with `{field, validationResult}` for each field as the user interacts with the form.

## Commands to the Iframe

Your page can send commands to the iframe:

| Command    | Format | Description                                                             |
| ---------- | ------ | ----------------------------------------------------------------------- |
| `validate` | String | Trigger form validation. The iframe responds with `valid` or `invalid`. |
| `submit`   | String | Submit the form programmatically.                                       |

```javascript theme={null}
var iframe = document.getElementById('card-form').contentWindow;
iframe.postMessage('validate', 'https://service.pcibooking.net/');
```

## Receiving Results via PostMessage

To receive tokenization results via postMessage instead of a redirect, add `submitWithPostMessage=true` to your iframe URL. On success, the iframe sends a `CardSubmitSuccess` message containing the token details. On failure, it sends `CardSubmitFailure` with the error.

## Dynamic Iframe Resizing

When the form content changes (e.g. validation errors appear), the iframe sends `frameDimensionsChanged:{width}:{height}`. Use this to resize the iframe:

```javascript theme={null}
window.addEventListener('message', function(event) {
  if (event.origin !== 'https://service.pcibooking.net') return;

  if (typeof event.data === 'string' && event.data.startsWith('frameDimensionsChanged')) {
    var parts = event.data.split(':');
    var iframe = document.getElementById('card-form');
    iframe.style.width = parts[1] + 'px';
    iframe.style.height = parts[2] + 'px';
  }
});
```

## Custom Validation

Custom validation lets your page inspect card details before tokenization and approve or reject the submission. Enable it by adding `useCustomValidation=true` to the iframe URL.

When the cardholder submits the form, the iframe pauses tokenization and sends a `CustomValidation` message with masked card details:

```javascript theme={null}
{
  "messageType": "CustomValidation",
  "cardType": "Visa",
  "lastDigits": "0068",
  "leadingDigits": "41111111",
  "expirationYear": "2029",
  "expirationMonth": "4",
  "ownerName": "John Doe",
  "cardDigitCount": 16,
  "cvvDigitCount": 3
}
```

Your page has **3 seconds** to respond. If no response is received, tokenization proceeds automatically.

### Approving

```javascript theme={null}
iframe.postMessage({
  action: 'customValidationResponse',
  success: true
}, 'https://service.pcibooking.net/');
```

### Rejecting

```javascript theme={null}
iframe.postMessage({
  action: 'customValidationResponse',
  success: false,
  message: 'AMEX cards are not accepted'
}, 'https://service.pcibooking.net/');
```

When rejected, the form displays the message as a validation error and the cardholder can correct their input or try a different card.

### Use Cases

* Restrict accepted card types or BIN ranges before tokenization.
* Check card details against your business rules (e.g. reject corporate cards, enforce expiry minimums).
* Log or audit card submissions before they are tokenized.

## Next Steps

<CardGroup>
  <Card title="Hosted Card Entry Form" icon="book" href="/capture-cards/hosted-card-entry-form">
    Set up the card entry form iframe.
  </Card>

  <Card title="Capture Cards Overview" icon="book" href="/capture-cards/overview">
    All tokenization methods.
  </Card>

  <Card title="Stylesheets" icon="palette" href="/account-setup/stylesheets">
    Customize the look of your card entry form.
  </Card>

  <Card title="Card Entry Form Callback" icon="code" href="/api-reference/tokenize-cards/card-entry-form-callback">
    API reference for form callback notifications.
  </Card>
</CardGroup>


# Store a Card (Direct API)
Source: https://developers.pcibooking.net/capture-cards/store-card-migration

Migrate existing card data to PCI Booking tokens using the Store Paycard API. For PCI DSS-compliant environments.

The [Store Paycard](/api-reference/tokenize-cards/store-paycard) endpoint lets you send raw card data directly to PCI Booking via API. PCI Booking stores the card securely and returns a token.

<Warning>
  Using this method means your system handles raw card details, which puts you in scope of PCI DSS compliance. We strongly recommend using this method only for:

  * **Card migration**. Moving cards from another storage system or third-party vault to PCI Booking.
  * **Temporary workaround**. Handling service interruptions where other tokenization methods are temporarily unavailable.

  For all other scenarios, use [Card Entry Form](/capture-cards/hosted-card-entry-form), [Card By Link](/capture-cards/card-by-link), or [Payments Library](/payments-library/setup). These methods keep card data off your servers entirely.
</Warning>

## Prerequisites

<Warning>
  Your system must be PCI DSS compliant to use this method, because it requires handling raw card numbers. If you are not PCI DSS compliant, use one of the other tokenization methods listed above.
</Warning>

Before starting a migration, ensure you have:

* A valid PCI Booking API key (sandbox for testing, production for the actual migration)
* PCI DSS compliance certification for the system sending card data
* A clear inventory of the cards to migrate, including which fields are available (card number, expiry, CVV, cardholder name)

## How It Works

Send card details directly to the [Store Paycard API](/api-reference/tokenize-cards/store-paycard). PCI Booking stores the card securely and returns a token in the `Location` response header.

```bash theme={null}
curl -X POST https://service.pcibooking.net/api/payments/paycard \
  -H "Authorization: APIKEY your-api-key" \
  -H "Content-Type: application/xml" \
  -d '<CardData>
    <CardNumber>4111111111111111</CardNumber>
    <ExpirationDate>12/2028</ExpirationDate>
    <CVV>123</CVV>
    <HolderName>John Doe</HolderName>
  </CardData>'
```

The response returns the token URI in the `Location` header. See the [API reference](/api-reference/tokenize-cards/store-paycard) for the full list of fields and query parameters.

## Validation Options

PCI Booking can validate the card data during storage:

* **Luhn check** verifies the card number is structurally valid
* **BIN lookup** identifies the card brand, issuing bank, and card type (credit, debit, prepaid)
* **Expiry validation** rejects cards that have already expired

These validations help catch data quality issues early in the migration rather than discovering them when you attempt to charge the card later.

## Migration Best Practices

* **Test in sandbox first.** Run your full migration script against the sandbox environment with test card numbers to validate the integration and error handling.
* **Migrate in batches.** If migrating a large volume of cards, break them into manageable batches and track progress. This makes it easier to resume if something goes wrong.
* **Map old references to new tokens.** Maintain a mapping table between your existing card references and the new PCI Booking tokens so you can update all dependent systems.
* **Delete source data.** Once migration is complete and validated, permanently delete all raw card records from your source systems to eliminate PCI DSS scope.
* **Vault-to-vault transfers.** If migrating from a third-party vault, check whether a direct vault-to-vault transfer is possible. Contact [support@pcibooking.net](mailto:support@pcibooking.net) for guidance.

## Next Steps

<CardGroup>
  <Card title="Token Management" icon="book" href="/manage-tokens/overview">
    Manage your migrated tokens.
  </Card>

  <Card title="Capture Cards Overview" icon="book" href="/capture-cards/overview">
    All available tokenization methods.
  </Card>
</CardGroup>


# Tokenization on Request (Gateway)
Source: https://developers.pcibooking.net/capture-cards/tokenization-on-request

Intercept inbound HTTP requests containing card data. PCI Booking tokenizes card numbers and forwards sanitized requests.

Tokenization on Request lets you intercept inbound HTTP requests from third parties before they reach your systems. PCI Booking sits as a gateway in front of your API. When a third party sends a request containing card data, PCI Booking tokenizes the card details and forwards a sanitized version to you. You never see raw card numbers.

This is the reverse of [Tokenization on Response](/capture-cards/tokenization-on-response), where you send a request to a third party and tokenize the response. Here, the third party sends a request to you, and PCI Booking tokenizes the request.

This is also the mirror of [Token Replacement in Response](/use-tokens/token-replacement-in-response) in the Use Tokens section. Both use the same gateway infrastructure, but in opposite directions: Tokenization on Request tokenizes card data in the third party's inbound request, while Token Replacement in Response detokenizes tokens in your outbound response.

## How It Works

1. **PCI Booking sets up a gateway endpoint**. The gateway is configured with your SSL certificate and a custom site name. Third parties send their requests to this gateway URL instead of directly to your API.
2. **Third party sends a request**. The request arrives at the PCI Booking gateway.
3. **Message filtering**. The gateway checks the request against pre-configured message filters (based on URL path or specific headers) to determine if the message should be processed.
4. **Card extraction and tokenization**. If the message matches a filter, PCI Booking parses the message body using [content filters](/account-setup/content-filters) that define where card data is located. All matching cards are tokenized.
5. **Sanitized relay**. PCI Booking masks the card details in the message body, adds the token URIs to a request header (typically `x-Token`), and forwards the amended request to your API.
6. **Response relay**. Your API's response is relayed back to the original sender.

<Info>
  While the flow above refers to one card, PCI Booking can tokenize all cards in the request, as many as are present, as long as the content filter identifies their locations.
</Info>

## What PCI Booking Adds to the Request

Before forwarding the request to your API, PCI Booking adds several headers:

* **Token header** (typically `x-Token`). Contains the token URI(s) for the card(s) found in the request.
* **`X-Forwarded-For`**. The original sender's IP address.
* **Error/warning headers**. If tokenization fails or encounters issues, diagnostic information is added.

## Target Profiles

The gateway uses a [target profile](/account-setup/target-profiles) to know where card data appears in the inbound request and how to tokenize it. Each profile includes [content filters](/account-setup/content-filters) that define the location of card fields in the message. The PCI Booking support team configures this as part of the gateway setup.

## Setting Up a Gateway Endpoint

Gateway setup is done by the PCI Booking support team. To set up a new gateway endpoint, contact [support@pcibooking.net](mailto:support@pcibooking.net) with the following details:

* Your PCI Booking username.
* The target URI where processed messages should be relayed to (your API endpoint).
* How to identify requests that contain card data. This can be based on URL path or a specific request header.
* A sample of the message structure (XML or JSON) that should be processed.
* How to handle duplicate cards:
  * **Eliminate duplicates (true)**. If a card already exists as a token, the existing token is returned.
  * **No deduplication (false)**. Every card processed gets a new token, regardless of whether it already exists.

## Use Cases

* Receiving reservation or booking requests from OTAs or channel managers that include card details.
* Any scenario where a third party pushes card data to your API and you want to keep card data off your servers.

## Next Steps

<CardGroup>
  <Card title="Tokenization on Response" icon="book" href="/capture-cards/tokenization-on-response">
    The reverse direction. Tokenize card data in responses from third parties.
  </Card>

  <Card title="Capture Cards Overview" icon="book" href="/capture-cards/overview">
    All available tokenization methods.
  </Card>
</CardGroup>


# Tokenization on Response
Source: https://developers.pcibooking.net/capture-cards/tokenization-on-response

Route outbound HTTP requests through PCI Booking to extract and tokenize card data from third-party responses.

Tokenization on Response lets you route HTTP requests through PCI Booking to a third party. When the third party responds with card data, PCI Booking parses the response, extracts and tokenizes the card details, and forwards a sanitized version back to you. You never see raw card numbers.

This is the mirror of [Token Replacement in Request](/use-tokens/token-replacement-in-request) in the Use Tokens section. Both use the same forward proxy infrastructure, but in opposite directions: Tokenization on Response tokenizes card data in the third party's response, while Token Replacement in Request detokenizes tokens in your outbound request.

## How It Works

1. **Create a profile**. A profile is a set of instructions that tells PCI Booking how to parse the third party's response and where to find card details in the message. You create profiles through the [PCI Booking portal](/account-setup/target-profiles) or with the help of our support team. You do this once per third-party message format.
2. **Send your request through PCI Booking**. Instead of calling the third party directly, send the request through PCI Booking's [proxy endpoint](/api-reference/tokenize-cards/tokenization-in-response). In the request, provide the profile name and the third party's connection details.
3. **PCI Booking forwards the request**. PCI Booking sends the request to the third party on your behalf and receives the response.
4. **Parse and tokenize**. PCI Booking's content engine parses the response using your profile, extracts all card details that match the defined locations, and creates a token for each card found.
5. **Sanitized response**. PCI Booking masks the card details in the response body, adds the tokens to a custom header, and forwards the amended message back to you.

## Profiles

A [target profile](/account-setup/target-profiles) defines how PCI Booking should parse a specific message format. Each profile includes [content filters](/account-setup/content-filters) with XPath or JSONPath expressions pointing to where card data appears in the message. Profiles are reusable - define one once and apply it to every request going to that third party.

<Info title="Need help creating a profile?">
  Send a copy of the message you receive from the third party to [support@pcibooking.net](mailto:support@pcibooking.net). Our support team will build the profile for you.
</Info>

## Universal Profiles (Pre-Built)

Many PCI Booking customers connect to the same third parties (booking platforms, OTAs, channel managers, GDS providers). For these common integrations, PCI Booking provides [universal profiles](/capture-cards/universal-tokenization) that are already built and ready to use. The flow is the same. You reference the universal profile name in your request instead of a custom one.

Check with [support@pcibooking.net](mailto:support@pcibooking.net) to see if a universal profile already exists for your third party.

## Security

* **Relay restrictions**. Your account can be configured with an endpoint whitelist. Requests to destinations not on the list are rejected. Contact support or use the Admin portal to manage your allowed endpoints.
* **Client certificates**. Target profiles can include [client certificates](/account-setup/client-certificates) for mutual TLS authentication with the destination.
* **Timeout**. Relay requests have a default timeout of 60 seconds.

## Use Cases

* Receiving reservation data from booking platforms that include card details.
* Integrating with OTAs or channel managers that pass card data in API responses.
* Any scenario where a third party sends you card data that you need to store as tokens.

## Next Steps

<CardGroup>
  <Card title="Universal Tokenization Profiles" icon="book" href="/capture-cards/universal-tokenization">
    Pre-built profiles for common third parties.
  </Card>

  <Card title="Capture Cards Overview" icon="book" href="/capture-cards/overview">
    All available tokenization methods.
  </Card>
</CardGroup>


# Universal Tokenization Profiles
Source: https://developers.pcibooking.net/capture-cards/universal-tokenization

Use pre-built parsing profiles for common integrations. Tokenize responses without custom configuration.

Universal Tokenization profiles are pre-built parsing profiles that PCI Booking maintains for commonly used third parties. Instead of creating your own profile, you reference one that is already configured and tested.

## What Is a Universal Profile?

A universal profile is a pre-configured parsing template that tells PCI Booking exactly where card data appears in a third party's API response. It defines the response format (JSON, XML, or other), the field paths that contain card numbers, expiration dates, CVV, and cardholder names, and how to replace them with tokens.

Universal profiles are maintained and tested by PCI Booking, so you do not need to create or manage the parsing logic yourself.

## How It Works

The flow is the same as [Tokenization on Response](/capture-cards/tokenization-on-response). The only difference is that you reference a universal profile name instead of a custom one when calling the [proxy endpoint](/api-reference/tokenize-cards/tokenize-on-response-using-preset-profiles).

1. Send your request through PCI Booking's proxy endpoint, specifying the universal profile name and the third party's connection details.
2. PCI Booking forwards the request to the third party.
3. PCI Booking parses the response using the universal profile, tokenizes all card data, and returns the sanitized response to you.

Your system receives the full response from the third party, but with all card data replaced by PCI Booking tokens. The response structure remains identical, so your existing parsing logic continues to work without changes.

## When to Use Universal Profiles vs. Custom Profiles

<Tabs>
  <Tab title="Universal Profiles">
    * Your third party is already supported by a pre-built profile
    * You want zero configuration on your side
    * You prefer PCI Booking to maintain and update the parsing rules when the third party changes their API
  </Tab>

  <Tab title="Custom Profiles">
    * Your third party is not covered by a universal profile
    * You need to parse a proprietary or uncommon response format
    * You want full control over which fields are tokenized
  </Tab>
</Tabs>

## Common Use Cases

Universal profiles are widely used in the travel and hospitality industry:

* **OTA integrations** where booking platforms receive virtual card details from online travel agencies
* **Channel managers** that aggregate reservation data (including payment cards) from multiple booking channels
* **GDS systems** that relay card data as part of reservation records
* **Property management systems** receiving cards from central reservation systems

## Available Profiles

You can retrieve the current list of universal profiles programmatically using the [Get Tokenization Profiles API](/api-reference/tokenize-cards/get-tokenization-profiles). Each profile includes the third party name, the response format it parses (JSON, XML, SOAP, etc.), and the specific fields it tokenizes.

Profiles are versioned. When a third party updates their API response format, PCI Booking updates the universal profile accordingly. Your integration does not need to change since the profile name stays the same and the updated parsing logic is applied automatically.

## Why Universal Profiles Exist

Many PCI Booking customers connect to the same third parties and receive the same message formats. Rather than having each customer build their own profile, PCI Booking maintains universal profiles for these common integrations. This reduces integration effort, ensures consistent tokenization across all customers using the same third party, and allows PCI Booking to react quickly when a third party changes their response format.

<Info>
  If you don't see a universal profile for your third party, contact [support@pcibooking.net](mailto:support@pcibooking.net). If multiple customers use the same third party, we may create a universal profile for it.
</Info>

## Related

* [Tokenization on Response](/capture-cards/tokenization-on-response) - Full guide including custom profile creation
* [Get Tokenization Profiles API](/api-reference/tokenize-cards/get-tokenization-profiles) - Retrieve available universal profiles programmatically

## Next Steps

<CardGroup>
  <Card title="Tokenization on Response" icon="book" href="/capture-cards/tokenization-on-response">
    Full guide including custom profile creation.
  </Card>

  <Card title="Capture Cards Overview" icon="book" href="/capture-cards/overview">
    All available tokenization methods.
  </Card>
</CardGroup>


# How PCI Booking Works
Source: https://developers.pcibooking.net/concepts/how-pci-booking-works

How PCI Booking removes PCI DSS scope from your systems. Card capture, token storage, and payment processing without handling card data.

## The Problem

Handling payment card data requires PCI DSS compliance, a costly, ongoing burden of audits, encryption infrastructure, network segmentation, and liability. Every system that touches card data is in scope. Even if you only pass card details from one entity to another without storing them, even for a split second, your systems are in PCI DSS scope.

## The Solution

PCI Booking handles **all** card data on your behalf. Your systems only work with tokens. These are random identifiers that carry no card information. This removes your systems from PCI DSS scope entirely.

PCI Booking is a PCI DSS Level 1 certified service provider. All card data is encrypted at rest and in transit, stored in isolated infrastructure, and protected by hardware security modules (HSMs) for key management.

## Architecture: The Three Pillars

Cards flow through three stages:

**Capture > Manage > Use**

### 1. Capture (Tokenize)

Card data enters PCI Booking through one of several methods, depending on your integration:

* **Hosted Card Entry Form** for web and mobile checkout
* **Card By Link (COTP)** for email and SMS-based capture
* **Payments Library** for client-side JavaScript integration
* **Tokenization on Response** for capturing cards from third-party API responses
* **Store Paycard API** for bulk migration from existing vaults

In every case, PCI Booking encrypts the card data and returns a token to your system. The token is a random URI that uniquely identifies the stored card but reveals nothing about it.

### 2. Manage (Store and Maintain)

Once tokenized, you store and reference tokens in your own systems freely. Tokens are safe to log, pass through APIs, and persist in databases. PCI Booking provides management capabilities including:

* Querying token metadata (masked card number, expiry, card brand)
* Updating expiration dates when cards are renewed
* Managing CVV retention policies
* Duplicating tokens across merchants or customer accounts
* Deleting tokens when they are no longer needed

### 3. Use (Detokenize)

When real card data is needed, PCI Booking substitutes the token with the actual card details and delivers them to the destination:

* **Universal Payment Gateway (UPG)** sends card data directly to a PSP to process a charge, refund, or authorization
* **Token Replacement in Request** injects card data into an outbound HTTP request to any third party
* **Card Display** renders the real card number in a secure iframe for authorized users

Your systems never see the real card data during detokenization. PCI Booking handles the substitution and delivery in its own secure environment.

## Who Handles What

| PCI Booking Handles       | You Handle                 |
| ------------------------- | -------------------------- |
| Card capture & encryption | Token storage & references |
| PCI DSS compliance        | Business logic             |
| Secure card storage       | UI integration             |
| PSP communication         | Transaction orchestration  |
| Key management & rotation | Merchant configuration     |

## PCI DSS Scope Reduction

Without PCI Booking, every server, database, and network segment that processes card data must be PCI-compliant. With PCI Booking, card data never enters your environment, significantly reducing your audit scope, cost, and risk.

<Info>
  PCI Booking supports SAQ A and SAQ A-EP compliance levels for merchants, depending on the integration method chosen. The hosted form and Card By Link methods provide the lowest compliance burden.
</Info>

[Talk to our PCI experts](https://pcibooking.net/talk-to-pci-experts/) to understand what PCI compliance requirements apply to your specific setup after integrating with PCI Booking.

## Security and Compliance

<Note>
  PCI Booking is a **PCI DSS Level 1** certified service provider (v4 compliant since December 2023). All card data is encrypted at rest and in transit, with key management handled by hardware security modules (HSMs). Personal data is stored on EU-located cloud infrastructure.

  * [PCI DSS compliance](https://pcibooking.net/pci-compliance/)
  * [ISO 27001:2022 certification](https://pcibooking.net/27001-certified)
  * [GDPR compliance and data residency](https://pcibooking.net/gdpr)
  * [PSD2 compliance](https://pcibooking.net/psd2)
  * [Security settings for your account](/account-setup/security-settings)
</Note>

## Related

* [Quickstart](/start-here/quickstart) - Get up and running with your first integration
* [Authentication](/getting-started/authentication) - Set up API keys and access tokens
* [Tokenization Explained](/concepts/tokenization-explained) - Deep dive into how tokenization works
* [How Do I...?](/use-cases/how-do-i) - Common integration scenarios and workflows


# Tokenization Explained
Source: https://developers.pcibooking.net/concepts/tokenization-explained

What is payment card tokenization? How tokens replace sensitive card data, how detokenization works, and the full token lifecycle.

## What Is Tokenization?

Tokenization replaces sensitive card data with a non-sensitive substitute: a **token**. The token has no mathematical relationship to the original card number and cannot be reversed without access to PCI Booking's secure vault.

When you tokenize a card through PCI Booking, the real card data is encrypted and stored in our PCI DSS Level 1 certified environment. You receive a token that you can safely store, log, and send through any system without PCI compliance concerns. For a step-by-step walkthrough of how tokenization fits into a real integration, see [How PCI Booking Works](/concepts/how-pci-booking-works).

## Why Tokenization Matters for PCI DSS

Any system that stores, processes, or transmits cardholder data falls under PCI DSS scope. This means audits, penetration testing, encryption requirements, access controls, and ongoing monitoring. Tokenization eliminates this burden by ensuring your systems never handle real card data. Instead, you work exclusively with tokens that have no value if intercepted or leaked.

## Tokenization vs. Encryption

Encryption transforms card data into ciphertext that can be reversed with the correct key. The encrypted data still represents the original card and must be protected under PCI DSS. Tokenization, by contrast, replaces card data with a completely unrelated value. There is no key that converts a token back to a card number. Detokenization can only happen inside PCI Booking's secure vault.

## How Tokens Work

A PCI Booking token:

* Uniquely identifies a stored card
* Can be used in any API call that requires a card reference
* Is safe to store in your database, pass through APIs, or log
* Cannot be used to reconstruct the original card number
* Can only be accessed by the customer that created it
* Takes the form of a URI (e.g., `/cards/abc123`) that you reference in subsequent API calls

## Detokenization: The Other Side

**Detokenization** is the reverse process. It replaces a token with real card data to send it to a destination. This is how card data flows OUT of PCI Booking.

Every operation that requires real card data is detokenization:

* **Processing a payment**. PCI Booking replaces the token with card data and sends it to a PSP via UPG.
* **Relaying card data**. Token replacement injects card data into HTTP requests or batch files.
* **Displaying a card**. Secure iframe renders the real card number to an authorized user.

<Info title="Key Concept">
  Tokenization gets cards IN. Detokenization gets cards OUT. Together, they form the complete lifecycle of card data in PCI Booking.
</Info>

## Token Lifecycle

1. **Created.** Card is captured and tokenized through any [supported capture method](/capture-cards/overview) (hosted form, Card By Link, API, or response parsing).
2. **Active.** Token is available for queries, updates, and detokenization. You can check metadata, update the expiration date, [manage CVV retention](/manage-tokens/cvv-management), or [duplicate the token](/api-reference/manage-tokens/duplicate-token). See [Manage Tokens](/manage-tokens/overview) for all available operations.
3. **Expired.** Card expiry has passed. The token still exists and can be queried, but the card may no longer be accepted for charges by the payment processor.
4. **Deleted.** Token and all associated card data, CVV, and 3DS data are permanently and irrecoverably removed from the vault.

## Get Started

* [Quickstart](/start-here/quickstart). Build your first tokenization integration in minutes.
* [Capture Cards](/capture-cards/overview). All available methods for capturing and tokenizing card data.
* [Use Tokens](/use-tokens/overview). Process payments, replace tokens in requests, and more.
* [Collect and Process a Payment](/use-cases/capture-and-charge). End-to-end example of capturing a card and charging it.

## Learn More

* [How Does Credit Card Tokenization Work?](https://pcibooking.net/how-does-credit-card-tokenization-work/)
* [Tokenization Vs. Encryption: What You Need to Know](https://pcibooking.net/tokenization-vs-encryption/)
* [PCI and Tokenization: How to Handle Data the Safe, Compliant Way](https://pcibooking.net/how-tokenization-works-for-pci-compliance/)


# Authentication
Source: https://developers.pcibooking.net/getting-started/authentication

PCI Booking API authentication methods: API key, access token, and temporary session token with code samples

PCI Booking supports three authentication methods. Each builds on the API key and serves a different purpose.

## API Key

Your API key is the foundation of all authentication. It grants unlimited, repeatable access and is used for most API calls. Pass it using either header format:

```bash theme={null}
# Option 1: Authorization header (most common)
Authorization: APIKEY your-api-key

# Option 2: Custom header
x-pcibooking-api-key: your-api-key
```

Both are equivalent. Use the API key for all server-to-server calls: processing payments, managing tokens, configuring credentials, querying data, and more.

<Warning>
  Keep your API key secret. Never expose it in client-side code, public repositories, or logs. If a request originates from a browser or any client-facing context, use a Session Token or Access Token instead.
</Warning>

## Session Token

A Session Token is generated from your API key via an API call. It is valid for **5 minutes** and can be used for **any API call** during that time.

Generate a session token:

```bash theme={null}
curl -X POST https://service.pcibooking.net/api/payments/paycard/tempsession \
  -H "Authorization: APIKEY your-api-key"
```

Response:

```text theme={null}
33b245a015cf4d10a3ca885e7f4c5600
```

Use it as a query parameter on subsequent requests:

```text theme={null}
<base_url>?sessionToken=YOUR_SESSION_TOKEN
```

Session tokens are commonly used for browser-facing operations like the hosted card entry form, card display, and sFTP tokenization.

## Access Token

An Access Token is generated **locally** using your API key and PCI Booking's SSL certificate. Unlike the session token, no API call is needed to create it. It is valid for a **configurable duration (1 to 60 minutes)** and is **single-use only**.

### How it works

1. [Download PCI Booking's SSL certificate](/getting-started/download-ssl-certificate) from `https://service.pcibooking.net/api`
2. Run the generation script locally (see code samples below)
3. The script encrypts your API key + a unique ID + expiration time using the certificate's public key
4. The output is your access token

Pass it as a query parameter:

```text theme={null}
<base_url>?accessToken=YOUR_ACCESS_TOKEN
```

### Code Samples

<Tabs>
  <Tab title="C#">
    ```csharp theme={null}
    using System;

    namespace CreateAccessToken
    {
        class Program
        {
            private static string[] helpLines = 
            { 
                "Usage: CreateAccessToken.exe <Certificate file path> <API Key> <Absolute time>",
                "Certificate file path: .cer as downloaded from https://service.pcibooking.net/api",
                "API Key: As generated in your PCI Booking account",
                "Absolute time: local time in format HH:MM:ss (up to 1 hour from now), e.g: 18:20:34"
            };

            static void Main(string[] args)
            {
                if (args.Length != 3)
                    Usage("Invalid number of arguments; expected 3");

                // read certificate
                System.Security.Cryptography.X509Certificates.X509Certificate2 cert = null;
                try
                {
                    cert = new System.Security.Cryptography.X509Certificates.X509Certificate2(args[0]);
                }
                catch (Exception ex)
                {
                    Usage("Cannot load certificate file: " + args[0] + " Error: " + ex.Message);
                }

                // read time and convert to absolute date time in UTC
                DateTime expectedExpirationLocalTime;
                if (!DateTime.TryParse(args[2], out expectedExpirationLocalTime))
                {
                    Usage("Invalid expected time: " + args[2]);
                }
                TimeSpan expiresIn = expectedExpirationLocalTime.Subtract(DateTime.Now);
                if (expiresIn > TimeSpan.FromHours(1) || expiresIn < TimeSpan.Zero)
                {
                    Usage(string.Format("Invalid expected time [{0}]. Should be up to one hour ahead ", args[2]));
                }
                DateTime expectedExpirationUTC = expectedExpirationLocalTime.ToUniversalTime();

                // Generate a guid
                string guid = Guid.NewGuid().ToString().Replace("-", "");

                // Construct data block: APIKey#GUID#ExpirationUTC
                string dataBlock = string.Format("{0}#{1}#{2}", args[1], guid, expectedExpirationUTC.ToString("o"));

                // encode and encrypt with certificate public key
                byte[] clearBytes = System.Text.Encoding.UTF8.GetBytes(dataBlock);
                System.Security.Cryptography.RSACryptoServiceProvider rsaCryptoServiceProvider = 
                    (System.Security.Cryptography.RSACryptoServiceProvider)cert.PublicKey.Key;
                byte[] encryptedBytes = rsaCryptoServiceProvider.Encrypt(clearBytes, false);

                // convert to hex string
                string accessToken = string.Concat(Array.ConvertAll(encryptedBytes, b => b.ToString("X2")));
                Console.WriteLine(accessToken);
            }

            private static void Usage(string message = "")
            {
                if (!string.IsNullOrEmpty(message))
                    Console.WriteLine(message);
                foreach (var line in helpLines)
                    Console.WriteLine(line);
                Environment.Exit(0);
            }
        }
    }
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    import java.io.*;
    import java.security.cert.Certificate;
    import java.security.cert.CertificateFactory;
    import java.text.SimpleDateFormat;
    import java.text.DateFormat;
    import java.util.Calendar;
    import java.util.Date;
    import java.util.TimeZone;
    import java.util.UUID;
    import javax.crypto.Cipher;

    public class CreateAccessToken {

        private static final String[] helpLines = {
            "Usage: CreateAccessToken <Certificate file path> <API Key> <Absolute time>",
            "Certificate file path: .cer as downloaded from https://service.pcibooking.net/api",
            "API Key: As generated in your PCI Booking account",
            "Absolute time: local time in format HH:MM:ss (up to 1 hour from now), e.g: 18:20:34"
        };

        public static void main(String[] args) {
            if (args.length != 3) {
                Usage("Invalid number of arguments; expected 3");
            }

            Certificate cert = null;
            try {
                InputStream fis = new FileInputStream(args[0]);
                BufferedInputStream bis = new BufferedInputStream(fis);
                CertificateFactory cf = CertificateFactory.getInstance("X.509");
                cert = cf.generateCertificate(bis);
            } catch (Exception ex) {
                Usage("Cannot load certificate file: " + args[0] + " Error: " + ex);
            }

            Date expectedExpirationLocalTime = null;
            Date date = new Date();
            SimpleDateFormat formatter = new SimpleDateFormat("yyyy-MM-dd");
            String cDate = formatter.format(date);
            formatter = new SimpleDateFormat("yyyy-MM-dd HH:mm:ss");
            try {
                expectedExpirationLocalTime = formatter.parse(cDate + " " + args[2]);
            } catch (Exception ex) {
                Usage("Invalid expected time: " + args[2] + " Error: " + ex);
            }

            Calendar cal = Calendar.getInstance();
            long expiresIn = expectedExpirationLocalTime.getTime() - cal.getTime().getTime();
            if (expiresIn > 3600000 || expiresIn < 0) {
                Usage("Invalid expected time [" + args[2] + "]. Should be up to one hour ahead ");
            }

            formatter.setTimeZone(TimeZone.getTimeZone("UTC"));
            DateFormat df = new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ssZ");
            df.setTimeZone(TimeZone.getTimeZone("UTC"));
            String asISO8601 = df.format(expectedExpirationLocalTime);

            String guid = UUID.randomUUID().toString().replace("-", "");
            String dataBlock = String.format("%1$s#%2$s#%3$s", args[1], guid, asISO8601);

            byte[] clearBytes = null;
            try {
                clearBytes = dataBlock.getBytes("UTF-8");
            } catch (Exception ex) {
                Usage("Cannot encode to UTF8: Error: " + ex);
            }

            byte[] encryptedBytes = null;
            try {
                final Cipher cipher = Cipher.getInstance("RSA");
                cipher.init(Cipher.ENCRYPT_MODE, cert.getPublicKey());
                encryptedBytes = cipher.doFinal(clearBytes);
            } catch (Exception ex) {
                Usage("Cannot encrypt: Error: " + ex);
            }

            String accessToken = byteArrayToHex(encryptedBytes);
            System.out.println(accessToken);
        }

        private static void Usage(String message) {
            if (!message.isEmpty()) System.out.println(message);
            for (String line : helpLines) System.out.println(line);
            System.exit(0);
        }

        private static String byteArrayToHex(byte[] a) {
            StringBuilder sb = new StringBuilder(a.length * 2);
            for (byte b : a) sb.append(String.format("%02X", b & 0xff));
            return sb.toString();
        }
    }
    ```
  </Tab>

  <Tab title="PHP">
    ```php theme={null}
    <?php

    require('vendor/autoload.php');

    class CreateAccessToken
    {
        private $certificate;
        private $apiKey;
        private $expirationTime;

        public function __construct($certificate, $apiKey, DateTime $expirationTime)
        {
            $this->certificate = $certificate;
            $this->apiKey = $apiKey;
            $this->expirationTime = $expirationTime;
        }

        public function createToken()
        {
            $cert = openssl_get_publickey($this->certificate);

            $this->expirationTime->setTimeZone(new DateTimeZone('UTC'));
            $expirationAsISO8601 = $this->expirationTime->format(DateTime::ISO8601);
            $guid = $this->generateUUID();
            $dataBlock = sprintf('%s#%s#%s', $this->apiKey, $guid, $expirationAsISO8601);

            openssl_public_encrypt($dataBlock, $encryptedData, $cert);
            $encryptedDataHex = strtoupper(bin2hex($encryptedData));

            return $encryptedDataHex;
        }

        private function generateUUID()
        {
            return str_replace('-', '', Ramsey\Uuid\Uuid::uuid4());
        }
    }
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import binascii
    import uuid
    import pytz

    from cryptography.hazmat.backends import default_backend
    from cryptography.hazmat.primitives.asymmetric import padding
    from cryptography.x509 import load_pem_x509_certificate


    def create_access_token(cert_file, api_key, expiration_time):
        cert = load_pem_x509_certificate(cert_file.read(), default_backend())
        public_key = cert.public_key()

        try:
            expiration_time = pytz.utc.localize(expiration_time)
        except ValueError:
            pass

        expiration_string = expiration_time.isoformat()
        data_block = '{}#{}#{}'.format(api_key, uuid.uuid4(), expiration_string)
        ciphertext = public_key.encrypt(data_block, padding.PKCS1v15())

        return binascii.hexlify(ciphertext)


    def main():
        import datetime
        import sys

        if len(sys.argv) != 4:
            print("Usage: {} cert_file api_key expiration_timestamp".format(sys.argv[0]))
            exit(1)

        with open(sys.argv[1], "rb") as cert_file:
            expiration_time = datetime.datetime.fromtimestamp(int(sys.argv[3]))
            print(create_access_token(cert_file, sys.argv[2], expiration_time))


    if __name__ == '__main__':
        main()
    ```
  </Tab>
</Tabs>

## Comparison

|                   | API Key                    | Session Token                                        | Access Token                                       |
| ----------------- | -------------------------- | ---------------------------------------------------- | -------------------------------------------------- |
| **How to create** | Provided with your account | API call using your API key                          | Generated locally using API key + SSL certificate  |
| **Lifetime**      | Permanent (until rotated)  | 5 minutes                                            | 1 to 60 minutes (configurable)                     |
| **Reuse**         | Unlimited                  | Unlimited (within lifetime)                          | Single use                                         |
| **Passed via**    | HTTP header                | `?sessionToken=` query parameter                     | `?accessToken=` query parameter                    |
| **Best for**      | Server-to-server calls     | Browser-facing operations (card forms, card display) | Delegated single operations with controlled expiry |

## Which should I use?

* **Server-to-server calls** (processing payments, managing tokens, configuring settings): use the **API key**
* **Browser-facing operations** (card entry form iframe, card display): use a **Session Token** or **Access Token**. Your API key must never be exposed to the browser.
* **Need precise control over expiry and single-use guarantees**: use an **Access Token**
* **Quick integration for browser operations**: use a **Session Token** (simpler, just one API call)

## Related

* [Create an Account](/getting-started/create-account) - Get your API keys and portal access
* [Quickstart](/start-here/quickstart) - End-to-end integration walkthrough
* [Testing and Going Live](/getting-started/testing-and-going-live) - Move from sandbox to production
* [API Conventions](/reference/api-conventions) - Request formats, headers, and common patterns


# Create an Account
Source: https://developers.pcibooking.net/getting-started/create-account

Set up sandbox and production accounts with PCI Booking. Learn what is included, how onboarding works, and how to start integrating.

## How to Get Started

PCI Booking does not offer self-service registration. To get an account, [talk to our PCI experts](https://pcibooking.net/talk-to-pci-experts/) who will set you up.

**Why?** PCI Booking is a feature-rich platform with many interchangeable capabilities. Our team helps guide you to the best integration flow for your specific needs so you don't get lost in the weeds.

## Onboarding Process

During onboarding, a PCI Booking solutions engineer will:

1. **Understand your use case** and recommend the right integration approach (hosted forms, Card By Link, API-level tokenization, or a combination).
2. **Create your sandbox account** so you can start building and testing immediately.
3. **Provide technical guidance** for your development team, including sample code and architecture review.
4. **Create your production account** once your integration is tested and validated.

## Sandbox vs. Production

<Tabs>
  <Tab title="Sandbox">
    * Uses test card numbers only (no real charges)
    * Full API access with all features enabled
    * Ideal for development, integration testing, and demos
    * No transaction volume limits during testing
  </Tab>

  <Tab title="Production">
    * Processes real card data with live PSP connections
    * Requires completed integration validation
    * Same API endpoints, different API key
    * Full SLA and support coverage
  </Tab>
</Tabs>

Both environments use the same base URL (`service.pcibooking.net`) and differ only by API key. See [Testing & Going Live](/getting-started/testing-and-going-live) for details on moving from sandbox to production.

## What You Get

* **API keys** for your sandbox and live accounts
* **Portal access** to configure stored settings (gateway credentials, stylesheets, security settings, and more)
* Access to [developer documentation](https://developers.pcibooking.net) and [API reference](/api-reference/general/authenticate)
* **Dedicated support** from PCI Booking's integration team during onboarding and beyond

## After Account Creation

Once you have your sandbox credentials:

1. **Authenticate** by setting up your API key. See [Authentication](/getting-started/authentication).
2. **Follow the Quickstart** to tokenize your first card and make a test payment. See [Quickstart](/start-here/quickstart).
3. **Configure your portal** with gateway credentials, card form styles, and security settings.
4. **Test your integration** end-to-end in sandbox before requesting production access.

## Next Steps

* [Authentication](/getting-started/authentication) - Set up your API keys and learn about authentication methods
* [Quickstart](/start-here/quickstart) - Start your first integration
* [How PCI Booking Works](/concepts/how-pci-booking-works) - Understand the architecture and how card data flows


# Download SSL Certificate
Source: https://developers.pcibooking.net/getting-started/download-ssl-certificate

Download PCI Booking's SSL certificate to generate Access Tokens. Step-by-step for Chrome, Firefox, Edge, and Safari.

To generate an [Access Token](/getting-started/authentication#access-token), you need PCI Booking's SSL certificate. The certificate contains the public key used to encrypt the token payload.

Download it from: `https://service.pcibooking.net/api`

Open that URL in your browser, then follow the steps for your browser below.

<Tabs>
  <Tab title="Chrome (v135+)">
    1. Navigate to `https://service.pcibooking.net/health`
    2. Click the icon immediately to the left of the URL in the address bar.
    3. Select **Security** / **Connection is secure**.
    4. Click **Certificate is valid** (opens a pop-up window).
    5. In the Certificate Viewer, select the **Details** tab.
    6. Select the certificate `*.pcibooking.net` and click **Export** at the bottom.
  </Tab>

  <Tab title="Chrome (v55-v134)">
    1. Press **F12** (or **Options > More Tools > Developer Tools**).
    2. Click the **Security** tab.
    3. Click the **View certificate** button.
    4. Go to the **Details** tab.
    5. Select **Copy to File...** to start the download wizard.
    6. Select a folder to save the certificate to.
  </Tab>

  <Tab title="Firefox">
    1. Click the lock icon to the left of the URL.
    2. Click **More Information**.
    3. Go to the **Security** tab.
    4. Click **View Certificate**.
    5. Go to the **Details** tab.
    6. Click **Export** to download the certificate.
  </Tab>

  <Tab title="Edge / IE">
    1. Click the lock icon to the left of the URL.
    2. Select **View certificates**.
    3. In the **General** tab, select **Install Certificate** to download the certificate.
  </Tab>
</Tabs>

<Info>
  The certificate file is typically saved as a `.cer` file. This is the file you pass to the access token generation scripts in the [Authentication](/getting-started/authentication#code-samples) page.
</Info>


# Testing & Going Live
Source: https://developers.pcibooking.net/getting-started/testing-and-going-live

Test your PCI Booking integration in sandbox mode with test cards for standard and 3D Secure flows. Go-live checklist for production.

Use your sandbox account to build and test your integration before going live. If you have not set up your account yet, start with [Create an Account](/getting-started/create-account) and [Authentication](/getting-started/authentication).

## Sandbox Environment

Sandbox and production run on the **same system** with the **same base URL**:

```
https://service.pcibooking.net/api
```

The only difference is your **API key**. Sandbox and production are two separate accounts on the same environment, so there are no surprises when you go live. To switch from sandbox to production, just swap your API key.

Your sandbox account stays active alongside your live account, so you can continue running tests or developing new features at any time.

### What's included in sandbox

A sandbox account is a **full replica of a production account**. Every API endpoint, feature, and configuration option available in production works identically in sandbox. The only differences are:

* Sandbox is limited to **100 tokenizations per month**. If you need more for testing, contact [support@pcibooking.net](mailto:support@pcibooking.net) to request a higher limit.
* Sandbox uses test payment gateways (like `NULLSuccess` and `NULLFailure`) instead of real PSP connections.
* Sandbox and production have separate API keys, users, and stored data.

### Test cards vs. real cards

PCI Booking does not differentiate between "test cards" and "real cards." For the system, all cards are the same. You can use test cards or real cards in both sandbox and production accounts.

Since your sandbox account runs in the same PCI-certified environment as production, real cards are handled with the same level of security. However, we generally recommend using test cards in sandbox accounts to avoid any unnecessary exposure of real card data.

<Info title="Request a free sandbox">
  PCI Booking offers free sandbox accounts for development and testing. [Request a sandbox account](https://pcibooking.net/sandbox/) to get started.
</Info>

## Test Cards

Use these card numbers in the sandbox environment. All test cards use any future expiry date.

### Standard Test Cards

| Brand      | Number                | CVV          |
| ---------- | --------------------- | ------------ |
| Visa       | `4111 1111 1111 1111` | Any 3 digits |
| Mastercard | `5500 0000 0000 0004` | Any 3 digits |
| Amex       | `3400 0000 0000 009`  | Any 4 digits |

### 3D Secure Test Cards

For all 3DS test cards, use cardholder name `Three DS test` and CVV `123`.

**Frictionless flow** (authenticates automatically, no user interaction):

| Brand      | Number                |
| ---------- | --------------------- |
| Visa       | `4761 7390 0006 0016` |
| Mastercard | `5455 3302 0000 0016` |

**Device fingerprint flow** (collects device info for risk analysis):

| Brand      | Number                |
| ---------- | --------------------- |
| Visa       | `4761 7390 0101 0010` |
| Mastercard | `5185 5200 5000 0010` |

**Challenge flow** (requires OTP entry):

| Brand      | Number                | Success OTP | Fail OTP |
| ---------- | --------------------- | ----------- | -------- |
| Visa       | `4018 8100 0015 0015` | `0101`      | `3333`   |
| Mastercard | `5299 9100 1000 0015` | `4445`      | `9999`   |

**Device fingerprint + challenge flow** (fingerprint first, then OTP):

| Brand      | Number                | Success OTP | Fail OTP |
| ---------- | --------------------- | ----------- | -------- |
| Visa       | `4018 8100 0019 0011` | `0101`      | `3333`   |
| Mastercard | `5420 7110 0040 1011` | `4445`      | `9999`   |

## Go-Live Checklist

Before switching to production:

* [ ] All API calls work correctly in sandbox
* [ ] Error handling covers all [API error codes](/reference/return-codes)
* [ ] API keys are stored securely (environment variables, not source code)
* [ ] Webhook endpoints (if used) are configured and tested
* [ ] Production API keys obtained from your PCI Booking account
* [ ] Sandbox API keys swapped for production API keys

<Info title="Need help going live?">
  [Talk to our PCI experts](https://pcibooking.net/talk-to-pci-experts/) for a pre-launch review.
</Info>

## Related

* [Quickstart](/start-here/quickstart). End-to-end integration walkthrough.
* [Authentication](/getting-started/authentication). How API keys work and how to include them in requests.
* [Create an Account](/getting-started/create-account). Set up your sandbox and production accounts.
* [Return Codes](/reference/return-codes). Full list of API error codes for your error handling logic.


# For Hotels & Accommodation Providers
Source: https://developers.pcibooking.net/guides/for-hotels

Learn how hotels use PCI Booking to receive tokenized card data from OTAs, display card details securely, process charges, and manage CVV data.

# For Hotels & Accommodation Providers

PCI Booking helps hotels and accommodation providers handle guest payment cards without managing PCI DSS compliance in-house. When an OTA or booking channel sends you a tokenized card, PCI Booking lets you view the card details securely, process charges through your preferred gateway, and manage CVV data according to your retention policies.

Instead of receiving raw card numbers (which would put you in PCI scope), you receive tokens that PCI Booking converts into real card data only when needed, such as at the point of charge or when displaying the card to authorized staff.

## Where to Start

<CardGroup>
  <Card title="How PCI Booking Works" icon="diagram-project" href="/concepts/how-pci-booking-works">
    Understand tokenization and how card data flows between OTAs and hotels.
  </Card>

  <Card title="Quickstart Guide" icon="rocket" href="/start-here/quickstart">
    Set up your PCI Booking account and start processing tokens.
  </Card>

  <Card title="Receive Tokens from OTAs" icon="inbox" href="/manage-tokens/overview">
    Learn how to manage tokens shared with you by OTAs and booking channels.
  </Card>

  <Card title="Display Card Details" icon="eye" href="/use-tokens/card-display">
    Show card data to authorized hotel staff using a secure, embedded iframe.
  </Card>

  <Card title="Charge Guest Cards" icon="money-check-dollar" href="/use-tokens/charge">
    Process charges, authorizations, and refunds through your payment gateway.
  </Card>

  <Card title="CVV Management" icon="lock" href="/manage-tokens/cvv-management">
    Configure CVV retention policies and capture CVV when needed for charges.
  </Card>

  <Card title="3D Secure Authentication" icon="shield-check" href="/manage-tokens/3ds-auth-management">
    Add 3D Secure authentication data to tokens for SCA compliance.
  </Card>

  <Card title="Common Use Cases" icon="route" href="/use-cases/how-do-i">
    Browse workflows designed for hotel scenarios.
  </Card>
</CardGroup>

## Typical Hotel Workflows

* **Receive and display**: An OTA sends a booking with a token. Your front desk staff views the card through a secure display form. See [Card Display](/use-tokens/card-display).
* **Receive and charge**: Use the token to charge the guest's card through your payment gateway at check-in or check-out. See [Charge](/use-tokens/charge).
* **CVV capture for charges**: If the CVV was not stored or has expired, send a secure link to the guest to recapture it. See [CVV Capture](/capture-cards/cvv-capture).

## Testing Your Integration

Validate your setup using PCI Booking's sandbox environment before processing real guest cards. See [Testing and Going Live](/getting-started/testing-and-going-live).


# For Online Travel Agencies
Source: https://developers.pcibooking.net/guides/for-otas

Learn how OTAs use PCI Booking to capture traveler card data, relay tokens to hotels, charge via payment gateways, and stay PCI DSS compliant.

# For Online Travel Agencies

PCI Booking helps Online Travel Agencies (OTAs) handle payment card data without the burden of PCI DSS certification. Whether you need to capture cards from travelers, relay card details to hotels, or charge cards through your payment gateway, PCI Booking acts as a secure middleman so sensitive data never touches your servers.

With PCI Booking, your OTA can tokenize cards at the point of booking, store them securely, and use tokens to process payments or forward card data to accommodation providers. This keeps you fully compliant with PCI DSS and PSD2/SCA requirements while maintaining a seamless booking experience for your customers.

## Where to Start

<CardGroup>
  <Card title="How PCI Booking Works" icon="diagram-project" href="/concepts/how-pci-booking-works">
    Understand the tokenization flow and how PCI Booking fits into your booking pipeline.
  </Card>

  <Card title="Quickstart Guide" icon="rocket" href="/start-here/quickstart">
    Get up and running with your first integration in minutes.
  </Card>

  <Card title="Capture Cards from Travelers" icon="credit-card" href="/capture-cards/overview">
    Embed a secure card entry form in your checkout flow to tokenize card data.
  </Card>

  <Card title="Card By Link" icon="link" href="/capture-cards/card-by-link">
    Send a secure link via email or SMS so travelers can enter card details for phone bookings.
  </Card>

  <Card title="Relay Tokens to Hotels" icon="hotel" href="/use-tokens/token-replacement-in-request">
    Forward tokenized card data to hotels and suppliers using token replacement.
  </Card>

  <Card title="Charge via Payment Gateway" icon="money-check-dollar" href="/use-tokens/charge">
    Process charges through 100+ supported payment gateways using stored tokens.
  </Card>

  <Card title="PSD2/SCA Compliance" icon="shield-check" href="/use-cases/comply-with-psd2">
    Implement Strong Customer Authentication to meet PSD2 requirements.
  </Card>

  <Card title="Common Use Cases" icon="route" href="/use-cases/how-do-i">
    Browse step-by-step workflows for OTA scenarios like capture-and-relay and capture-and-charge.
  </Card>
</CardGroup>

## Typical OTA Workflows

* **Capture and relay to hotel**: Tokenize the traveler's card at booking, then use token replacement to send the card data to the hotel's system. See [Capture and Relay to Hotel](/use-cases/capture-and-relay-to-hotel).
* **Capture and charge**: Tokenize the card and process a charge through your payment gateway in a single flow. See [Capture and Charge](/use-cases/capture-and-charge).
* **Phone bookings**: Use Card By Link to send a secure card capture form to travelers who book by phone. See [Card By Link](/capture-cards/card-by-link).

## Testing Your Integration

Before going live, use PCI Booking's sandbox environment to validate your integration end to end. See [Testing and Going Live](/getting-started/testing-and-going-live).


# For Payment Service Providers
Source: https://developers.pcibooking.net/guides/for-payment-providers

Learn how PSPs integrate with PCI Booking's API, Payments Library, Apple Pay and Google Pay support, gateway credentials management, and data blocks.

# For Payment Service Providers

PCI Booking provides payment service providers (PSPs) with a robust API for tokenization, card data management, and payment processing. Whether you are building a gateway integration, adding digital wallet support (Apple Pay, Google Pay, PayPal), or storing sensitive data on behalf of merchants, PCI Booking's PCI DSS Level 1 certified infrastructure handles the compliance burden.

The Payments Library offers a client-side SDK for accepting multiple payment methods through a single integration. Data blocks let you store arbitrary sensitive data (not just card numbers) in a tokenized, compliant manner.

## Where to Start

<CardGroup>
  <Card title="API Overview" icon="code" href="/api-reference/overview">
    Explore the full PCI Booking REST API for tokenization, token management, and payment processing.
  </Card>

  <Card title="Quickstart Guide" icon="rocket" href="/start-here/quickstart">
    Set up authentication and make your first API call.
  </Card>

  <Card title="Payments Library" icon="wallet" href="/payments-library/overview">
    Integrate the client-side SDK to accept credit cards, Apple Pay, Google Pay, PayPal, and more.
  </Card>

  <Card title="Gateway Credentials" icon="key" href="/account-setup/gateway-credentials">
    Store and manage payment gateway credentials for processing transactions.
  </Card>

  <Card title="Apple Pay Setup" icon="apple" href="/account-setup/applepay-setup">
    Configure Apple Pay for use with the Payments Library.
  </Card>

  <Card title="Google Pay Setup" icon="google" href="/account-setup/googlepay-setup">
    Configure Google Pay for use with the Payments Library.
  </Card>

  <Card title="Data Blocks" icon="database" href="/additional-functions/data-blocks">
    Store and retrieve arbitrary sensitive data using tokenized data blocks.
  </Card>

  <Card title="Testing and Going Live" icon="flask-vial" href="/getting-started/testing-and-going-live">
    Use the sandbox environment to validate your integration before production.
  </Card>
</CardGroup>

## Key Integration Points

* **Server-side tokenization**: Tokenize card data on incoming or outgoing API calls without changing your existing message format. See [Tokenization on Response](/capture-cards/tokenization-on-response) and [Tokenization on Request](/capture-cards/tokenization-on-request).
* **Token replacement**: Inject real card data into outgoing requests to downstream providers. See [Token Replacement](/use-tokens/token-replacement-in-request).
* **Payments Library credentials**: Store PSP credentials for Apple Pay, Google Pay, PayPal, and other methods. See [Payments Library Credentials](/account-setup/payments-library-credentials).
* **Data blocks**: Tokenize and store any sensitive data (passports, IDs, PII) with the same compliance guarantees as card data. See [Data Blocks](/additional-functions/data-blocks).

## API Reference

For detailed endpoint documentation including request/response schemas, authentication, and error codes, see the [API Reference](/api-reference/overview).


# 3DS Auth Management
Source: https://developers.pcibooking.net/manage-tokens/3ds-auth-management

Store, retrieve, and delete 3D Secure authentication data for payment tokens. CAVV, ECI, and transaction IDs.

3D Secure (3DS) authentication data (CAVV, ECI, transaction ID) proves that a cardholder was verified. PCI Booking stores this data alongside the card token so it can be used in subsequent transactions.

## How 3DS Data Gets Stored

In most cases, 3DS data is stored automatically and you do not need to call the Store endpoint:

* **PCI Booking performs the 3DS challenge**. When you tokenize a card via the [Card Entry Form](/capture-cards/hosted-card-entry-form), [Card By Link](/capture-cards/card-by-link), or [Payments Library](/capture-cards/payments-library) with 3DS enabled, PCI Booking runs the 3DS flow and stores the authentication data on the token automatically.
* **Tokenization on Response with 3DS extraction**. When you receive card details from a third party via [Tokenization on Response](/capture-cards/tokenization-on-response), the profile can be configured to extract 3DS authentication data from the message alongside the card details. Both are stored on the token in one step. You can update your profile through the PCI Booking portal or contact [support@pcibooking.net](mailto:support@pcibooking.net) for assistance.
* **Tokenization on Request with 3DS extraction**. Similarly, when a third party sends card data to your API via [Tokenization on Request](/capture-cards/tokenization-on-request), the gateway profile can extract 3DS data from the inbound message. Contact [support@pcibooking.net](mailto:support@pcibooking.net) to enhance your gateway profile with 3DS extraction.

## Store 3DS Data Manually

Use the [Store 3DS Token](/api-reference/manage-tokens/store-3d-token) endpoint when you receive 3DS authentication data separately after the card has already been tokenized. For example, if a third party performs the 3DS challenge on their side and sends you the authentication results, you can attach that data to your existing token.

## Using 3DS Data in Transactions

When you use a token to send card data to a PSP or third party, PCI Booking can inject the stored 3DS authentication data into the outgoing message alongside the card details:

* **[Universal Payment Gateway](/use-tokens/universal-payment-gateway)**. 3DS data is included automatically when processing payments through a PSP.
* **[Token Replacement in Request](/use-tokens/token-replacement-in-request)**. 3DS data can be injected into the request body alongside the detokenized card data.

This means you typically do not need to retrieve 3DS data and send it yourself.

## Retrieve 3DS Data

Use the [Retrieve 3DS Token](/api-reference/manage-tokens/retrieve-3d-token) endpoint when you need to send the 3DS authentication data separately from the card details. For example, if your integration requires you to pass 3DS data in a separate API call to your PSP rather than in the same message as the card.

## Delete 3DS Data

Remove stored 3DS data from a token via the [Delete 3DS Token](/api-reference/manage-tokens/delete-3d-token) endpoint when it is no longer valid or needed.

<Info>
  3DS authentication data has a limited validity window. Check with your payment processor for their specific reuse policies.
</Info>

## Next Steps

<CardGroup>
  <Card title="Token Management Overview" icon="book" href="/manage-tokens/overview">
    All token management capabilities
  </Card>
</CardGroup>


# CVV Management
Source: https://developers.pcibooking.net/manage-tokens/cvv-management

Manage CVV storage, retention policies, and re-capture for stored card tokens. PCI DSS compliant.

CVV data is stored within the card token, subject to your [CVV retention policy](/capture-cards/cvv-retention-policy). This page covers how to manage the CVV data on an existing token.

## How CVV Retention Works

PCI DSS prohibits permanent storage of CVV data. PCI Booking enforces this through configurable retention policies that automatically clear CVV after a defined period or usage count.

The default retention window is **60 minutes** after capture. After this window closes, PCI Booking automatically deletes the CVV from the token. You can customize this behavior per account or per token through the [CVV Retention Policy](/capture-cards/cvv-retention-policy) configuration.

Retention policies support two modes:

* **Time-based**: CVV is cleared after a set duration (e.g., 60 minutes, 24 hours, 7 days)
* **Usage-based**: CVV is cleared after a set number of detokenization uses per destination, allowing you to control exactly how many times the CVV can be sent to each PSP

<Info>
  You can combine both modes. For example, retain CVV for up to 7 days or 3 uses per destination, whichever comes first. This gives you flexibility to support multiple charge attempts while still enforcing strict limits.
</Info>

## Check CVV Status

Use the [Retrieve Token Metadata](/api-reference/manage-tokens/retrieve-token-metadata) endpoint to check whether CVV is currently stored on a token. The response includes the `CvvExists` flag and the `EndRetentionDate` indicating when the CVV is scheduled to be cleared.

To see the full retention policy with per-destination quotas and usage counts, use the [Get CVV Retention Policy](/api-reference/manage-tokens/get-cvv-retention-policy) endpoint. To check the policy for a specific destination, use [Get Specific Policy](/api-reference/manage-tokens/get-cvv-retention-policy-specific).

## Capture CVV Separately

When you already have a card token but need the CVV for a transaction, send a CVV-only capture form to the cardholder. This is useful when the original CVV has expired or been cleared, or when the card was tokenized without a CVV in the first place. See the [CVV Capture Form](/capture-cards/cvv-capture) guide for details.

## Clear CVV Manually

Explicitly remove stored CVV from a token at any time using the [Clear CVV](/api-reference/manage-tokens/clear-cvv) endpoint, regardless of the retention policy. This is useful when you have completed all planned charges and want to proactively remove the CVV before the retention window expires. Once cleared, CVV cannot be recovered. You must capture it again from the cardholder.

## Next Steps

<CardGroup>
  <Card title="CVV Capture Form" icon="book" href="/capture-cards/cvv-capture">
    Capture CVV separately from the cardholder
  </Card>

  <Card title="CVV Retention Policy" icon="book" href="/capture-cards/cvv-retention-policy">
    Configure how long CVV is retained and under what conditions
  </Card>

  <Card title="Token Management Overview" icon="book" href="/manage-tokens/overview">
    All token management capabilities
  </Card>
</CardGroup>


# Delete Tokens
Source: https://developers.pcibooking.net/manage-tokens/delete-tokens

Permanently delete stored payment card tokens and all associated data. This action cannot be undone.

Permanently remove a token and its associated card data from the vault using the [Delete Token](/api-reference/manage-tokens/delete-token) endpoint.

## What Gets Deleted

When you delete a token, the following data is permanently and irrecoverably removed from PCI Booking's vault:

* **Card data** including the full card number, expiration date, and cardholder name
* **CVV data** if it was stored on the token
* **3DS authentication data** associated with the token
* **Merchant and customer associations** linked to the token
* **The cardURI itself**, which becomes invalid and cannot be reused or queried

There is no soft-delete or recycle bin. Once deleted, none of this data can be recovered.

## When to Delete Tokens

Common scenarios for deleting tokens:

* A guest checks out and you no longer need their card on file
* A cardholder requests removal of their payment data (GDPR or similar data privacy requirements)
* You have replaced an old token with a new one after a card renewal or CVV re-capture
* A token was created in error or during testing

<Warning>
  Before deleting, verify that the token is not referenced by any pending or future transactions. Deletion is permanent and cannot be undone. If a recurring charge or no-show policy depends on the token, deleting it will cause those operations to fail.
</Warning>

## Bulk Deletion Considerations

PCI Booking does not provide a bulk delete endpoint. Each token must be deleted individually using its `cardURI`. If you need to delete a large number of tokens (for example, during a data cleanup or after a system migration), iterate through your stored token list and call the delete endpoint for each one.

When planning a bulk cleanup:

* **Query tokens first.** Use the [Retrieve Token Metadata](/api-reference/manage-tokens/retrieve-token-metadata) endpoint to verify each token's status before deleting. This helps you avoid accidentally deleting tokens that are still in use.
* **Log deletions.** Keep a record of deleted `cardURI` values in your system for audit purposes. Once deleted from PCI Booking's vault, the data cannot be retrieved.
* **Rate limits.** For large batch deletions, space your API calls to stay within your account's rate limits. Contact support if you need temporary rate limit increases for a migration.

## Duplicate Before Deleting

If you need to preserve the card data under a different account or reference, [duplicate the token](/api-reference/manage-tokens/duplicate-token) first to create a copy, then delete the original. This is useful when transferring card data between merchant accounts or customer profiles.

## Data Retention and Compliance

Token deletion supports compliance with data privacy regulations such as GDPR, CCPA, and PCI DSS data minimization requirements. Under GDPR, a cardholder can request erasure of their personal data (right to be forgotten). Deleting the token satisfies this request for card data stored in PCI Booking's vault. Your own systems must also remove any local references or metadata associated with the token.

PCI DSS requires that cardholder data not be stored beyond business necessity. Regularly reviewing and deleting tokens that are no longer needed is a recommended practice to minimize your data footprint and reduce risk.

## Next Steps

<CardGroup>
  <Card title="Token Management Overview" icon="book" href="/manage-tokens/overview">
    See all token management capabilities
  </Card>

  <Card title="CVV Management" icon="book" href="/manage-tokens/cvv-management">
    Manage CVV data on existing tokens
  </Card>
</CardGroup>


# Manage Tokens Overview
Source: https://developers.pcibooking.net/manage-tokens/overview

Query, update, duplicate, and manage PCI Booking card tokens. Covers expiration, CVV retention, 3DS data, customer and property associations.

Regardless of which [tokenization method](/capture-cards/overview) you used to capture a card, the result is the same: a token. Every token works the same way and gives you access to the same management capabilities.

## What a Token Contains

A token represents a complete card record. All data associated with a card is stored within the single token, regardless of how much or how little was provided at capture time:

* **PAN** (Primary Account Number). The full card number.
* **Expiration date**.
* **Cardholder name**.
* **CVV** (if captured). Subject to [CVV retention policy](/capture-cards/cvv-retention-policy).
* **3D Secure authentication data** (if captured). CAVV, ECI, and transaction ID from 3DS challenges.
* **Non-sensitive metadata**. Card type, masked number (first 6 / last 4), creation date, creator reference.

Whether a card was tokenized with just a PAN or with full details including CVV and 3DS data, it is all stored in one token.

## Token Identifier

Every token is identified by a **cardURI**:

```text theme={null}
https://service.pcibooking.net/api/payments/paycard/{token}
```

Use this cardURI in all API calls that reference the token.

## What You Can Do

| Capability                                                    | Description                                                                                               |
| ------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| **[Query & Retrieve](/manage-tokens/query-retrieve)**         | Search tokens by reference, card details, or date range. Retrieve metadata for a specific token.          |
| **[Update Card Data](/manage-tokens/update-card-data)**       | Update expiration dates or other card information on an existing token.                                   |
| **[CVV Management](/manage-tokens/cvv-management)**           | Check whether CVV exists on a token, see how many times it was used, capture CVV separately, or clear it. |
| **[3DS Auth Management](/manage-tokens/3ds-auth-management)** | Store, retrieve, and delete 3DS authentication data attached to a token.                                  |
| **[Delete Tokens](/manage-tokens/delete-tokens)**             | Permanently remove card data from the vault.                                                              |

## Next Steps

<Card title="Use Tokens Guide" icon="arrow-right" href="/use-tokens/overview">
  All the ways to put your stored tokens to work
</Card>


# Query & Retrieve Tokens
Source: https://developers.pcibooking.net/manage-tokens/query-retrieve

Search stored tokens by card type, expiration, or customer. Retrieve card details or metadata without exposing sensitive data.

## Query Tokens

Search your stored tokens using the [Query Tokens](/api-reference/manage-tokens/query-tokens) endpoint. You can filter by:

* **Creator reference**. The reference you provided when the card was tokenized (e.g. a booking ID or customer ID). Exact match only.
* **Associated property**. A merchant or property ID linked to the token.

You must provide at least one of these filters. Results are ordered by creation date.

### Pagination

The query endpoint supports offset-based pagination:

| Parameter | Default | Description                                                               |
| --------- | ------- | ------------------------------------------------------------------------- |
| `num`     | 100     | Maximum number of tokens to return per request.                           |
| `from`    | 0       | Zero-based offset. Set to `100` to get the next page when `num` is `100`. |

To page through all results, increment `from` by `num` on each request until the response returns fewer items than `num`.

### What You Get Back

Each result includes token metadata only. No full card numbers are ever returned:

* Token URI (cardURI).
* Masked card number (first 6 and last 4 digits).
* Card type and brand.
* Expiration date.
* Cardholder name.
* Creation date.
* CVV status (whether CVV is stored and its retention end date).
* Associated merchants and properties.

## Retrieve Token Metadata

Fetch metadata for a specific token by its cardURI using the [Retrieve Token Metadata](/api-reference/manage-tokens/retrieve-token-metadata) endpoint. Returns the same masked data as the query endpoint, plus:

* Creator reference.
* Virtual card information (if applicable).
* 3DS authentication data (if stored).

This is the recommended way to look up a token's details. No sensitive card data is exposed.

## Next Steps

<CardGroup>
  <Card title="Update Card Data" icon="book" href="/manage-tokens/update-card-data">
    Update expiry dates and other card details
  </Card>

  <Card title="Token Management Overview" icon="book" href="/manage-tokens/overview">
    All token management capabilities
  </Card>
</CardGroup>


# Third-Party Permissions
Source: https://developers.pcibooking.net/manage-tokens/third-party-permissions

Share card tokens between PCI Booking customers. Set read, write, and process permissions for multi-party workflows.

PCI Booking allows you to share stored tokens with other PCI Booking customers (merchants). You remain the owner and are responsible for any action taken on the card.

## Associating with Customers

Associating a token with another PCI Booking customer allows them to view card details or perform actions (relay to third parties, charge, etc.).

* A token can be associated with multiple customers.
* If a customer attempts an action on a token not associated with them, they receive an error.

| Action                        | API Endpoint                                                                          |
| ----------------------------- | ------------------------------------------------------------------------------------- |
| Associate token with customer | [Associate with Customer](/api-reference/manage-tokens/associate-with-customer)       |
| Remove association            | [Disassociate from Customer](/api-reference/manage-tokens/disassociate-from-customer) |
| List associated customers     | [List Customer Associations](/api-reference/manage-tokens/list-customer-associations) |

<Info>
  If the third party needs to use the CVV, you must set a [CVV Retention Policy](/capture-cards/cvv-retention-policy) that permits it before they attempt to access the card.
</Info>

## Next Steps

<CardGroup>
  <Card title="CVV Retention Policy" icon="book" href="/capture-cards/cvv-retention-policy">
    Control how long CVV data is retained and who can use it
  </Card>
</CardGroup>


# Update Card Data
Source: https://developers.pcibooking.net/manage-tokens/update-card-data

Update expiration dates and creator references on stored card tokens without re-tokenizing.

## Update Expiration Date

When a cardholder's card is renewed with a new expiration date, update the token via the [Update Expiration](/api-reference/manage-tokens/update-expiration) endpoint rather than creating a new one. This keeps the same token in use across your system.

## Update Creator Reference

The **creator reference** is your internal identifier for the token. It can be a booking ID, customer number, or any string meaningful to your system. You can update it at any time via the [Update Creator Reference](/api-reference/manage-tokens/update-creator-reference) endpoint.

## Delete Creator Reference

Remove the creator reference from a token without deleting the token itself via the [Delete Creator Reference](/api-reference/manage-tokens/delete-creator-reference) endpoint.

## When to Update vs. Create New

* **Same card, new expiry**. Update the existing token.
* **Different card number**. Create a new token (the card number cannot be changed on an existing token).
* **Changed reference**. Update the creator reference.

## Next Steps

<CardGroup>
  <Card title="Query & Retrieve Tokens" icon="book" href="/manage-tokens/query-retrieve">
    Search and retrieve token details
  </Card>

  <Card title="Token Management Overview" icon="book" href="/manage-tokens/overview">
    All token management capabilities
  </Card>
</CardGroup>


# Payments Library Overview
Source: https://developers.pcibooking.net/payments-library/overview

Integrate PCI Booking's JavaScript library for card capture, Apple Pay, Google Pay, PayPal, BankPay, and UPI in your checkout page

The Payments Library (`@pcibooking/ewallet`) is a client-side JavaScript SDK that handles card capture and payment processing in your checkout page. It renders secure payment forms, manages communication with PCI Booking's servers, and supports multiple payment methods from a single integration point.

For how the Payments Library fits into the overall tokenization flow, see [Payments Library under Capture Cards](/capture-cards/payments-library).

## Key Capabilities

* **Card payments.** Render a secure card form (in popup or iframe mode) for credit and debit card entry with full 3D Secure support.
* **Digital wallets.** Accept Apple Pay, Google Pay, PayPal, BankPay, and UPI alongside card payments on the same checkout page.
* **Multiple operations.** Support for CHARGE, TOKENIZE, CHARGE\_AND\_TOKENIZE, PREAUTH\_AND\_TOKENIZE, and GATEWAY\_TOKENIZE, depending on the payment method.
* **PCI compliance.** Card data is captured inside PCI Booking's secure environment and never touches your servers, keeping you out of PCI DSS scope.

## How It Works

The Payments Library uses a session-based architecture with JWS (JSON Web Signature) signing for secure communication:

1. **Your server** calls the PCI Booking API to [create a session](/api-reference/payments-library/create-session), specifying the operation type and amount.
2. **Your frontend** initializes the Payments Library with the session token.
3. **The library** renders payment method buttons and forms based on the session configuration and the customer's device capabilities.
4. **The customer** selects a payment method and completes the transaction.
5. **PCI Booking** processes the payment and returns the result to your frontend callback.

## Architecture

The Payments Library follows a client-server model where sensitive operations happen on PCI Booking's servers and your frontend only handles the UI layer.

* **Session creation (server-side).** Your backend calls PCI Booking's API to create a session, specifying the operation type (CHARGE, TOKENIZE, CHARGE\_AND\_TOKENIZE, PREAUTH\_AND\_TOKENIZE, or GATEWAY\_TOKENIZE), the PSP credentials, amount, and currency. PCI Booking returns a signed JWS session token.
* **Library initialization (client-side).** Your frontend loads the `@pcibooking/ewallet` package and initializes it with the session token. The library verifies the token signature and configures itself based on the session parameters.
* **Payment method rendering.** The library detects the customer's device and browser capabilities, then renders only the payment methods that are available. For example, Apple Pay buttons appear only on Safari with a compatible device, and Google Pay buttons appear only in Chrome with a linked Google account.
* **Secure data handling.** Card form fields are rendered inside PCI Booking's secure environment (either an iframe or a popup). Card data is submitted directly from the form to PCI Booking's servers. Your page never has access to the raw card data, keeping you fully outside PCI DSS scope.
* **Result callback.** After the payment is processed (or the card is tokenized), PCI Booking calls your frontend callback function with the result, including the token, transaction status, and any error details.

## Supported Payment Methods

The library supports six payment methods from a single integration point: **CardPay** (credit and debit cards with 3D Secure), **Apple Pay**, **Google Pay**, **PayPal**, **BankPay** (Open Banking / ACH), and **UPI** (India instant payments). Each method has different supported operations and device requirements. See [Supported Payment Methods](/payments-library/supported-methods) for the full comparison.

## Credentials Setup

Each payment method requires credentials from the respective provider (Apple, Google, PayPal, etc.) stored in PCI Booking. See [Payments Library Credentials](/account-setup/payments-library-credentials) for the full list of required credentials per method.

## End-to-End Integration Example

This example shows the complete flow: creating a session on your server, loading the library on the client, and handling the payment result.

### Step 1: Create a Session (Server-Side)

<CodeGroup>
  ```javascript Node.js theme={null}
  // Server: create a session and return sessionId to the frontend
  const response = await fetch('https://service.pcibooking.net/api/eWalletOperation', {
    method: 'POST',
    headers: {
      'Authorization': 'APIKEY your-api-key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      operation: 'CHARGE',
      mode: 'LIVE',
      PaymentGatewayAccountId: 'my-gateway-credentials',
      AllowedeWalletAccountIds: 'my-applepay,my-googlepay',
      CurrencyCode: 'USD',
      Amount: 49.99,
      CountryCode: 'US',
      AllowedBrands: 'visa,mastercard,amex',
      CustomerEmail: 'customer@example.com'
    })
  });
  const { sessionId } = await response.json();
  // Return sessionId to your frontend (e.g. via API response)
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://service.pcibooking.net/api/eWalletOperation',
      headers={
          'Authorization': 'APIKEY your-api-key',
          'Content-Type': 'application/json'
      },
      json={
          'operation': 'CHARGE',
          'mode': 'LIVE',
          'PaymentGatewayAccountId': 'my-gateway-credentials',
          'AllowedeWalletAccountIds': 'my-applepay,my-googlepay',
          'CurrencyCode': 'USD',
          'Amount': 49.99,
          'CountryCode': 'US',
          'AllowedBrands': 'visa,mastercard,amex',
          'CustomerEmail': 'customer@example.com'
      }
  )
  session_id = response.json()['sessionId']
  # Return session_id to your frontend (e.g. via API response)
  ```
</CodeGroup>

### Step 2: Load the Library and Present Payment UI (Client-Side)

```html theme={null}
<script src="https://cdn.jsdelivr.net/npm/@pcibooking/ewallet@latest/dist/index.js"></script>

<div id="payment-buttons"></div>

<script>
  async function startPayment(sessionToken) {
    // Initialize the engine with the session token from your server
    const engine = new eWallet.Engine(sessionToken, null, 'EN', {
      displayMode: 'iframe',
      iframeContainerSelector: '#card-form-container'
    });

    // Detect which payment methods are available on this device
    const methods = await engine.checkAvailability();

    // Render payment buttons and handle the result
    engine.payBy(methods, function(result) {
      if (!result) {
        console.log('Payment cancelled by user');
        return;
      }

      const [data, success] = engine.parseResultToken(result.token);
      if (data.clientSuccess && success) {
        // Send result.token to your server for validation
        fetch('/api/validate-payment', {
          method: 'POST',
          headers: { 'Content-Type': 'application/json' },
          body: JSON.stringify({ token: result.token })
        });
      }
    }, {
      containerSelector: '#payment-buttons'
    });
  }

  // Fetch the session token from your server, then start the payment flow
  fetch('/api/create-session')
    .then(res => res.json())
    .then(data => startPayment(data.sessionId));
</script>
```

### Step 3: Validate the Result (Server-Side)

<CodeGroup>
  ```javascript Node.js theme={null}
  // Server: validate the result token received from the frontend
  const response = await fetch('https://service.pcibooking.net/api/eWalletOperation/validateResults', {
    method: 'POST',
    headers: {
      'Authorization': 'APIKEY your-api-key',
      'Content-Type': 'text/plain'
    },
    body: resultToken
  });
  const { valid } = await response.json();
  if (valid) {
    // Payment is verified, fulfill the order
  }
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://service.pcibooking.net/api/eWalletOperation/validateResults',
      headers={
          'Authorization': 'APIKEY your-api-key',
          'Content-Type': 'text/plain'
      },
      data=result_token
  )
  if response.json()['valid']:
      # Payment is verified, fulfill the order
      pass
  ```
</CodeGroup>

## Integration Guides

<CardGroup>
  <Card title="Setup" icon="book" href="/payments-library/setup">
    Install the library, create a session, and run a working example
  </Card>

  <Card title="Supported Payment Methods" icon="book" href="/payments-library/supported-methods">
    All methods with browser support, device requirements, and supported operations
  </Card>

  <Card title="Library Reference" icon="code" href="/payments-library/reference">
    Full API surface: constructor parameters, methods, UI options, and operation types
  </Card>
</CardGroup>


# Library Reference
Source: https://developers.pcibooking.net/payments-library/reference

JavaScript API reference for PCI Booking's Payments Library. Methods, events, configuration options, and callbacks.

## Constructor

```javascript theme={null}
const engine = new eWallet.Engine(sessionToken, requiredAncillaryInfo, language, uiOptions);
```

### Parameters

| Parameter               | Type     | Required | Description                                     |
| ----------------------- | -------- | -------- | ----------------------------------------------- |
| `sessionToken`          | `string` | Yes      | Session token obtained from the PCI Booking API |
| `requiredAncillaryInfo` | `object` | No       | Billing and shipping data requirements          |
| `language`              | `string` | No       | UI language code (auto-detected if omitted)     |
| `uiOptions`             | `object` | No       | UI display configuration                        |

### Supported Languages

`EN`, `ES`, `FR`, `DE`, `IT`, `PT`, `NL`, `PL`, `RU`, `JA`, `ZH`, `KO`, `AR`, `HE`, `TR`, `SV`, `NO`, `DA`, `FI`, and more.

### UI Options

| Property                  | Type      | Default   | Description                                                               |
| ------------------------- | --------- | --------- | ------------------------------------------------------------------------- |
| `hideLogo`                | `boolean` | `false`   | Hide the merchant logo in the payment UI                                  |
| `displayMode`             | `string`  | `'popup'` | Card form display mode: `'popup'` or `'iframe'`                           |
| `iframeContainerSelector` | `string`  |           | CSS selector for the container element when using `'iframe'` display mode |

```javascript theme={null}
const engine = new eWallet.Engine(sessionToken, null, 'EN', {
  displayMode: 'iframe',
  iframeContainerSelector: '#card-form-container',
  hideLogo: true
});
```

## Methods

### `checkAvailability()`

Returns a Promise that resolves to a list of payment methods available for the current session and device. **This method is async.**

```javascript theme={null}
const methods = await engine.checkAvailability();
// e.g. ['CardPay', 'ApplePay', 'GooglePay']
```

The result depends on the session configuration, browser capabilities, and device support. For example, Apple Pay only appears in Safari.

### `payBy(eWalletList, callback, buttonProperties)`

Renders payment buttons and starts the payment flow.

| Parameter          | Type       | Description                                                                 |
| ------------------ | ---------- | --------------------------------------------------------------------------- |
| `eWalletList`      | `array`    | Payment methods to display (from `checkAvailability()`)                     |
| `callback`         | `function` | Called with the result object on completion, or `undefined` on cancellation |
| `buttonProperties` | `object`   | Button rendering options (container selector, styling)                      |

```javascript theme={null}
engine.payBy(['CardPay', 'ApplePay'], function(result) {
  if (!result) return; // cancelled
  console.log(result.token);
}, {
  containerSelector: '#payment-buttons'
});
```

### `parseResultToken(token)`

Decodes a result token into structured data.

```javascript theme={null}
const [data, success] = engine.parseResultToken(result.token);
```

Returns a tuple of `[data, success]` where `data` contains transaction details and `success` is a boolean indicating client-side success.

### `getSessionType()`

Returns the operation type for the current session.

```javascript theme={null}
const type = engine.getSessionType();
// e.g. 'CHARGE', 'TOKENIZE', 'CHARGE_AND_TOKENIZE'
```

### `getSelectedProviderName()`

Returns the name of the payment method the user selected.

```javascript theme={null}
const provider = engine.getSelectedProviderName();
// e.g. 'CardPay', 'ApplePay'
```

### `getBillingInfo()`

Returns billing address data collected during the payment flow, if applicable.

### `getShippingInfo()`

Returns shipping address data collected during the payment flow, if applicable.

## Operations

| Operation              | Description                                              |
| ---------------------- | -------------------------------------------------------- |
| `CHARGE`               | Process a one-time payment                               |
| `TOKENIZE`             | Store the payment method for future use without charging |
| `CHARGE_AND_TOKENIZE`  | Process a payment and store the method for future use    |
| `PREAUTH_AND_TOKENIZE` | Pre-authorize an amount and store the method             |
| `GATEWAY_TOKENIZE`     | Tokenize directly with the payment gateway               |

The operation type is set when creating the session via the PCI Booking API and determines which payment methods and flows are available.

## Related

* [Payments Library Overview](/payments-library/overview) - Introduction and architecture
* [Setup Guide](/payments-library/setup) - Integration steps and session creation
* [Supported Methods](/payments-library/supported-methods) - Available payment methods and browser compatibility


# Payments Library Setup
Source: https://developers.pcibooking.net/payments-library/setup

Install and initialize PCI Booking's JavaScript Payments Library. Script loading, configuration, and first render.

## Prerequisites

* A PCI Booking merchant account.
* Credentials configured for the payment methods you want to accept. Contact your PCI Booking account manager for setup.

## Installation

### npm

```bash theme={null}
npm install @pcibooking/ewallet
```

```javascript theme={null}
import eWallet from '@pcibooking/ewallet';
```

### CDN

```html theme={null}
<script src="https://cdn.jsdelivr.net/npm/@pcibooking/ewallet@latest/dist/index.js"></script>
```

The library exposes a global `eWallet` object when loaded via CDN.

## Create a Session

Before initializing the library, your server must create a [payment session](/api-reference/payments-library/create-session) with PCI Booking. The session defines the operation type (e.g. `TOKENIZE`, `CHARGE`) and returns a session token.

Pass the session token to your frontend to initialize the library.

<CodeGroup>
  ```javascript Node.js theme={null}
  const response = await fetch('https://service.pcibooking.net/api/eWalletOperation', {
    method: 'POST',
    headers: {
      'Authorization': 'APIKEY your-api-key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      operation: 'CHARGE',
      mode: 'LIVE',
      PaymentGatewayAccountId: 'my-gateway-credentials',
      AllowedeWalletAccountIds: 'my-applepay,my-googlepay',
      CurrencyCode: 'USD',
      Amount: 99.99,
      CountryCode: 'US',
      AllowedBrands: 'visa,mastercard,amex',
      CustomerEmail: 'customer@example.com',
      merchantReference: 'ORDER-12345'
    })
  });
  const { sessionId } = await response.json();
  // Pass sessionId to your frontend
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://service.pcibooking.net/api/eWalletOperation',
      headers={
          'Authorization': 'APIKEY your-api-key',
          'Content-Type': 'application/json'
      },
      json={
          'operation': 'CHARGE',
          'mode': 'LIVE',
          'PaymentGatewayAccountId': 'my-gateway-credentials',
          'AllowedeWalletAccountIds': 'my-applepay,my-googlepay',
          'CurrencyCode': 'USD',
          'Amount': 99.99,
          'CountryCode': 'US',
          'AllowedBrands': 'visa,mastercard,amex',
          'CustomerEmail': 'customer@example.com',
          'merchantReference': 'ORDER-12345'
      }
  )
  session_id = response.json()['sessionId']
  # Pass session_id to your frontend
  ```
</CodeGroup>

## Minimal Working Example

```html theme={null}
<!DOCTYPE html>
<html>
<head>
  <title>Checkout</title>
  <script src="https://cdn.jsdelivr.net/npm/@pcibooking/ewallet@latest/dist/index.js"></script>
</head>
<body>
  <div id="payment-buttons"></div>

  <script>
    async function startCheckout() {
      // Session token from your server (via Create Session API)
      const sessionToken = 'YOUR_SESSION_TOKEN';

      const engine = new eWallet.Engine(sessionToken);
      const methods = await engine.checkAvailability();

      engine.payBy(methods, function(result) {
        if (!result) {
          alert('Payment cancelled');
          return;
        }

        const [data, success] = engine.parseResultToken(result.token);
        if (data.clientSuccess && success) {
          // Send result.token to your server for validation
          console.log('Success, token:', result.token);
        }
      }, {
        containerSelector: '#payment-buttons'
      });
    }

    startCheckout();
  </script>
</body>
</html>
```

<Info>
  Session tokens are single-use. Create a new session for each checkout attempt.
</Info>

## Server-Side Validation

After the customer completes the payment, your callback receives a result token. Send this token to your server and call the [Validate Operation](/api-reference/payments-library/validate-operation) endpoint to confirm the result is authentic.

<CodeGroup>
  ```javascript Node.js theme={null}
  // In your server endpoint that receives the result token from the frontend
  async function validatePaymentResult(resultToken) {
    const response = await fetch('https://service.pcibooking.net/api/eWalletOperation/validateResults', {
      method: 'POST',
      headers: {
        'Authorization': 'APIKEY your-api-key',
        'Content-Type': 'text/plain'
      },
      body: resultToken
    });
    const data = await response.json();
    return data.valid; // true if the token is authentic
  }
  ```

  ```python Python theme={null}
  import requests

  def validate_payment_result(result_token):
      """Call from your server after receiving the result token from the frontend."""
      response = requests.post(
          'https://service.pcibooking.net/api/eWalletOperation/validateResults',
          headers={
              'Authorization': 'APIKEY your-api-key',
              'Content-Type': 'text/plain'
          },
          data=result_token
      )
      data = response.json()
      return data['valid']  # True if the token is authentic
  ```
</CodeGroup>

## Next Steps

<CardGroup>
  <Card title="Supported Payment Methods" icon="book" href="/payments-library/supported-methods">
    See which methods are available and their supported operations
  </Card>

  <Card title="Library Reference" icon="code" href="/payments-library/reference">
    Full API surface: constructor parameters, all methods, UI options
  </Card>
</CardGroup>


# Supported Payment Methods
Source: https://developers.pcibooking.net/payments-library/supported-methods

Payment methods available through the Payments Library: card entry, Apple Pay, Google Pay, PayPal, BankPay, UPI.

## Payment Methods Overview

| Method     | Description                   | Operations  | Tokenization | 3D Secure      |
| ---------- | ----------------------------- | ----------- | ------------ | -------------- |
| CardPay    | Credit and debit cards        | All         | Yes          | Yes            |
| Apple Pay  | Safari on iOS and macOS       | All         | Yes          | N/A (built-in) |
| Google Pay | Chrome on Android and desktop | All         | Yes          | N/A (built-in) |
| PayPal     | All browsers                  | CHARGE only | No           | N/A            |
| BankPay    | Open Banking / ACH            | CHARGE only | No           | N/A            |
| UPI        | India instant payments        | CHARGE only | No           | N/A            |

## CardPay

Credit and debit card payments with full 3D Secure support. Works in all modern browsers. The card form is rendered by the Payments Library in either popup or iframe mode, ensuring card data never touches your servers.

**Browser support:** All modern browsers (Chrome, Firefox, Safari, Edge)
**Operations:** CHARGE, TOKENIZE, CHARGE\_AND\_TOKENIZE, PREAUTH\_AND\_TOKENIZE, GATEWAY\_TOKENIZE

## Apple Pay

Native Apple Pay integration for Safari on iOS and macOS. Requires Apple Pay merchant setup through PCI Booking.

**Browser support:** Safari on iOS 10+ and macOS Sierra+
**Device support:** iPhone, iPad, Mac with Touch ID or Apple Watch

<Info>
  Apple Pay buttons only appear when `checkAvailability()` detects a compatible device and browser.
</Info>

## Google Pay

Native Google Pay integration for Chrome and Android. Requires Google Pay merchant setup through PCI Booking.

**Browser support:** Chrome on Android, desktop Chrome with linked Google account
**Device support:** Android devices, desktop with Chrome

## PayPal

PayPal checkout integration. Supports charge operations only, the user is redirected to PayPal to authorize the payment.

**Browser support:** All modern browsers
**Operations:** CHARGE only

## BankPay

Open Banking and ACH direct bank payments. The user selects their bank and authorizes the payment through their banking app or website.

**Browser support:** All modern browsers
**Operations:** CHARGE only
**Availability:** Varies by region and bank support

## UPI

Unified Payments Interface for instant payments in India. The user scans a QR code or enters their UPI ID to complete the payment.

**Browser support:** All modern browsers
**Operations:** CHARGE only
**Availability:** India only

<Info>
  For credential setup instructions for each payment method, contact your PCI Booking account manager or refer to the [merchant configuration guide](https://pcibooking.net).
</Info>

## Next Steps

<CardGroup>
  <Card title="Payments Library Overview" icon="book" href="/payments-library/overview">
    Architecture, capabilities, and how the library fits into your integration.
  </Card>

  <Card title="Setup Guide" icon="book" href="/payments-library/setup">
    Install the library, create a session, and run your first payment.
  </Card>

  <Card title="Library Reference" icon="code" href="/payments-library/reference">
    Full API surface: constructor parameters, methods, callbacks, and operation types.
  </Card>
</CardGroup>


# API Conventions
Source: https://developers.pcibooking.net/reference/api-conventions

Base URL, content types, authentication headers, error format, and pagination for PCI Booking's REST API.

General conventions that apply across all PCI Booking API calls.

## Response Content Format

PCI Booking supports responses in both JSON and XML. Set the `Accept` header to control the format:

```http theme={null}
Accept: application/json
```

```http theme={null}
Accept: application/xml
```

### JSON Conventions

* DateTime fields use ISO 8601 format
* Enum values are serialized as strings

### Currency Format

Currency codes follow the [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) standard (e.g., `USD`, `EUR`, `GBP`).

## Message Compression

PCI Booking supports response compression in **gzip** and **deflate** formats.

If your request includes an `Accept-Encoding` header, PCI Booking compresses the response accordingly. Make sure your client can decompress the format(s) you request.

```http theme={null}
Accept-Encoding: deflate, gzip;q=1.0
```

If you do not send an `Accept-Encoding` header, responses are returned uncompressed.

## Tokenization Errors and Warnings

When performing tokenization via [Tokenization on Request](/capture-cards/tokenization-on-request), [Tokenization on Response](/capture-cards/tokenization-on-response), or [Universal Tokenization](/capture-cards/universal-tokenization), PCI Booking may encounter cards that cannot be tokenized. In these cases, card data is relayed as-is and the reason is returned in a response header.

<Info>
  Only valid, non-expired cards are tokenized. Card data with incorrect numbers or past expiry dates does not fall under PCI compliance and is not tokenized.
</Info>

### Error Header

When a card fails tokenization, the reason appears in the `X-pciBooking-Tokenization-Errors` header.

If the message contains multiple cards, errors are separated by double semicolons (`;;`). The position in the list matches the card's position in the message. Successfully tokenized cards have an empty entry.

Example with 3 cards where the second fails:

```http theme={null}
X-pciBooking-Tokenization-Errors: ;;Luhn (Mod10) error;;
```

| Error                          | Description                                                                                   |
| ------------------------------ | --------------------------------------------------------------------------------------------- |
| Luhn (Mod10) error             | Card number fails the [Luhn algorithm](https://en.wikipedia.org/wiki/Luhn_algorithm) checksum |
| Expired card                   | Card expiration date is in the past                                                           |
| Number has less than 12 digits | Card number too short                                                                         |
| Number is longer than 22 chars | Card number too long                                                                          |

### Warning Header

A `X-pciBooking-Tokenization-Warnings` header is added when a card was tokenized but some information is mismatched. Most common with [Tokenization on Request](/capture-cards/tokenization-on-request).

| Warning                      | Description                                                                              |
| ---------------------------- | ---------------------------------------------------------------------------------------- |
| Card type validation message | Card type does not match the card number (e.g., type says Visa but number is MasterCard) |
| The Card type is missing     | Request does not contain a card type                                                     |

## Gateway Request Headers

When PCI Booking relays requests through the gateway (token replacement), it adds the following headers to the outbound request. See [Gateway Request Headers](/reference/gateway-request-headers) for details.

## Supported File Types for FTP Transfer

When using [File Transfer Token Replacement](/use-tokens/file-transfer-token-replacement) or [File Transfer Tokenization](/capture-cards/file-transfer-tokenization), PCI Booking supports:

| Format           | Filter Parameter | Description                                                                    |
| ---------------- | ---------------- | ------------------------------------------------------------------------------ |
| **TADC**         | `TADC`           | Travel Agency Data Capture XML format (used by AMEX for travel reconciliation) |
| **AMEX GBT CSV** | `GBT`            | AMEX CSV format for Global Business Travel                                     |
| **Simple CSV**   | `SIMPLECSV`      | Generic CSV file with card data fields                                         |
| **Simple JSON**  | `SIMPLEJSON`     | Generic JSON file with card data fields                                        |
| **AIR**          | `AIR`            | AIR (Airline Industry Reporting) format                                        |
| **IUR**          | `IUR`            | IUR (Industry Usage Reporting) format                                          |
| **CSV**          | `CSV`            | Standard CSV format                                                            |

## Pagination

Some list and search endpoints return paginated results. PCI Booking uses offset-based pagination with two parameters:

| Endpoint                                                           | Items Parameter | Offset Parameter | Default Items | Max Items     |
| ------------------------------------------------------------------ | --------------- | ---------------- | ------------- | ------------- |
| [Query Tokens](/api-reference/manage-tokens/query-tokens)          | `num`           | `from`           | 100           | No hard limit |
| [Search Data Blocks](/api-reference/additional/search-data-blocks) | `maxItems`      | `offset`         | All results   | 50            |

Both use zero-based offsets. To page through results, increment the offset by the number of items returned:

```
# First page
GET /api/payments/paycard/meta?num=50&from=0

# Second page
GET /api/payments/paycard/meta?num=50&from=50
```

Responses do not include a total count or next-page indicator. Continue requesting pages until fewer items than requested are returned.

## System Limits

| Description                       | Value                                            |
| --------------------------------- | ------------------------------------------------ |
| Session timeout (idle)            | 15 minutes                                       |
| Card data storage                 | No time limitation                               |
| Supported browsers for card forms | Latest versions of Chrome, Safari, Edge, Firefox |

## CVV Storage

PCI compliance requires that CVV cannot be stored indefinitely. CVV can only be stored until it is "used," with the definition varying by workflow. PCI Booking enforces this through a [CVV Retention Policy](/capture-cards/cvv-retention-policy) that lets you set relay restrictions and storage period limits.

## Card Storage

PCI Booking does not limit how long cards can be stored. Cards remain in the system as long as needed, regardless of expiration date. You can [delete cards](/manage-tokens/delete-tokens) on demand or automatically as part of the CVV retention policy.

## Password Character Set

Passwords for PCI Booking portal accounts accept alphanumeric characters plus these symbols:

`! " # $ % & ' ( ) * + , - . / ; < = > ? @ [ \ ]` and space.


# Card Data XML Structure
Source: https://developers.pcibooking.net/reference/card-data-xml-structure

XML schema for card data elements used in token replacement and card display requests. Field definitions and examples.

PCI Booking stores and returns card data in a standard XML format. This structure is used when [migrating cards](/capture-cards/store-card-migration) via the API and when retrieving card data through [token replacement](/use-tokens/token-replacement-in-request).

## Full Card Data

```xml theme={null}
<BankCardDetails xmlns="http://www.pcibooking.net/reservation"
                 schemaVersion="1.0">
  <BankCard>
    <Type>Visa</Type>
    <Number>4580458045804580</Number>
    <NameOnCard>MR Y. ALON</NameOnCard>
    <ExpirationDate>
      <Month>04</Month>
      <Year>2023</Year>
    </ExpirationDate>
    <IssueNumber>2</IssueNumber>
    <OwnerID>123456789</OwnerID>
    <CVV>306</CVV>
  </BankCard>
</BankCardDetails>
```

## Tokenized (Masked) Card Data

After tokenization, the XML returned by PCI Booking masks sensitive fields:

```xml theme={null}
<?xml version='1.0' encoding='utf-8'?>
<BankCard>
  <Type>Visa</Type>
  <Number>458045******4580</Number>
  <NameOnCard>MR Y. ALON</NameOnCard>
  <ExpirationDate>
    <Month>04</Month>
    <Year>2023</Year>
  </ExpirationDate>
  <IssueNumber>2</IssueNumber>
</BankCard>
```

Differences from the full card data:

1. The card number shows the first 6 and last 4 digits. The rest is replaced with `*`.
2. The CVV is removed entirely.

## Card Fields

| Field                | Description                                                                         | Example          |
| -------------------- | ----------------------------------------------------------------------------------- | ---------------- |
| Type                 | Card brand (2 to 16 characters). See [Supported Card Types](/reference/card-types). | Visa             |
| Number               | Card number, max 19 digits                                                          | 4580458045804580 |
| NameOnCard           | Cardholder name                                                                     | MR Y. ALON       |
| ExpirationDate/Month | Expiration month (MM)                                                               | 04               |
| ExpirationDate/Year  | Expiration year (YYYY)                                                              | 2023             |
| IssueNumber          | Additional number found on some cards                                               | 1                |
| OwnerID              | Cardholder's national ID number (required in some countries)                        | 123456789        |
| CVV                  | Card verification number, 3 or 4 digits                                             | 306              |

## Virtual Card Fields

Virtual cards include additional attributes on the `<Virtual>` element inside `<BankCard>`:

```xml theme={null}
<BankCard>
  <Type>Visa</Type>
  <Virtual isMultiuse="false" currency="AUD" maxAmount="500"
           cardRules="Chapter 11"
           validFromDay="31" validFromMonth="08" validFromYear="2014"
           validToDay="1" validToMonth="11" validToYear="2017" />
  <Number>4580458045804580</Number>
  <!-- other fields -->
</BankCard>
```

| Attribute      | Description                                 | Example      |
| -------------- | ------------------------------------------- | ------------ |
| isMultiuse     | Whether the card can be used more than once | true / false |
| maxAmount      | Maximum charge amount                       | 500          |
| currency       | Currency of the max amount                  | AUD          |
| cardRules      | Rules for clearing the virtual card         | Chapter 11   |
| validFromDay   | Day the card becomes valid (DD)             | 31           |
| validFromMonth | Month the card becomes valid (MM)           | 08           |
| validFromYear  | Year the card becomes valid (YYYY)          | 2014         |
| validToDay     | Day the card expires (DD)                   | 1            |
| validToMonth   | Month the card expires (MM)                 | 11           |
| validToYear    | Year the card expires (YYYY)                | 2017         |


# Supported Card Types
Source: https://developers.pcibooking.net/reference/card-types

Complete list of card types PCI Booking identifies and tokenizes: Visa, Mastercard, Amex, JCB, Diners, and more.

<Info>
  You can retrieve this list programmatically via the [Get Supported Credit Cards](/api-reference/general/get-supported-cards) API endpoint.
</Info>

PCI Booking supports the following card brands. The **Code** column shows the exact string value used in API requests and responses.

## Card Types

| Card Brand        | Code         | Notes                         |
| ----------------- | ------------ | ----------------------------- |
| American Express  | `AMEX`       |                               |
| BC Card           | `BC`         | South Korean card brand       |
| Carta Si          | `CartaSi`    | Italian card brand            |
| Dankort           | `Dankort`    | Danish debit card             |
| Delta             | `Delta`      | Visa Delta (UK debit)         |
| Diners Club       | `DinersClub` | Including Carte Blanche       |
| Discover          | `Discover`   |                               |
| Electron          | `Electron`   | Visa Electron                 |
| Elo               | `Elo`        | Brazilian card brand          |
| enRoute           | `enRoute`    | Travel and entertainment card |
| Hipercard         | `Hipercard`  | Brazilian card brand          |
| JCB               | `JCB`        | Japan Credit Bureau           |
| Maestro           | `Maestro`    | International debit           |
| MasterCard        | `MasterCard` |                               |
| MasterCard Alaska | `MC_Alaska`  |                               |
| MasterCard Canada | `MC_Canada`  |                               |
| Switch            | `Switch`     | UK debit card (now Maestro)   |
| Troy              | `Troy`       | Turkish payment network       |
| UATP              | `UATP`       | Universal Air Travel Plan     |
| UnionPay          | `UnionPay`   | China UnionPay                |
| Visa              | `Visa`       |                               |

## Card Type Detection

PCI Booking automatically detects the card type from the card number (BIN range) during tokenization. The detected type is included in the token metadata.

## Filtering Card Types

You can restrict which card types are accepted on the [card entry form](/capture-cards/hosted-card-entry-form) by passing a `cardTypes` parameter with a comma-separated list of codes from the table above.

## Requesting a New Card Type

If you need PCI Booking to support a card type not listed here, contact [support@pcibooking.net](mailto:support@pcibooking.net) and provide the BIN range or BIN identifiers for the card type. Our team will evaluate and add support.

## Related

* [Query Tokens API](/api-reference/manage-tokens/query-tokens) - Search tokens by card type and other criteria
* [Retrieve Card Details API](/api-reference/manage-tokens/retrieve-card-details) - Get full card metadata including detected card type


# Card Validation Errors
Source: https://developers.pcibooking.net/reference/card-validation-errors

Error codes returned when card entry validation fails. Invalid number, expiration, CVV, and Luhn check failures.

When card data is submitted to PCI Booking (via a [hosted card entry form](/capture-cards/hosted-card-entry-form), [Card By Link](/capture-cards/card-by-link), or API), the data is validated before tokenization. If validation fails, one of the following error messages is returned.

## Card Number Errors

| Error                                | Description                                                                       |
| ------------------------------------ | --------------------------------------------------------------------------------- |
| Number is longer than 22 chars       | Card number exceeds maximum length                                                |
| Invalid character at position        | Non-numeric character found in card number                                        |
| Invalid separator                    | Unrecognized separator character between digit groups                             |
| Number has less than 12 digits       | Card number too short                                                             |
| Luhn (Mod10) error                   | Card number fails the Luhn checksum algorithm                                     |
| Too many separator characters        | Excess separators in card number                                                  |
| Invalid number                       | Card number is not valid                                                          |
| Card number does not match card type | The entered number does not match the selected card type (card capture form only) |

## Expiration Date Errors

| Error                   | Description                        |
| ----------------------- | ---------------------------------- |
| Month should be 1 to 12 | Month value is out of range        |
| Expired card            | The expiration date is in the past |

## CVV Errors

| Error                     | Description                                                 |
| ------------------------- | ----------------------------------------------------------- |
| CVV must be 3 or 4 digits | CVV length is invalid (3 digits for most cards, 4 for AMEX) |

## Issue Number Errors

| Error                             | Description                               |
| --------------------------------- | ----------------------------------------- |
| Issue number should be "1" or "2" | Issue number is outside the allowed range |

## Cardholder Name Rules

The cardholder name field accepts:

* Maximum **32 characters**
* Alphanumeric characters (A-Z, a-z, 0-9)
* Special characters: `'` `-` `.` `!` `£` `$` `%` `^` `*` and space

## Related

* [Hosted Card Entry Form](/capture-cards/hosted-card-entry-form) - Set up the card capture form that triggers these validations
* [Request Card Entry Form API](/api-reference/tokenize-cards/request-card-entry-form) - API reference for generating the card entry form


# Changelog
Source: https://developers.pcibooking.net/reference/changelog

Recent changes, new features, and bug fixes in the PCI Booking API and related services.

Recent production releases with customer-facing changes. Internal-only updates are omitted.

## July 2026

### 2026-07-03

* **New PSP**: Added **Fabrick** (Payment Orchestra) as a new payment gateway integration in the [Universal Payment Gateway](/use-tokens/universal-payment-gateway), supporting MOTO transactions via Fabrick's REST API.

## June 2026

### 2026-06-24

* **New PSP**: Added **PayWay** (payway.com.au) as a new payment gateway integration in the [Universal Payment Gateway](/use-tokens/universal-payment-gateway), including 3DS external MPI support.

### 2026-06-17

* **New PSP**: Added **CreditGuard** as a new payment gateway integration in the [Payments Library](/payments-library/overview).
* **eWallet Library**: Added CardPay `GATEWAY_TOKENIZE` operation and CardPay iframe display mode. Added Pelecard as a bank provider.

### 2026-06-15

* **Fix**: eWallet payments processed via NEXI with [Apple Pay](/account-setup/applepay-setup) or [Google Pay](/account-setup/googlepay-setup) now correctly populate the 3DS "ppo" parameter sent to NEXI.

### 2026-06-11

* **Fix**: Resolved a bug in 3DS data tokenization affecting [Universal Tokenization](/capture-cards/universal-tokenization) and [Tokenization in Response](/capture-cards/tokenization-on-response) flows.

## May 2026

### 2026-05-31

* **New PSP**: Added **Checkout.com** as a new payment gateway integration in the [Universal Payment Gateway](/use-tokens/universal-payment-gateway).


# File Transfer Formats
Source: https://developers.pcibooking.net/reference/file-transfer-formats

Supported file formats for SFTP/FTPS tokenization and token replacement: TADC XML, AMEX CSV, and standard delimited formats.

PCI Booking supports several file formats for [file transfer tokenization](/capture-cards/file-transfer-tokenization) and [file transfer token replacement](/use-tokens/file-transfer-token-replacement). This page provides format specifications and downloadable examples.

## Supported Formats

| Format        | Type                          | Use Case                                                       |
| ------------- | ----------------------------- | -------------------------------------------------------------- |
| **Delimited** | CSV, TSV, or custom delimiter | General-purpose flat file tokenization                         |
| **TADC**      | XML                           | Travel Agency Data Capture format (AMEX travel reconciliation) |
| **AMEX CSV**  | CSV                           | AMEX-specific card data format                                 |
| **AIR**       | Fixed-width                   | Airline industry record format                                 |
| **IUR**       | Fixed-width                   | Insurance/utility record format                                |

## TADC (Travel Agency Data Capture)

TADC is an XML format used by American Express for travel industry card data reconciliation. PCI Booking can tokenize card numbers within TADC files during SFTP/FTPS transfer, and replace tokens with real card data when sending TADC files outbound.

### TADC XML Schema (XSD)

The full XML Schema Definition for validating TADC files is available for download:

<a href="/public/tadc-schema.xsd">Download TADC XML Schema (tadc-schema.xsd)</a>

The schema defines the complete structure including:

* `Message` root element with version, submitter ID, and sequence numbers
* `TravelBatch` elements containing provider and currency info
* `TravelTran` elements with transaction details, card data, and travel segments
* Date, amount, and card number format restrictions

### TADC Example File

A complete example TADC XML file with realistic (masked) data is available for download:

<a href="/public/tadc-example.xml">Download TADC Example File (tadc-example.xml)</a>

The example includes multiple travel batches with air, hotel, and car rental transactions.

## AMEX CSV

The AMEX CSV format is a semicolon-delimited file used for AMEX card data exchange. Each row represents one transaction.

### Example

```text theme={null}
6JC5EE/1;3723******468;EUR;359.1;20200121;F-001 1813000;The Manor Amsterdam;Amsterdam;Netherlands;00 31 99 999 9999;Linnaeusstraat 89;na;3;OFF;https://www.hcorpo.com/book/pnr/6JC5EE;Vernon.bear@customer.FR;12;99999999999;BOUILLO;FG10;SR;DACLIN;na;na;na
TMPBLX/1;3723*****6732;EUR;239.4;20200121;F-001 1814000;The Manor Amsterdam;Amsterdam;Netherlands;00 31 99 999 9999;Linnaeusstraat 89;na;2;OFF;https://www.hcorpo.com/book/pnr/TMPBLX;Vernon.bear@customer.FR;FG10;9999999999;bouillo;fg10;SR;HADJIEV;na;na;na
PF292G/1;3723*****3606;EUR;257.04;20200121;F-001 1812899;The Manor Amsterdam;Amsterdam;Netherlands;00 31 99 999 9999;Linnaeusstraat 89;na;2;OFF;https://www.hcorpo.com/book/pnr/PF292G;Vernon.bear@customer.FR;12;99999999999;bouillo;fg10;SR;jaganna;na;na;na
```

The card number field (second column) is tokenized/detokenized by PCI Booking during file transfer.

<a href="/public/amex-csv-example.csv">Download AMEX CSV Example (amex-csv-example.csv)</a>

## Delimited Formats (CSV, TSV)

For standard delimited files, PCI Booking identifies card numbers by column position or pattern matching. Configure the column mapping through [target profiles](/account-setup/target-profiles) or [tokenization profiles](/api-reference/tokenize-cards/get-tokenization-profiles).

## Related

<CardGroup>
  <Card title="File Transfer Tokenization" icon="book" href="/capture-cards/file-transfer-tokenization">
    Tokenize card data in SFTP/FTPS file transfers
  </Card>

  <Card title="File Transfer Token Replacement" icon="book" href="/use-tokens/file-transfer-token-replacement">
    Replace tokens with card data in outbound file transfers
  </Card>
</CardGroup>


# Gateway Request Headers
Source: https://developers.pcibooking.net/reference/gateway-request-headers

HTTP headers PCI Booking adds to proxied gateway requests. Trace IDs, original IP forwarding, and custom headers.

When a request passes through PCI Booking's gateway (during [tokenization on request](/capture-cards/tokenization-on-request) or [token replacement](/use-tokens/token-replacement-in-request)), PCI Booking adds headers to the relayed request. Some are for diagnostics, some provide useful information about the tokenization result.

## Example

```http theme={null}
X-Amzn-Trace-Id: Root=1-5c2a3e7f-534419405f0a9800b1ba9920
X-Forwarded-For: 109.76.169.47, 172.200.3.67, 34.243.68.114
X-Forwarded-Port: 443
X-Forwarded-Proto: https
X-Forwarded-Protocol: https
X-Forwarded-Ssl: on
X-pciBooking-Tokenization-Warnings: [1005] Card type is missing
X-Real-Ip: 34.243.68.114
X-Token: https://service.pcibooking.net/api/payments/paycard/c8882c7d3b6a433f91d64cb21eb70d0a
```

## Header Reference

| Header                                       | Description                                                                                                                                       | Action                                                                                                                                             |
| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `X-Token`                                    | Card token URI(s), semicolon-separated if multiple cards in the request.                                                                          | **Process this.** Store the token(s) for future operations. Handle multiple tokens if your messages can contain multiple cards.                    |
| `X-Forwarded-For`                            | Comma-separated list of IP addresses that processed the message, from the original sender to PCI Booking.                                         | **Recommended.** Process this if you perform IP whitelisting. See [IP Restrictions](/account-setup/security-settings#ip-restrictions) for details. |
| `X-pciBooking-Tokenization-Warnings`         | Warnings about tokenization issues (e.g., missing card type). See [API Conventions](/reference/api-conventions#tokenization-errors-and-warnings). | **Strongly recommended.** Set up a workflow to address these warnings.                                                                             |
| `X-pciBooking-Tokenization-Errors`           | Errors when cards could not be tokenized (e.g., Luhn failure, expired card). Double-semicolon separated for multi-card messages.                  | **Strongly recommended.** Cards that fail tokenization are relayed as-is with the original card data.                                              |
| `X-Amzn-Trace-Id`                            | Internal diagnostics trace ID.                                                                                                                    | Optional. Log for troubleshooting with PCI Booking support.                                                                                        |
| `X-Real-Ip`                                  | IP address of the last server to process the request (usually PCI Booking).                                                                       | Optional. `X-Forwarded-For` provides more complete information.                                                                                    |
| `X-Forwarded-Port`                           | Port the request was forwarded on. Always `443`.                                                                                                  | Ignore.                                                                                                                                            |
| `X-Forwarded-Proto` / `X-Forwarded-Protocol` | Protocol used. Always `https`.                                                                                                                    | Ignore.                                                                                                                                            |
| `X-Forwarded-Ssl`                            | Whether SSL was enabled. Always `on`.                                                                                                             | Ignore.                                                                                                                                            |


# Glossary
Source: https://developers.pcibooking.net/reference/glossary

Definitions of key terms: tokenization, detokenization, PCI DSS, CVV retention, 3D Secure, card-on-file, and more.

Key terms used throughout PCI Booking documentation, listed alphabetically.

| Term                                                    | Definition                                                                                                                                                                                                                                                                                               |
| ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **3DS (3D Secure)**                                     | Cardholder authentication protocol (e.g., Verified by Visa, Mastercard SecureCode) that adds a verification step during online payment. See [3DS merchant setup](/account-setup/3ds-merchant-setup) and [3DS auth management](/manage-tokens/3ds-auth-management).                                       |
| **Access Token**                                        | Locally-generated, single-use [authentication](/getting-started/authentication) token (1-60 minute validity) created using your API key and the PCI Booking SSL certificate. No API call needed to generate.                                                                                             |
| **API Key**                                             | Primary [authentication](/getting-started/authentication) credential for server-to-server PCI Booking API calls. Long-lived and reusable. Managed in the PCI Booking portal.                                                                                                                             |
| **Authorization (Pre-Auth)**                            | First step of [two-step payment processing](/use-tokens/authorize-capture). Places a hold on cardholder funds without transferring them. Followed by a [Capture](#capture).                                                                                                                              |
| **BIN (Bank Identification Number)**                    | First 6-8 digits of a card number. Identifies the issuing bank and [card type](/reference/card-types).                                                                                                                                                                                                   |
| **Callback URL**                                        | HTTP endpoint on your server that PCI Booking calls to deliver [card form results](/capture-cards/postmessage-notifications) or status notifications.                                                                                                                                                    |
| **Capture**                                             | Second step of [two-step payment](/use-tokens/authorize-capture). Settles a previous authorization to transfer the held funds.                                                                                                                                                                           |
| **Card By Link**                                        | Feature that sends [secure card capture links](/capture-cards/card-by-link) via email or SMS, enabling remote card collection without PCI scope. Formerly known as Card Over The Phone (COTP). You can customize the email and SMS with [Card By Link templates](/account-setup/card-by-link-templates). |
| **Card Display Form**                                   | PCI Booking's hosted form that [displays masked or full card details](/use-tokens/card-display) to authorized users.                                                                                                                                                                                     |
| **Card Display with OTP**                               | Standalone hosted page that [shows card details after two-factor verification](/use-tokens/card-display-otp) (email link + phone OTP).                                                                                                                                                                   |
| **Card Entry Form**                                     | PCI Booking's [hosted form](/capture-cards/hosted-card-entry-form) where cardholders enter payment card details securely inside an iframe.                                                                                                                                                               |
| **CardURI**                                             | A URI-format [token](/concepts/tokenization-explained) identifier used to reference a specific stored card. Template: `https://service.pcibooking.net/api/paycards/bankcard/{cardToken}`.                                                                                                                |
| **CAVV (Cardholder Authentication Verification Value)** | Cryptographic value from a successful [3DS authentication](/manage-tokens/3ds-auth-management) proving the cardholder was verified. Sent to PSPs with the transaction.                                                                                                                                   |
| **Charge**                                              | Single-step payment transaction that [authorizes and settles funds](/use-tokens/charge) in one request.                                                                                                                                                                                                  |
| **Client Certificate**                                  | Certificate uploaded to PCI Booking for mutual TLS authentication when relaying card data to third-party destinations. See [client certificates setup](/account-setup/client-certificates).                                                                                                              |
| **Contact Verification**                                | Feature to [verify a property's email and phone number](/additional-functions/contact-verification) are valid and reachable, via email link and phone OTP.                                                                                                                                               |
| **Content Filter**                                      | XML configuration within a [target profile](/account-setup/target-profiles) that specifies where card fields are located in a message using XPath, JSONPath, or field name selectors. See [content filters](/account-setup/content-filters).                                                             |
| **COTP (Card Over The Phone)**                          | Legacy name for [Card By Link](/capture-cards/card-by-link).                                                                                                                                                                                                                                             |
| **Creator Reference**                                   | Custom identifier or metadata attached to a token for tracking its origin or purpose. Managed via the [query and update](/manage-tokens/query-retrieve) APIs.                                                                                                                                            |
| **Credentials ID**                                      | Unique reference assigned when storing PSP credentials in PCI Booking via [gateway credentials](/account-setup/gateway-credentials). Used in [UPG](/use-tokens/universal-payment-gateway) payment requests.                                                                                              |
| **CVV (Card Verification Value)**                       | 3-4 digit security code on payment cards. PCI Booking can store it temporarily under a [CVV retention policy](/capture-cards/cvv-retention-policy). See also [CVV capture](/capture-cards/cvv-capture).                                                                                                  |
| **CVV Retention Policy**                                | Rules defining how long CVV data is stored and how many times it can be used before automatic deletion. See [CVV retention policy](/capture-cards/cvv-retention-policy) and [CVV management](/manage-tokens/cvv-management).                                                                             |
| **Data Block**                                          | Arbitrary non-card data (text, XML, images, PDFs) stored in PCI Booking's vault for secure data handling. See [data blocks](/additional-functions/data-blocks).                                                                                                                                          |
| **Detokenization**                                      | Replacing a [token](/concepts/tokenization-explained) with real card data for payment processing, relaying, or display. The reverse of [tokenization](/concepts/tokenization-explained). See [use tokens overview](/use-tokens/overview).                                                                |
| **ECI (Electronic Commerce Indicator)**                 | Value indicating the outcome of [3D Secure authentication](/manage-tokens/3ds-auth-management). Sent to PSPs alongside CAVV.                                                                                                                                                                             |
| **FTPS**                                                | FTP with TLS encryption. Used for secure [batch file transfers](/use-tokens/file-transfer-token-replacement) and [file transfer tokenization](/capture-cards/file-transfer-tokenization).                                                                                                                |
| **IP Restrictions**                                     | Whitelist of IP addresses permitted to call the PCI Booking API. Configured in the portal under [security settings](/account-setup/security-settings).                                                                                                                                                   |
| **Merchant**                                            | A business account (sub-account) within your PCI Booking organization. Each merchant operates independently with its own credentials and tokens. See [account creation](/getting-started/create-account) and [user management](/account-setup/manage-users).                                             |
| **OTP (One-Time Password)**                             | Temporary numeric code sent via SMS or voice call for identity verification. Used in [card display with OTP](/use-tokens/card-display-otp).                                                                                                                                                              |
| **PAN (Primary Account Number)**                        | The full card number printed on a payment card. See [card data XML structure](/reference/card-data-xml-structure).                                                                                                                                                                                       |
| **Paycard**                                             | Collective term for bank cards, credit cards, and debit cards. See [supported card types](/reference/card-types).                                                                                                                                                                                        |
| **Payments Library**                                    | Client-side JavaScript SDK for collecting payments via [alternative payment methods](/payments-library/supported-methods) (Apple Pay, Google Pay, PayPal, BankPay, UPI). See the [Payments Library overview](/payments-library/overview) and [setup guide](/payments-library/setup).                     |
| **PCI DSS**                                             | Payment Card Industry Data Security Standard. The security standard PCI Booking is certified against, removing PCI scope from your systems. Learn more about [how PCI Booking works](/concepts/how-pci-booking-works).                                                                                   |
| **PostMessage**                                         | Browser cross-domain messaging mechanism for secure communication between the PCI Booking iframe and the parent page. See [PostMessage notifications](/capture-cards/postmessage-notifications).                                                                                                         |
| **Property**                                            | A specific location or entity (hotel, branch) registered under a merchant account. Tokens can be associated with properties for scoped card access. See [property management](/additional-functions/property-management).                                                                                |
| **PSP (Payment Service Provider)**                      | A third-party payment gateway or processor (e.g., Stripe, Adyen, Worldpay). PCI Booking connects to PSPs through the [Universal Payment Gateway](/use-tokens/universal-payment-gateway).                                                                                                                 |
| **Refund**                                              | Returns funds from a completed charge or captured authorization back to the cardholder. See [refunds and voids](/use-tokens/refunds-voids).                                                                                                                                                              |
| **Relay**                                               | The operation of securely sending card data from PCI Booking to an authorized destination via [token replacement](/use-tokens/token-replacement-in-request). Also called "Send".                                                                                                                         |
| **Relay Restrictions**                                  | Whitelist of destination URLs allowed to receive card data via token replacement. Configured per user under [security settings](/account-setup/security-settings).                                                                                                                                       |
| **Risk Assessment**                                     | Fraud scoring that cross-references card issuer country, billing address, and client IP geolocation to produce a risk level. See [risk assessment](/use-tokens/risk-assessment).                                                                                                                         |
| **Sandbox**                                             | Testing environment with test cards and a separate API key from production. See [testing and going live](/getting-started/testing-and-going-live).                                                                                                                                                       |
| **Session Token**                                       | Short-lived (5 minute) token generated from your API key via the [authentication](/getting-started/authentication) endpoint. Used for browser-facing operations like [card entry forms](/capture-cards/hosted-card-entry-form).                                                                          |
| **SFTP**                                                | SSH File Transfer Protocol. Used for secure [batch card tokenization](/capture-cards/file-transfer-tokenization) and [token replacement](/use-tokens/file-transfer-token-replacement).                                                                                                                   |
| **Target Profile**                                      | Reusable configuration defining how PCI Booking parses or replaces card data in a specific third-party message format. Contains [content filters](#content-filter), certificates, and other settings. See [target profiles](/account-setup/target-profiles).                                             |
| **Token (Paycard)**                                     | A secure reference to a stored payment card. Replaces the actual card number in your systems. Learn how [tokenization works](/concepts/tokenization-explained).                                                                                                                                          |
| **Token Replacement**                                   | Process of substituting a token with real card data in outbound HTTP requests, file transfers, or responses. See [token replacement in request](/use-tokens/token-replacement-in-request) and the [token replacement API](/use-tokens/token-replacement-api).                                            |
| **Tokenization on Request**                             | Gateway mode where PCI Booking intercepts inbound HTTP requests from third parties, [tokenizes card data](/capture-cards/tokenization-on-request), and forwards a sanitized version to your API.                                                                                                         |
| **Tokenization on Response**                            | Forward proxy mode where PCI Booking [tokenizes card data found in a third party's HTTP response](/capture-cards/tokenization-on-response) before passing it to you.                                                                                                                                     |
| **Universal Tokenization**                              | [Pre-built parsing profiles](/capture-cards/universal-tokenization) maintained by PCI Booking for commonly used third parties, so you do not need to create custom profiles.                                                                                                                             |
| **UPG (Universal Payment Gateway)**                     | PCI Booking's [payment proxy](/use-tokens/universal-payment-gateway) that intercepts merchant-to-PSP requests and injects real card data from tokens. Supports 100+ [gateway integrations](/use-tokens/gateway-guidance).                                                                                |
| **Void**                                                | Cancels a pre-authorization before capture, releasing the hold without any fund transfer. See [refunds and voids](/use-tokens/refunds-voids).                                                                                                                                                            |
| **XID**                                                 | 3DS v1 transaction identifier that uniquely identifies a [3DS authentication](/manage-tokens/3ds-auth-management) session.                                                                                                                                                                               |


# Return Codes
Source: https://developers.pcibooking.net/reference/return-codes

HTTP status codes and PCI Booking-specific error codes. Lookup table for API response troubleshooting.

PCI Booking API responses use standard HTTP status codes combined with application-specific return codes. Error responses include a numeric `returnCode` and a human-readable `description`.

## Success Codes

| HTTP Status   | Meaning                        |
| ------------- | ------------------------------ |
| `200 OK`      | Request completed successfully |
| `201 Created` | Resource created successfully  |

## Error Response Format

Error responses are returned in the same format as the request. For XML requests:

```xml theme={null}
<Response>
  <returnCode>-125</returnCode>
  <description>Invalid card number</description>
</Response>
```

For JSON requests:

```json theme={null}
{
  "returnCode": -125,
  "description": "Invalid card number"
}
```

## Application Error Codes

| Return Code | Name                 | Description                                                               |
| ----------- | -------------------- | ------------------------------------------------------------------------- |
| `-112`      | Bad Destination      | Destination URL is unreachable or invalid                                 |
| `-113`      | Disallowed Operation | Not authorized to perform this action on the resource                     |
| `-123`      | Bad Document         | Request body is not valid XML or is badly formatted                       |
| `-125`      | Bad Data             | Input data is invalid (e.g., invalid card number, missing required field) |
| `-126`      | Data Too Long        | Input data exceeds maximum allowed length                                 |
| `-150`      | System Error         | Internal server error                                                     |
| `-160`      | URI Not Found        | Requested resource (e.g., card token) does not exist                      |
| `-168`      | Data Conflict        | Action cannot be performed on the resource in its current state           |
| `-174`      | Too Many Items       | Request exceeds the maximum number of allowed items                       |
| `-175`      | Timeout              | Operation timed out (e.g., third-party server did not respond)            |
| `-176`      | Too Many Retries     | Maximum retry attempts exceeded                                           |
| `-179`      | Bad Parameter        | Request parameter is invalid or missing                                   |
| `-180`      | User Blocked         | User account is blocked                                                   |
| `-1002`     | Missing Auth Header  | The `Authorization` header is missing from the request                    |
| `-1003`     | Unauthorized         | Authentication failed (invalid API key or credentials)                    |
| `-1004`     | Password Expired     | User password must be changed before API access is allowed                |
| `-1005`     | User Suspended       | User account has been suspended                                           |
| `-1006`     | User Closed          | User account has been closed                                              |
| `-1010`     | Locked for Updates   | Resource is locked and cannot be modified                                 |

## HTTP Status Code Mapping

PCI Booking maps application errors to standard HTTP status codes:

| HTTP Status                 | When Returned                                                        |
| --------------------------- | -------------------------------------------------------------------- |
| `400 Bad Request`           | Bad data, bad document, bad parameter, data too long, too many items |
| `401 Unauthorized`          | Missing auth header, unauthorized, password expired                  |
| `403 Forbidden`             | Disallowed operation, user closed                                    |
| `417 Expectation Failed`    | User suspended                                                       |
| `426 Upgrade Required`      | User blocked                                                         |
| `404 Not Found`             | URI not found                                                        |
| `408 Request Timeout`       | Timeout                                                              |
| `409 Conflict`              | Data conflict, locked for updates                                    |
| `500 Internal Server Error` | System error                                                         |

## Related

* [API Conventions](/reference/api-conventions) - Request and response formats, headers, and common patterns
* [Authentication](/getting-started/authentication) - API key, session token, and access token setup


# Troubleshooting
Source: https://developers.pcibooking.net/reference/troubleshooting

Diagnose and resolve common integration issues with PCI Booking.

Common issues and how to resolve them. If your problem is not covered here, contact [PCI Booking support](https://pcibooking.net/pci-booking-support/).

## Authentication Errors

### 401 Unauthorized

**Symptom:** API returns error code `-1003` with "Not authorized to access this resource."

**What to check:**

1. Verify the `Authorization` header uses the correct format: `Authorization: APIKEY your-key-here`
2. If using a session token, confirm it has not expired (sessions time out after 15 minutes of inactivity).
3. If using an access token, verify it was generated for the correct endpoint.
4. Check that the authenticated user has the required permission for the operation (e.g., `CanTokenize` for card storage, `ForceCVVRetentionPolicy` for CVV policy updates).

### Multiple auth methods provided

PCI Booking accepts API Key, Session Token, and Access Token authentication. If multiple are provided, precedence is: Session Token > Access Token > API Key. If you are getting unexpected auth errors, make sure you are not accidentally sending conflicting credentials.

## Card Tokenization Issues

### Card validation failures

**Symptom:** Tokenization fails with error code `-179` or validation errors.

**What to check:**

1. **Luhn check:** The card number must pass the [Luhn algorithm](https://en.wikipedia.org/wiki/Luhn_algorithm). You can disable this with `validateLuhn=false` for cards that intentionally fail (e.g., some test cards).
2. **Expiration date:** If `ValidateExpiration=true` is set, expired cards are rejected. Set to `false` if you need to store expired cards (e.g., during migration).
3. **CVV format:** CVV must be 3 digits (4 for AMEX).
4. **Card number length:** Must be between 12 and 22 digits.

See [Card Validation Errors](/reference/card-validation-errors) for the full list of validation error messages.

### Hosted card form redirect not received

**Symptom:** A token is created in PCI Booking, but your server never receives the redirect to the success URL. You see tokens in your PCI Booking account that have no corresponding record in your system.

**What is happening:** When using the [URL-parameter card entry form](/capture-cards/hosted-card-entry-form), the redirect to your success URL happens entirely in the guest's browser. PCI Booking's server returns an HTTP response to the iframe that instructs the browser to navigate to your success URL. If the guest closes the tab, loses internet connectivity, or their browser blocks the redirect, the token exists on PCI Booking's side but your server never receives it.

**What to do:**

1. **Quick fix:** Use a unique `creatorReference` per reservation instead of a generic value. This lets you [query tokens](/api-reference/manage-tokens/query-tokens) by reference to find any that were created but not received.
2. **Recommended fix:** Switch to the [session-based card entry form](/capture-cards/hosted-card-entry-form#session-based-approach), which provides a server-to-server `CallBackURL` in addition to the browser redirect. The callback goes directly from PCI Booking's servers to yours and cannot be lost due to client-side issues.

With the session-based form, you get three independent layers of assurance:

* **Server-to-server callback** guarantees you receive the token
* **Success page redirect** continues to work for the guest's user experience
* **Unique creator reference** lets you query tokens as a safety net

### Token not found (error -160)

**Symptom:** API returns error code `-160` when trying to use a token.

**What to check:**

1. Verify the token URI is correct and complete (e.g., `https://service.pcibooking.net/api/payments/paycard/tok_abc123`).
2. The token may have been deleted. Deletions are permanent and cannot be reversed.
3. The token may have been auto-deleted by a CVV retention policy with `DeleteCardUponCVVCleanup` set to `true`.
4. Confirm the token belongs to the authenticated user. Tokens created by one user cannot be accessed by another unless [third-party permissions](/manage-tokens/third-party-permissions) have been set up.

## CVV Issues

### CVV retention policy locked (error -1010)

**Symptom:** Cannot update the CVV retention policy. API returns error code `-1010`.

**What is happening:** CVV retention policies can only be modified within 60 minutes of being set. After this window, the policy is locked.

**What to do:** Create a new token with the CVV and set the correct policy from the start. The 60-minute window is a PCI compliance requirement and cannot be bypassed.

### CVV not included in transaction

**Symptom:** A payment gateway transaction does not include the CVV, even though the token has a CVV stored.

**What to check:**

1. Verify the CVV has not expired. Check the `CvvEndRetentionDate` using [Get CVV Retention Policy](/api-reference/manage-tokens/get-cvv-retention-policy).
2. Check the destination whitelist. The CVV is only sent to destinations listed in the retention policy. If your payment gateway is not in the whitelist, the CVV is stripped.
3. Check the quota. Each destination has a maximum number of times the CVV can be sent to it. Once the quota is exhausted, the CVV is no longer included.

## Payment Gateway Issues

### Transaction rejected

**Symptom:** A transaction returns `Rejected` status.

**What to check:**

1. Read the `GatewayDescription` and `AcquirerDescription` fields. These contain the gateway's own rejection reason (e.g., insufficient funds, do-not-honor).
2. Review [gateway-specific guidance](/api-reference/process-cards/gateway-guidance) for your payment gateway. Some gateways have unique requirements:
   * **AMEX:** `myRef` is required and must be 6+ characters
   * **Authorize.net:** `ECCenabled` affects refund behavior
   * **Azul, First Data:** Require a client certificate
3. Verify the gateway credentials. If using `credentialsId`, confirm the stored credentials are still valid with [List Credentials](/api-reference/process-cards/list-credentials).

### Transaction timeout (error -175)

**Symptom:** API returns error code `-175` or the call times out.

**What to do:**

1. Do **not** retry the charge immediately. The original transaction may still be processing at the gateway.
2. Check the transaction status in your payment gateway's dashboard using the `myRef` you provided.
3. If the transaction went through at the gateway, use the gateway reference for subsequent Capture, Void, or Refund operations.
4. If using [fallback routing](/api-reference/process-cards/process-transaction#fallback-routing), PCI Booking automatically tries the next gateway in your `FallbackUpgs` list.

## Token Replacement Issues

### Card data not replaced in request

**Symptom:** The outbound request to the third party still contains the token URI instead of real card data.

**What to check:**

1. Verify the token URI format matches what PCI Booking expects. The token must be the full URI (e.g., `https://service.pcibooking.net/api/payments/paycard/tok_abc123`).
2. Check the content type. Token replacement works with JSON, XML/SOAP, form-encoded, and query string formats. The request body must be parseable in the declared content type.
3. For SFTP token replacement, verify the file type filter matches your file format. See [Supported File Types](/reference/api-conventions#supported-file-types-for-ftp-transfer).

## Network Tokenization Issues

### Card cannot be network-tokenized

**Symptom:** Network tokenization returns "Card cannot be Network-tokenized."

**What to check:**

1. Only Visa, Mastercard, and Amex cards support network tokenization.
2. The card must be active and not expired.
3. The issuing bank may not support network tokenization for this card.
4. Verify the cardholder details (name, address, IP) are provided. The card network uses these for risk scoring.

## Debugging Tips

### Use `ref` and `creatorReference` consistently

Always include a unique reference in every API call that supports it. This makes it easy to trace operations in the PCI Booking portal, match tokens to your internal records, and do reconciliation.

* **Tokenization:** Use the `ref` query parameter on [Store Paycard](/api-reference/tokenize-cards/store-paycard) or `creatorReference` on the hosted card form.
* **Gateway transactions:** Use the `myRef` body parameter on [Process Transaction](/api-reference/process-cards/process-transaction).
* **Token queries:** Search by reference with [Query Tokens](/api-reference/manage-tokens/query-tokens).

### Check the response format

PCI Booking returns errors in the same format as the request. If you send XML, errors come back as XML. If you send JSON, errors come back as JSON. Make sure your error handling parses both the `code` (or `returnCode`) and `moreInfo` fields for the full error detail.

### Contact support with context

When reaching out to support, include:

* The full API response body (especially the `code`, `message`, and `moreInfo` fields)
* The token URI or `myRef` value
* The endpoint URL you called and the HTTP method
* Whether you are using test or production credentials

## Related

* [Return Codes](/reference/return-codes) - Full list of PCI Booking error codes
* [Card Validation Errors](/reference/card-validation-errors) - Card number, expiration, and CVV validation errors
* [API Conventions](/reference/api-conventions) - Request and response formats, compression, pagination
* [Gateway-Specific Guidance](/api-reference/process-cards/gateway-guidance) - Per-gateway parameter requirements


# Versioning and Rate Limits
Source: https://developers.pcibooking.net/reference/versioning-and-rate-limits

PCI Booking API versioning policy and rate limit details. The API is unversioned and backwards compatible.

## API Versioning

PCI Booking does not version its API. There is a single API endpoint and all changes are backwards compatible. You do not need to specify a version number, pin to a version, or migrate between versions.

When new features are added, they are made available at the same base URL:

```text theme={null}
https://service.pcibooking.net/api
```

New fields may be added to response objects over time. Your integration should ignore unknown fields rather than failing on them. Existing fields, endpoints, and behaviors are not removed or changed in a breaking way.

If a breaking change is ever required, PCI Booking will notify affected customers directly with migration guidance and a transition period.

<Info>
  Check the [Changelog](/reference/changelog) for recent feature additions and bug fixes.
</Info>

## Rate Limits

PCI Booking enforces per-user rate limits on certain API endpoints. The rate limit is configured per account and measured in **requests per second**.

### Which endpoints are rate-limited

Rate limiting applies to the following endpoint groups:

| Endpoint Group         | Description                                                                                    |
| ---------------------- | ---------------------------------------------------------------------------------------------- |
| **Card management**    | Token operations: create, query, update, delete, duplicate, transfer, CVV management, 3DS data |
| **Payment gateway**    | Transaction processing via UPG: charge, pre-auth, capture, void, refund                        |
| **eWallet operations** | Payments Library session operations                                                            |

Other endpoints (account management, SFTP, stylesheet management, card capture forms) are not rate-limited.

### Rate limit behavior

* The limit is measured per calendar second. Each API user has a maximum number of allowed requests per second.
* When the limit is exceeded, the API returns HTTP `429 Too Many Requests` with a plain text message.
* There are no `Retry-After` or `X-RateLimit-*` response headers. Wait at least one second before retrying.

### Example 429 response

```text theme={null}
Rate limit exceeded max 10 requests per second for user example-user
```

### Increasing your rate limit

Rate limits are set per account. If your integration requires a higher throughput, contact PCI Booking support to adjust your limit.

<Warning>
  If your account does not have a rate limit configured, no throttling is applied. This is the default for new accounts. PCI Booking may set a limit on your account if usage patterns require it.
</Warning>


# Introduction
Source: https://developers.pcibooking.net/start-here/introduction

PCI Booking tokenization platform. Capture, store, and process payment cards without PCI DSS scope on your servers.

## What Is PCI Booking?

PCI Booking is a **tokenization service** that outsources your PCI DSS compliance. We securely capture, store, and send payment card data so you never have to touch it.

You integrate once. We handle the card data. You work only with tokens.

## Three Core features

| feature                                      | What It Does                                                                                                                                                             |
| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **[Capture Cards](/capture-cards/overview)** | Capture card data through hosted forms, email/SMS links, client-side libraries, file uploads, or migration and receive a token back.                                     |
| **[Manage Cards](/manage-tokens/overview)**  | Query token details, update expiry dates, manage CVV, set permissions, run risk checks, or delete tokens.                                                                |
| **[Use Tokens](/use-tokens/overview)**       | Send card data where it needs to go: to a PSP for payment processing, to a partner via HTTP relay, via batch file delivery, or displayed securely to an authorized user. |

Processing a payment is simply **detokenization**. PCI Booking replaces the token with real card data and sends it to the PSP on your behalf.

## Service Endpoint

All API calls go to:

```
https://service.pcibooking.net/api
```

## Prerequisites

* Working knowledge of HTTP requests
* Familiarity with JSON or XML payloads
* A PCI Booking account with an API key. [Talk to our experts](https://pcibooking.net/talk-to-pci-experts/) to request a sandbox account.

## AI Agent Integration

Building an AI agent or tool that needs to work with PCI Booking? We publish machine-readable documentation following the [llms.txt convention](https://llmstxt.org/) in two formats:

| File                                                                | Size     | Best For                                                                                                                                                                                                                                                        |
| ------------------------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`/llms.txt`](https://developers.pcibooking.net/llms.txt)           | \~4 KB   | A lightweight index with page titles, short descriptions, and links. Use this when your LLM can follow URLs or when you only need to find the right page.                                                                                                       |
| [`/llms-full.txt`](https://developers.pcibooking.net/llms-full.txt) | \~550 KB | The full content of all 160+ documentation pages in a single file. Use this when your LLM needs the actual content upfront without making additional requests. Note: this is a large file and may consume a significant portion of your model's context window. |

## Next Steps

* [Quickstart](/start-here/quickstart). Tokenize your first card in minutes.
* [Capture Cards](/capture-cards/overview). All card capture methods.
* [Manage Tokens](/manage-tokens/overview). Token lifecycle management.
* [Use Tokens](/use-tokens/overview). Send card data to PSPs, partners, or display it.


# Quickstart
Source: https://developers.pcibooking.net/start-here/quickstart

Tokenize a card and process a payment in minutes using PCI Booking's hosted card form and Universal Payment Gateway

This quickstart walks through one common flow: capture a card using the hosted card entry form, inspect the token, and process a payment through the Universal Payment Gateway.

This is one example. Each step has alternatives you can swap in depending on your use case:

| Step         | This Example                    | Other Options                                                                                                                                                                                                                                                                          |
| ------------ | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Tokenize** | Hosted Card Entry Form (iframe) | [Card Entry Form Session](/capture-cards/hosted-card-entry-form), [Card By Link](/capture-cards/card-by-link), [Payments Library](/payments-library/setup), [Card Migration](/capture-cards/store-card-migration), [Tokenization on Response](/capture-cards/tokenization-on-response) |
| **Inspect**  | Query token metadata            | [Query by reference](/manage-tokens/query-retrieve)                                                                                                                                                                                                                                    |
| **Use**      | Charge via UPG                  | [Authorize & Capture](/use-tokens/authorize-capture), [Token Replacement](/use-tokens/token-replacement-in-request), [Card Display](/use-tokens/card-display)                                                                                                                          |

See [Capture Cards Overview](/capture-cards/overview) and [Use Tokens Overview](/use-tokens/overview) for the full list.

***

## Step 1: Authenticate

Log in to your PCI Booking account and navigate to the API Keys section. Copy your API key. You will use it for server-to-server calls in the format:

```http theme={null}
Authorization: APIKEY your-api-key
```

The hosted card entry form runs in the cardholder's browser, so it cannot use your API key directly. Instead, generate a temporary session token:

```bash theme={null}
curl -X POST https://service.pcibooking.net/api/payments/paycard/tempsession \
  -H "Authorization: APIKEY your-api-key"
```

The response returns a session token as a plain string:

```text theme={null}
33b245a015cf4d10a3ca885e7f4c5600
```

Save this token. you will pass it as a query parameter when building the card form URL in the next step.

## Step 2: Tokenize a Card

Build a URL to the PCI Booking hosted card entry form. This URL is the `src` of an iframe you embed in your page. When the browser loads this URL, PCI Booking serves a secure card entry form directly to the cardholder. Card data never touches your servers.

The URL includes the session token from Step 1 and your configuration as query parameters:

```text theme={null}
https://service.pcibooking.net/api/payments/capturecard?accessToken=YOUR_SESSION_TOKEN&language=en&autoDetectCardType=true&success=https://yoursite.com/success&failure=https://yoursite.com/failure
```

This example uses only a few basic parameters. The card entry form supports many additional options including custom styling, card type restrictions, CVV requirements, and more. See the [full parameter reference](/api-reference/tokenize-cards/request-card-entry-form) for the complete list.

Embed it in your page:

```html theme={null}
<iframe
  src="https://service.pcibooking.net/api/payments/capturecard?accessToken=YOUR_SESSION_TOKEN&language=en&autoDetectCardType=true&success=https://yoursite.com/success&failure=https://yoursite.com/failure"
  width="400"
  height="350"
  frameborder="0">
</iframe>
```

After the cardholder submits the form, PCI Booking tokenizes the card and redirects to your `success` URL with the token appended. You can also use a [callback URL](/capture-cards/hosted-card-entry-form) instead of redirect URLs.

<Info>
  There are other ways to tokenize cards: [Card Entry Form Sessions](/capture-cards/hosted-card-entry-form), [Card By Link](/capture-cards/card-by-link), [Payments Library](/payments-library/setup), [direct API storage](/capture-cards/store-card-migration), and more. See [Capture Cards Overview](/capture-cards/overview).
</Info>

## Step 3: Retrieve Your Token

Confirm the card was stored by checking the token metadata. This includes the card brand, last four digits, expiration date, and the issuing bank and country. useful for routing decisions between PSPs.

```bash theme={null}
curl -X GET "https://service.pcibooking.net/api/payments/paycard/{token}/meta" \
  -H "Authorization: APIKEY your-api-key"
```

The response includes the masked card number, expiry, card brand, and token metadata. You will never see the full card number through this endpoint.

## Step 4: Use Your Token (Process a Payment)

Send the token through the Universal Payment Gateway (UPG). PCI Booking detokenizes the card and forwards it to your PSP.

For testing, PCI Booking provides two built-in mock payment gateways:

| Mock Gateway    | Behavior                        |
| --------------- | ------------------------------- |
| **NULLSuccess** | Always approves the transaction |
| **NULLFailure** | Always declines the transaction |

Mock gateways require no credentials and return instant responses. Use them to test your integration before connecting a real PSP.

```bash theme={null}
curl -X POST https://service.pcibooking.net/api/paymentgateway \
  -H "Authorization: APIKEY your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "PaymentGateway": {
      "Name": "NULLSuccess"
    },
    "CardToken": "{token}",
    "OperationType": "Charge",
    "Amount": 100.00,
    "Currency": "USD"
  }'
```

PCI Booking replaces the token with real card data, sends it to the gateway, and returns the result. You never see the card. With `NULLSuccess`, the response will always be a successful charge.

When you are ready for production, replace `NULLSuccess` with your real PSP name and credentials:

```bash theme={null}
curl -X POST https://service.pcibooking.net/api/paymentgateway \
  -H "Authorization: APIKEY your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "PaymentGateway": {
      "Name": "YourPSPName",
      "Credentials": {
        "MerchantId": "your-merchant-id",
        "ApiKey": "your-psp-api-key"
      }
    },
    "CardToken": "{token}",
    "OperationType": "Charge",
    "Amount": 100.00,
    "Currency": "USD"
  }'
```

<Info>
  You can also store your PSP credentials in PCI Booking and pass a `credentialsId` query parameter instead of including credentials in every request. See [Gateway Credentials](/account-setup/gateway-credentials).
</Info>

<Info>
  Processing payments through the UPG is one way to use a token. You can also [relay card data via HTTP](/use-tokens/token-replacement-in-request), [relay via file](/use-tokens/file-transfer-token-replacement), or [display the card](/use-tokens/card-display). See [Use Tokens Overview](/use-tokens/overview).
</Info>

## What's Next

* [Authentication](/getting-started/authentication): All authentication methods in detail.
* [Capture Cards Overview](/capture-cards/overview): All card capture and tokenization methods.
* [Token Management](/manage-tokens/overview): Query, update, and manage stored tokens.
* [Use Tokens Overview](/use-tokens/overview): All ways to use your tokens.
* [Payments Library](/payments-library/overview): Cards, Apple Pay, Google Pay, PayPal via the Payments Library.


# System Status
Source: https://developers.pcibooking.net/support/system-status

Real-time operational status of PCI Booking's tokenization and payment processing services.

The system status page shows the real-time operational state of PCI Booking's core services, including tokenization, payment processing, the API gateway, and the merchant portal. Each service component is listed with its current status: operational, degraded performance, partial outage, or major outage.

## Current Status

<iframe />

## What the Status Page Monitors

The status page tracks the operational state of each core PCI Booking component:

* **Tokenization Service.** Card capture, token creation, and vault storage across all tokenization methods (hosted form, API, file transfer, response parsing).
* **Payment Processing (UPG).** The Universal Payment Gateway that routes charges, authorizations, refunds, and voids to PSPs.
* **API Gateway.** The main API endpoint at `service.pcibooking.net` that handles all inbound requests, authentication, and rate limiting.
* **Payments Library.** The client-side SDK infrastructure that serves the card form, digital wallet integrations, and session management.
* **Merchant Portal.** The web portal at `users.pcibooking.net` where merchants manage their account, credentials, and token data.

Each component displays one of four statuses: **Operational**, **Degraded Performance**, **Partial Outage**, or **Major Outage**.

## Service Level Agreement

PCI Booking targets **99.95% uptime** for its core tokenization and payment processing services, measured on a monthly basis. Scheduled maintenance windows are excluded from uptime calculations. For SLA details specific to your account, refer to your service agreement or contact your account manager.

## Incident Notifications

To stay informed about service disruptions and scheduled maintenance, subscribe to status notifications. You will receive alerts when an incident is reported, updated, or resolved.

Visit the status page above and click the **Subscribe** button to choose your preferred notification channel (email or webhook). Webhook subscribers receive a JSON payload with the incident details, affected components, and current status, which can be integrated into your own monitoring or alerting systems.

## Incident Response

When an incident occurs, PCI Booking's operations team follows a structured response process:

1. **Detection.** Automated monitoring detects the issue and triggers an alert.
2. **Acknowledgment.** The operations team acknowledges the incident and posts an initial update on the status page.
3. **Investigation.** The team investigates the root cause and provides periodic updates (typically every 30 minutes during active incidents).
4. **Resolution.** The issue is resolved and the status page is updated to reflect the fix.
5. **Post-incident review.** For major incidents, PCI Booking conducts a post-incident review and may share a summary with affected customers.

## Scheduled Maintenance

PCI Booking schedules maintenance windows in advance and announces them on the status page. Maintenance notifications include the expected start time, duration, and which services may be affected. Where possible, maintenance is performed with zero downtime using rolling deployments.

## Need Help?

If you are experiencing issues that are not reflected on the status page, or if you need assistance during an incident, contact the PCI Booking support team:

* **Email:** [support@pcibooking.net](mailto:support@pcibooking.net)
* **Portal:** [PCI Booking Portal](https://users.pcibooking.net) (submit a support ticket)


# Collect a Card and Process a Payment
Source: https://developers.pcibooking.net/use-cases/capture-and-charge

Securely collect card details from a cardholder and charge through any connected payment gateway. PCI Booking handles the card data so your servers never touch it.

This workflow covers collecting card details directly from the cardholder and charging the card through a payment gateway using PCI Booking. Your servers never handle raw card data, keeping you out of PCI scope while you process payments through any supported gateway.

## Card capture and payment processing options

| Capture Method                                                                          | Charge Method                                                                                                          |
| --------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| [Hosted Card Entry Form](/capture-cards/hosted-card-entry-form) - embed in your website | [Universal Payment Gateway](/use-tokens/universal-payment-gateway) - send to gateway via PCI Booking **(recommended)** |
| [Card By Link](/capture-cards/card-by-link) - send a capture link via email/SMS         | [Token Replacement](/use-tokens/token-replacement-in-request) - inject card data into your own gateway API call        |

You can mix and match any capture method with any charge method. The example below uses Card By Link and Universal Payment Gateway.

## Step 1: Set Up Your Payment Gateway

Before processing charges, set up an account with a supported payment gateway.

1. Find a supported gateway on the [PCI Booking website](https://pcibooking.net/universal-payment-gateway/).
2. Set up an account with that gateway (or use existing credentials).
3. Store your gateway credentials in PCI Booking via the [Gateway Credentials](/account-setup/gateway-credentials) setup.

## Step 2: Customize the Card Capture Experience

Brand the capture experience to match your business:

* [Custom Translations](/account-setup/custom-translations) - localize form labels and messages
* [Stylesheets](/account-setup/stylesheets) - apply custom CSS to the card form
* [Card By Link Templates](/account-setup/card-by-link-templates) - customize the Card By Link email, SMS, and landing page

## Step 3: Collect the Card

Using Card By Link as an example:

1. Send a [Card By Link request](/api-reference/tokenize-cards/cotp-send-card-form) to PCI Booking with the cardholder's email or phone number. Include optional details like amount, currency, and reference number.
2. PCI Booking sends a secure link to the cardholder via email or SMS.
3. The cardholder clicks the link and enters their card details on a mobile-friendly, PCI Booking-hosted page.
4. If configured, a [3D Secure prompt](/account-setup/3ds-merchant-setup) is displayed.
5. PCI Booking validates, tokenizes the card, and sends a [callback](/api-reference/tokenize-cards/cotp-callback) to your system with the token.

## Step 4: Charge the Card

Send a [Process Transaction](/api-reference/process-cards/process-transaction) request with:

* Card token (from the callback)
* Amount and currency
* Gateway name
* Gateway credentials

PCI Booking injects the real card data and forwards the charge to the gateway. You receive the gateway's response directly.

## Related

* [Universal Payment Gateway](/use-tokens/universal-payment-gateway). Full guide on charging cards through supported gateways.
* [Authorize and Capture](/use-tokens/authorize-capture). Two-step auth + capture flow instead of direct charge.
* [Refunds and Voids](/use-tokens/refunds-voids). Reverse or refund a processed transaction.
* [Charge and Save for Future Payments](/use-cases/capture-charge-and-store). Need to save the card for future charges? See the full lifecycle guide.
* [Process OTA and Channel Manager Payments](/use-cases/third-party-to-gateway). Receiving cards from a third party instead? See this workflow.


# Collect a Guest's Card and Share It with a Hotel
Source: https://developers.pcibooking.net/use-cases/capture-and-relay-to-hotel

Collect card details directly from a guest via a secure form or email link, then give a hotel property access to view the card. All PCI compliant, no card data on your servers.

This workflow is for when you need to capture the card directly from the cardholder (for example, at booking time on your website or through an email link) and then share it with a hotel. Your servers never handle raw card data, keeping you out of PCI scope. If you already have a token and just need to share it with a hotel, see [Send Stored Card Details to a Hotel Property](/use-cases/capture-and-send-to-hotel) instead.

## Card capture and delivery options

| Capture Method                                                                          | Delivery Method                                                                                                                                        |
| --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [Hosted Card Entry Form](/capture-cards/hosted-card-entry-form) - embed in your website | [Card Display with OTP](/use-tokens/card-display-otp) - hotel receives a secure link and verifies identity with OTP to view the card **(recommended)** |
| [Card By Link](/capture-cards/card-by-link) - send a capture link via email/SMS         | [Token Replacement](/use-tokens/token-replacement-in-request) - send card data directly to the hotel's API                                             |

You can mix and match. The example below uses Card By Link to capture and Card Display with OTP to share the card with the hotel.

## Step 1: Collect the Card

Using Card By Link as an example:

1. Send a [Card By Link request](/api-reference/tokenize-cards/cotp-send-card-form) to PCI Booking with the cardholder's email or phone number. Include optional details like amount, reference number, and header/footer text for the landing page.
2. PCI Booking sends a secure link to the cardholder.
3. The cardholder enters their card details on the hosted page.
4. If configured, a [3D Secure prompt](/account-setup/3ds-merchant-setup) is displayed.
5. PCI Booking tokenizes the card and sends a [callback](/api-reference/tokenize-cards/cotp-callback) with the token.

## Step 2: Share the Card with the Hotel

Using Card Display with OTP as an example:

1. Call the [Card Display OTP endpoint](/api-reference/process-cards/card-display-otp) with the card token, the hotel contact's email, phone number, and name. Set a time-to-live for how long the link should remain valid.
2. PCI Booking sends the hotel contact an email containing a secure link.
3. The hotel contact clicks the link and verifies their identity by entering a code sent to their phone via SMS.
4. After verification, the card details are displayed on PCI Booking's hosted page. The session stays active for 15 minutes.
5. Delete the token when no longer needed.

No portal setup or user accounts are needed on the hotel's side. PCI Booking handles the entire identity verification and card display flow.

## Related

* [Card Display with OTP](/use-tokens/card-display-otp). Full guide on the OTP-secured card display flow.
* [Third-Party Permissions](/manage-tokens/third-party-permissions). Control which merchants can access your tokens.
* [CVV Retention Policy](/capture-cards/cvv-retention-policy). Configure CVV access for card display.
* [Send Stored Card Details to a Hotel](/use-cases/capture-and-send-to-hotel). Already have a token? Share it with a hotel without re-capturing.
* [Collect and Process a Payment](/use-cases/capture-and-charge). Need to charge the card instead of sharing it with a hotel?


# Send Stored Card Details to a Hotel Property
Source: https://developers.pcibooking.net/use-cases/capture-and-send-to-hotel

Tokenize a guest's card and let the hotel securely view or retrieve the card details, without the card data touching your systems.

This workflow covers tokenizing a card from any source and giving a hotel access to view the card details. Use this when you already have a token (or are tokenizing from a third-party source like an OTA or channel manager) and need to share it with a hotel. If you need to capture the card directly from the cardholder first, see [Collect a Guest's Card and Share with a Hotel](/use-cases/capture-and-relay-to-hotel) instead.

## Step 1: Tokenize the Card

Capture and tokenize the card using any of PCI Booking's methods:

* [Hosted Card Entry Form](/capture-cards/hosted-card-entry-form) - embed a card form in your website
* [Card By Link](/capture-cards/card-by-link) - send a secure capture link via email or SMS
* [Tokenization on Response](/capture-cards/tokenization-on-response) - tokenize card data from a third-party API response
* [Universal Tokenization](/capture-cards/universal-tokenization) - tokenize cards from any source format

The result is a card token (a URI pointing to the stored card details in PCI Booking).

## Step 2: Send the Card to the Hotel

How you deliver the card to the hotel depends on your integration approach:

### Option A: Card Display with OTP (Recommended)

Send the hotel contact a secure link. PCI Booking handles identity verification and card display. No portal setup or user accounts needed on the hotel's side.

1. Call the [Card Display OTP endpoint](/api-reference/process-cards/card-display-otp) with the card token, the hotel contact's email, phone number, and name.
2. PCI Booking sends an email with a secure link.
3. The hotel contact clicks the link and verifies their identity via SMS code.
4. Card details are displayed on PCI Booking's hosted page.

See [Card Display with OTP](/use-tokens/card-display-otp) for full details.

### Option B: Card Display (iframe in your portal)

If you operate your own portal where hotels can log in, display the card details in a secure iframe embedded in your system.

* Generate a [Card Display Form](/api-reference/process-cards/request-card-display-form) link for the token.
* Embed the iframe in your portal. The card details render inside PCI Booking's secure domain, so card data never touches your servers.

See [Card Display](/use-tokens/card-display) for setup details.

### Option C: Token Replacement

Send the card details directly to the hotel's API using [Token Replacement](/use-tokens/token-replacement-in-request).

* Build an API request to the hotel's system containing the card token.
* PCI Booking replaces the token with real card data in transit.
* The hotel receives the card details without you ever handling them.

## Related

* [Card Display with OTP](/use-tokens/card-display-otp). OTP-secured card display with no portal needed.
* [Third-Party Permissions](/manage-tokens/third-party-permissions). Control which properties and merchants can access your tokens.
* [CVV Retention Policy](/capture-cards/cvv-retention-policy). If the hotel needs to see the CVV, set a retention policy before they access the card.
* [Process OTA and Channel Manager Payments](/use-cases/third-party-to-gateway). Need to charge the card instead of sharing it? See this workflow.
* [Share a Token Between Merchants](/use-cases/share-token-between-merchants). Both companies on PCI Booking? Share the token directly without relaying card data.


# Charge a Card and Save It for Future Payments
Source: https://developers.pcibooking.net/use-cases/capture-charge-and-store

Collect a guest's card, process the payment, and securely store a token for repeat charges, all in one PCI-compliant flow. Works with any PSP through PCI Booking.

This workflow covers the full lifecycle of a guest's card: capturing it on first visit, charging it, and storing a PCI DSS compliant token for future use. By tokenizing at capture time, you can process recurring payments and send card details to a property management system (PMS) without ever handling raw card data.

## Capture and charge a new customer's card

When a new customer arrives (or a returning customer provides a new card), use the Payments Library to handle card capture, payment, and tokenization in a single flow. The Payments Library renders a secure card form inside your checkout page, processes the payment through your PSP, and returns a token, all without card data touching your servers.

### Step 1: Set Up the Payments Library

Integrate the Payments Library into your web or mobile application. The library handles the card form UI, payment processing, and tokenization. You can render the card form in popup mode (opens a modal overlay) or iframe mode (embeds directly in your page layout). Both modes keep card data inside PCI Booking's secure environment.

* [Payments Library Setup Guide](/payments-library/setup). How to embed and configure the library.
* [Supported Payment Methods](/payments-library/supported-methods). Available payment methods (card, Apple Pay, Google Pay, etc.).

### Step 2: Initiate a Charge and Tokenize Session

Your backend calls the PCI Booking API to create a session with the `CHARGE_AND_TOKENIZE` operation type. This session specifies the PSP credentials, charge amount, and currency. PCI Booking returns a signed session token (JWS) that your frontend passes to the Payments Library. The session token is single-use and expires after a short period, so it must be created fresh for each transaction.

* [Create Session API Reference](/api-reference/payments-library/create-session). Use the `CHARGE_AND_TOKENIZE` operation type.

### Step 3: Customer completes the payment

The Payments Library displays the card form (or digital wallet buttons for Apple Pay, Google Pay, etc.) to the customer. The customer enters their card details or selects a wallet. The library sends the card data directly to PCI Booking, which charges the card through your configured PSP and tokenizes the card in one step. Your frontend receives a callback with the transaction result and the token.

### Step 4: Store the Token

Once the Payments Library completes processing, PCI Booking returns the token (a `cardURI`). Store this token in the customer's profile in your system for future use. The token is safe to store in any database since it contains no actual card data. You can query the token later to retrieve metadata such as the masked card number, brand, and expiry date without accessing the real card number.

## Charge a returning customer's stored card

When a returning customer makes a new reservation and wants to use their stored card, charge it directly through the API using the token you stored earlier. There is no need to recapture the card or present a payment form.

### Step 1: Send a Charge Request

Use the [Universal Payment Gateway](/use-tokens/universal-payment-gateway) to send a charge request to the selected PSP using the stored token. Pass the `cardURI` token, amount, currency, and your PSP credentials. PCI Booking retrieves the real card data from its vault and submits the charge to the PSP on your behalf.

* [Charge Guide](/use-tokens/charge). How to charge a card through a supported PSP.
* [Process Transaction API Reference](/api-reference/process-cards/process-transaction). API details for submitting a charge with a stored token.

### Step 2: Handle the Response

PCI Booking returns the PSP's response, including approval status, transaction reference, and any error codes. Store the transaction reference for later use if you need to process a [refund or void](/use-tokens/refunds-voids). If the charge fails (for example, due to insufficient funds or an expired card), the token remains valid and you can retry or prompt the customer to provide a new card.

### Handling Expired Cards

If a returning customer's card has expired since their last visit, you do not need to collect the full card number again. Use the [Update Expired Card](/use-cases/update-expired-card) flow to refresh the token with a new expiration date or new card details while preserving the existing token reference in your system.

## Sending Card Details to a PMS

When you need to send card details to a Property Management System (PMS), use Token Replacement to inject the real card data into an outgoing API request to the PMS. The card data never passes through your servers.

* [Token Replacement Guide](/use-tokens/token-replacement-in-request). How token replacement works for outgoing requests.
* [Token Replacement API Reference](/api-reference/process-cards/token-replacement). API details for token replacement requests.

## Related

* [Payments Library Overview](/payments-library/overview). Full overview of the Payments Library and its capabilities.
* [Universal Payment Gateway](/use-tokens/universal-payment-gateway). Alternative way to process payments through supported gateways.
* [Refunds and Voids](/use-tokens/refunds-voids). Reverse or refund a processed transaction.
* [Collect and Process a Payment](/use-cases/capture-and-charge). Just need to charge without storing? See this guide.
* [Update an Expired Card Token](/use-cases/update-expired-card). Card expired? Update the token without re-collecting the full card number.


# PSD2 and 3D Secure Implementation Guide
Source: https://developers.pcibooking.net/use-cases/comply-with-psd2

Add 3D Secure (3DS2) authentication to your payment flow with PCI Booking. Supports hosted forms, third-party 3DS data, and in-transit tokenization. Includes test cards for all challenge types.

The EU's [PSD2 (Payment Services Directive)](https://en.wikipedia.org/wiki/Payment_Services_Directive) requires Strong Customer Authentication (SCA) for online card payments. [3D Secure 2 (3DS2)](https://en.wikipedia.org/wiki/3-D_Secure) satisfies the SCA requirement by verifying the cardholder's identity during the transaction. PCI Booking handles the 3DS2 flow on your behalf, so you can add frictionless authentication to your payment process without building the 3DS integration yourself.

## How PCI Booking Handles 3D Secure

PCI Booking supports 3DS authentication in three ways, depending on how you capture cards:

### Hosted Card Entry Form with 3DS

When you capture a card directly from the cardholder using the [Hosted Card Entry Form](/capture-cards/hosted-card-entry-form), enable 3DS in your [merchant setup](/account-setup/3ds-merchant-setup) and PCI Booking triggers the 3DS2 challenge automatically during card capture. The cardholder completes authentication on the same page, and you receive the fully authenticated token in the callback.

### Store 3DS authentication from a third party

When you receive 3DS authentication data from a third party (for example, an OTA that has already verified the cardholder), use the [Store 3DS Authentication](/api-reference/manage-tokens/store-3d-token) endpoint to attach the 3DS result to an existing card token. The stored authentication data can then be used when processing a charge through the payment gateway.

### Tokenize in transit with 3DS data

When tokenizing card data in transit from a third party using [Tokenization on Response](/capture-cards/tokenization-on-response) or [Tokenization on Request](/capture-cards/tokenization-on-request), PCI Booking preserves any 3DS authentication data alongside the token. This lets you charge the card with the original 3DS proof intact.

To configure your 3DS merchant details, follow the [3DS Merchant Setup](/account-setup/3ds-merchant-setup) guide.

## Test Cards

Use these cards to test 3DS flows in your sandbox environment. For all cards below:

* **Expiry date**: any future date
* **Name on card**: `Three DS test`
* **CVV**: `123`

### Frictionless

Cardholder is authenticated based on transaction data alone. No additional challenge is shown. You receive a fully authenticated 3DS result immediately.

| Card Scheme | Card Number      |
| ----------- | ---------------- |
| Visa        | 4761739000060016 |
| Mastercard  | 5455330200000016 |

### Device Fingerprint (DFP)

The issuer requests additional device information for risk analysis. The cardholder does not see any change in the flow.

| Card Scheme | Card Number      |
| ----------- | ---------------- |
| Visa        | 4761739001010010 |
| Mastercard  | 5185520050000010 |

### Challenge

The issuer requires a user challenge (OTP prompt).

| Card Scheme | Card Number      | Success OTP | Fail OTP |
| ----------- | ---------------- | ----------- | -------- |
| Visa        | 4018810000150015 | 0101        | 3333     |
| Mastercard  | 5299910010000015 | 4445        | 9999     |

### Device Fingerprint + Challenge

The issuer requests device information followed by a user challenge.

| Card Scheme | Card Number      | Success OTP | Fail OTP |
| ----------- | ---------------- | ----------- | -------- |
| Visa        | 4018810000190011 | 0101        | 3333     |
| Mastercard  | 5420711000401011 | 4445        | 9999     |

## Frequently asked questions

### Does PCI Booking handle the 3DS challenge flow automatically?

Yes. When you use the Hosted Card Entry Form with 3DS enabled, PCI Booking manages the entire 3DS2 flow including device fingerprinting and challenges. Your system receives the final authentication result.

### Can I use 3DS with cards received from an OTA?

Yes. If the OTA has already completed 3DS authentication, you can store the authentication data alongside the card token using the [Store 3DS Authentication](/api-reference/manage-tokens/store-3d-token) endpoint.

## Related

* [3DS Merchant Setup](/account-setup/3ds-merchant-setup). Configure merchant information for 3DS authentication.
* [3DS Auth Management](/manage-tokens/3ds-auth-management). Store, retrieve, and delete 3DS data on tokens.
* [Collect and Process a Payment](/use-cases/capture-and-charge). Full card capture and charge workflow with 3DS support.


# PCI Booking Use Cases & Integration Guides
Source: https://developers.pcibooking.net/use-cases/how-do-i

Step-by-step guides for common PCI Booking workflows: capture and charge cards, share tokens between merchants, send card details to hotels, comply with PSD2, and more.

PCI Booking provides PCI DSS compliant payment tokenization for travel companies, hotels, and online merchants. Whether you need to capture and charge a card, send payment details to a hotel property, or process OTA virtual cards, the guides below walk you through each workflow step by step.

## Capture Cards

| Task                                           | Guide                                                                   |
| ---------------------------------------------- | ----------------------------------------------------------------------- |
| Capture cards via a hosted web form            | [Card Entry Form](/capture-cards/hosted-card-entry-form)                |
| Capture cards via email or SMS link            | [Card By Link](/capture-cards/card-by-link)                             |
| Capture cards in a web/mobile checkout         | [Payments Library](/payments-library/overview)                          |
| Tokenize cards from a third-party API response | [Tokenization on Response](/capture-cards/tokenization-on-response)     |
| Tokenize cards pushed to my API                | [Tokenization on Request](/capture-cards/tokenization-on-request)       |
| Tokenize cards from a batch file               | [File Transfer Tokenization](/capture-cards/file-transfer-tokenization) |
| Migrate cards from another provider            | [Card Migration](/capture-cards/store-card-migration)                   |

## Manage Cards

| Task                                            | Guide                                                             |
| ----------------------------------------------- | ----------------------------------------------------------------- |
| Query stored token details                      | [Query Cards](/manage-tokens/query-retrieve)                      |
| Update card expiry or details                   | [Update Cards](/manage-tokens/update-card-data)                   |
| Manage CVV for a token                          | [CVV Management](/manage-tokens/cvv-management)                   |
| Share a token with another PCI Booking customer | [Third-Party Permissions](/manage-tokens/third-party-permissions) |
| Run risk/fraud checks                           | [Risk Assessment](/use-tokens/risk-assessment)                    |
| Delete a stored token                           | [Delete Cards](/manage-tokens/delete-tokens)                      |

## Use Tokens

| Task                                           | Guide                                                                          |
| ---------------------------------------------- | ------------------------------------------------------------------------------ |
| Process a payment through a PSP                | [Universal Payment Gateway](/use-tokens/universal-payment-gateway)             |
| Send card data to any HTTP endpoint            | [Token Replacement in Request](/use-tokens/token-replacement-in-request)       |
| Send card data in my API response              | [Token Replacement in Response](/use-tokens/token-replacement-in-response)     |
| Send card data via batch file                  | [File Transfer Token Replacement](/use-tokens/file-transfer-token-replacement) |
| Display card details securely (in your portal) | [Card Display](/use-tokens/card-display)                                       |
| Display card details securely (via OTP link)   | [Card Display with OTP](/use-tokens/card-display-otp)                          |

## Common Workflows

| Scenario                                              | Use Case                                                                               |
| ----------------------------------------------------- | -------------------------------------------------------------------------------------- |
| Capture, charge, and store a card for future use      | [Charge and Save for Future Payments](/use-cases/capture-charge-and-store)             |
| Capture a card and charge it through a gateway        | [Collect and Process a Payment](/use-cases/capture-and-charge)                         |
| Tokenize a card and share it with a hotel             | [Send Stored Card Details to a Hotel](/use-cases/capture-and-send-to-hotel)            |
| Capture a card from a guest and give the hotel access | [Collect a Guest's Card and Share with a Hotel](/use-cases/capture-and-relay-to-hotel) |
| Receive a card from a third party and charge it       | [Process OTA and Channel Manager Payments](/use-cases/third-party-to-gateway)          |
| Share a token between two PCI Booking customers       | [Share a Card Token Between Merchants](/use-cases/share-token-between-merchants)       |
| Comply with PSD2 / 3D Secure                          | [PSD2 and 3D Secure Implementation](/use-cases/comply-with-psd2)                       |
| Update a stored card with a new expiration date       | [Update an Expired Card Token](/use-cases/update-expired-card)                         |

## Set Up My Account

| Task                           | Guide                                                     |
| ------------------------------ | --------------------------------------------------------- |
| Manage users and API keys      | [Manage Users](/account-setup/manage-users)               |
| Store PSP credentials          | [Gateway Credentials](/account-setup/gateway-credentials) |
| Configure security settings    | [Security Settings](/account-setup/security-settings)     |
| Customize card form appearance | [Stylesheets](/account-setup/stylesheets)                 |
| Set up 3D Secure               | [3DS Merchant Setup](/account-setup/3ds-merchant-setup)   |

## Build with AI

| Task                                          | Guide                                                                 |
| --------------------------------------------- | --------------------------------------------------------------------- |
| Feed PCI Booking docs to my AI agent or LLM   | [AI Agent Integration](/start-here/introduction#ai-agent-integration) |
| Get a lightweight doc index for AI tools      | [`/llms.txt`](https://developers.pcibooking.net/llms.txt)             |
| Get the full docs in one file for LLM context | [`/llms-full.txt`](https://developers.pcibooking.net/llms-full.txt)   |

## Alternative Payment Methods

| Task              | Guide                                              |
| ----------------- | -------------------------------------------------- |
| Accept Apple Pay  | [Apple Pay Setup](/account-setup/applepay-setup)   |
| Accept Google Pay | [Google Pay Setup](/account-setup/googlepay-setup) |
| Accept PayPal     | [PayPal Setup](/account-setup/paypal-setup)        |


# Share a Card Token Between Two Merchants
Source: https://developers.pcibooking.net/use-cases/share-token-between-merchants

Let two merchants use the same card token without duplicating card data. Saves on tokenization and storage fees while keeping both parties PCI compliant.

When two companies are both PCI Booking customers, they can share a token instead of relaying the card data and creating duplicate tokens. This is common in travel: an OTA tokenizes the guest's card and shares the token with the hotel, so the hotel can charge for incidentals or no-shows without the guest re-entering their card. Sharing saves on transaction fees (no relay + re-tokenization) and storage fees (one token instead of two).

## How token sharing works between merchants

* **Company A** tokenizes the card and owns the token.
* Company A **associates** the token with **Company B**.
* Company B can now perform actions on the token (charge, relay, display, etc.) as if they created it.
* Company A retains ownership, responsibility, and billing for all actions on the token.

## Step 1: Tokenize the Card

Company A tokenizes the card using any available method:

* [Hosted Card Entry Form](/capture-cards/hosted-card-entry-form)
* [Card By Link](/capture-cards/card-by-link)
* [Tokenization on Response](/capture-cards/tokenization-on-response)
* [Tokenization on Request](/capture-cards/tokenization-on-request)
* [Universal Tokenization](/capture-cards/universal-tokenization)

## Step 2: Associate the Token with Company B

Company A calls [Associate with Customer](/api-reference/manage-tokens/associate-with-customer) to grant Company B access to the token.

After association, Company A sends Company B the token URI. The token URI is not sensitive data and can be shared through any channel (email, API, etc.).

## Step 3: Company B Uses the Token

Once associated, Company B can perform any action on the token:

* Charge via [Universal Payment Gateway](/use-tokens/universal-payment-gateway)
* Relay to a third party via [Token Replacement](/use-tokens/token-replacement-in-request)
* View card details via [Card Display](/use-tokens/card-display)
* [Delete the token](/manage-tokens/delete-tokens) (removes their association, not the token itself)

<Info>
  **Ownership stays with Company A.** All fees for actions performed on the card are billed to Company A. CVV retention policy and long-term storage responsibility remain with Company A.
</Info>

## Step 4: Remove Access

When Company B no longer needs access, Company A calls [Disassociate from Customer](/api-reference/manage-tokens/disassociate-from-customer) to revoke access.

## Related

* [Third-Party Permissions](/manage-tokens/third-party-permissions). Overview of property and customer token associations.
* [CVV Retention Policy](/capture-cards/cvv-retention-policy). If Company B needs CVV access, Company A must set a retention policy first.
* [Send Stored Card Details to a Hotel](/use-cases/capture-and-send-to-hotel). Need to send the actual card data to a hotel instead of sharing the token?
* [Process OTA and Channel Manager Payments](/use-cases/third-party-to-gateway). Receiving cards from a third party and need to charge them?


# Process OTA and Channel Manager Card Payments
Source: https://developers.pcibooking.net/use-cases/third-party-to-gateway

Receive card data from Booking.com, Expedia, or any channel manager, tokenize it automatically, and charge through your payment gateway, without card data touching your servers.

This workflow covers receiving card details from a third party such as an OTA (Booking.com, Expedia) or channel manager, tokenizing the data automatically, and charging the card through a payment gateway. This is how most hotel platforms process OTA virtual credit cards (VCCs). PCI Booking intercepts the card data in transit so it never reaches your servers, keeping you out of PCI scope even when processing payments from any channel manager integration.

## Stage 1: Receive Card Details from Third Party

Two patterns depending on your integration:

### Pull: You Fetch from the Third Party's API

1. Third party sends you a notification with a reservation ID (no card data).
2. Your system calls the third party's API to retrieve reservation details including card data.
3. Route that API call through PCI Booking using [Tokenization on Response](/capture-cards/tokenization-on-response). PCI Booking intercepts the response, extracts the card data, stores it, and returns a token to you.
4. You store the reservation details and the token.

### Push: Third Party Sends Data to Your API

1. Third party sends reservation details (including card data) to your API endpoint.
2. Configure your endpoint behind PCI Booking using [Tokenization on Request](/capture-cards/tokenization-on-request). PCI Booking intercepts the incoming request, extracts the card data, stores it, and forwards the tokenized request to you.
3. You store the reservation details and the token.

## Stage 2: Charge the Card

Once you hold the token, charge the card through a payment gateway:

### Option A: Universal Payment Gateway (Recommended)

Use the [Universal Payment Gateway](/use-tokens/universal-payment-gateway) to charge the card directly.

1. Send a [Process Transaction](/api-reference/process-cards/process-transaction) request with the token, amount, currency, and gateway credentials.
2. PCI Booking injects the real card data and sends the charge request to the payment gateway.
3. You receive the gateway's response.

### Option B: Token Replacement

Use [Token Replacement](/use-tokens/token-replacement-in-request) to send the card to the gateway's API yourself.

1. Build an API request to your payment gateway containing the card token.
2. Route it through PCI Booking. PCI Booking replaces the token with real card data in transit.
3. The gateway processes the charge and responds.

## Frequently asked questions

### How does PCI Booking handle OTA virtual credit cards?

PCI Booking intercepts the card data from the OTA's API response (or incoming webhook), extracts the virtual card details, stores them as a token, and returns the token to your system. The card data never reaches your servers.

### Does this work with Booking.com and Expedia?

Yes. PCI Booking's tokenization works with any third party that sends card data via API, including Booking.com, Expedia, and all major channel managers.

## Related

* [Tokenization on Response](/capture-cards/tokenization-on-response). Tokenize card data from third-party API responses.
* [Tokenization on Request](/capture-cards/tokenization-on-request). Tokenize card data pushed to your API.
* [Universal Payment Gateway](/use-tokens/universal-payment-gateway). Charge cards through 100+ supported gateways.
* [Gateway Credentials](/account-setup/gateway-credentials). Set up your payment gateway credentials.
* [Send Stored Card Details to a Hotel](/use-cases/capture-and-send-to-hotel). Need to share the card with a hotel property instead of charging it?
* [Collect and Process a Payment](/use-cases/capture-and-charge). Capturing the card directly from the cardholder? See this workflow.


# Update an Expired Card Token
Source: https://developers.pcibooking.net/use-cases/update-expired-card

When a stored card expires and the guest gets a replacement, update the token's expiration date and CVV without re-collecting the full card number. Keeps recurring charges running.

When a stored card expires and the cardholder receives a new card with the same number but a new expiration date (and new CVV), you need to update the token. This avoids the friction of asking the guest to re-enter their full card details and prevents failed charges on recurring bookings.

This is common for hotels and travel platforms that store guest cards for future bookings, no-show charges, or recurring invoicing. When the card issuer sends a replacement with a new expiration date, you can update the token without asking the guest to go through the full card entry process again.

## Choosing the Right Approach

The best method depends on whether you need only the new expiration date or also the new CVV.

<Tabs>
  <Tab title="Expiration Only">
    Use the API to update the expiration date directly. This is the simplest approach and does not require any interaction with the cardholder.

    **Best for:** Situations where CVV is not required for charges (e.g., merchant-initiated transactions, recurring billing without CVV).
  </Tab>

  <Tab title="Expiration + CVV">
    Update the expiration via API, then send a CVV capture link to the cardholder to collect the new security code. This requires the cardholder to take action.

    **Best for:** Situations where the PSP requires CVV for each charge, or when your business rules mandate CVV presence.
  </Tab>

  <Tab title="Full Re-capture">
    If the cardholder received an entirely new card number (not just a renewed expiry), you need to capture the full card details again using [Card By Link](/capture-cards/card-by-link) or the [Hosted Card Entry Form](/capture-cards/hosted-card-entry-form). This creates a new token entirely.

    **Best for:** Lost or stolen card replacements where the card number itself has changed.
  </Tab>
</Tabs>

## Simple Case: Update Expiration Only

If you only store card number and expiration (no CVV), use the [Update Expiration](/api-reference/manage-tokens/update-expiration) API to submit the new month and year. The existing token is updated in place. No cardholder interaction is required.

## Full Case: Update Expiration and CVV

If you also need the new CVV, follow this workflow:

1. **Update the expiration date.** Call [Update Expiration](/api-reference/manage-tokens/update-expiration) with the new month and year.
2. **Send a CVV capture link.** Use [CVV Capture](/capture-cards/cvv-capture) (via Card By Link) to send the cardholder a link to enter their new CVV.
3. **Cardholder enters CVV.** The cardholder receives the link and enters the new security code.
4. **PCI Booking creates a new token.** A full copy of the original card details is created with the captured CVV attached. You receive the new token in a [callback](/api-reference/tokenize-cards/cotp-callback).
5. **Set CVV retention policy.** If needed, configure a [CVV Retention Policy](/capture-cards/cvv-retention-policy) for the new token.
6. **Delete the old token.** Call [Delete Token](/api-reference/manage-tokens/delete-token) to remove the old entry.
7. **Update your database.** Replace the old token with the new one in your system.

At the end of this process, you have one token with the updated card details.

<Info>
  If you use network tokenization, card networks (Visa, Mastercard) can automatically update card details when a replacement card is issued. This eliminates the need for manual updates in many cases. Contact [support@pcibooking.net](mailto:support@pcibooking.net) to learn more about network token lifecycle management.
</Info>

## Related

* [Update Expiration](/api-reference/manage-tokens/update-expiration). API reference for updating expiration date.
* [CVV Capture](/capture-cards/cvv-capture). Send a CVV-only capture link to the cardholder.
* [CVV Retention Policy](/capture-cards/cvv-retention-policy). Control how long CVV data is stored.
* [Charge and Save for Future Payments](/use-cases/capture-charge-and-store). See the full card lifecycle from initial capture to stored token.


# Authorize & Capture
Source: https://developers.pcibooking.net/use-tokens/authorize-capture

Pre-authorize a card token and capture later. Two-step payment flow via PCI Booking's Universal Payment Gateway.

Authorize and capture is a two-step flow through PCI Booking's [Universal Payment Gateway (UPG)](/use-tokens/universal-payment-gateway). It separates the fund hold from the settlement, which is useful for delayed fulfillment scenarios like hotel bookings or rental reservations.

## Pre-Authorize (Hold Funds)

The first step detokenizes your card token to place a hold on the cardholder's funds. PCI Booking replaces the token with real card data and sends an authorization request to your configured PSP.

* Submit a **card token**, **amount**, **currency**, and **gateway credentials ID**.
* PCI Booking detokenizes and forwards the authorization to the PSP.
* The PSP places a hold on the funds and returns an authorization reference.
* No funds are transferred yet.

This is the same UPG detokenization mechanism as a charge. The only difference is the transaction type.

```bash theme={null}
curl -X POST "https://service.pcibooking.net/api/paymentGateway?credentialsId=my-stored-credentials" \
  -H "Authorization: APIKEY your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "CardToken": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
    "OperationType": "PreAuth",
    "Amount": 250.00,
    "Currency": "EUR"
  }'
```

## Capture (Settle Funds)

The second step settles a previous authorization. You reference the original transaction ID. No card token or card data is needed, since the PSP already has the authorization on file.

* Submit the **original transaction reference** and the **amount to capture**.
* The capture amount can be equal to or less than the authorized amount.
* PCI Booking forwards the capture to the PSP, which transfers the funds.

```bash theme={null}
curl -X POST "https://service.pcibooking.net/api/paymentGateway?credentialsId=my-stored-credentials" \
  -H "Authorization: APIKEY your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "CardToken": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
    "OperationType": "Capture",
    "GatewayReference": "txn_abc123",
    "Amount": 250.00,
    "Currency": "EUR"
  }'
```

## When to Use

* **Hotels and travel**. Authorize at booking, capture at checkout.
* **Rentals**. Authorize at pickup, capture at return.
* **E-commerce**. Authorize at order, capture at shipment.
* **Partial captures**. Capture less than the authorized amount if the final total changes.

Both steps use the same UPG endpoint. Your systems never see card data at any point in the flow.

## Next Steps

<CardGroup>
  <Card title="Charge" icon="book" href="/use-tokens/charge">
    Process a simple one-step charge instead.
  </Card>

  <Card title="Refunds & Voids" icon="book" href="/use-tokens/refunds-voids">
    Reverse or refund completed transactions.
  </Card>
</CardGroup>


# Card Display
Source: https://developers.pcibooking.net/use-tokens/card-display

Display stored card details to authorized users via a secure hosted form. Hotels can view guest card data without PCI scope.

The Card Display form is a secure iframe that renders stored card details for authorized viewing, without exposing raw card data to your application.

Use Card Display when you operate a portal for your customers and need to let authorized users view card details. You manage the credentials and access control on your side, deciding who can log in and who has permission to view cards. When an authorized user requests to see a card, your portal calls PCI Booking to generate the display iframe. This way you control access while PCI Booking handles the secure rendering of card data.

## How It Works

1. Your system builds a [Card Display URL](/api-reference/process-cards/request-card-display-form) with the card token, authentication credentials, and any display options as query parameters.
2. You set this URL as the `src` of an iframe on your page.
3. PCI Booking renders the card details directly inside the iframe. Your application never receives the raw card data.

## What Is Displayed

The card display form shows:

* Cardholder name.
* Card number (full or masked, based on permissions).
* Expiration date.
* Card type / brand.
* CVV (if stored and permitted).
* Virtual card details (if applicable).

## Customization

You can customize the display form appearance:

| Parameter       | Description                                                            |
| --------------- | ---------------------------------------------------------------------- |
| `language`      | ISO 639-1 language code for localized labels.                          |
| `css`           | Name of a custom CSS stylesheet configured in your account.            |
| `removeBaseCss` | Set to `true` to strip default styling and apply only your custom CSS. |

Custom stylesheets are managed through the PCI Booking Admin portal under account settings.

## Security

* **Authentication required**. API key, access token, or session-based authentication.
* **Session-limited**. Display URLs are time-limited and tied to the authenticated session.
* **Iframe isolation**. Card data is rendered inside PCI Booking's secure domain. Your application's JavaScript cannot access the iframe content due to cross-origin restrictions.

<Warning title="PCI compliance">
  Even though the card display form keeps raw data out of your systems, displaying full card numbers to users may have PCI DSS implications for your organization. Consult your QSA to determine if card display affects your compliance scope.
</Warning>

## Next Steps

<CardGroup>
  <Card title="Card Display with OTP" icon="book" href="/use-tokens/card-display-otp">
    Add OTP verification for higher-security card viewing.
  </Card>

  <Card title="Use Tokens Overview" icon="book" href="/use-tokens/overview">
    All detokenization methods.
  </Card>
</CardGroup>


# Card Display with OTP
Source: https://developers.pcibooking.net/use-tokens/card-display-otp

Send a one-time password link to view stored card details. Secure card display for hotel staff and partners.

Card Display with OTP is a PCI Booking-hosted page that displays stored card details after verifying the viewer's identity with two one-time passwords - one sent to their email and one sent to their phone number.

Use this when you don't have your own portal for managing user access to card details, or when you don't want to deal with the security and PCI compliance implications of building user management for card viewing into your systems. PCI Booking handles the entire authentication and display flow.

Unlike [Card Display](/use-tokens/card-display) (which uses an iframe embedded in your portal), Card Display with OTP is a standalone hosted page. The viewer accesses it directly on PCI Booking's domain.

## How It Works

1. **Initiate a view request**. Your system calls the [initView endpoint](/api-reference/process-cards/card-display-otp) with the card token, the viewer's phone number, email, and name.
2. **Email verification**. PCI Booking sends an email to the viewer containing a link. The first OTP is embedded in the link, so the viewer verifies email access simply by clicking it.
3. **Phone verification**. After clicking the link, the viewer is prompted to verify their phone number. They choose to receive a code via SMS or voice call, then enter it on screen.
4. **Card revealed**. After both verifications succeed, the card details are displayed on PCI Booking's hosted page.

## Security

* Each OTP is a single-use 6-digit code, hashed and salted before storage. PCI Booking does not retain the plain-text code.
* OTPs expire after a limited time window.
* Two-factor verification (email link + phone code) ensures the viewer controls both channels.

<Info>
  Use Card Display with OTP when you want PCI Booking to handle the entire card viewing flow, including identity verification. Use [Card Display](/use-tokens/card-display) when you already have a portal with your own user management and access control.
</Info>

## Next Steps

<CardGroup>
  <Card title="Card Display" icon="book" href="/use-tokens/card-display">
    Iframe-based card display for use within your own portal.
  </Card>

  <Card title="Use Tokens Overview" icon="book" href="/use-tokens/overview">
    All detokenization methods.
  </Card>
</CardGroup>


# Charge
Source: https://developers.pcibooking.net/use-tokens/charge

One-step charge via PCI Booking's Universal Payment Gateway. Tokenize once, charge any PSP without handling card data.

Send a token to PCI Booking's [Universal Payment Gateway (UPG)](/use-tokens/universal-payment-gateway) to process an immediate payment. PCI Booking replaces the token with the real card data and forwards the charge request to your configured PSP. You never handle or see card data.

## How It Works

A charge is the simplest UPG operation. You submit:

* A **card token** (obtained during card capture).
* The **PSP name and credentials** (or a stored `credentialsId`).
* The **amount and currency**.

PCI Booking detokenizes the card, constructs the PSP-specific request with real card data, sends it, and returns the PSP's response to you.

## Example: Charge with Inline Credentials

```bash theme={null}
curl -X POST https://service.pcibooking.net/api/paymentgateway \
  -H "Authorization: APIKEY your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "PaymentGateway": {
      "Name": "YourPSPName",
      "Credentials": {
        "MerchantId": "your-merchant-id",
        "ApiKey": "your-psp-api-key"
      }
    },
    "CardToken": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
    "OperationType": "Charge",
    "Amount": 100.00,
    "Currency": "USD"
  }'
```

## Example: Charge with Stored Credentials

If you have pre-stored your PSP credentials via [PSP Credentials](/account-setup/gateway-credentials), pass the `credentialsId` as a query parameter instead:

```bash theme={null}
curl -X POST "https://service.pcibooking.net/api/paymentgateway?credentialsId=my-stored-credentials" \
  -H "Authorization: APIKEY your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "CardToken": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
    "OperationType": "Charge",
    "Amount": 100.00,
    "Currency": "USD"
  }'
```

## Key Points

* **No card data in your request**. Only the token. PCI Booking injects real card details during detokenization.
* **PCI scope reduction**. Your systems never touch sensitive card data.
* **PSP-agnostic**. The same endpoint works regardless of which PSP you route to. Change PSPs by updating your gateway credentials, not your code.
* **Immediate settlement**. Funds are charged and settled in a single step, unlike authorize-and-capture flows. Use a charge when you need immediate payment.

## Next Steps

<CardGroup>
  <Card title="Authorize & Capture" icon="book" href="/use-tokens/authorize-capture">
    Split authorization and capture for more control.
  </Card>

  <Card title="Refunds & Voids" icon="book" href="/use-tokens/refunds-voids">
    Reverse or refund completed transactions.
  </Card>

  <Card title="PSP Credentials" icon="book" href="/account-setup/gateway-credentials">
    Set up and manage your PSP credentials.
  </Card>
</CardGroup>


# File Transfer Token Replacement
Source: https://developers.pcibooking.net/use-tokens/file-transfer-token-replacement

Replace tokens with card data in SFTP/FTPS file transfers. PCI Booking acts as secure proxy for batch file processing.

File Transfer Token Replacement lets you deliver card data to partners via SFTP or FTPS. You upload a file containing card tokens to PCI Booking, which replaces the tokens with real card data and sends the file to the destination server.

## How It Works

1. Your system sends a PUT request to PCI Booking's SFTP/FTPS relay endpoint, providing the destination host, file path, server credentials, and the file content with card tokens.
2. PCI Booking applies a content filter to locate tokens in the file, retrieves the real card data, and substitutes it.
3. The modified file, now containing real card data, is uploaded to the destination SFTP or FTPS server.

## Supported File Formats

PCI Booking supports several preset content filters for common file formats:

| Filter     | Description                        |
| ---------- | ---------------------------------- |
| CSV        | Standard comma-separated values.   |
| SIMPLECSV  | Simplified CSV layout.             |
| SIMPLEJSON | JSON file format.                  |
| TADC       | Travel agent data capture format.  |
| GBT        | Global distribution system format. |
| AIR        | Airline industry format.           |
| IUR        | GDS interchange format.            |

## Authentication

Destination server credentials (username and password) are passed via the HTTP Basic Authorization header on your relay request. PCI Booking uses these credentials to connect to the destination SFTP or FTPS server. Card tokens are specified in the `X-PciBooking-cardUri` request header.

<Info>
  The reverse operation is also available: you can download a file from an SFTP/FTPS server through PCI Booking, which tokenizes any card data found in the file before returning it to your system. See [File Transfer Tokenization](/capture-cards/file-transfer-tokenization).
</Info>

## Next Steps

<CardGroup>
  <Card title="Token Replacement in Request" icon="book" href="/use-tokens/token-replacement-in-request">
    Send card data via HTTP proxy instead.
  </Card>

  <Card title="Use Tokens Overview" icon="book" href="/use-tokens/overview">
    All detokenization methods.
  </Card>
</CardGroup>


# Gateway-Specific Guidance
Source: https://developers.pcibooking.net/use-tokens/gateway-guidance

PSP-specific notes for processing payments through PCI Booking. Required fields, quirks, and configuration for each gateway.

Each PSP has specific requirements for how card data and transaction parameters are formatted. PCI Booking handles these differences automatically, but some PSPs require additional input that only you can provide. This page explains what varies and where to find the details.

## What Varies by Gateway

* **Required fields**. Some PSPs require additional parameters beyond the standard set (e.g. merchant category codes, terminal IDs).
* **Supported operations**. Not all PSPs support every transaction type (charge, authorize, capture, void, refund).
* **Card brand support**. PSP-specific restrictions on accepted card networks.
* **Currency handling**. Minor unit formatting and supported currencies differ by PSP.
* **3D Secure**. Integration patterns for 3DS vary across PSPs.

## Gateway-Specific Documentation

PCI Booking provides guidance for each supported PSP, including the required credential fields, supported operations, and any PSP-specific parameters you need to include in your request.

See the [Additional Guidance for Specific Payment Gateways](/api-reference/process-cards/gateway-guidance) in the API Reference for the full list.

<Info>
  If your PSP is not listed or you need help with a specific integration, contact [support@pcibooking.net](mailto:support@pcibooking.net).
</Info>

## Next Steps

<CardGroup>
  <Card title="PSP Credentials" icon="book" href="/account-setup/gateway-credentials">
    Set up and manage your PSP credentials.
  </Card>

  <Card title="Universal Payment Gateway" icon="book" href="/use-tokens/universal-payment-gateway">
    UPG overview and supported operations.
  </Card>
</CardGroup>


# Use Tokens Overview
Source: https://developers.pcibooking.net/use-tokens/overview

Use PCI Booking tokens to charge, authorize, refund, display cards, replace tokens in API requests, and transfer files, all without handling card data

Once a card is tokenized, you use the token to send card data wherever it needs to go. PCI Booking retrieves the real card data from the vault, substitutes it at the point of delivery, and your systems never handle sensitive card details.

## Assessing Risk

Before using a token, you can analyze the card for fraud risk indicators to decide whether you are willing to proceed with the transaction.

| Method                                             | How It Works                                                                                                                                                       |
| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **[Risk Assessment](/use-tokens/risk-assessment)** | Send a token to PCI Booking's risk assessment endpoint. Returns a risk score and contributing factors that you can use as input to your fraud prevention workflow. |

## Processing Payments

Use the Universal Payment Gateway to charge, authorize, or refund through a payment service provider (PSP).

| Method                                                                       | How It Works                                                                                                                                                                                                                                                                                                                            |
| ---------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **[Universal Payment Gateway (UPG)](/use-tokens/universal-payment-gateway)** | Send a token, amount, and your PSP credentials to PCI Booking's single API endpoint. PCI Booking detokenizes the card and sends the transaction to your chosen PSP. 100+ PSPs supported. Supports [charge](/use-tokens/charge), [authorize & capture](/use-tokens/authorize-capture), and [refunds & voids](/use-tokens/refunds-voids). |

## Inserting Card Data into Messages via HTTP

Send card data to third parties by routing HTTP traffic through PCI Booking. Tokens are replaced with real card data in transit.

| Method                                                                         | How It Works                                                                                                                                                                                                                                            |
| ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **[Token Replacement in Request](/use-tokens/token-replacement-in-request)**   | You send an HTTP request through PCI Booking as a proxy, with tokens in the request body. PCI Booking replaces tokens with real card data and forwards the request to the destination. Supports JSON, XML/SOAP, form-encoded, and query string formats. |
| **[Token Replacement in Response](/use-tokens/token-replacement-in-response)** | A third party sends a request to your API through a PCI Booking gateway. Your API responds with tokens. PCI Booking replaces the tokens with real card data before relaying the response back to the sender.                                            |

## Inserting Card Data into Messages via File

Send card data to third parties by routing file transfers through PCI Booking.

| Method                                                                             | How It Works                                                                                                                                           |
| ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **[File Transfer Token Replacement](/use-tokens/file-transfer-token-replacement)** | Upload a file containing tokens to PCI Booking. Tokens are replaced with real card data and the file is delivered to the destination via SFTP or FTPS. |

## Displaying Card Data

Use these methods when authorized staff need to view card details.

| Method                                                    | How It Works                                                                                                                 |
| --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| **[Card Display](/use-tokens/card-display)**              | Render stored card details in a secure iframe. Your application never receives the raw card data.                            |
| **[Card Display with OTP](/use-tokens/card-display-otp)** | Same as Card Display, with an additional one-time password verification step via SMS or voice before revealing card details. |

## Retrieving Raw Card Data via API

The [Token Replacement (API)](/use-tokens/token-replacement-api) endpoint returns the full, unmasked card number directly in the API response. Unlike all other methods above, this means your system receives raw card data, putting it in scope of PCI DSS compliance.

<Warning>
  This method is intended for sandbox testing only. If you need to view card details in production, use [Card Display](/use-tokens/card-display) instead. See the [Token Replacement (API)](/use-tokens/token-replacement-api) page for details and PCI compliance implications.
</Warning>


# Refunds & Voids
Source: https://developers.pcibooking.net/use-tokens/refunds-voids

Process refunds and void transactions on payments made through PCI Booking's Universal Payment Gateway.

Refunds and voids reverse previous transactions through PCI Booking's [Universal Payment Gateway (UPG)](/use-tokens/universal-payment-gateway). Neither operation requires card data or a token. They reference the original transaction.

## Void

A void cancels a pre-authorization before it has been captured. No funds were transferred, so the hold is simply released.

* Submit the **original transaction reference**.
* The PSP releases the hold on the cardholder's funds.
* Only works on uncaptured authorizations.

Use a void when a booking is cancelled before fulfillment, or when an authorization is no longer needed.

```bash theme={null}
curl -X POST "https://service.pcibooking.net/api/paymentGateway?credentialsId=my-stored-credentials" \
  -H "Authorization: APIKEY your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "CardToken": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
    "OperationType": "Void",
    "GatewayReference": "txn_abc123"
  }'
```

## Refund

A refund returns funds from a completed transaction, either a charge or a captured authorization. The PSP processes the return using the original transaction details.

* Submit the **original transaction reference** and the **refund amount**.
* Full or partial refunds are supported.
* The PSP credits the cardholder's account.

```bash theme={null}
curl -X POST "https://service.pcibooking.net/api/paymentGateway?credentialsId=my-stored-credentials" \
  -H "Authorization: APIKEY your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "CardToken": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
    "OperationType": "Refund",
    "GatewayReference": "txn_abc123",
    "Amount": 50.00,
    "Currency": "EUR"
  }'
```

## Timing: When to Void vs. When to Refund

The key distinction is whether the transaction has been settled (funds transferred from the cardholder's bank to the merchant's bank).

* **Before settlement:** Use a **void**. The authorization hold is released and no funds move. Settlement timing varies by PSP but typically happens at end of day or within 24 hours.
* **After settlement:** Use a **refund**. The PSP initiates a credit back to the cardholder's account. Refunds may take several business days to appear on the cardholder's statement, depending on the issuing bank.

If you attempt a void after settlement has already occurred, the PSP will reject it. In that case, submit a refund instead. Some PSPs automatically convert a void request into a refund if settlement has passed, but this behavior is not universal.

## Partial Refunds

You can refund less than the full transaction amount by specifying a lower value in the `Amount` field. Partial refunds are useful for scenarios such as:

* A guest shortens their hotel stay and is owed a partial credit
* One item in an order is returned while others are kept
* A service fee is waived after a complaint

Some PSPs support multiple partial refunds against a single transaction, up to the original charge amount. Others allow only one refund per transaction. Check your PSP's documentation for their specific partial refund policy.

## PSP-Specific Considerations

PCI Booking routes void and refund requests to the PSP that processed the original transaction. Each PSP has its own rules and limitations:

* **Void windows.** Some PSPs allow voids only within a few hours of the original authorization, while others allow voids until end-of-day settlement.
* **Refund timeframes.** Most PSPs allow refunds for up to 180 days after the original charge. Some extend this to 365 days.
* **Currency handling.** Refunds are processed in the same currency as the original charge. Cross-currency refund adjustments (due to exchange rate changes) are handled by the issuing bank, not PCI Booking.
* **Transaction references.** The `GatewayReference` you submit must match the reference returned by the PSP in the original charge or capture response.

## Key Points

* **No card data involved.** Both operations reference the original transaction, not the card token.
* **Same UPG endpoint.** Voids and refunds use the same [Universal Payment Gateway](/use-tokens/universal-payment-gateway) as charges and authorizations.
* **PSP handles the reversal.** PCI Booking routes your request to the correct PSP based on the original transaction.
* **Idempotency.** Submitting the same void or refund request twice may result in a duplicate reversal, depending on the PSP. Use unique references and check the transaction status before retrying.

## Next Steps

<CardGroup>
  <Card title="Charge" icon="book" href="/use-tokens/charge">
    Process charge transactions.
  </Card>

  <Card title="Authorize & Capture" icon="book" href="/use-tokens/authorize-capture">
    Two-step payment processing.
  </Card>
</CardGroup>


# Risk Assessment
Source: https://developers.pcibooking.net/use-tokens/risk-assessment

Assess fraud risk on a stored card token using payer details, billing address, and device metadata. Returns a risk score.

Score a token for fraud risk indicators before processing a payment.

## What It Does

Risk assessment analyzes the stored card data against the payer's billing information and IP address. It returns a risk level with contributing factors such as country mismatches and anonymous proxy usage. Use it as an input to your fraud prevention workflow.

## When to Use It

* Before processing high-value transactions.
* When a token is used from an unusual context.
* As part of automated fraud screening.

## How It Works

Send the token's cardURI along with the payer's billing details to the [risk assessment endpoint](/api-reference/manage-tokens/risk-assessment). PCI Booking cross-references the card's issuer country, the payer's billing country, and the client's IP geolocation to produce a risk score.

```bash theme={null}
curl -X POST \
  'https://service.pcibooking.net/api/payments/paycard/{token}/op/validate' \
  -H 'Authorization: PCIBOOKING apikey={your-api-key}' \
  -H 'Content-Type: application/json' \
  -d '{
    "ClientIPAddress": "203.0.113.42",
    "CountryCode": "US",
    "City": "New York",
    "StateProvince": "NY",
    "FirstName": "John",
    "LastName": "Smith"
  }'
```

```json Example response theme={null}
{
  "RiskLevel": "Low",
  "Description": "Mismatch between billing address and credit card issuer country.",
  "CountryByIP": "US",
  "IssuerCountry": "GB",
  "IssuerName": "BARCLAYS BANK PLC",
  "CardBrand": "VISA",
  "CardType": "CREDIT",
  "CardCategory": "CLASSIC",
  "CountryFromBillingAddress": "US",
  "AnonymousProxyUsed": false
}
```

## Risk Levels

| Level        | Meaning                                                                                                    |
| ------------ | ---------------------------------------------------------------------------------------------------------- |
| **VeryHigh** | Anonymous proxy detected, or mismatch between billing address, card issuer country, and client IP address. |
| **High**     | Mismatch between billing address and card issuer country.                                                  |
| **Low**      | Billing address and card issuer country match, but do not match the client's IP address.                   |
| **VeryLow**  | Billing address, card issuer country, and client IP address all match.                                     |

<Info>
  Risk assessment is an advisory signal. Combine it with your own fraud rules to make accept/decline decisions.
</Info>

## Next Steps

<CardGroup>
  <Card title="Use Tokens Overview" icon="book" href="/use-tokens/overview">
    All ways to use your tokens.
  </Card>

  <Card title="Charge" icon="book" href="/use-tokens/charge">
    Process a payment after assessing risk.
  </Card>
</CardGroup>


# Token Replacement (API)
Source: https://developers.pcibooking.net/use-tokens/token-replacement-api

Replace tokens with real card data in outbound API calls to payment gateways. PCI Booking proxies the request securely.

The [Retrieve Card Details](/api-reference/manage-tokens/retrieve-card-details) endpoint returns the **full, unmasked card number** directly in the API response. If the `retrieveCvv` parameter is set, it also returns the CVV.

Unlike [Token Replacement in Request](/use-tokens/token-replacement-in-request) or the [Universal Payment Gateway](/use-tokens/universal-payment-gateway), this method delivers raw card data to your system rather than routing it directly to a third party.

<Warning>
  Using this endpoint means your system receives raw card data in the API response. This puts your system, network, and all connected components in scope of PCI DSS compliance.

  We strongly recommend:

  * **Do not use this endpoint in production.** Use it only in your sandbox environment with test card data to verify that card details were stored correctly.
  * If you have a legitimate production need to retrieve full card details, consult with your PCI QSA before implementing. Consider using [Card Display](/use-tokens/card-display) instead, which renders card details in a secure iframe without exposing raw data to your systems.
</Warning>

## How It Differs from Token Replacement in Request

PCI Booking offers two distinct "token replacement" concepts. Understanding the difference is important:

|                       | This Endpoint (Retrieve Card Details)       | Token Replacement in Request                                    |
| --------------------- | ------------------------------------------- | --------------------------------------------------------------- |
| **Direction**         | Card data is returned to your system        | Card data is injected into an outbound request to a third party |
| **PCI scope**         | Your system is in PCI DSS scope             | Your system stays out of scope                                  |
| **Use case**          | Sandbox testing, PCI-compliant environments | Production payment processing, partner integrations             |
| **Supported formats** | API response only                           | JSON, XML/SOAP, form-encoded, query string                      |

For production use, [Token Replacement in Request](/use-tokens/token-replacement-in-request) is the recommended approach. PCI Booking acts as a proxy, replacing tokens with real card data in the outbound request body and forwarding it to the destination. Your systems never see the real card details.

## When to Use This Endpoint

* **Sandbox verification.** Confirm that card data was stored correctly during integration development.
* **PCI-compliant environments.** If your system is already fully PCI DSS compliant and you need raw card data for a workflow that cannot use proxy-based token replacement.
* **Migration validation.** After migrating cards from another vault, verify that the data was transferred accurately.

## Recommended Alternatives

For most production scenarios, use one of these methods instead:

* **[Token Replacement in Request](/use-tokens/token-replacement-in-request)** to inject card data into outbound API calls to any HTTP endpoint
* **[Universal Payment Gateway](/use-tokens/universal-payment-gateway)** to process payments through supported PSPs with built-in formatting
* **[Card Display](/use-tokens/card-display)** to show card details to authorized users via a secure iframe

## Next Steps

<CardGroup>
  <Card title="Card Display" icon="book" href="/use-tokens/card-display">
    View card details in a secure iframe without handling raw data.
  </Card>

  <Card title="Token Replacement in Request" icon="book" href="/use-tokens/token-replacement-in-request">
    Inject card data into outbound requests without PCI scope.
  </Card>

  <Card title="Use Tokens Overview" icon="book" href="/use-tokens/overview">
    All ways to use your tokens.
  </Card>
</CardGroup>


# Token Replacement in Request
Source: https://developers.pcibooking.net/use-tokens/token-replacement-in-request

Intercept outbound HTTP requests and replace card tokens with real card data before forwarding to the destination.

Token Replacement in Request lets you send an HTTP request through PCI Booking as a transparent proxy. PCI Booking replaces card tokens in your request with real card data, forwards the request to the destination, and returns the response. Your systems never handle sensitive card details.

This is the mirror of [Tokenization on Response](/capture-cards/tokenization-on-response) in the Capture Cards section. Both use the same forward proxy infrastructure, but in opposite directions: Tokenization on Response tokenizes card data in the third party's response, while Token Replacement in Request detokenizes tokens in your outbound request.

## How It Works

1. Your system sends an HTTP request to the PCI Booking relay endpoint, specifying the destination URL and including card tokens in the request body.
2. PCI Booking validates the destination against your account's **allowed endpoints** (relay restrictions).
3. PCI Booking retrieves the real card data for each token and substitutes it into the request body.
4. The modified request is forwarded to the destination with the real card data.
5. The destination's response is returned to your system.

## Supported Content Types

PCI Booking detects the content type automatically and applies the appropriate replacement engine:

| Content Type                                          | Engine          | Notes                                   |
| ----------------------------------------------------- | --------------- | --------------------------------------- |
| `application/json`                                    | JSON (JSONPath) | Supports nested objects and arrays.     |
| `text/xml`, `application/xml`, `application/soap+xml` | XML (XPath)     | Supports SOAP envelopes and namespaces. |
| `application/x-www-form-urlencoded`                   | Form-encoded    | Key-value pair replacement.             |
| Query string parameters                               | Query string    | Token replacement in URL parameters.    |

## Bi-Directional: Tokenization on the Way Back

The same proxy call can also tokenize card data in the destination's response. If your profile is configured for it, PCI Booking extracts card data from the response, tokenizes it, and returns tokens to you instead of raw card numbers. See [Tokenization on Response](/capture-cards/tokenization-on-response) for details on setting up profiles for this.

When tokenization on response is active, the response includes:

| Header                               | Description                                                                                  |
| ------------------------------------ | -------------------------------------------------------------------------------------------- |
| `X-PciBooking-cardUri`               | Token URI(s) for cards extracted from the response. Multiple tokens are semicolon-separated. |
| `X-PciBooking-Tokenization-Errors`   | Error details if tokenization failed for any card.                                           |
| `X-PciBooking-Tokenization-Warnings` | Warnings from the tokenization process.                                                      |

## Target Profiles

Instead of specifying replacement rules in every request, you configure a [target profile](/account-setup/target-profiles) once per third-party message format and reference it by name. Each profile includes [content filters](/account-setup/content-filters) that define where card fields appear in the message, plus optional client certificates for mutual TLS.

## Security

* **Relay restrictions**. Your account can be configured with an endpoint whitelist. Requests to destinations not on the list are rejected. Contact support or use the Admin portal to manage your allowed endpoints.
* **Client certificates**. Target profiles can include [client certificates](/account-setup/client-certificates) for mutual TLS authentication with the destination.
* **Timeout**. Relay requests have a default timeout of 60 seconds.

## Next Steps

<CardGroup>
  <Card title="Token Replacement in Response" icon="book" href="/use-tokens/token-replacement-in-response">
    The reverse direction: third parties send requests to your API through PCI Booking.
  </Card>

  <Card title="File Transfer Token Replacement" icon="book" href="/use-tokens/file-transfer-token-replacement">
    Send card data via SFTP/FTPS.
  </Card>

  <Card title="Use Tokens Overview" icon="book" href="/use-tokens/overview">
    All detokenization methods.
  </Card>
</CardGroup>


# Token Replacement in Response
Source: https://developers.pcibooking.net/use-tokens/token-replacement-in-response

Extract card data from third-party responses and replace with tokens before the data reaches your systems.

Token Replacement in Response lets you send card data to a third party without making the outbound call yourself. PCI Booking sits as a gateway in front of your API. When a third party sends a request, your API processes it and responds with tokens. PCI Booking replaces the tokens with real card data before relaying the response back to the sender.

This is the mirror of [Tokenization on Request](/capture-cards/tokenization-on-request) in the Capture Cards section. Both use the same gateway infrastructure, but in opposite directions: Tokenization on Request tokenizes card data in the third party's inbound request, while Token Replacement in Response detokenizes tokens in your outbound response.

## How It Works

1. **PCI Booking sets up a gateway endpoint**. The gateway is configured with your SSL certificate and a custom site name. Third parties send their requests to this gateway URL instead of directly to your API.
2. **Third party sends a request**. The request arrives at the PCI Booking gateway.
3. **Request forwarded to your API**. PCI Booking relays the request to your API endpoint (with optional [tokenization of inbound card data](/capture-cards/tokenization-on-request)).
4. **Your API responds with tokens**. Your API processes the request and includes card tokens in the response body.
5. **Token replacement**. PCI Booking parses your response, retrieves the real card data for each token, and substitutes it into the response body.
6. **Response relayed to sender**. The third party receives the response with real card data. Your systems never handled raw card details.

## Bi-Directional: Tokenize and Detokenize in One Call

The same gateway can handle both directions simultaneously:

* **Inbound**: Tokenize card data in the third party's request before it reaches your API ([Tokenization on Request](/capture-cards/tokenization-on-request)).
* **Outbound**: Replace tokens in your API's response with real card data before relaying back to the sender (this page).

This means a single gateway endpoint can keep card data off your systems in both directions.

## Target Profiles

The gateway uses a [target profile](/account-setup/target-profiles) to know where tokens appear in your response and how to replace them. Each profile includes [content filters](/account-setup/content-filters) that define the location of card fields in the message. The PCI Booking support team configures this as part of the gateway setup.

## Setting Up the Gateway

Gateway setup is done by the PCI Booking support team. Contact [support@pcibooking.net](mailto:support@pcibooking.net) with:

* Your PCI Booking username.
* The target URI where requests should be relayed to (your API endpoint).
* How to identify which responses contain tokens that need replacement.
* A sample of your response structure (XML or JSON) showing where tokens appear.

<Info>
  If you already have a [Tokenization on Request](/capture-cards/tokenization-on-request) gateway set up, the same gateway can be enhanced to also perform token replacement on the response. Contact support to enable it.
</Info>

## Use Cases

* Sending card details back to a booking platform or OTA that originally sent you the reservation.
* Responding to a channel manager's request with card data for payment processing on their end.
* Any scenario where a third party expects real card data in your API response.

## Next Steps

<CardGroup>
  <Card title="Token Replacement in Request" icon="book" href="/use-tokens/token-replacement-in-request">
    The forward direction: you send requests to a third party through PCI Booking.
  </Card>

  <Card title="File Transfer Token Replacement" icon="book" href="/use-tokens/file-transfer-token-replacement">
    Send card data via SFTP/FTPS.
  </Card>

  <Card title="Use Tokens Overview" icon="book" href="/use-tokens/overview">
    All detokenization methods.
  </Card>
</CardGroup>


# Universal Payment Gateway (UPG)
Source: https://developers.pcibooking.net/use-tokens/universal-payment-gateway

Process payments through 100+ PSPs with a single API. PCI Booking's UPG handles card data and gateway routing.

The Universal Payment Gateway (UPG) is PCI Booking's single API endpoint for processing payments. You specify which PSP to use by providing your gateway credentials, and PCI Booking detokenizes the card and sends the transaction to that PSP. Over 100 PSPs are supported.

## How It Works

The UPG provides a unified request structure that is the same regardless of which PSP you are processing with. You send one standard request with a card token, amount, currency, and your PSP credentials. PCI Booking handles everything from there: it detokenizes the card, constructs whatever API calls the specific PSP requires, and returns a standardized response in a consistent format regardless of which PSP processed the transaction.

1. You send a standard request to the [UPG endpoint](/api-reference/process-cards/process-transaction) with the card token, transaction details, and PSP credentials.
2. PCI Booking detokenizes the card, replacing the token with real card data.
3. PCI Booking translates your request into the PSP-specific format and sends all necessary API calls to complete the operation.
4. PCI Booking normalizes the PSP's response into a standardized format and returns it to you.

Your systems never touch card data. You integrate once with PCI Booking and work exclusively with tokens. PCI Booking handles the individual integrations with each PSP.

### Providing PSP Credentials

You can provide your PSP credentials in two ways:

* **Inline**. Include the PSP name and credential key-value pairs directly in the request body. Useful for testing or when credentials vary per transaction.
* **Stored credentials**. Pre-save your PSP credentials via [PSP Credentials](/account-setup/gateway-credentials) and pass a `credentialsId` query parameter. Recommended for production use.

## Supported Operations

| Operation                                          | Description                                            |
| -------------------------------------------------- | ------------------------------------------------------ |
| **[Charge](/use-tokens/charge)**                   | Detokenize and process an immediate payment.           |
| **[Pre-Authorize](/use-tokens/authorize-capture)** | Detokenize and place a hold on funds.                  |
| **[Capture](/use-tokens/authorize-capture)**       | Settle a previous authorization (no card data needed). |
| **[Void](/use-tokens/refunds-voids)**              | Cancel an uncaptured authorization.                    |
| **[Refund](/use-tokens/refunds-voids)**            | Return funds from a completed transaction.             |

## Supported PSPs

See the [full list of supported PSPs](https://pcibooking.net/universal-payment-gateway/) on our website. If your PSP is not listed, we can add it. Contact [support@pcibooking.net](mailto:support@pcibooking.net) with:

* Your PCI Booking username.
* The PSP's API documentation.
* A test account or instructions on how to set one up.
* A support contact at the PSP.

## Key Benefits

* **One endpoint, 100+ PSPs**. The same API call works for Stripe, Adyen, Worldpay, and any other supported PSP.
* **Zero PCI scope**. Card data never passes through your infrastructure.
* **PSP portability**. Switch processors by changing your gateway credentials ID, not your integration code.
* **Consistent interface**. PCI Booking normalizes request and response formats across all PSPs.

## Next Steps

<CardGroup>
  <Card title="Charge" icon="book" href="/use-tokens/charge">
    Process a simple charge transaction.
  </Card>

  <Card title="Authorize & Capture" icon="book" href="/use-tokens/authorize-capture">
    Split authorization and capture into two steps.
  </Card>

  <Card title="PSP Credentials" icon="book" href="/account-setup/gateway-credentials">
    Set up and manage your PSP credentials.
  </Card>

  <Card title="Gateway-Specific Guidance" icon="book" href="/use-tokens/gateway-guidance">
    PSP-specific requirements and configuration.
  </Card>
</CardGroup>