Adjust an authorization

This page explains how to adjust authorizations for card payments. The process to adjust an authorized amount is as follows:

1. To indicate that you will probably make changes later, you use the authorization type pre-authorization in your payment request.
   The payment is pre-authorized for the amount specified in the payment request.
2. When the amount due increases (or decreases), you send a request to adjust the pre-authorized amount.
   Each time that the amount due changes or the validity period of the authorization is about to expire, you send another authorization adjustment request.
3. After your last authorization adjustment, you manually capture the payment.

In addition, we describe how to adjust authorizations for Klarna payments.

Requirements

Before you configure and use pre-authorization for a card or Klarna payment:

1. Build an integration that can make a payment.
2. Set up webhooks.
   You'll rely on webhook events to know whether the capture succeeds. If you use asynchronous authorization adjustment, you'll also rely on webhook events for the authorization adjustment result.
3. Implement logic on your end to decide when to use the pre-authorisation flow, and to calculate the amount when you make an authorisation adjustment.
4. Make sure that you are aware of the limitations with regard to the availability of authorization adjustments and the expiration of authorizations.

(Optional) Configure your account

If you plan to implement synchronous authorization adjustments, contact our Support Team to enable the Synchronous authorization adjustment setting. This setting allows you to receive the initial adjustAuthorisationData blob with your pre-authorization request, and to subsequently receive the authorization adjustment results synchronously.

To capture payments in the authorization adjustment flow, manual capture must be enabled. You can set this for your account, but then all payments require manual capture. The alternative is to enable manual capture in the individual pre-authorization request.

To make multiple partial captures, ask our Support Team to enable that feature.

Step 1: Pre-authorize a payment

1. Make a payment request that specifies:

   • additionalData.authorisationType: PreAuth.
   • additionalData.manualCapture: true. This is optional. The alternative is to enable manual capture for your account.

2. From the response, save the pspReference for later use when adjusting the authorization or capturing the payment.

Step 2: Adjust the pre-authorized amount

Limitations:

• You cannot make a zero-value authorization when you adjust an authorization.
• You can make a maximum of 50 adjustments to the pre-authorized amount on a single payment transaction. After that, all subsequent requests to adjust the pre-authorized amount will be declined. You will still be able to capture the transaction up to the last successfully pre-authorized amount.

To increase or decrease the pre-authorized amount or to extend the authorization, make an authorization adjustment request.

Extend the authorization

To extend the authorization period, make a /payments/{paymentPspReference}/amountUpdates request with the same amount as the current balance on the authorization:

• If you haven't adjusted the authorization yet, use the amount from the original pre-authorization request.
• If you did adjust the authorization, use the amount from the last adjustment.

See Adjust the pre-authorized amount for instructions. To check the status of the authorization (the original and the extension), make sure to consume webhook events.

Step 3: Capture the payment

After you make your last authorization adjustment, you must manually capture the payment to transfer the reserved funds to your account.

1. Decide whether you are ready to capture the payment:

   • If there are additional charges to make, first adjust the authorization.

   • If the customer wants to settle the bill using a different payment method than the one used for the pre-authorization, do not capture the payment. Instead, cancel the pre-authorization by sending a POST /payments/{paymentPspReference}/cancels request, where {paymentPspReference} is the PSP reference from the pre-authorization response.

2. When you are ready to capture the payment, make a POST /payments/{paymentPspReference}/captures request, where {paymentPspReference} is the PSP reference from the pre-authorization response. Specify:

   Parameter	Required	Description
   amount		The currency of the final amount and its value in minor units. This is the sum of the original, pre-authorized amount and all later adjustments.
   merchantAccount		The name of your merchant account that is used to process the payment.
   reference		Your reference to this payment modification, for use in your reconciliation process.

3. When you receive the /captures response, note the following:

   • pspReference: the PSP reference associated with this /captures request. This is different from the PSP reference associated with the pre-authorization request.
   • status: received
   • reference: your reference to this payment modification, for use in your reconciliation process.

4. Wait for the webhook. This informs you whether the final amount has been captured.
   If the capture is successful, this event contains:

   • eventCode: CAPTURE
   • originalReference: The pspReference of the pre-authorization.
   • pspReference: The PSP reference associated with this /captures request.
   • success: true

   If the capture fails, the webhook contains success: false. Review the reason you received in the webhook, fix the issue, and submit the /captures request again.

