Skip to main content

Pre-authorization

Pre-authorization is like opening a digital tab. It allows you to provide a seamless experience without charging the customer multiple times.

  • The Start: You begin by authorizing a base amount (e.g., £10) to verify the card.
  • The Build: As the customer continues to order, you can "top up" or increment that authorization to match their real-time spending.
  • The Finish: When they’re ready to leave, you capture the final total to settle the funds in a single transaction.

Use Case: This is the gold standard for hospitality environments like bars, restaurants, or hotels where the final bill isn't known upfront. It's also ideal for corporate events where the cardholder does not have to stay until the end to settle the tab.

The Start​

Step 1: Create a payment intent​

First, ensure you have already created a payment intent. This intent stores important information like payment details, amount, and currency. Please see the documentation for more information on configuration options. The example below is the basic request:

{
  "amount": {
    "value": 1000,
    "currencyCode": "GBP"
  },
  "reference": "Order 234",
  "description": "Demo payment intent",
  "captureMode": "Manual",
  "autoExpireAction": "Release",
"autoExpireIn": "00.10:00:00"
}
tip

For pre-authorization, the captureMode must be set to Manual.

Step 2: Check which terminals are available​

GET /terminals

Main page: Retrieve all terminals

You can check which terminals are available by requesting a list of all terminals or by requesting a filtered list of Available terminals.

Step 3: Create a terminal session​

POST /terminal-sessions

Main page: Create session

In your request, you will need to specify the terminal sessionType and the ID of the payment intent you have already created.

{
  "terminalId": "tm_sandbox_65c5fe8a104a1222b2d8b968",
  "details": {
    "sale": {
      "paymentIntentId": "pi_sandbox_81Q7HAZSGkWLKFx_DFEe9Q"
    },
    "sessionType": "Sale"
  }
}
tip

To allow for bills greater than £100, payment via Chip and PIN or device verification (e.g., a mobile wallet) is required.

A session will end once the initial authorization is complete.

The Build​

Increment the authorized amount​

POST /payment-intents/{paymentIntentId}/amount

To update the pre-authorized amount, use the Change a payment intent amount endpoint. This can be used multiple times for the same pre-authorization before you capture the final amount.

{
  "amount": {
    "value": 5500,
    "currencyCode": "GBP"
  }
}

The Finish​

Capturing a final amount​

POST payment-intents/{paymentIntentId}/captures

To complete the transaction, specify the final amount you wish to capture. You can capture the full authorized amount or a lower amount. Any remaining balance will be returned to the cardholder immediately after capture.

{
    "amount": 2000
}

Response example​

If your capture request is successful, the response will return information about the capture.

{
  "message": "collect payment for the order 3443",
  "captureId": "cp_itIiJMEAvES3ynYF_Yhs2g"
}

API reference Learn about the API and integrate with API endpoints.

Introduction Return to the introduction page.

Support Our support team is always happy to help with any questions you have.

Last updated on