Skip to main content
POST
Store Paycard (Card Migration)

Card Migration Guide

Migrate existing card data into PCI Booking tokens
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.
Sending raw card data through this endpoint puts your system in PCI DSS scope, since it requires handling raw card numbers to call it. This endpoint is intended for a one-time migration from a system that is already PCI DSS compliant - it is not recommended as an ongoing capture method for production traffic. Use a card capture method that keeps card data off your systems instead. See Card Migration for the full guidance.
This endpoint accepts card details in XML format only. Set Content-Type: text/xml.

Error Responses

Error detail

Each condition below gives the exact moreInfo text, why it happens and how to resolve it. The full set is on the Error Handling page.
HTTP status: 400message: Message badly formattedmoreInfo:
Reason. The endpoint expects XML that validates against its schema, and the body either did not parse as XML or failed validation. When validation is the cause, the failing details are listed in moreInfo.How to resolve.
  1. Read the list in moreInfo. It names the elements that failed, which is usually enough on its own.
  2. Check element order. The schema is sequence-sensitive, so correctly named elements in the wrong order still fail.
  3. Check the declared encoding matches what you actually sent.
See also: Card Data XML Structure
HTTP status: 400message: Bad input datamoreInfo:
Reason. The expiration month or year is missing, out of range, or in a format the endpoint does not accept.How to resolve.
  1. Send the month as two digits, 01 through 12.
  2. Check the year format the endpoint expects. Some accept two digits and some four, and they are not interchangeable.
  3. Check the date is not in the past. An expired card is rejected at tokenization.
See also: Card Validation Errors
HTTP status: 400message: Bad input parametermoreInfo:
Reason. The CVV was present but did not match three or four digits. The API applies the same rule to every card brand.How to resolve.
  1. Send three or four digits, digits only, with no spaces or punctuation. The API accepts either length for any brand - it does not require four digits for American Express, and it does not reject four digits on other brands.
  2. Omit the field entirely rather than sending an empty string. An absent or empty CVV is accepted, and the card is simply stored without one.
The hosted card entry form is stricter than the API. Where it has detected the brand it accepts exactly three digits for every brand except American Express, which takes three or four; where the brand is unknown it accepts three or four. A CVV that the form rejects would therefore have been accepted had you sent it to the API directly.
HTTP status: 401message: You are not authorized to access this resource. Please contact customer support.moreInfo:
The two expiration variants apply to one-time access tokens: the first means the token has passed its expiry, the second that the requested lifetime exceeded the maximum allowed and was refused outright rather than capped.Reason. Authentication itself failed: the API key or session token was not recognised, has expired, or belongs to a different environment than the endpoint you called.How to resolve.
  1. Confirm the APIKEY prefix is present and there is a single space between it and the key.
  2. Confirm the key belongs to the same environment as the host you called. Sandbox and production keys are not interchangeable.
  3. If you are using a session token, check it has not passed its time to live and start a new session if it has.
See also: Authentication

Parameter Constraints

The request body must contain a BankCardDetails XML document. See Card Data XML Structure for the full field reference.
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

string
required
Your API key prefixed with APIKEY. Example: APIKEY your-api-key. For server-to-server calls.
This endpoint also accepts token-based authentication via query parameters:If multiple methods are provided, precedence: Session Token > Access Token > API Key.
string
default:"text/xml"
required
Must be text/xml. This endpoint accepts card details in XML format only.

Query String

string
A reference value that can be used to query for this card token.
string
User ID of the property to associate the token with. Found under “Property settings” in the user’s site.
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.
boolean
default:"false"
Whether to save the CVV in the database. true - save the CVV. false - do not save the CVV.
boolean
default:"false"
When true, PCI Booking checks whether this card already exists as a token in your account (same card number + expiration date) and returns the existing token instead of creating a new one.
boolean
default:"false"
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.
boolean
default:"true"
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.

Request Body

object
The BankCardDetails object. See the XML structure and example above.

Request Example

Store a Visa card and associate it with a reference and property:
On success, the token URI is returned in the Location response header (e.g. Location: https://service.pcibooking.net/api/payments/paycard/555fd7b49f134b42a5dbe4d576b2e527).

Response

201 - Card stored. A Location header is returned with the token URI. The response body contains the card details with sensitive data masked.
Remember to set the CVV Retention Policy on the token if you stored the CVV.