Create Card Entry Form Session

const response = await fetch('https://service.pcibooking.net/api/capturecard', {
  method: 'POST',
  headers: {
    'Authorization': 'APIKEY your-api-key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    TTL: 300,
    creatorReference: 'booking-12345',
    CallBackURL: 'https://yoursite.com/webhook/card-captured',
    Properties: {
      Language: 'en',
      AutoDetectCardType: true,
      ShowCVV: true,
      Success: 'https://yoursite.com/success?cardToken={cardToken}',
      Failure: 'https://yoursite.com/failure',
      postMessageHost: 'yoursite.com',
      CardTypes: ['Visa', 'MasterCard', 'AMEX']
    }
  })
});

const formUrl = response.headers.get('Location');
const data = await response.json();
console.log('Request ID:', data.RequestID);
console.log('Form URL:', formUrl);

import requests

response = requests.post(
    'https://service.pcibooking.net/api/capturecard',
    headers={
        'Authorization': 'APIKEY your-api-key',
        'Content-Type': 'application/json'
    },
    json={
        'TTL': 300,
        'creatorReference': 'booking-12345',
        'CallBackURL': 'https://yoursite.com/webhook/card-captured',
        'Properties': {
            'Language': 'en',
            'AutoDetectCardType': True,
            'ShowCVV': True,
            'Success': 'https://yoursite.com/success?cardToken={cardToken}',
            'Failure': 'https://yoursite.com/failure',
            'postMessageHost': 'yoursite.com',
            'CardTypes': ['Visa', 'MasterCard', 'AMEX']
        }
    }
)

form_url = response.headers.get('Location')
data = response.json()
print('Request ID:', data['RequestID'])
print('Form URL:', form_url)

{
  "RequestID": "ITGdnzZuR7hQOI583EUB8U9vC3aPjuoV",
  "SenderId": "RoeeSandbox",
  "CreatorReference": "Card capture request",
  "TTL": 600,
  "CallBackURL": "http://httpbin.org/post",
  "CreateTime": "2019-11-20T11:36:46.8062564Z",
  "Properties": {
    "Language": "en",
    "Css": "test",
    "removeBaseCss": false,
    "CardTypes": [
      "Visa",
      "electron",
      "mastercard",
      "maestro",
      "UnionPay"
    ],
    "DefaultCardType": "Visa",
    "AutoDetectCardType": true,
    "ShowOwnerID": false,
    "MinExpiration": "082020",
    "ShowCVV": true,
    "Success": "https://www.google.com?cardToken={cardToken}",
    "Failure": "https://www.pcibooking.net",
    "autoFocus": true,
    "submitWithPostMessage": false,
    "postMessageHost": "https://www.example.com",
    "ThreeDS": true,
    "UnavailThreeDSAuth": "Accept",
    "ExpirationMonths": "Names"
  }
}

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

Empty response body.
Authentication failed: the API key, session token or access token is missing or was not accepted.
See "Authentication and Permission Failures" on the Error Handling page.

POST

api

capturecard

const response = await fetch('https://service.pcibooking.net/api/capturecard', {
  method: 'POST',
  headers: {
    'Authorization': 'APIKEY your-api-key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    TTL: 300,
    creatorReference: 'booking-12345',
    CallBackURL: 'https://yoursite.com/webhook/card-captured',
    Properties: {
      Language: 'en',
      AutoDetectCardType: true,
      ShowCVV: true,
      Success: 'https://yoursite.com/success?cardToken={cardToken}',
      Failure: 'https://yoursite.com/failure',
      postMessageHost: 'yoursite.com',
      CardTypes: ['Visa', 'MasterCard', 'AMEX']
    }
  })
});

const formUrl = response.headers.get('Location');
const data = await response.json();
console.log('Request ID:', data.RequestID);
console.log('Form URL:', formUrl);

import requests

response = requests.post(
    'https://service.pcibooking.net/api/capturecard',
    headers={
        'Authorization': 'APIKEY your-api-key',
        'Content-Type': 'application/json'
    },
    json={
        'TTL': 300,
        'creatorReference': 'booking-12345',
        'CallBackURL': 'https://yoursite.com/webhook/card-captured',
        'Properties': {
            'Language': 'en',
            'AutoDetectCardType': True,
            'ShowCVV': True,
            'Success': 'https://yoursite.com/success?cardToken={cardToken}',
            'Failure': 'https://yoursite.com/failure',
            'postMessageHost': 'yoursite.com',
            'CardTypes': ['Visa', 'MasterCard', 'AMEX']
        }
    }
)

form_url = response.headers.get('Location')
data = response.json()
print('Request ID:', data['RequestID'])
print('Form URL:', form_url)

