Checkout icon

Adjust an authorization

Pre-authorize a payment, adjust the authorized amount, and capture the payment.

  Postman collection

Implementation examples
  Java Spring
  .NET
  Node.js

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.

For information about use cases, asynchronous or synchronous adjustment, and restrictions, see Authorization adjustment.

Before you begin

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

You cannot make a zero-value authorization when you adjust an authorization.

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.

To extend authorizations, we strongly recommend using the asynchronous flow because Visa and Discover only support asynchronous adjustments for extending the validity period.

If an issuer refuses to extend the authorization period, this ends the initially authorized payment. Make sure to consume webhook events to know what to do, for example, withhold shipment, or authorize the card again at a later time.

With Mastercard, a request to adjust the pre-authorized amount automatically extends the validity period of the authorization. If you have adjusted the amount of an authorization, you do not immediately have to extend its validity.

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.

Always double-check that you have completed all authorization adjustments for the payment before you capture it. Captures are done asynchronously, so it may seem that the payment hasn't been completely captured yet and that it is still possible to adjust the authorization.

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

If you need to charge the customer for an additional amount after they have left, and you stored the customer's payment details with your pre-authorisation request, you can apply these late charges in a recurring payment request using the token.

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.

To increase the authorization amount, Klarna performs a second risk assessment or credit lookup on the customer. If this causes the transaction to be rejected, the customer must place a new order. The original authorization remains valid.

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 -white_check_mark- The name of your merchant account that is used to process the payment.
    amount.currency -white_check_mark- The three-character ISO currency code.
    amount.value -white_check_mark- 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 -white_check_mark- 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 -white_check_mark- The name of your merchant account that is used to process the payment.
    amount.currency -white_check_mark- The three-character ISO currency code.
    amount.value -white_check_mark- The amount of the transaction, in minor units.

    This is the sum of the original, pre-authorized amount and all later adjustments.
    lineItems -white_check_mark- 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:

    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