> ## Documentation Index
> Fetch the complete documentation index at: https://developers.pcibooking.net/llms.txt
> Use this file to discover all available pages before exploring further.

# Process Transaction

> Process a payment gateway transaction using a stored card token.

<Card title="Processing Charges Guide" icon="book" href="/use-tokens/charge">
  Process payments using stored tokens
</Card>

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.

<Note>
  Some payment gateways have additional requirements. Review the [gateway-specific guidance](/api-reference/process-cards/gateway-guidance) before sending your first transaction.
</Note>

## Error Responses

| Code    | HTTP Status | Condition                                                                                    |
| ------- | ----------- | -------------------------------------------------------------------------------------------- |
| `-1003` | `401`       | API key is missing or invalid.                                                               |
| `-1003` | `401`       | The token does not belong to the authenticated user.                                         |
| `-125`  | `400`       | Request body could not be parsed as JSON.                                                    |
| `-125`  | `400`       | Missing `cardToken` when the operation requires card data and no `GatewayToken` is provided. |
| `-125`  | `400`       | Invalid or malformed `cardToken` URI.                                                        |
| `-125`  | `400`       | Missing `Amount` for operations other than `Void` and `Tokenize`.                            |
| `-125`  | `400`       | Missing `GatewayReference` when `OperationType` is `Refund`.                                 |
| `-125`  | `400`       | The `credentialsId` was provided but the credentials were not found or could not be parsed.  |
| `-125`  | `400`       | The `PaymentGateway` JSON section could not be parsed.                                       |
| `-125`  | `400`       | The payment gateway does not support network tokens, but a network token brand was provided. |
| `-125`  | `400`       | Client certificate name was provided but the certificate could not be retrieved.             |
| `-150`  | `500`       | Failed to retrieve the bank card data from the vault.                                        |

## 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

<ParamField header="Authorization" type="string" required>
  Your API key prefixed with `APIKEY`. Example: `APIKEY your-api-key`. See the [Authentication guide](/getting-started/authentication).
</ParamField>

### Query String

<ParamField query="credentialsId" type="string">
  The ID of credentials [stored in PCI Booking](/api-reference/process-cards/store-credentials). When provided, omit the `PaymentGateway` object from the request body.
</ParamField>

<ParamField query="certName" type="string">
  The name of a [client certificate](/account-setup/client-certificates) to use for gateway authentication, if required by the gateway.
</ParamField>

### Request Body

<ParamField body="cardToken" type="string" required>
  The PCI Booking card token URI, received during tokenization.
</ParamField>

<ParamField body="OperationType" type="string" required>
  The operation to perform. One of: `Charge`, `PreAuth`, `Capture`, `Void`, `Refund`, `Tokenize`.
</ParamField>

<ParamField body="Amount" type="number">
  The transaction amount. Required for all operations except `Void` and `Tokenize`.
</ParamField>

<ParamField body="Currency" type="string">
  ISO 4217 currency code (e.g. `USD`, `EUR`). Required for all operations except `Void` and `Tokenize`.
</ParamField>

<ParamField body="PaymentGateway" type="object">
  The payment gateway name and credentials. Not required if `credentialsId` is provided.

  <Expandable title="Properties">
    <ParamField body="PaymentGateway.Name" type="string" required>
      The payment gateway name (e.g. `Stripe`, `Adyen`, `Worldpay`). See [supported gateways](/api-reference/process-cards/get-payment-gateways).
    </ParamField>

    <ParamField body="PaymentGateway.Credentials" type="object" required>
      Gateway-specific credential key-value pairs. See [gateway guidance](/api-reference/process-cards/gateway-guidance) for required credentials per gateway.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="GatewayReference" type="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).
</ParamField>

<ParamField body="GatewayToken" type="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.
</ParamField>

<ParamField body="myRef" type="string">
  Your own reference for this transaction. Some gateways have specific format requirements. See [gateway guidance](/api-reference/process-cards/gateway-guidance).
</ParamField>

<ParamField body="GenerateToken" type="boolean" default="false">
  For `Charge` and `PreAuth` operations, additionally generates a token from the payment gateway. The gateway token is returned in the response.
</ParamField>

<ParamField body="ThreeDS" type="boolean" default="true">
  Whether to use 3D Secure authentication for this transaction.
</ParamField>

<ParamField body="Parameters" type="object">
  Gateway-specific parameters as key-value pairs. These are passed through to the payment gateway. See [gateway guidance](/api-reference/process-cards/gateway-guidance) for supported parameters per gateway.
</ParamField>

### Payer and Order Details

