Skip to main content
POST
Process Transaction

Processing Charges Guide

Process payments using stored tokens
PCI Booking retrieves the real card data from the token, constructs a PSP-specific request, sends it to your configured payment gateway, and returns the gateway’s response.
Some payment gateways have additional requirements. Review the gateway-specific guidance before sending your first transaction.

​
Error Responses

​
Error detail

Each condition below gives the exact moreInfo text, why it happens and how to resolve it. The full set is on the Error Handling page.
HTTP status: 400message: Bad input datamoreInfo:
Reason. The body could not be deserialised into the object the endpoint expects, so no field level validation ran. A single malformed field or a wrong container type is enough.How to resolve.
  1. Validate the body against the endpoint’s schema before sending.
  2. Check for a value sent as the wrong type, most often a number sent as a string or an object sent where an array is expected.
  3. Check Content-Type matches the body format.
HTTP status: 400message: Bad input datamoreInfo:
Reason. The transaction carried no card to charge. Either the card object is absent, or the CardToken property is missing or not a readable token URI.How to resolve.
  1. Send exactly one of a card object or a CardToken, as the endpoint requires.
  2. Pass the full token URI, not the bare 32-hex token, unless the endpoint documents otherwise.
  3. Check the property name and its capitalisation against the endpoint reference.
HTTP status: 400message: Bad input datamoreInfo:
Reason. A field the operation cannot run without was absent. Which field is required depends on the operation: a capture or refund needs the GatewayReference of the original authorisation, and an amount is required wherever money moves.How to resolve.
  1. Add the field named in moreInfo.
  2. For a capture, refund or void, send the GatewayReference returned by the original transaction rather than your own reference.
  3. Send the amount in the units the gateway expects, and check whether it takes minor units.
HTTP status: 400message: Bad input datamoreInfo:
Reason. The profile or gateway configuration names a client certificate for mutual TLS, but it could not be loaded. This is a configuration problem on the account, not a fault in your request.How to resolve.
  1. Check the certificate is uploaded against the account and the profile names it exactly.
  2. Check the certificate has not expired.
  3. Contact support with the profile name if both look correct. Certificate installation is done on the PCI Booking side.
HTTP status: 404message: Uri not foundmoreInfo:
Reason. The token is well formed but no card is stored against it. Either it never existed, or it was deleted. Deletion is permanent and cannot be undone.How to resolve.
  1. Confirm the tokenization call that should have created it returned success and returned this exact token.
  2. Check whether the token was deleted, either explicitly or by a CVV retention policy configured to delete the card on cleanup.
  3. Check the environment. A token from one environment is not visible in the other.
Some endpoints report a deleted token as -1003 rather than -160. Treat the two as the same investigation and start with whether the token still exists.
HTTP status: 401message: You are not authorized to access this resource. Please contact customer support.moreInfo: one of the following, depending on which check failed:
Reason. The credential authenticated fine, but it is not allowed to act on the token in the request. The generic wording makes this the single most misread error in the API. On a token call it is far more often one of the causes below than an actual permissions problem.How to resolve.
  1. Check the token was not deleted. This is the most common cause. Deletion is permanent, and every later call on that token returns -1003 rather than a not-found error. Support can confirm when and by which user a token was deleted.
  2. Check the tokenization actually succeeded. If the call that should have created the token failed, the token never existed, and the first call that uses it reports -1003.
  3. Check the environment. A sandbox token cannot be used from production, or the reverse.
  4. Check ownership and association. See the rules below.
Ownership and association.A token is owned by the account that created it. Another account can use the token only if the token was explicitly associated with it:
  • At tokenization, by passing merchantId on the tokenizing call.
  • After tokenization, by associating the token with the merchant.
Two rules catch people out:
  • An association can only target a primary account. If you pass the ID of a sub-user or a secondary property, the request is rejected and you must associate the token with the parent account instead.
  • Tokens never cross environments. A token created in sandbox cannot be used from production, and the reverse is also true.
