Create Payments Library Session

const response = await fetch('https://service.pcibooking.net/api/eWalletOperation', {
  method: 'POST',
  headers: {
    'Authorization': 'APIKEY your-api-key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    operation: 'CHARGE',
    mode: 'LIVE',
    PaymentGatewayAccountId: 'my-gateway-credentials',
    PaymentGatewayParameters: { 'SomePspParameterName': 'SomeValue' },
    AllowedeWalletAccountIds: ['my-applepay', 'my-googlepay'],
    CurrencyCode: 'USD',
    Amount: 99.99,
    CountryCode: 'US',
    AllowedBrands: ['VISA', 'MASTERCARD', 'AMEX'],
    CustomerEmail: 'customer@example.com',
    merchantReference: 'ORDER-12345',
    // Optional: offer previously tokenized cards for CVV-only payment (max 3)
    StoredCards: [{
      Token: 'a21af1bb711d4daf89ee095d22a51f47',
      Brand: 'MasterCard',
      LastDigits: '1234',
      ExpirationMonth: 12,
      ExpirationYear: 2030,
      NameOnCard: 'John Doe'
    }]
  })
});
const { token } = await response.json();
// Pass token to your frontend

import requests

response = requests.post(
    'https://service.pcibooking.net/api/eWalletOperation',
    headers={
        'Authorization': 'APIKEY your-api-key',
        'Content-Type': 'application/json'
    },
    json={
        'operation': 'CHARGE',
        'mode': 'LIVE',
        'PaymentGatewayAccountId': 'my-gateway-credentials',
        'PaymentGatewayParameters': { 'SomePspParameterName': 'SomeValue' },
        'AllowedeWalletAccountIds': ['my-applepay', 'my-googlepay'],
        'CurrencyCode': 'USD',
        'Amount': 99.99,
        'CountryCode': 'US',
        'AllowedBrands': ['VISA', 'MASTERCARD', 'AMEX'],
        'CustomerEmail': 'customer@example.com',
        'merchantReference': 'ORDER-12345',
        # Optional: offer previously tokenized cards for CVV-only payment (max 3)
        'StoredCards': [{
            'Token': 'a21af1bb711d4daf89ee095d22a51f47',
            'Brand': 'MasterCard',
            'LastDigits': '1234',
            'ExpirationMonth': 12,
            'ExpirationYear': 2030,
            'NameOnCard': 'John Doe'
        }]
    }
)
token = response.json()['token']
# Pass token to your frontend

{
    "token": "abc123def456",
    "status": "Created"
}

{
    "code": -125,
    "message": "Bad input data",
    "moreInfo": "...",
    "errorList": null
}

POST

api

eWalletOperation

const response = await fetch('https://service.pcibooking.net/api/eWalletOperation', {
  method: 'POST',
  headers: {
    'Authorization': 'APIKEY your-api-key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    operation: 'CHARGE',
    mode: 'LIVE',
    PaymentGatewayAccountId: 'my-gateway-credentials',
    PaymentGatewayParameters: { 'SomePspParameterName': 'SomeValue' },
    AllowedeWalletAccountIds: ['my-applepay', 'my-googlepay'],
    CurrencyCode: 'USD',
    Amount: 99.99,
    CountryCode: 'US',
    AllowedBrands: ['VISA', 'MASTERCARD', 'AMEX'],
    CustomerEmail: 'customer@example.com',
    merchantReference: 'ORDER-12345',
    // Optional: offer previously tokenized cards for CVV-only payment (max 3)
    StoredCards: [{
      Token: 'a21af1bb711d4daf89ee095d22a51f47',
      Brand: 'MasterCard',
      LastDigits: '1234',
      ExpirationMonth: 12,
      ExpirationYear: 2030,
      NameOnCard: 'John Doe'
    }]
  })
});
const { token } = await response.json();
// Pass token to your frontend

import requests

response = requests.post(
    'https://service.pcibooking.net/api/eWalletOperation',
    headers={
        'Authorization': 'APIKEY your-api-key',
        'Content-Type': 'application/json'
    },
    json={
        'operation': 'CHARGE',
        'mode': 'LIVE',
        'PaymentGatewayAccountId': 'my-gateway-credentials',
        'PaymentGatewayParameters': { 'SomePspParameterName': 'SomeValue' },
        'AllowedeWalletAccountIds': ['my-applepay', 'my-googlepay'],
        'CurrencyCode': 'USD',
        'Amount': 99.99,
        'CountryCode': 'US',
        'AllowedBrands': ['VISA', 'MASTERCARD', 'AMEX'],
        'CustomerEmail': 'customer@example.com',
        'merchantReference': 'ORDER-12345',
        # Optional: offer previously tokenized cards for CVV-only payment (max 3)
        'StoredCards': [{
            'Token': 'a21af1bb711d4daf89ee095d22a51f47',
            'Brand': 'MasterCard',
            'LastDigits': '1234',
            'ExpirationMonth': 12,
            'ExpirationYear': 2030,
            'NameOnCard': 'John Doe'
        }]
    }
)
token = response.json()['token']
# Pass token to your frontend