{
  "RequestID": "ITGdnzZuR7hQOI583EUB8U9vC3aPjuoV",
  "SenderId": "RoeeSandbox",
  "CreatorReference": "Card capture request",
  "TTL": 600,
  "CallBackURL": "http://httpbin.org/post",
  "CreateTime": "2019-11-20T11:36:46.8062564Z",
  "Properties": {
    "Language": "en",
    "Css": "test",
    "removeBaseCss": false,
    "CardTypes": [
      "Visa",
      "electron",
      "mastercard",
      "maestro",
      "UnionPay"
    ],
    "DefaultCardType": "Visa",
    "AutoDetectCardType": true,
    "ShowOwnerID": false,
    "MinExpiration": "082020",
    "ShowCVV": true,
    "Success": "https://www.google.com?cardToken={cardToken}",
    "Failure": "https://www.pcibooking.net",
    "autoFocus": true,
    "submitWithPostMessage": false,
    "postMessageHost": "https://www.example.com",
    "ThreeDS": true,
    "UnavailThreeDSAuth": "Accept",
    "ExpirationMonths": "Names"
  }
}

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

Empty response body.
Authentication failed: the API key, session token or access token is missing or was not accepted.
See "Authentication and Permission Failures" on the Error Handling page.

Hosted Card Entry Form Guide

API session approach for embedded card capture

The successful response of this method will include the following:

RequestID for this Card Entry Form session. You will need to use this request ID in future requests relating to this Card Entry Form session.
Location header for the URL of the card form. You will need to set this URL as the value of the SRC attribute of your iframe in your webpage.

All URLs should be HTTPS.

Error Responses

Code	HTTP Status	Condition
-179	400	Validation error: missing required fields, invalid field format, or malformed JSON body.
-125	400	Invalid credentials ID provided via the `credentialsId` query parameter.
none	401	Missing or invalid API key in the `Authorization` header. The response body is empty.
-160	404	Resource not matching request (e.g. wrong capture type).

Parameter Constraints

Parameter	Constraint
`TTL`	Integer, range 30 to 600 (seconds). Default: 120.
`CreatorReference`	Max 50 characters.
`CallBackURL`	Must be a valid URL.
`Properties.MinExpiration`	Format `mmyyyy`, regex `^(1[0-2]	0[1-9])(20\d\d)$`. Cards with expiration before this date are rejected.
`Properties.Language`	2-letter ISO 639-1 language code. `zh` is automatically mapped to `cn` internally.

Parameters

Authentication

API key only. This endpoint does not accept access tokens or session tokens.

string

required

Your API key prefixed with APIKEY. Example: APIKEY your-api-key. The x-pcibooking-api-key header is also accepted. See the Authentication guide.

Request Body

string

URL where PCI Booking will push the status of the request.

integer

default:"120"

required

Number of seconds the request will be valid for. Minimum 30, maximum 600.

string

Your own reference, stored on the token that this session produces, so you can find the token later with Query Tokens. It does not identify the session and need not be unique.

object

The settings of the card entry form. The request example shows common ones.

Show Properties

string

default:"en"

The form’s language, as a 2-letter ISO 639-1 code.

string

The name of one of your stylesheets. If omitted, your default stylesheet is used.

boolean

default:"false"

Set to true to leave out PCI Booking’s base stylesheet, so that the form is styled only by your stylesheet.

boolean

default:"false"

Shows the CVV field. When true, the CVV the cardholder enters is also stored with the token, subject to your CVV retention policy.

boolean

default:"false"

Shows the cardholder ID field.

string[]

Limits the card types accepted on the form. Use the exact Code values from Supported Card Types. Invalid values are ignored, and if none are valid the form accepts all types. A card of another type is rejected with a BadData callback.

string

The card type selected in the dropdown when the form opens. Only relevant when AutoDetectCardType is false.

boolean

default:"false"

When true, the form detects the card type from the card number. When false, the cardholder selects it from a dropdown.

string

The earliest accepted expiration date, in mmyyyy format. A card that expires earlier is rejected with a BadData callback.

string

default:"Numbers"

How the expiration months are shown: Numbers or Names.

string

Set to NO_DIGITS to reject digits in the name on card.

boolean

default:"false"

If the same card is already stored in your account, returns the existing token instead of creating a new one. A duplicate has the same card number and expiration date; the name and CVV do not matter.

string

default:"IE"

The region where the card data is stored. One of: US, IN, AU, JP, CA, IE, GB, BR. If omitted, the card is stored in Ireland. Your account’s default region is not used. See Card Storage Regions.

boolean