Account level blocks.An account that has exceeded its processing allowance is blocked, and every billable API call from it then fails with -1003 even though the credentials are still valid and can still sign in to the portal. The response carries no moreInfo explaining this, so it is indistinguishable from a permissions failure by looking at the response alone.This is a common cause on sandbox accounts, which have a lower allowance than production.Check for it when -1003 appears suddenly across calls that used to work, on more than one token. A block affects every billable call on the account at once, whereas a genuine ownership problem affects only the specific token. Contact support with your account name to have the allowance reviewed and the block lifted.

​
Parameter Constraints

  • OperationType: Must be one of Charge, PreAuth, Capture, Void, Refund, Tokenize.
  • Amount: Required for all operations except Void and Tokenize.
  • GatewayReference: Required for Refund operations.
  • cardToken: Required when the operation needs card data and no GatewayToken is provided. Must be a valid PCI Booking token URI containing a 32-character hex token.
  • credentialsId or PaymentGateway object: One must be provided. If using credentialsId, the credentials must already be stored.

​
Parameters

​
Headers

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

​
Query String

​
string
The ID of credentials stored in PCI Booking. When provided, omit the PaymentGateway object from the request body.
​
string
The name of a client certificate to use for gateway authentication, if required by the gateway.

​
Request Body

​
string
The PCI Booking card token URI, received during tokenization.
​
string
required
The operation to perform. One of: Charge, PreAuth, Capture, Void, Refund, Tokenize.
​
number
The transaction amount. Required for all operations except Void and Tokenize.
​
string
ISO 4217 currency code (e.g. USD, EUR). Required for all operations except Void and Tokenize.
​
object
The payment gateway name and credentials. Not required if credentialsId is provided.
​
string
The transaction ID of a prior operation. Required for Capture (reference the PreAuth), Refund (reference the Charge or Capture), and Void (reference the operation to void).
​
string
A token previously generated by the payment gateway. When provided, PCI Booking uses this gateway token instead of the card token for the transaction.
​
string
Your own reference for this transaction. Some gateways have specific format requirements. See gateway guidance.
​
boolean
default:"false"
For Charge and PreAuth operations, additionally generates a token from the payment gateway. The gateway token is returned in the response.
​
boolean
default:"true"
Whether to include the token’s stored 3DS authentication data (if any) in the request to the PSP, for PSPs that support it - see 3D Secure and the UPG. This does not trigger a new 3DS challenge; it only controls whether existing 3DS data on the token is forwarded. Set to false to charge without forwarding 3DS data even if the token has it.
​
object
Gateway-specific parameters as key-value pairs. These are passed through to the payment gateway. See gateway guidance for supported parameters per gateway.

​
Payer and Order Details

​
object
Details about the customer being charged. Some gateways require specific payer fields.
​
string
Order description. Used by specific payment gateways. See gateway guidance for details.
​
boolean
Indicates digital goods. Used by specific gateways (e.g. WorldPay).

​
Fallback Routing

​
array
A list of fallback payment gateway accounts. If the primary gateway fails, PCI Booking tries each fallback in order.

​
Request Example

A Charge operation for $150.00 USD, using inline gateway credentials:
To use stored credentials instead of inline ones, pass the credentialsId query parameter and omit the PaymentGateway object:

​
Response

The response contains the gateway’s transaction result.

​
Response Fields

​
string
The outcome of the operation. See the status table below.
​
string
PCI Booking’s internal transaction identifier.
​
string
The authorization code returned by the payment gateway. Only present on successful authorizations and charges.
​
string
The gateway’s own transaction reference. Use this value for subsequent Capture, Void, or Refund operations on the same transaction.
​
string
Human-readable message from the payment gateway describing the result.
​
string
Raw response description from the acquirer/processor.

​
Operation Statuses

Consider adding business logic based on the CVV retention policy status after a transaction.