> ## Documentation Index
> Fetch the complete documentation index at: https://developers.pcibooking.net/llms.txt
> Use this file to discover all available pages before exploring further.

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