Incremental Authorisation

The incremental authorisation feature allows you to increment the value of your original pre-authorisation for scenarios where you need to charge your customer a higher total amount.

By incrementing the pre-authorisation value, you will be able to capture the total amount that you wish to charge your customer when you are ready.

You can be assured the total amount that will be charged to the consumer can be captured at a later stage. This is because the amount is ring-fenced in the consumer’s account.

We will describe how an original pre-authorisation can be updated to include additional amounts.

There may be additional considerations to take into account to ensure that incremental authorisation can work with Apple Pay™. We will update you with any requirements, once we know more. For Google Pay™, currently there are no additional considerations for incremental authorisation flows, however this may change over the course of 2026 and we will update you accordingly.

Important to Consider

Make sure you are using Judopay's API version 6.21.0 or higher.

This feature is not available with all acquirers. Check with our customer service team, or your account manager for your eligibility to use this.

You can only increment a preAuth that has been set up correctly.

Setting up the Incremental Authorisation

An incremental authorisation can only be used in the context of an existing pre- authorisation. The end to end flow contains the following steps:

Step One: Initial Pre-Authorisation

The initial step is to process a preAuth request.

When submitting the preAuth request, to increment a preAuth set the allowIncrement flag to true in the request body.

This ensures the acquirer is expecting the amount of the initial preAuth to be amended in the future.

You can set the allowIncrement flag in the following ways:

Using our SDKs when invoking a preAuth:

See our SDK integration sections for more details:

Web SDK

Judokit Android

Judokit iOS

Judokit React Native

Directly via the Judopay Transaction API:

As part of the POST /transactions/preauths request body

Web Payments (Hosted Payments):

As part of the POST /webpayments/preauths request body

Step Two: Incremental Authorisation

Here, the amount of the initial preAuth request can be incremented.

Make a call to the Judopay Transaction API using the endpoint: POST /transactions/incrementalAuth

This request must contain the:

receiptId of the initial preAuth from Step One.

Additional Incremental Amount.

The amount sent in the incrementalAuth request should contain only the additional amount you wish to authorise and not the cumulative authorised total. For example:

Initial preAuth: £9.00

Additional amount required: £2.60

incrementalAuth request amount: £2.60

Total authorised amount after increment: £11.60

The incrementalAuth step can be repeated multiple times if required.

Each new increment must reference the receiptId of the original initial preAuth.

For the purpose of this exercise, the following example is using the request body for the POST /transactions/incrementalAuthendpoint:

{
  "receiptId": "1001131610340495360",
  "amount": 5.99,
  "yourPaymentMetaData": {
    "internalLocationRef": "Example",
    "internalId": 99
  },
  "yourPaymentReference": "aa648425-2230-4e4e-8a61-27f06df54542"
}

Step Three: Capture the Full Amount

To capture the full amount to collect from your customer:

Make a call to the Judopay Transaction API using the endpoint: POST /transactions/collections

The amount specified in the request should include the total amount you wish to collect. This can be less than, or equal to the total amount authorised.

Voiding an Incremental Authorisation Transaction

Each incremental authorisation generates its own receiptId.

If an authorisation has been incremented, any subsequent void request must reference the receiptId of the original pre-authorisation transaction.

Using the receiptId returned following an incremental authorisation will result in an error.

The void amount must be the sum of the original authorisation amount and all successful increments. Any attempt to process a partial void, the sum of any but not all authorisations and increments, will result in an error.

For example:

Initial preAuth: £100

incrementalAuth request amount: £20

incrementalAuth request amount: £30

Total authorised amount after increments: £150

To void this transaction:

Use the receiptId of the Initial preAuth.

Submit a void request for £150.