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: 401Response body: empty. There is no code, message or moreInfo.Reason. PCI Booking could not identify the caller. The response is the same for every cause:
  • The Authorization header (or the x-pcibooking-api-key header) is missing, badly formatted, or has no APIKEY keyword.
  • The API key is not valid, or it belongs to the other environment (sandbox or production).
  • The sessionToken is not valid or has expired.
  • The accessToken is not valid, has expired, has an expiration time further ahead than the maximum allowed, or was already used. An access token works once only, so reloading a page that uses it, such as a card display iframe, also returns this response.
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 use a session token, check it has not expired and start a new session if it has.
  4. If you use an access token, generate a new one for every request, including every reload of an iframe.
  5. Check that your HTTP client does not drop the Authorization header on a redirect. Most clients remove it after a 301 or 302.
See also: Authentication, Authentication and Permission Failures

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

Authentication

API key, access token or session token. Use the API key for server-to-server calls, and an access token or a session token when the call is made from a browser. Send one of the three.
string
Your API key prefixed with APIKEY. Example: APIKEY your-api-key. The x-pcibooking-api-key header is also accepted. See the Authentication guide.
string
Generated on your side. Single use, and valid for up to 72 hours. How to generate.
string
Returned by an API call. Valid for 5 minutes, and can be used more than once within that time. How to generate.

Headers

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. Property Management only. Property Management is closed to new accounts; see Property Management.
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.
string
The region where the card data is stored. One of: US, IN, AU, JP, CA, IE, GB, BR. If omitted, your account’s default region is used, or Ireland if your account has no default. See Card Storage Regions.

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.