default:"false"

Runs 3D Secure authentication when the card is submitted.

string

default:"Accept"

What to do if the 3D Secure service is unavailable: Accept stores the card without 3D Secure, Reject does not store it and redirects to the Failure URL.

string

The name of your 3DS merchant profile to use for 3D Secure. See the warning below.

string

The cardholder’s email address, sent with the 3D Secure authentication.

string

The cardholder’s phone number, sent with the 3D Secure authentication. Digits only, including the country code, without +.

integer

default:"0"

The transaction amount, in minor units (for example 12550 for 125.50), sent with the 3D Secure authentication.

string

default:"EUR"

The currency of Amount, as an ISO 4217 code.

string

The URL the form redirects to after the card is stored. The token details are appended as query parameters. See success and failure URLs.

string

The URL the form redirects to if the card cannot be stored. See success and failure URLs.

boolean

default:"false"

Places the cursor in the first field when the form loads.

boolean

default:"false"

Removes the form’s own submit button, so that your page submits the form with a postMessage.

string

The origin of your page, which receives the form’s postMessage events.

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.

const response = await fetch('https://service.pcibooking.net/api/capturecard', {
  method: 'POST',
  headers: {
    'Authorization': 'APIKEY your-api-key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    TTL: 300,
    creatorReference: 'booking-12345',
    CallBackURL: 'https://yoursite.com/webhook/card-captured',
    Properties: {
      Language: 'en',
      AutoDetectCardType: true,
      ShowCVV: true,
      Success: 'https://yoursite.com/success?cardToken={cardToken}',
      Failure: 'https://yoursite.com/failure',
      postMessageHost: 'yoursite.com',
      CardTypes: ['Visa', 'MasterCard', 'AMEX']
    }
  })
});

const formUrl = response.headers.get('Location');
const data = await response.json();
console.log('Request ID:', data.RequestID);
console.log('Form URL:', formUrl);

import requests

response = requests.post(
    'https://service.pcibooking.net/api/capturecard',
    headers={
        'Authorization': 'APIKEY your-api-key',
        'Content-Type': 'application/json'
    },
    json={
        'TTL': 300,
        'creatorReference': 'booking-12345',
        'CallBackURL': 'https://yoursite.com/webhook/card-captured',
        'Properties': {
            'Language': 'en',
            'AutoDetectCardType': True,
            'ShowCVV': True,
            'Success': 'https://yoursite.com/success?cardToken={cardToken}',
            'Failure': 'https://yoursite.com/failure',
            'postMessageHost': 'yoursite.com',
            'CardTypes': ['Visa', 'MasterCard', 'AMEX']
        }
    }
)

form_url = response.headers.get('Location')
data = response.json()
print('Request ID:', data['RequestID'])
print('Form URL:', form_url)

Response

201 - Session created. A Location header is returned with the card form URL. Set this URL as the src of your iframe.

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

{
  "RequestID": "ITGdnzZuR7hQOI583EUB8U9vC3aPjuoV",
  "SenderId": "RoeeSandbox",
  "CreatorReference": "Card capture request",
  "TTL": 600,
  "CallBackURL": "http://httpbin.org/post",
  "CreateTime": "2019-11-20T11:36:46.8062564Z",
  "Properties": {
    "Language": "en",
    "Css": "test",
    "removeBaseCss": false,
    "CardTypes": [
      "Visa",
      "electron",
      "mastercard",
      "maestro",
      "UnionPay"
    ],
    "DefaultCardType": "Visa",
    "AutoDetectCardType": true,
    "ShowOwnerID": false,
    "MinExpiration": "082020",
    "ShowCVV": true,
    "Success": "https://www.google.com?cardToken={cardToken}",
    "Failure": "https://www.pcibooking.net",
    "autoFocus": true,
    "submitWithPostMessage": false,
    "postMessageHost": "https://www.example.com",
    "ThreeDS": true,
    "UnavailThreeDSAuth": "Accept",
    "ExpirationMonths": "Names"
  }
}

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

Empty response body.
Authentication failed: the API key, session token or access token is missing or was not accepted.
See "Authentication and Permission Failures" on the Error Handling page.

Start Here

Authentication & General

Capture Cards

Manage Tokens

Use Tokens

Additional Functions

Payments Library

Create Card Entry Form Session

Hosted Card Entry Form Guide

Error Responses

Parameter Constraints

Parameters

Authentication

Request Body

Response

Hosted Card Entry Form Guide

​Error Responses

​Parameter Constraints

​Parameters

​Authentication

​Request Body

​Response

Error Responses

Parameter Constraints

Parameters

Authentication

Request Body

Response