Partial captures

You can combine the above steps to suit your use case. For example, if you want to make multiple partial captures, modify the amount authorized after the first partial capture:

1. Pre-authorize a payment.
2. Partially capture the payment.
3. Adjust the authorization amount.

Adjust a Klarna authorization

Klarna also supports authorization adjustments. However, there are a few differences compared to the flow for cards:

• The authorization type for Klarna payments is pre-authorization by default. This means you do not need to specify the authorization type (additionalData.authorisationType) in the initial payment request.
• Klarna only supports asynchronous authorization adjustment.

You can adjust the authorization for any Klarna payment that has not been cancelled, expired, or fully captured.

Adjust the authorized amount

After your Klarna payment request is authorized, make an asynchronous authorization adjustment request:

1. Make a POST /payments/{paymentPspReference}/amountUpdates request, where {paymentPspReference} is the PSP reference from the Klarna payment response. Specify:

   Parameter	Required	Description
   merchantAccount		The name of your merchant account that is used to process the payment.
   amount.currency		The three-character ISO currency code.
   amount.value		The amount of the transaction, in minor units. This is the sum of the original, pre-authorized amount and all later adjustments. If an order is partially captured, the adjusted amount cannot be less than the already captured amount.
   lineItems		Price and product information about the purchased items, to be included on the invoice sent to the shopper. For an authorization adjustment, always specify every line item, including all captured or refunded items. See examples of Klarna-specific payment scenarios at Invoice lines and discounts.
   reference		A reference that you specify for this payment modification, for use in your reconciliation process. The reference you submitted in the initial authorization response remains the primary merchant reference, and this reference does not overwrite it.

   The following example shows how to add a charge of EUR 64.15 to a pre-authorized amount of EUR 150.00.

2. Note that the /amountUpdates response contains:

   • pspReference: the PSP reference for this /amountUpdates request. This is different from the PSP reference of the original Klarna payment request.
   • status: received

3. Wait for the AUTHORISATION_ADJUSTMENT webhook. This informs you whether the new amount has been authorized.

Manually capture the payment

After you make your last authorization adjustment, you must manually capture the payment to transfer the reserved funds to your account:

1. Decide whether you are ready to capture the payment:

   • If there are additional charges to make, first adjust the authorization.

   • If the customer wants to settle the bill using a different payment method than the one used for the pre-authorization, do not capture the payment. Instead, cancel the authorization by sending a POST /payments/{paymentPspReference}/cancels request, where {paymentPspReference} is the PSP reference from the Klarna payment response.

2. When you are ready to capture the payment, make a POST /payments/{paymentPspReference}/captures request, where {paymentPspReference} is the PSP reference from the original payment (pre-authorization) response. Specify:

   Parameter	Required	Description
   merchantAccount		The name of your merchant account that is used to process the payment.
   amount.currency		The three-character ISO currency code.
   amount.value		The amount of the transaction, in minor units. This is the sum of the original, pre-authorized amount and all later adjustments.
   lineItems		Price and product information about the purchased items, to be included on the invoice sent to the shopper. For an authorization adjustment, always specify every line item, including all captured or refunded items. See examples of Klarna-specific payment scenarios at Invoice lines and discounts.
   reference		A reference that you specify for this payment modification, for use in your reconciliation process. The pspReference you received in the initial authorization response remains the primary merchant reference, and this reference does not overwrite it.

3. When you receive the /payments/{paymentPspReference}/captures response, note the following:

   • pspReference: The PSP reference associated with this /captures request. This is different from the PSP reference associated with the original payment (pre-authorization) request.
   • status: received
   • reference: Your reference to this payment modification, for use in your reconciliation process.

4. Wait for the webhook event. This informs you whether the final amount has been captured.
   If the capture is successful, this event contains:

   • eventCode: CAPTURE
   • originalReference: The pspReference of the pre-authorization.
   • pspReference: The PSP reference associated with this /payments/{paymentPspReference}/captures request.
   • success: true

   If the capture fails, this event contains success: false. Review the reason you received in the webhook event, fix the issue, and submit the capture request again.

See examples of other Klarna-specific payment scenarios at Invoice lines and discounts.

See also