Send Card Capture Link

const response = await fetch('https://service.pcibooking.net/api/cardrequest', {
  method: 'POST',
  headers: {
    'Authorization': 'APIKEY your-api-key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    SenderID: 'myhotel',
    DestinationType: 'email',
    Destination: 'guest@example.com',
    RecipientName: 'Jane Smith',
    RequestTTL: 12,
    Language: 'en',
    AutoDetectCardType: true,
    CVV: true,
    SenderReference: 'booking-12345',
    Description: 'Card for reservation #12345',
    CompanyName: 'Sunrise Hotel',
    Success: 'https://yoursite.com/success',
    Failure: 'https://yoursite.com/failure',
    CallBackURL: 'https://yoursite.com/webhook/card-status'
  })
});

const requestUri = response.headers.get('Location');
console.log('Request URI:', requestUri);

import requests

response = requests.post(
    'https://service.pcibooking.net/api/cardrequest',
    headers={
        'Authorization': 'APIKEY your-api-key',
        'Content-Type': 'application/json'
    },
    json={
        'SenderID': 'myhotel',
        'DestinationType': 'email',
        'Destination': 'guest@example.com',
        'RecipientName': 'Jane Smith',
        'RequestTTL': 12,
        'Language': 'en',
        'AutoDetectCardType': True,
        'CVV': True,
        'SenderReference': 'booking-12345',
        'Description': 'Card for reservation #12345',
        'CompanyName': 'Sunrise Hotel',
        'Success': 'https://yoursite.com/success',
        'Failure': 'https://yoursite.com/failure',
        'CallBackURL': 'https://yoursite.com/webhook/card-status'
    }
)

request_uri = response.headers.get('Location')
print('Request URI:', request_uri)

Empty response body. The Location header contains the request URI:
Location: https://service.pcibooking.net/api/payments/paycard/CardForm/SULqe7pa22gghYDnX6O3J7QDMhyyUzNb

{
    "code": -179,
    "message": "Bad input parameter",
    "moreInfo": "Bad input data",
    "errorList": [
        "Bad json format"
    ]
}

{
  "code": -1003,
  "message": "Not authorized to access this resource",
  "moreInfo": "Bad or missing authorization data, expected APIKEY",
  "errorList": null
}

POST

api

cardrequest

const response = await fetch('https://service.pcibooking.net/api/cardrequest', {
  method: 'POST',
  headers: {
    'Authorization': 'APIKEY your-api-key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    SenderID: 'myhotel',
    DestinationType: 'email',
    Destination: 'guest@example.com',
    RecipientName: 'Jane Smith',
    RequestTTL: 12,
    Language: 'en',
    AutoDetectCardType: true,
    CVV: true,
    SenderReference: 'booking-12345',
    Description: 'Card for reservation #12345',
    CompanyName: 'Sunrise Hotel',
    Success: 'https://yoursite.com/success',
    Failure: 'https://yoursite.com/failure',
    CallBackURL: 'https://yoursite.com/webhook/card-status'
  })
});

const requestUri = response.headers.get('Location');
console.log('Request URI:', requestUri);

import requests

response = requests.post(
    'https://service.pcibooking.net/api/cardrequest',
    headers={
        'Authorization': 'APIKEY your-api-key',
        'Content-Type': 'application/json'
    },
    json={
        'SenderID': 'myhotel',
        'DestinationType': 'email',
        'Destination': 'guest@example.com',
        'RecipientName': 'Jane Smith',
        'RequestTTL': 12,
        'Language': 'en',
        'AutoDetectCardType': True,
        'CVV': True,
        'SenderReference': 'booking-12345',
        'Description': 'Card for reservation #12345',
        'CompanyName': 'Sunrise Hotel',
        'Success': 'https://yoursite.com/success',
        'Failure': 'https://yoursite.com/failure',
        'CallBackURL': 'https://yoursite.com/webhook/card-status'
    }
)

request_uri = response.headers.get('Location')
print('Request URI:', request_uri)

Empty response body. The Location header contains the request URI:
Location: https://service.pcibooking.net/api/payments/paycard/CardForm/SULqe7pa22gghYDnX6O3J7QDMhyyUzNb

{
    "code": -179,
    "message": "Bad input parameter",
    "moreInfo": "Bad input data",
    "errorList": [
        "Bad json format"
    ]
}

{
  "code": -1003,
  "message": "Not authorized to access this resource",
  "moreInfo": "Bad or missing authorization data, expected APIKEY",
  "errorList": null
}

Card By Link Guide

Send secure card capture links via email or SMS

Use this endpoint to send a secure card capture link to a cardholder via email or SMS. The recipient clicks the link to open a PCI-compliant form where they enter their card details, which are tokenized and stored by PCI Booking. This is ideal for scenarios like phone bookings or back-office operations where you need to collect card data without handling it directly.

Error Responses

Code	HTTP Status	Condition
-179	400	Validation error: missing required fields, invalid field format, or malformed JSON body.
-112	400	Destination phone number exceeds maximum length (SMS delivery).
-1003	401	Missing or invalid API key in the `Authorization` header.
-1003	401	`SenderID` does not match the identity associated with the API key.
-150	500	Internal system error while creating the card request.