{
    "token": "abc123def456",
    "status": "Created"
}

{
    "code": -125,
    "message": "Bad input data",
    "moreInfo": "...",
    "errorList": null
}

Payments Library Setup Guide

Get started with the Payments Library

Creates a session for a digital wallet operation. The session ID returned is used by the client-side Payments Library to present the payment UI to the payer.

Error Responses

Code	HTTP Status	Condition
none	`401`	API key is missing or invalid. The response body is empty.
`-125`	`400`	A sandbox user attempted a `LIVE` mode operation. Sandbox users can only use `TEST` mode.
`-125`	`400`	Session creation failed due to invalid parameters (e.g. missing required fields, invalid wallet account IDs).

Parameter Constraints

operation: Must be one of TOKENIZE, CHARGE, CHARGE_AND_TOKENIZE, PREAUTH_AND_TOKENIZE, GATEWAY_TOKENIZE.
mode: Must be TEST or LIVE. Sandbox users are restricted to TEST only.
PaymentGatewayAccountId: Must reference a valid stored credential ID. Required for every operation that sends the payment to a payment provider: CHARGE, CHARGE_AND_TOKENIZE, PREAUTH_AND_TOKENIZE and GATEWAY_TOKENIZE. Not required for TOKENIZE, which only stores the card, or for sessions that offer only PayPal, BankPay or UPI.
AllowedeWalletAccountIds: Array of stored digital wallet credential IDs.
CurrencyCode: Must be a valid ISO 4217 currency code.
CountryCode: Must be a valid ISO 3166-1 alpha-2 country code.
CustomerEmail: Must be a valid email format (when provided for 3DS).
CustomerPhone: Digits only (when provided for 3DS).
StoredCards: Maximum 3 cards. Not allowed with the TOKENIZE operation. Each token must belong to your account, and cards with a past expiration date are rejected. When the payer pays with a stored card in a CHARGE_AND_TOKENIZE or PREAUTH_AND_TOKENIZE session, the card is not tokenized again and the result contains no new token.

Tokenization (TOKENIZE operation) is only available for card pay, Apple Pay, and Google Pay. Other payment methods support charge only.3D Secure behavior varies by method:

Apple Pay: 3DS is always performed by Apple when the cardholder interacts with their device. The card always includes 3DS authentication results.
Google Pay: 3DS depends on cardholder interaction and device. If Google Pay performed two-factor authentication, the card includes the 3DS result.
Card pay: You choose whether to perform 3DS after the cardholder enters their card details. If enabled, PCI Booking performs 3DS and only proceeds if successful. When the payment gateway runs its own authentication (ThreeDsSupportedBy is PaymentProcessor in Get Payment Gateways, for example Paystack or RedDotPayment), the library opens the gateway’s authentication page for the payer instead.

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.

Operation

string

required

The type of operation to perform:

TOKENIZE: Retrieve card details from the digital wallet and store them as a token in PCI Booking’s vault. No charge is made.
CHARGE: Retrieve card details from the digital wallet and submit a charge to the payment gateway.
CHARGE_AND_TOKENIZE: Charge immediately, then store the payment method as a token for future use.
PREAUTH_AND_TOKENIZE: Authenticate/pre-authorize the card, then store the payment method as a token for future use.
GATEWAY_TOKENIZE: Store the payment method with the payment gateway itself (gateway tokenization).

Payment Gateway

string

The credentialsId of your payment gateway credentials, stored using Store Gateway Credentials. Required for every operation that sends the payment to a payment provider: CHARGE, CHARGE_AND_TOKENIZE, PREAUTH_AND_TOKENIZE and GATEWAY_TOKENIZE. Not required for TOKENIZE, which only stores the card, or for sessions that offer only PayPal, BankPay or UPI.

array

required

An array of digital wallet credential IDs stored using the Store Digital Wallet Credentials method.

object

Optional payment gateway parameters to pass to the PSP. Key-value pairs, where the key is the parameter name and the value is the parameter value. Some PSPs require specific parameters to be passed in order to process the payment.

array

Backup payment gateway accounts. If the payment fails at the primary gateway, PCI Booking tries each fallback in order and stops at the first success. Not used after the decline reasons CardExpired, Fraud, LostOrStolenCard or InsufficientFunds. Every account and certificate is checked when the session is created, and the session is refused if one does not exist. See Fallback Payment Gateways.

Show Properties

string

required

The ID of the stored payment gateway credentials to use as a fallback.

string

The client certificate for this gateway, if it needs one.

object

Gateway parameters for this gateway, as key-value pairs.

boolean

default:"false"

Whether to send the 3D Secure authentication data to this gateway.

Transaction

string

required

The environment. Possible values: TEST, LIVE.

string

required

ISO 4217 currency code (e.g. USD, EUR).

number

required

The transaction amount.

string

required

ISO 3166-1 alpha-2 country code of the payer (e.g. US, GB).

array

required

