HomeGuideMethod ReferenceAssess YourselfRequest Sandbox Account
Method Reference
Ask For AssistanceLogin

Request to Send Card Capture Form to Recipient

post
https://service.pcibooking.net/api/cardrequest

The request will trigger a message to be sent to the recipient (via email or text message) with a link to the card capture form.
We recommend that you first review the guide for this method.

When submitted successfully, the response body will be blank and there will be a header added:

  • Location: The URI for the card request which can be referenced later to retrieve status or cancel.

🚧

3D Secure challenge timeout

Please note that if you enable 3DS processing during card capture, the 3DS challenge window will have a 5 minute timeout period. If the card owner does not submit the response to the 3DS challenge within that timeframe, their authentication will be rejected.

📘

Encoding URLs

Since the URLs provided in this request are provided in the body of the message instead of in the request URL's query string, the URLs mentioned above should not be urlEncoded.

📘

Requests specific parameters vs account parameters

The following parameters - CustomerSupportLink, CustomerSupportLinkText, CustomerSupportEmail and CustomerSupportPhone - can be provided either as specific values for each individual request, or their value can be retrieved from your account settings (as set in our portal).

If specific values are provided in the request, they will override the values from the account and the specific values will be displayed in the card capture form.

📘

CVV Retention Policy

Remember to set the CVV Retention Policy for this token.

❗️

Custom Merchant Information

Please do not use the merchantName parameter in the request unless you have followed our guide on managing merchant information for 3D Secure authentication as this may cause problems in your 3DS processing.

If you plan to use the PCI Booking merchant information for 3DS Authentication, please set "ThreeDs" as True and "merchantName" blank.
Please note that the PCI Booking merchant can only be used to perform 3D Secure authentication on Visa and Mastercard cards.

📘

Complying with Visa 3DS Authentication requirements

As of August 12th 2024, Visa requires all merchants performing 3D Secure authentication to send additional information for the purpose of the authentication. Many of these additional details are sent automatically, in the background, by our system, but there are some parameters that you will need to provide PCI Booking in your request - you would need to provide either the email address or the phone number of the person you are authenticating.

You will find two new additional parameters in this request to provide these values.

If you are using 3DS authentication, you MUST provide at least one of these values.

Body Params
string
required

The user ID of the booker

string
Defaults to EN

The form's language in ISO 639-1 (2-letter) format - see here. If an unsupported language is received, English will be displayed. Adding languages is simple to do through our user's control panel.

string

The CSS resource name. Please follow our guide on managing stylesheets. If no CSS is provided, PCI Booking will implement the default CSS.

string

A URL where the status of the request will be pushed to by PCI Booking.

CardTypes
array of strings

An optional parameter, which will limit the list of card types. If it is omitted, or if no valid card types are found, all types of cards will be displayed.
The list of card types should be separated by comma (,).
Read more on our supported card types.

CardTypes
boolean
Defaults to false

Will be displayed in the form (required in some countries). true: include the field. false: exclude the field.

string

Indicates which of the card types will be set as default in the card drop down menu. Read more on our supported card types.

boolean
Defaults to false

Indication whether to use card detection according to card number or not. true: use card detection. false: do not use card detection. There will be a drop down menu, indicating the card type.

string

Minimum expiration month/year parameter. Format: mmyyyy. The expiration validation will be checked vs. the minimum expiration date. The expiration date must be a valid date, in the specified format. Use case: Used when the card expiration should be later than a check-in date.

boolean
Defaults to false

Indicate whether to add the CVV field or not. true: include the CVV, and save it in the database. false: exclude the field.

int32
required

The number of hours that the request will be valid for. Minimum 1 hour, maximum 24 hours.

string
required

Indicates how to send the link to the card capture form - by Email or by text message. Optional values are email and sms.

string
required

The destination of the message. Email address or a phone number. If providing a phone number, the number should be formatted as an international dial number: Country code + area code + phone number.

string

A reference value which then can be used to query for this card token.

string

Free text field to provide a description of this request. The Description parameter can contain up to 50 characters.

string
required

Free text field to provide the recipient's name. The RecipientName parameter can contain up to 70 characters.

string

An optional value to indicate the merchant to be used for the 3D Secure authentication. To control the merchant information used for the 3D Secure authentication follow these instructions.
The value provided must be URL encoded and unique per the 3DS merchant account data used.

double

An optional parameter to indicate the amount of the transaction and the transaction amount to be displayed in the 3D Secure challenge screen.
The Amount parameter is required if the Currency parameter is provided.

string

