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: 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 cannot act on the token in the request. Either the token does not exist or it is not yours to use. 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 still exists. This is the most common cause. On every token endpoint except Delete Token, a token that does not exist or was deleted returns this error, the same as a token that belongs to another account. See Token Not Found or Not Accessible.
  2. Check the tokenization actually succeeded. If the call that should have created the token failed, the token never existed, and calls that use it report -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 HTTP 403 and code -1003, even though the credentials are still valid and can still sign in to the portal. In this response message is empty (null) and moreInfo holds only the generic -1003 text, so nothing in the body explains the block. The 403 status is what tells it apart from a token that is not accessible, which returns 401.This is a common cause on sandbox accounts, which have a lower allowance than production.Check for it when a 403 with -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. The block stays until support lifts it.

​
Timeouts

The whole request, including the time the payment gateway takes to answer, must complete within 29 seconds. If it does not, you receive HTTP 504. A 504 is an unknown result, not a failure: the gateway may still have processed the transaction. Before you retry, check the transaction in your gateway’s portal, using the myRef you sent. If your gateway regularly takes longer than 29 seconds, contact support@pcibooking.net for an alternative setup.

​
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. If you send credentialsId and a PaymentGateway object, the stored credentials are used in full and the object in the body is ignored. The two are not merged, and no error is returned. To vary a value per transaction, use the Parameters object rather than partial credentials.

​
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.

​
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
Backup payment gateway accounts for a charge. If the charge does not succeed at the primary gateway, PCI Booking tries each fallback in order and stops at the first success. Used for charges only, and not after the decline reasons CardExpired, Fraud, LostOrStolenCard or InsufficientFunds. A fallback account that cannot be loaded is skipped. See Fallback Payment Gateways.

​
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 is the result of the operation at the payment gateway. Field names are in PascalCase and status values are sent as strings. Which fields are filled, and the values in the Gateway fields, depend on the payment gateway. For example, some gateways do not return an authorization code, and on a declined operation some do not return the amount, currency or gateway reference. The examples below come from a Stripe charge.

​
Response Fields

​
string
The operation that was performed: PreAuth, Capture, Charge, Refund or Void.
​
string
The outcome of the operation. See Operation Results below.
​
string
A description of the outcome.
​
string
The payment gateway that processed the operation.
​
string
The payment gateway’s own transaction reference. Use this value for subsequent Capture, Void or Refund operations on the same transaction.
​
string
The result code returned by the payment gateway, in the gateway’s own format.
​
string
The result description returned by the payment gateway.
​
string
A secondary result code, when the payment gateway returns one.
​
string
A secondary result description, when the payment gateway returns one.
​
string
The authorization code returned by the payment gateway.
​
string
The currency of the operation, as an ISO 4217 code.
​
number
The amount of the operation.
​
string
A standardized reason for a declined or failed operation, the same for every payment gateway. Not included when the operation succeeds. See Reject Reason Codes below.
​
object
The payment gateway’s token for the card, when the operation creates one. Not included otherwise.
​
object
Additional data specific to the payment gateway. Not included when empty.

​
Operation Results

​
Reject Reason Codes

Use RejectReasonCode to handle declines in the same way for every payment gateway, instead of interpreting each gateway’s own codes.
Consider adding business logic based on the CVV retention policy status after a transaction.