Skip to main content
Common issues and how to resolve them. If your problem is not covered here, contact 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. 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 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, 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 by reference to find any that were created but not received.
  2. Recommended fix: Switch to the session-based card entry form, 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 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.
  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 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.

​
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, 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.

​
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 or creatorReference on the hosted card form.
  • Gateway transactions: Use the myRef body parameter on Process Transaction.
  • Token queries: Search by reference with 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