An optional parameter to indicate the currency of the amount of the transaction and the transaction amount to be displayed in the 3D Secure challenge screen. Currency should be provided in ISO 4217 (3-letter) format.
The Currency parameter is required if the Amount parameter is provided.
If the Currency parameter has an incorrect value, error code 401 BAD DATA will be returned.

string

Free text to be displayed in the header of the message to the recipient. The CustomHeaderText parameter can contain up to 1000 characters.

If the RecipientName, Amount and Currency placeholders are not listed in the CustomHeaderText or in the portal customizations - however, they are provided in the other parameters of this request, the recipient name will be displayed under the header text area, and the amount and currency will be displayed under the recipient name.

string

Free text to be displayed in the footer of the message to the recipient. The CustomFooterText parameter can contain up to 1000 characters.

If the CustomerSupportEmail and CustomerSupportPhone placeholders are not listed in the CustomFooterText or in the portal customizations - however, they are provided in the other parameters of this request, the contact details will be displayed under the header text area.

string

Free text to be displayed as the phone number displayed in the email message to the recipient and in the landing page. The CustomerSupportPhone parameter can contain up to 20 characters.

string

Free text to be displayed in the email address displayed in the email message to the recipient and in the landing page. The CustomerSupportEmail parameter can contain up to 50 characters.

string

Free text to be displayed in the URL for customer support displayed in the email message to the recipient and in the landing page. The CustomerSupportLink parameter can contain up to 255 characters. The CustomerSupportLink parameter is required if the CustomerSupportLinkText parameter is provided.

string

Free text to be displayed in the display name of the URL for customer support displayed in the email message to the recipient and in the landing page. The CustomerSupportLinkText parameter can contain up to 100 characters. The CustomerSupportLinkText parameter is required if the CustomerSupportLink parameter is provided.

string

The name of the company sending the message
This field is required when sending a message as a SMS.

string

The URL where a successful response will be redirected to. Read more on how to set up success / failure redirection pages.

string

The URL where a failed response will be redirected to. Read more on how to set up success / failure redirection pages.

string

The URL to the logo that will be displayed in the COTP email and landing page.

  • If you prefer not to have a logo at all, please submit this parameter with a null value.
  • If the parameter is not supplied in the request, the logo displayed will be taken from the Booker information in our portal.
  • Images must be publically accessible, in HTTPS url with file type in one of the following: png, gif, bmp, jpeg or jpg.

    • string

    The title of the logo.

  • If not provided, the name of the booker (as set in our portal) will be used.
  • If you prefer that there will be no title to the logo image, please provide this parameter with a null value.
  • The LogoTitle can be up to 100 characters.

    • string

    The URL to the favicon that will be displayed in the COTP landing page.

  • If the parameter is not supplied in the request, the favicon displayed will be the browser default.
  • Images must be publically accessible, in HTTPS url in either ico or png format, size 1616 or 3232.

    • string
    Defaults to Card Display

    The page title to be displayed. The SiteTitle can be up to 40 characters.

    boolean
    Defaults to false

    Indicates whether to perform 3D secure authentication following card entry. Default value is False, i.e. not to run 3D secure authentication.
    If you enable 3D Secure authentication on this card capture and you are using access token authorization, please remember to provide two access tokens as mentioned above.

    string
    Defaults to Accept

    Instruction on what to do in case of a technical problem with the 3D process.
    Accept - Ignores 3D secure processing and proceeds with tokenizing the credit card.
    Reject - do not continue, and do not tokenize the card. In this case, the card owner will be directed to the failure page URL provided.

    string

    The email parameter should be used to provide the Cardholder's e-mail address for 3D Secure authentication. The Cardholder's email address must be in a valid email address format, e.g. [email protected].

    string

    The phone parameter should be used to provide the Cardholder's telephone number for 3D Secure authentication. The Cardholder's telephone number may only contain digits [0-9], e.g.: 00353112223344.

    boolean

    Indicates whether the PCI Booking system should look up this card details in cards previously stored and return the token of the existing card (if found) or always return a new token.
    Possible values are True: look up new card in existing cards and False: always create new tokens.
    If this parameter is not specified in the request, the default behavior of the system would be to create a new token for each tokenized card - regardless of whether it is already stored in PCI Booking.

    string

    An optional parameter to define additional input validation on the Name On Card field. Possible values are:

  • NO_DIGITS - indicates that the Name On Card field cannot contain digits.

    • Headers
    string
    required

    The authorization mechanism for this method is with the API key in the format of APIKEY {value}.
    For example, APIKEY bd3ce883352e42539a2b7644f72e6311.

    Responses

    Updated over 1 year ago

    Language
    Response 
    Click Try It! to start a request and see the response here! Or choose an example:
    application/json
    Updated over 1 year ago