<ParamField body="PayerDetails" type="object">
  Details about the customer being charged. Some gateways require specific payer fields.

  <Expandable title="Properties">
    <ParamField body="PayerDetails.FirstName" type="string">
      Customer's first name.
    </ParamField>

    <ParamField body="PayerDetails.LastName" type="string">
      Customer's last name.
    </ParamField>

    <ParamField body="PayerDetails.Email" type="string">
      Customer's email address.
    </ParamField>

    <ParamField body="PayerDetails.Phone" type="string">
      Customer's phone number.
    </ParamField>

    <ParamField body="PayerDetails.Address1" type="string">
      Billing address line 1.
    </ParamField>

    <ParamField body="PayerDetails.Address2" type="string">
      Billing address line 2.
    </ParamField>

    <ParamField body="PayerDetails.Address3" type="string">
      Billing address line 3.
    </ParamField>

    <ParamField body="PayerDetails.City" type="string">
      Billing city.
    </ParamField>

    <ParamField body="PayerDetails.StateProvince" type="string">
      Billing state or province.
    </ParamField>

    <ParamField body="PayerDetails.PostCode" type="string">
      Billing postal code.
    </ParamField>

    <ParamField body="PayerDetails.CountryCode" type="string">
      ISO 3166-1 alpha-2 country code (e.g. `US`, `GB`).
    </ParamField>

    <ParamField body="PayerDetails.ClientIPAddress" type="string">
      Customer's IP address. Required by some gateways for fraud screening.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="OrderDesc" type="string">
  Order description. Used by specific payment gateways. See [gateway guidance](/api-reference/process-cards/gateway-guidance) for details.
</ParamField>

<ParamField body="IsDigital" type="boolean">
  Indicates digital goods. Used by specific gateways (e.g. WorldPay).
</ParamField>

### Fallback Routing

<ParamField body="FallbackUpgs" type="array">
  A list of fallback payment gateway accounts. If the primary gateway fails, PCI Booking tries each fallback in order.

  <Expandable title="Properties">
    <ParamField body="FallbackUpgs[].PaymentGatewayAccountName" type="string">
      The stored credentials ID for the fallback gateway.
    </ParamField>

    <ParamField body="FallbackUpgs[].PaymentGatewayCertName" type="string">
      The client certificate name for the fallback gateway, if required.
    </ParamField>
  </Expandable>
</ParamField>

## Request Example

A `Charge` operation for \$150.00 USD, using inline gateway credentials:

<Tabs>
  <Tab title="curl">
    ```bash theme={null}
    curl -X POST "https://service.pcibooking.net/api/paymentGateway" \
      -H "Authorization: APIKEY your-api-key" \
      -H "Content-Type: application/json" \
      -d '{
        "cardToken": "https://service.pcibooking.net/api/payments/paycard/tok_abc123",
        "OperationType": "Charge",
        "Amount": 150.00,
        "Currency": "USD",
        "PaymentGateway": {
          "Name": "Stripe",
          "Credentials": {
            "SecretKey": "sk_test_abc123"
          }
        },
        "myRef": "order-98765",
        "PayerDetails": {
          "FirstName": "Jane",
          "LastName": "Smith",
          "Email": "jane.smith@example.com"
        }
      }'
    ```
  </Tab>

  <Tab title="Node.js">
    ```javascript theme={null}
    const response = await fetch("https://service.pcibooking.net/api/paymentGateway", {
      method: "POST",
      headers: {
        "Authorization": "APIKEY your-api-key",
        "Content-Type": "application/json"
      },
      body: JSON.stringify({
        cardToken: "https://service.pcibooking.net/api/payments/paycard/tok_abc123",
        OperationType: "Charge",
        Amount: 150.00,
        Currency: "USD",
        PaymentGateway: {
          Name: "Stripe",
          Credentials: {
            SecretKey: "sk_test_abc123"
          }
        },
        myRef: "order-98765",
        PayerDetails: {
          FirstName: "Jane",
          LastName: "Smith",
          Email: "jane.smith@example.com"
        }
      })
    });

    const data = await response.json();
    console.log(data);
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import requests

    response = requests.post(
        "https://service.pcibooking.net/api/paymentGateway",
        headers={
            "Authorization": "APIKEY your-api-key",
            "Content-Type": "application/json"
        },
        json={
            "cardToken": "https://service.pcibooking.net/api/payments/paycard/tok_abc123",
            "OperationType": "Charge",
            "Amount": 150.00,
            "Currency": "USD",
            "PaymentGateway": {
                "Name": "Stripe",
                "Credentials": {
                    "SecretKey": "sk_test_abc123"
                }
            },
            "myRef": "order-98765",
            "PayerDetails": {
                "FirstName": "Jane",
                "LastName": "Smith",
                "Email": "jane.smith@example.com"
            }
        }
    )

    print(response.json())
    ```
  </Tab>
