Adjust authorisation

In a pre-authorised payment, the amount is authorised first and captured later. Before you capture it, you can increase or decrease the authorised amount, for example when the final order total differs from what the shopper first paid. Changes to a pre-authorised payment are called authorisation adjustments.

Be aware that:

• You rely on webhooks to know whether the capture succeeds.
• You need to implement logic on your end to decide when to adjust, and to calculate the new amount.

RequirementsCopy Anchor Link

Before you begin, take into account the following requirements, limitations, and preparations.

1. Pre-authorise a paymentCopy Anchor Link

Take the payment as a pre-authorisation, then save the xref from the payment status webhook with status authorisation and success true. You need the xref for the adjustment and the capture.

2. Adjust the pre-authorised amountCopy Anchor Link

To increase or decrease the pre-authorised amount:

1. Make an adjustment request with your api_token header and the following parameters:

   Parameter	Required	Description
   xref	Required	The payment's reference, O<order_id>M<merchant_id>T<payment_id>.
   merchant_id	Required	The merchant that took the payment, as a string.
   amount	Required	The new authorised amount, in major units. This is the full new total, not the difference. Minimum 0.01.
   split_fee		New split instructions. Each item has partner_merchant_id, type_id, value and value_type (amount or percentage). If you leave it out, the existing splits are kept. The total of the splits must be less than amount.

   For example, when the shopper adds a drink, Example Pizza Ltd increases a GBP 24.50 pre-authorisation by sending amount 27.75. The Adjust the amount of a pre-authorised payment page in the API Explorer has the full request, with examples you can try.

2. In the response, note the following:

   • HTTP status 201: the acquirer accepted the adjustment.
   • outcome: success.
   • payment_reference: the acquirer's reference for this adjustment.
   • status: authorised.

   Adjustment response

   Copy Text

   {
     "outcome": "success",
     "payment_reference": "QFQTPCQ8HXSKGK82",
     "status": "authorised",
     "amount": 27.75
   }

   If the acquirer refuses the adjustment, you receive HTTP 422 with outcome success, message Amount adjustment refused, and resultCode and reason Refused.

3. Datman also sends a payment status webhook with status authorisation_adjustment, and success true if the new amount was authorised or false if it wasn't.

Reasons for a failed adjustment requestCopy Anchor Link

If the request fails before it reaches the acquirer, you receive HTTP 200 with outcome failed and a message. The most common messages are:

If the acquirer returns an error, you receive its HTTP status, for example 500, with outcome success and a message.

3. Capture the paymentCopy Anchor Link

After you make your last authorisation adjustment, you must capture the payment to take the reserved funds.

Always double-check that you have completed all adjustments for the payment before you capture it. Captures are processed asynchronously.

1. Decide whether you are ready to capture the payment:
   • If there are additional charges to make, first adjust the authorisation.
   • If you don't want to take the payment, don't capture it. Instead, reverse the authorisation.
2. When you are ready, make a capture request with the same xref. See Capture.

See alsoCopy Anchor Link

• Adjust a payment amount in the API Explorer
• Capture
• Reverse authorisation
• Webhooks