Parameter Constraints

Parameter	Constraint
`RequestTTL`	Integer, range 1 to 24 (hours).
`Destination`	Max 255 characters. For SMS, phone number is sanitized (non-digit characters and leading `+`/`0` removed) then validated against a maximum length.
`RecipientName`	Required. Max 70 characters.
`SenderReference`	Max 50 characters.
`Description`	Max 50 characters.
`CompanyName`	Max 20 characters. Required when `DestinationType` is `sms`.
`CustomHeaderText`	Max 1000 characters.
`CustomFooterText`	Max 1000 characters.
`CustomerSupportPhone`	Max 20 characters.
`CustomerSupportEmail`	Max 50 characters.
`CustomerSupportLink`	Max 255 characters. Must be a valid URL.
`CustomerSupportLinkText`	Max 100 characters.
`LogoTitle`	Max 100 characters.
`SiteTitle`	Max 40 characters.
`ClientLogoUrl`	Must be a valid fully-qualified HTTP, HTTPS, or FTP URL (if provided).
`MinExpiration`	Format `mmyyyy`, regex `^(1[0-2]	0[1-9])(20\d\d)$`.

Parameters

Headers

string

required

Your API key prefixed with APIKEY. Example: APIKEY your-api-key. See the Authentication guide.

Request Configuration

string

required

The user ID of the booker.

string

default:"EN"

The form’s language in ISO 639-1 (2-letter) format. See supported languages. If an unsupported language is received, English will be displayed.

string

The CSS resource name. Follow the guide on managing stylesheets. If not provided, PCI Booking will use the default CSS.

string

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

integer

required

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

Card Form Settings

string[]

Limits the list of card types accepted on the form. Use the exact Code values from Supported Card Types, e.g. ["Visa", "MasterCard", "AMEX"]. If omitted, all types are displayed. Values that don’t match a supported code are ignored - and if none of the provided values are valid, the form falls back to displaying all card types, so double-check spelling if you rely on this restriction. The list can also be retrieved via the Get Supported Credit Cards endpoint.

boolean

default:"false"

Whether to display the Owner ID field in the form (required in some countries). true: include the field. false: exclude the field.

string

Which card type will be set as default in the card drop down menu. Read more on supported card types.

boolean

default:"false"

Whether to use card detection according to card number. true: use card detection. false: show a drop down menu for card type selection.

string

Minimum expiration month/year. Format: mmyyyy. The expiration validation will be checked against this date. Must be a valid date in the specified format. Use case: when the card expiration should be later than a check-in date.

boolean

default:"false"

Whether to add the CVV field. true: include the CVV and save it in the database. false: exclude the field.

string

Additional input validation on the Name On Card field. Possible values: NO_DIGITS - the field cannot contain digits.

boolean

Whether PCI Booking should look up this card in previously stored cards and return the existing token (if found) or always return a new token. True: look up in existing cards. False: always create new tokens. If not specified, the default behavior is taken from the account settings. 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.

Delivery

string

required

How to send the link to the card capture form. Values: email or sms.

string

required

The destination of the message - email address or phone number. For phone numbers, format as international dial number: Country code + area code + phone number.

string

required

The recipient’s name. Max 70 characters.

string

Free text description of this request. Max 50 characters.

string

A reference value that can be used to query for this card token later.

Branding

CustomerSupportLink, CustomerSupportLinkText, CustomerSupportEmail, and CustomerSupportPhone can also be set in your account settings. Values provided in the request override the account defaults.

URLs in the request body (e.g. ClientLogoURL, Success, Failure) should not be URL-encoded, since they are sent in JSON, not as query parameters.

string

The name of the company sending the message. Required when sending via SMS.

string

URL to the logo displayed in the Card By Link email and landing page. Submit with a null value to hide the logo. If not supplied, the logo from the Booker information in the portal is used. Images must be publicly accessible, HTTPS URL. Supported image formats: png, gif, bmp, jpeg, jpg.

string

The title of the logo. If not provided, the booker name (as set in the portal) is used. Submit with a null value for no title. Max 100 characters.

string

URL to the favicon displayed in the Card By Link landing page. If not supplied, the browser default is used. Images must be publicly accessible, HTTPS URL in ico or png format, size 16x16 or 32x32.

string

The page title to be displayed. Max 40 characters.

string

Text displayed in the header of the card capture page. Max 1000 characters. Overrides the portal template. Supports dynamic variables in $~name~$ syntax (e.g. $~recipient_name~$ , $~amount~$ ) - see Dynamic Variables. Variables you do not use here (or in the footer) are embedded in the page automatically by PCI Booking when their values are provided in other request parameters.

string

Text displayed in the footer of the card capture page. Max 1000 characters. Overrides the portal template. Supports dynamic variables in $~name~$ syntax (e.g. $~cs_phone~$ , $~cs_email~$ , $~cs_link~$ ) - see Dynamic Variables. Variables you do not use here (or in the header) are embedded in the page automatically by PCI Booking when their values are provided in other request parameters.

string

Phone number displayed in the email message and landing page. Max 20 characters.

