Skip to main content
POST

Universal Tokenization Guide

Tokenize cards from any source using preset profiles
PCI Booking forwards your request to the third party defined in the profile, tokenizes any card data found in the response, and returns the sanitized response with the following custom headers:

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: Bad input datamoreInfo: the wording depends on which endpoint you called:
The first is returned by token replacement in a request (paycard/relay). The second is returned by tokenization on response (paycard/capture). They mean the same thing.Reason. The profileName you passed could not be resolved for the account making the request. In almost every case the profile does exist, but on a different account than the one your credentials belong to. A misspelled profile name produces the same error.How to resolve.A PCI Shield profile belongs to the account, not to the sub-user that calls the API. When a sub-user makes a request, the profile is looked up against that sub-user’s parent account. A profile configured on one account is never visible to a sub-user of a different account, and sandbox and production accounts are separate.To check which profiles your credential can see:
  1. Identify the parent account of the sub-user whose credentials you are using.
  2. Sign in to the PCI Booking portal as that account and open PCI Shield Settings > PCI Shield Profile Settings.
  3. Confirm the profile name appears there, spelled exactly as you send it. Profile names are matched exactly.
  4. If the profile is listed under a different account, switch your request to a sub-user of that account rather than copying the profile.
There is no API endpoint that lists the profiles on your own account. GET /api/booker returns the platform-wide preset tokenization profiles, which are a different set. Your own profiles are visible in the portal only.
See also: Content Filters, Target Profiles
HTTP status: 400message: Bad input datamoreInfo:
Reason. The body parsed, but the profile’s selectors did not match anything in it, so no card data was substituted. The request was not relayed. This is a mismatch between the profile and the payload, not a problem with the token.How to resolve.
  1. Compare the profile’s selectors against the exact payload you sent. A selector that assumes a different nesting depth or element name matches nothing.
  2. Check the namespaces. For XML and SOAP, a selector written without namespace handling will not match a namespaced document.
  3. Confirm the body is the format the profile was written for. A profile written for XML will not match a JSON body.
  4. Test the profile against a saved copy of a real request before using it in production.
See also: Content Filters

Parameter Constraints

  • ProfileName: Must match an existing profile name (see Get Tokenization Profiles).
  • pathSegments: Required if the profile’s target URL has dynamic path segments. Provide key-value pairs in query string format.
  • eliminateCardDuplication: When true, a 200 status indicates the card already existed; 201 means a new token was created.

Parameters

Authentication

This is a browser-facing endpoint. Use one of the authentication methods below instead of the API key shown above.
string
Recommended. A long-lived token for browser-side calls. How to generate.
string
Alternative. Valid for 5 minutes. How to generate.
If both are provided, the session token takes precedence.

Path Parameters

string
required
The name of the profile as returned from the Get Tokenization Profiles method.

Query String

string
Dynamic path segments to append to the profile’s target URL. Some third-party endpoints include dynamic values in the URL path (e.g. https://ws.mydomain.com/{customerName}). The Get Tokenization Profiles response lists the required path segments for each profile.
string
Query string parameters to append to the profile’s target URL. Some third-party endpoints require additional parameters (e.g. ?param1=value1&param2=value2). Provide the full query string as needed.
boolean
default:"false"
Whether to save the CVV in the database. true: save the CVV. false: discard the CVV.
string
A reference value which can be used to query for this card token.
string
The user ID of the property to associate the token with. Found under “Property settings” in the user’s site.
boolean
default:"false"
Controls whether PCI Booking checks if the card already exists as a token in your account. A duplicate is a card with the same card number and expiration date as an existing token in your account; differences in cardholder name or CVV do not matter.
  • true: PCI Booking looks up the card in your stored tokens. If a match is found, the existing token URI is returned instead of creating a new one. The response status will be 200 instead of 201.
  • false (default): A new token is always created, even if the same card was previously stored.

Request Body

The request body and headers are passed through to the third party as-is. Include any body content and headers that the third party requires.

Response

200 - The card already exists in your account (when eliminateCardDuplication is true). The response body contains the third-party response with card details masked. The existing token URI is returned in the X-pciBooking-cardUri header. 201 - A new card was tokenized. The response body contains the third-party response with card details masked. The new token URI is returned in the X-pciBooking-cardUri header.
Remember to set the CVV Retention Policy on the token.