Skip to main content
POST

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

Parameter Constraints

  • operation: Must be TOKENIZE or CHARGE.
  • mode: Must be TEST or LIVE. Sandbox users are restricted to TEST only.
  • PaymentGatewayAccountId: Must reference a valid stored credential ID.
  • AllowedeWalletAccountIds: Comma-separated list 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).
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.

Parameters

Headers

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

Operation

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.
  • CHARGE: Retrieve card details from the digital wallet and submit a charge to the payment gateway.

Payment Gateway

PaymentGatewayAccountId
string
required
The credentialsId of your payment gateway credentials, stored using the Store Gateway Credentials method.
AllowedeWalletAccountIds
string
required
A comma-separated list of digital wallet credential IDs stored using the Store Digital Wallet Credentials method.
FallbackUpgs
array
Fallback payment gateway accounts to try if the primary gateway fails. Each object contains the fallback gateway account details.

Transaction

mode
string
required
The environment. Possible values: TEST, LIVE.
CurrencyCode
string
required
ISO 4217 currency code (e.g. USD, EUR).
Amount
number
required
The transaction amount.
CountryCode
string
required
ISO 3166-1 alpha-2 country code of the payer (e.g. US, GB).
AllowedBrands
string
required
Comma-separated list of accepted card brands. If the payer’s card does not match, they are prompted to enter a different card.
PaymentNote
string
A note sent to and recorded by the payment processor.
merchantReference
string
Your own reference for this transaction (e.g. booking number, order ID).

3D Secure

CustomerEmail
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.
CustomerPhone
string
The cardholder’s phone number for 3D Secure authentication. Digits only (e.g. 00353112223344). Either CustomerEmail or CustomerPhone is required when performing 3DS.

Response

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