string

Email address displayed in the email message and landing page. Max 50 characters.

string

URL for customer support displayed in the email message and landing page. Max 255 characters. Required if CustomerSupportLinkText is provided.

string

Display name for the customer support URL in the email message and landing page. Max 100 characters. Required if CustomerSupportLink is provided.

Redirect URLs

string

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

string

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

3D Secure

The 3DS challenge window has a 5 minute timeout. If the cardholder does not respond in time, authentication is rejected.
Do not use merchantName unless you have configured your 3DS merchant information. To use PCI Booking’s merchant, set ThreeDS to True and leave merchantName blank (Visa and Mastercard only). An unregistered merchantName does not return an error - PCI Booking silently falls back to its default merchant and the cardholder sees PCI Booking’s name.
Visa requirement (Aug 2024): You must provide at least the cardholder’s email or phone for 3DS authentication.
UnavailThreeDSAuth defaults to Accept. If 3DS can’t complete for any reason, the card is still tokenized - silently, without 3DS data. If you later charge that token through a PSP that requires 3DS, the charge will be rejected. Set this to Reject if every token in your flow must have 3DS data.

boolean

default:"False"

Whether to perform 3D Secure authentication following card entry. If enabled with access token authorization, provide two access tokens.

string

default:"Accept"

What to do if there is a technical problem with the 3DS process. Accept - ignore 3DS and proceed with tokenizing the card. Reject - do not continue or tokenize; the card owner will be directed to the failure page URL.

string

The merchant to use for 3D Secure authentication. Must match a merchant name registered in your 3DS merchant setup.

double

The transaction amount, also displayed in the 3DS challenge screen. Required if Currency is provided.

string

The transaction currency in ISO 4217 (3-letter) format, also displayed in the 3DS challenge screen. Required if Amount is provided.

string

Cardholder’s email address for 3D Secure authentication. Must be in a valid email format, e.g. joe@bloggs.com.

string

Cardholder’s telephone number for 3D Secure authentication. May only contain digits [0-9], e.g.: 00353112223344.

const response = await fetch('https://service.pcibooking.net/api/cardrequest', {
  method: 'POST',
  headers: {
    'Authorization': 'APIKEY your-api-key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    SenderID: 'myhotel',
    DestinationType: 'email',
    Destination: 'guest@example.com',
    RecipientName: 'Jane Smith',
    RequestTTL: 12,
    Language: 'en',
    AutoDetectCardType: true,
    CVV: true,
    SenderReference: 'booking-12345',
    Description: 'Card for reservation #12345',
    CompanyName: 'Sunrise Hotel',
    Success: 'https://yoursite.com/success',
    Failure: 'https://yoursite.com/failure',
    CallBackURL: 'https://yoursite.com/webhook/card-status'
  })
});

const requestUri = response.headers.get('Location');
console.log('Request URI:', requestUri);

import requests

response = requests.post(
    'https://service.pcibooking.net/api/cardrequest',
    headers={
        'Authorization': 'APIKEY your-api-key',
        'Content-Type': 'application/json'
    },
    json={
        'SenderID': 'myhotel',
        'DestinationType': 'email',
        'Destination': 'guest@example.com',
        'RecipientName': 'Jane Smith',
        'RequestTTL': 12,
        'Language': 'en',
        'AutoDetectCardType': True,
        'CVV': True,
        'SenderReference': 'booking-12345',
        'Description': 'Card for reservation #12345',
        'CompanyName': 'Sunrise Hotel',
        'Success': 'https://yoursite.com/success',
        'Failure': 'https://yoursite.com/failure',
        'CallBackURL': 'https://yoursite.com/webhook/card-status'
    }
)

request_uri = response.headers.get('Location')
print('Request URI:', request_uri)

Response

201 - Empty body. A Location header is returned with the URI for this card request. Use this URI to retrieve the request status or delete the request.

Remember to set the CVV Retention Policy on the token once the card is captured.

Empty response body. The Location header contains the request URI:
Location: https://service.pcibooking.net/api/payments/paycard/CardForm/SULqe7pa22gghYDnX6O3J7QDMhyyUzNb

{
    "code": -179,
    "message": "Bad input parameter",
    "moreInfo": "Bad input data",
    "errorList": [
        "Bad json format"
    ]
}

{
  "code": -1003,
  "message": "Not authorized to access this resource",
  "moreInfo": "Bad or missing authorization data, expected APIKEY",
  "errorList": null
}

Start Here

Authentication & General

Capture Cards

Manage Tokens

Use Tokens

Additional Functions

Payments Library

Send Card Capture Link

Card By Link Guide

Error Responses

Parameter Constraints

Parameters

Headers

Request Configuration

Card Form Settings

Delivery

Branding

Redirect URLs

3D Secure

Response

Card By Link Guide

​Error Responses

​Parameter Constraints

​Parameters

​Headers

​Request Configuration

​Card Form Settings

​Delivery

​Branding

​Redirect URLs

​3D Secure

​Response

Error Responses

Parameter Constraints

Parameters

Headers

Request Configuration

Card Form Settings

Delivery

Branding

Redirect URLs

3D Secure

Response