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

# 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