</Tabs>

To use stored credentials instead of inline ones, pass the `credentialsId` query parameter and omit the `PaymentGateway` object:

<Tabs>
  <Tab title="curl">
    ```bash theme={null}
    curl -X POST "https://service.pcibooking.net/api/paymentGateway?credentialsId=my-stripe-prod" \
      -H "Authorization: APIKEY your-api-key" \
      -H "Content-Type: application/json" \
      -d '{
        "cardToken": "https://service.pcibooking.net/api/payments/paycard/tok_abc123",
        "OperationType": "Charge",
        "Amount": 150.00,
        "Currency": "USD",
        "myRef": "order-98765"
      }'
    ```
  </Tab>

  <Tab title="Node.js">
    ```javascript theme={null}
    const response = await fetch(
      "https://service.pcibooking.net/api/paymentGateway?credentialsId=my-stripe-prod",
      {
        method: "POST",
        headers: {
          "Authorization": "APIKEY your-api-key",
          "Content-Type": "application/json"
        },
        body: JSON.stringify({
          cardToken: "https://service.pcibooking.net/api/payments/paycard/tok_abc123",
          OperationType: "Charge",
          Amount: 150.00,
          Currency: "USD",
          myRef: "order-98765"
        })
      }
    );

    const data = await response.json();
    console.log(data);
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import requests

    response = requests.post(
        "https://service.pcibooking.net/api/paymentGateway",
        params={"credentialsId": "my-stripe-prod"},
        headers={
            "Authorization": "APIKEY your-api-key",
            "Content-Type": "application/json"
        },
        json={
            "cardToken": "https://service.pcibooking.net/api/payments/paycard/tok_abc123",
            "OperationType": "Charge",
            "Amount": 150.00,
            "Currency": "USD",
            "myRef": "order-98765"
        }
    )

    print(response.json())
    ```
  </Tab>
</Tabs>

## Response

The response contains the gateway's transaction result.

### Response Fields

<ParamField body="Status" type="string">
  The outcome of the operation. See the status table below.
</ParamField>

<ParamField body="TransactionID" type="string">
  PCI Booking's internal transaction identifier.
</ParamField>

<ParamField body="AuthorizationCode" type="string">
  The authorization code returned by the payment gateway. Only present on successful authorizations and charges.
</ParamField>

<ParamField body="GatewayReference" type="string">
  The gateway's own transaction reference. Use this value for subsequent Capture, Void, or Refund operations on the same transaction.
</ParamField>

<ParamField body="GatewayDescription" type="string">
  Human-readable message from the payment gateway describing the result.
</ParamField>

<ParamField body="AcquirerDescription" type="string">
  Raw response description from the acquirer/processor.
</ParamField>

### Operation Statuses

| Status             | Description                                                                                         |
| ------------------ | --------------------------------------------------------------------------------------------------- |
| `Accepted`         | The payment gateway accepted the request.                                                           |
| `Success`          | The operation completed successfully.                                                               |
| `Rejected`         | The gateway rejected the operation. See `GatewayDescription` and `AcquirerDescription` for details. |
| `TemporaryFailure` | The operation failed but can be retried.                                                            |
| `FatalFailure`     | The operation failed permanently.                                                                   |

<Info>
  Consider adding business logic based on the [CVV retention policy](/capture-cards/cvv-retention-policy) status after a transaction.
</Info>

<ResponseExample>
  ```json 200 Success theme={null}
  {
      "Status": "Success",
      "TransactionID": "txn_abc123",
      "AuthorizationCode": "AUTH456",
      "GatewayDescription": "Approved",
      "AcquirerDescription": "Transaction approved"
  }
  ```

  ```json 200 Rejected theme={null}
  {
      "Status": "Rejected",
      "TransactionID": "txn_abc123",
      "GatewayDescription": "Insufficient funds",
      "AcquirerDescription": "51 - Insufficient Funds"
  }
  ```

  ```json 400 theme={null}
  {
      "code": -125,
      "message": "Bad input data",
      "moreInfo": "...",
      "errorList": null
  }
  ```

  ```json 401 theme={null}
  {
      "code": -1003,
      "message": "Not authorized to access this resource",
      "moreInfo": "Bad or missing authorization data, expected APIKEY",
      "errorList": null
  }
  ```
</ResponseExample>