This page is only relevant for card payments.

​
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
The initial authorization is still necessary. As its name suggests, authorization adjustment aims to modify an authorization that happened previously for an estimated amount.
Below are some use cases where authorization adjustment is applicable:

Hospitality

The final amount may change based on additional incurred costs after the initial payment.

Micromobility / Transport Renting

The journey length is unknown at the beginning of the journey and so the amount to charge is also not known - it can only be estimated.

Food ordering/delivery

An amount is usually authorized at the point of order creation but the final amount can vary up to when the delivery is complete, such as an additional tip or an updated order.

​
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.
Primer is the underlying payment infrastructure and you should still speak to your processor before implementing authorization adjustment to ensure it’s enabled for your account for each card network.

​
Get Started with adjust authorization

Only available on API >= v2.2
You can implement adjust authorization in 3 steps:
  1. Authorize the payment with an estimated amount
  2. Adjust the estimated amount by calling
  3. Capture the final amount

​
Step 1: Create estimated authorization

First, you need to pass the flag authorizationType = ESTIMATED on either: 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

JSON
// 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

JSON
// 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 and pass the amount field which should equal the new desired authorized amount:
JSON
// 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)
See more about this endpoint in the API reference, including examples of unsuccessful responses.
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.
See more here about how to capture a payment.

​
Additional information

  • 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.

    Adjust Authorization event in payment timeline

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