Array of accepted card brands (e.g. ['VISA', 'MASTERCARD', 'AMEX']). If the payer’s card does not match, they are prompted to enter a different card.

string

A note sent to and recorded by the payment processor.

string

Your own reference for this transaction (e.g. booking number, order ID).

Stored Cards

array

Optional list of up to 3 previously tokenized cards to offer the payer for card pay. When provided, the card entry page shows one button per card, labelled with the card brand and last 4 digits (for example Pay by VISA ****1234), alongside the option to enter another card. The payer selects a card and enters only its CVV; the charge is made against the real card resolved from the token.Each object contains:

Token (string, required): a card token belonging to your account.
Brand (string): card brand displayed to the payer (e.g. Visa, MasterCard).
LastDigits (string): last 4 digits displayed to the payer.
ExpirationMonth (number), ExpirationYear (number): the card’s expiration.
NameOnCard (string): cardholder name displayed to the payer.
OwnerId (string): cardholder owner ID, where applicable.

The display fields (Brand, LastDigits, NameOnCard, expiration) are shown to the payer exactly as you provide them and are not validated against the card behind the token. Keep them accurate: you can store these non-sensitive details in your own system, or retrieve them just before creating the session using Retrieve Token Metadata (single token) or Query Tokens (batch). The metadata response fields CardType, LastDigits, ExpirationMonth/ExpirationYear, and OwnerName map directly to the stored card fields.

3D Secure

string

The cardholder’s email address for 3D Secure authentication. Must be a valid email format. Either CustomerEmail or CustomerPhone is required when performing 3DS.

string

The cardholder’s phone number for 3D Secure authentication. Digits only (e.g. 00353112223344). Either CustomerEmail or CustomerPhone is required when performing 3DS.

const response = await fetch('https://service.pcibooking.net/api/eWalletOperation', {
  method: 'POST',
  headers: {
    'Authorization': 'APIKEY your-api-key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    operation: 'CHARGE',
    mode: 'LIVE',
    PaymentGatewayAccountId: 'my-gateway-credentials',
    PaymentGatewayParameters: { 'SomePspParameterName': 'SomeValue' },
    AllowedeWalletAccountIds: ['my-applepay', 'my-googlepay'],
    CurrencyCode: 'USD',
    Amount: 99.99,
    CountryCode: 'US',
    AllowedBrands: ['VISA', 'MASTERCARD', 'AMEX'],
    CustomerEmail: 'customer@example.com',
    merchantReference: 'ORDER-12345',
    // Optional: offer previously tokenized cards for CVV-only payment (max 3)
    StoredCards: [{
      Token: 'a21af1bb711d4daf89ee095d22a51f47',
      Brand: 'MasterCard',
      LastDigits: '1234',
      ExpirationMonth: 12,
      ExpirationYear: 2030,
      NameOnCard: 'John Doe'
    }]
  })
});
const { token } = await response.json();
// Pass token to your frontend

import requests

response = requests.post(
    'https://service.pcibooking.net/api/eWalletOperation',
    headers={
        'Authorization': 'APIKEY your-api-key',
        'Content-Type': 'application/json'
    },
    json={
        'operation': 'CHARGE',
        'mode': 'LIVE',
        'PaymentGatewayAccountId': 'my-gateway-credentials',
        'PaymentGatewayParameters': { 'SomePspParameterName': 'SomeValue' },
        'AllowedeWalletAccountIds': ['my-applepay', 'my-googlepay'],
        'CurrencyCode': 'USD',
        'Amount': 99.99,
        'CountryCode': 'US',
        'AllowedBrands': ['VISA', 'MASTERCARD', 'AMEX'],
        'CustomerEmail': 'customer@example.com',
        'merchantReference': 'ORDER-12345',
        # Optional: offer previously tokenized cards for CVV-only payment (max 3)
        'StoredCards': [{
            'Token': 'a21af1bb711d4daf89ee095d22a51f47',
            'Brand': 'MasterCard',
            'LastDigits': '1234',
            'ExpirationMonth': 12,
            'ExpirationYear': 2030,
            'NameOnCard': 'John Doe'
        }]
    }
)
token = response.json()['token']
# Pass token to your frontend

Response

The response contains the session details needed by the client-side Payments Library.

{
    "token": "abc123def456",
    "status": "Created"
}

{
    "code": -125,
    "message": "Bad input data",
    "moreInfo": "...",
    "errorList": null
}

Start Here

Authentication & General

Capture Cards

Manage Tokens

Use Tokens

Additional Functions

Payments Library

Create Payments Library Session

Payments Library Setup Guide

Error Responses

Parameter Constraints

Parameters

Authentication

Operation

Payment Gateway

Transaction

Stored Cards

3D Secure

Response

Payments Library Setup Guide

​Error Responses

​Parameter Constraints

​Parameters

​Authentication

​Operation

​Payment Gateway

​Transaction

​Stored Cards

​3D Secure

​Response

Error Responses

Parameter Constraints

Parameters

Authentication

Operation

Payment Gateway

Transaction

Stored Cards

3D Secure

Response