What is adjust authorization?

There are scenarios where the final amount of the payment is not known at payment creation (the initial authorization).

Adjust authorization, sometimes referred to as incremental authorization, is a mechanism that enables the authorized amount to be adjusted before finally capturing the payment. This gives merchants great flexibility to increase the amount authorized as conditions change or additional charges accrue.

This is the preferred implementation to:

• Capturing an amount greater than the authorized amount, which is more likely to be rejected by the card networks
• Canceling and reauthorizing for larger amount, which can incur additional processor fees and negatively affects the customer experience

Below are some use cases where authorization adjustment is applicable:

Availability

Adjust authorization is available for Visa, MasterCard, Amex, and Discover card networks, where these networks set specific rules around which businesses are able to adjust an authorization. Your eligibility is determined by your Merchant Category Code (MCC), where support is ultimately up to the issuer.

To access the feature, you will need to use a processor on Primer that supports this capability. Below are the processors currently supported on Primer for adjust authorization:

• Checkout.com
• Paygent

Primer is extending the usage across all our connected processors where it’s supported. If there is a processor you use that isn’t currently available, please reach out to your CSM.

Getting started with adjust authorization

You can implement adjust authorization in 3 steps:

1. 1
   Authorize the payment with an estimated amount
2. 2
   Adjust the estimated amount by calling POST/payments/{paymentId}/adjust-authorization
3. 3
   Capture the final amount

Step 1: Create estimated authorization

First, you need to pass the flag authorizationType = ESTIMATED on either:

• POST/client-session or PATCH/client-session
• POST/payments if using the advanced manual SDK flow

authorizationType defaults to FINAL if not set to ESTIMATED. Authorization adjustments only work on estimated authorizations so without this step, any future attempts to adjust the authorization will not work.

POST or PATCH /client-session

123456789101112131415161718192021222324

// POST or PATCH /client-session{  "customerId": "customer-123",  "amount": 2000,  "currencyCode": "GBP",  "orderId": "order-123",    "paymentMethod": {        "authorizationType": "ESTIMATED"    }}
// response - 200 OK{    "customerId": "customer-123",    "orderId": "order-123",    "amount": 2000,    "currencyCode": "GBP",    "paymentMethod": {        "vaultOnSuccess": false,        "authorizationType": "ESTIMATED"    },    "clientToken": "client-token-string",    "clientTokenExpirationDate": "2023-11-15T10:30:36.020109"}

As the authorizationType field is optional, it is only included in the response if it is passed on the request. So, by default, this field will not be included in the client session response unless you actively choose to pass it in the request.

POST /payments

12345678910111213141516171819202122232425262728

// POST /payments{  "orderId": "order-123",  "amount": 2000,  "currencyCode": "GBP",  "customerId": "customer-123",  "paymentMethodToken": "payment-method-token",  "paymentMethod": {    "authorizationType": "ESTIMATED"  }}
// response - 200 OK{  "id": "kkdEwEEE",  "date": "2023-03-21T15:36:16.367687",  "status": "AUTHORIZED",  "orderId": "order-123",  "currencyCode": "GBP",  "amount": 2000,  "customerId": "customer-123",  "paymentMethod": {    "authorizationType": "ESTIMATED",    "paymentMethodToken": "payment-method-token",    ...  },  ...}

authorizationType is always returned in the response to the POST /payments endpoint, even if it’s not included in the request - the default FINAL will be returned if it’s not set to ESTIMATED in the request.

Also, as is the case with all other fields, the authorizationType value provided in POST /payments takes priority over the client session value if you add the field to both requests.

Step 2: Submit adjust authorization

When you want to adjust the authorization amount for a successful estimated authorization, send POST/payments/<payment-id>/adjust-authorization and pass the amount field which should equal the new desired authorized amount:

123456789101112131415161718192021

// POST /payments/<payment_id>/adjust-authorization{    "amount": 5000}
// response - 200 OK{  "id": "kkdEwEEE",  "date": "2023-03-21T15:36:16.367687",  "status": "AUTHORIZED",  "orderId": "order-123",  "currencyCode": "GBP",  "amount": 5000,  "customerId": "customer-123",  "paymentMethod": {    "authorizationType": "ESTIMATED",    "paymentMethodToken": "payment-method-token",    ...  },  ...}

This API call is always synchronous and will not be successful if:

• authorizationType = FINAL
• status ≠ AUTHORIZED
• paymentInstrumentType ≠ PAYMENT_CARD
• the processor used on the initial estimated authorization does not support authorization adjustment.
• the amount is not correct (e.g. the processor only supports amount greater than the authorized amount)

You can submit multiple authorization adjustments but the rules around the number supported varies per processor and per network and this could result in failed adjust authorization requests. It’s recommended you confirm your expected use case with your processor.

Step 3: Capture final amount

When you’re ready and the final amount has been authorized, simply capture the payment as usual and it will use the last authorized amount from the last successful authorization adjustment.

Notes

• No webhook is sent for a successful adjust authorization as no payment status change has occurred. You can confirm the adjust authorization request is successful by the response to the API request as it is synchronous.

• The authorization adjustment event will appear in the payment timeline, including the request and response to the processor.

  

• Usually, an unsuccessful adjust authorization doesn’t impact the initial authorization but it’s advised you confirm this with your processor.