Terminal-2 icon

Capture

Capture in-person payments automatically, with a delay, or manually.

By default, payments are captured automatically without a delay, immediately after authorization of the payment request.

For some payment methods, you can capture a payment separately from authorization. We refer to this as manual capture. The authorization reserves the funds on the shopper's bank account. Then, when you send a request to capture the payment, the reserved funds are transferred from the shopper's bank account to your account.

For point-of-sale payments, it is usually recommended to set up a delay between authorization and capture. In case of a mistake, you can then cancel the authorization instead of having to issue a refund.

Requirements

Requirement Description
Integration type A Terminal API integration
Customer Area roles To edit capture settings, make sure that you have the following roles:
  • Merchant admin
  • View Payments
  • Merchant manage payments
Webhooks Listen to the following webhook events:
Limitations Most wallet payment methods do not support separate capture of in-person payments.
Alipay and WeChat Pay are always captured immediately; these wallets do not support delayed capture.
Setup steps If you intend to use multiple partial captures, ask our Support Team to enable that feature.

Types of capture

For payments that support separate capture, you can set up one of the following, so that payments do not automatically get captured immediately after authorization:

Type of capture Description
Delayed automatic capture Set an amount of time between authorization and capture. The capture happens automatically after the time delay that you set.

The delay gives you time to cancel the authorization when a mistake was made or the shopper changed their mind after the payment terminal approved the transaction. Without capture delay, you would need to issue a refund.
Manual capture Set a separate capture that does not happen automatically. After a payment is authorized, you must manually capture the payment.

Manual capture lets you settle funds on fulfillment, for example, when customers close their bar tab or check out of a hotel. It is also part of flows like authorization adjustment and tipping on the receipt.

Some payment methods also allow partial manual capture.

Partial manual capture

Type of partial capture Description
Single partial capture Any unclaimed amount that is left over after partially capturing a payment is automatically cancelled.

With some schemes, you can flag each payment request as either a pre-authorization or a final authorization. For partial captures, we recommend that you flag the payment request as a pre-authorization. For more information, refer to Authorization types.
Multiple partial captures The unclaimed amount after an initial partial capture is not automatically cancelled. This is useful in omnichannel scenarios where the shopper orders items in a physical store. If you have an order with multiple items to ship separately, each shipment correlates to a partial capture.

Multiple partial capture is disabled by default, so you need to contact our Support Team to enable this feature.

Delayed automatic capture

When you set up delayed automatic capture, you specify the amount of time between authorization and capture. You can enable it in your Customer Area for every payment, or in the API request for an individual payment. The setting in the API request for an individual payment overrides the setting in the Customer Area.

A payment that is automatically captured does not trigger a separate CAPTURE webhook. If you are using delayed automatic capture, consider enabling a CAPTURE webhook. To do this, enable the default event codes CAPTURE and CAPTURE_FAILED in the Standard webhook, and turn on Delayed Capture in the webhook settings.

Manual capture

When you set up manual capture, you must send a capture request after the payment is authorized. After capturing, the funds for the payment get transferred to your account.

To use manual capture:

  1. Enable manual capture, either for every payment or for an individual payment.
  2. Capture the payment.

Enable manual capture

You can enable manual capture in your Customer Area for every payment, or in the API request for an individual payment. The setting in the API request for an individual payment overrides the setting in the Customer Area.

Capture a payment

When you have enabled manual capture, either for your account or for an individual transaction, you need to capture the payment as follows:

  1. From the transactionID field in the payment response , get the pspReference of the authorization you want to capture.

  2. Make a POST request to the /payments/{paymentPspReference}/captures endpoint, where paymentPspReference is the pspReference of the authorization you want to capture.

    In your request, include:

    Parameter Required Description
    merchantAccount -white_check_mark- The name of your merchant account that is used to process the payment.
    amount.value -white_check_mark- The amount in minor units (without a decimal point) being captured.
    To capture the full amount, specify a value equal to the requestedAmount you authorized in the payment request.
    To make a partial capture, specify a value less than the requestedAmount you authorized in the payment request. The remainder is released back to the shopper's card.
    amount.currency -white_check_mark- This must match the currency of the payment you are capturing.
    reference Your unique identifier for the capture operation. The reference field is useful to tag a partial capture for future reconciliation.

    The following example shows how to capture a EUR 25.00 payment authorization that has the pspReference WNS7WQ756L2GWR82.

    The request header must include the x-api-key parameter set to your API key.

  3. In the capture response, note the following:

    • paymentPspReference: the PSP reference of the authorization.
    • pspReference: the PSP reference associated with this capture request. This is different from the PSP reference of the authorization.
    • status: received. Your capture request will be processed asynchronously. You will receive the result in a webhook.
  4. Wait for the CAPTURE webhook to learn the outcome of the request.

Webhooks for captures

Manual capture is an asynchronous process. To keep you informed, we send webhook event messages:

  • CAPTURE: Indicates if the capture request was valid. There are several reasons why a capture request can fail. If the request was valid, we send it to the issuing bank through the card scheme, and this usually means the funds will be transferred to your account.

  • CAPTURE_FAILED: Indicates that the card scheme or issuing bank rejected the capture. This happens only in rare cases.

CAPTURE webhook

When we have processed your capture request, we send you a webhook event with:

  • eventCode: CAPTURE.
  • originalReference: The PSP reference of the authorization.
  • pspReference: The PSP reference associated with the capture request.
  • success: Indicates whether the capture request was successful. Possible values:

    • true: The capture request is valid (for example, the authorization has not expired, and the balance is available) and has been submitted to the bank/third-party processor. In most cases, this means that the funds will be transferred to your account. In rare cases the card scheme can still reject the capture, and you will receive a CAPTURE_FAILED webhook.
    • false: The capture request failed. The webhook event includes a reason field with a short description of the problem. Review the reason, fix the issue if possible, and resubmit the capture request.

For more information about the included fields, see the CAPTURE webhook reference.

Reasons for an unsuccessful capture request

When a capture request fails, you receive a CAPTURE webhook with success: false and the reason why the request failed. The next table shows the most common reasons.

reason Description
Transaction not found The capture failed because:
  • The pspReference is missing or incorrect.
  • You provided an incorrect merchantAccount.
Check that the reference you provided is unique and matches exactly one pspReference.
Transaction is expired The authorization for this payment is expired. You can try to re-authorize the payment in your Customer Area.
This is a sale transaction, not possible to capture a smaller amount This payment method doesn't support separate captures.
Operation maximum period allowed: X days The capture operation can only be performed within X days from the date the payment was authorized.
Only possible to capture the full amount This payment method doesn't support partial captures.
Modification in different currency than authorisation The capture currency does not match the authorized payment currency.
Amount too low to be accepted by Card Network The capture amount is below the threshold permitted by the card scheme rules.
Insufficient balance on payment The requested capture amount is more than the balance on the payment.
Internal error Something unexpected happened on Adyen's end. Contact our Support Team.
Operation not available You do not have the required capture functionality enabled for this payment method. Contact our Support Team.
Operation failed The capture functionality failed for this payment method. Contact our Support Team.

The balance on the payment is the amount that remains from the original authorization. For example, if a transaction is authorized for EUR 10 but not captured, the balance on the payment is EUR 10. If the full amount is cancelled, or if the authorization expired, the remaining balance on the payment is EUR 0. If a transaction is authorized for EUR 50, and then partially captured for EUR 30, the remaining balance on the payment is EUR 20.

CAPTURE_FAILED webhook

In rare cases, a capture fails even after you received a CAPTURE webhook with successtrue. The successful webhook event means that we sent the request to the card scheme, but the scheme can still reject the request at this point. This can even happen a few days after you submitted the capture request.

Most of the time Adyen can fix the issue, so that you will eventually receive the funds. Sometimes, however, you need to take action yourself. To learn why a capture can fail and what, if anything, you need to do in each case, refer to Reasons for failed capture.

When a capture fails, we inform you of this with a webhook event with:

  • eventCode: CAPTURE_FAILED
  • originalReference: The pspReference of the authorization.
  • pspReference: The pspReference of the capture request.

The webhook event contains the reason why the card scheme rejected the capture. You can also find the capture failure reason on the Payment details page in your Customer Area.

An overview of failed captures is available in your Payment accounting report.

Cancel an authorization

When you use a capture delay or manual capture, you can cancel the authorization on an uncaptured payment using an API request from your POS app.

But before you can do that, you need to:

  • Set up webhooks. Canceling is an asynchronous operation. We inform you whether this is successful with a CANCELLATION webhook.
  • Generate an API key. To cancel authorisations from a POS app, the request header must include the x-api-key parameter set to your API key.

    If you are using cloud-based communications, you can use the existing API key that you use for Terminal API requests.

To cancel a payment that has been authorized but not captured yet:

  1. From the AUTHORISATION webhook, get the pspReference of the authorization you want to cancel.

  2. Make a POST request to the /payments/{paymentPspReference}/cancels endpoint, where paymentPspReference is the PSP reference of the authorization you want to cancel.

    If you are not sure whether the authorization has been captured, use the /payments/{paymentPspReference}/reversals endpoint instead.

    In your request, include:

    Parameter Required Description
    merchantAccount -white_check_mark- The name of your merchant account that is used to process the payment.
    reference Your reference for the cancel request.

    The following example shows how to cancel an authorization that has the pspReference XB7XNCQ8HXSKGK82.

    The request header must include the x-api-key parameter set to your API key.

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

    • paymentPspReference: the PSP reference of the authorization you want to cancel.
    • pspReference: Adyen's unique reference associated with this cancel request.
    {
        "merchantAccount": "ADYEN_MERCHANT_ACCOUNT",
        "paymentPspReference": "XB7XNCQ8HXSKGK82",
        "pspReference" : "JDD6LKT8MBLZNN84",
        "reference": "YOUR_UNIQUE_REFERENCE",
        "status" : "received"
    }
  4. Wait for the CANCELLATION webhook to learn the outcome of the cancel request.

CANCELLATION webhook

You receive the outcome of the cancel request asynchronously, in a webhook that includes :

  • eventCode: CANCELLATION.
  • originalReference: The PSP reference of the authorization.
  • pspReference: The same as the pspReference in the /payments/{paymentPspReference}/cancels response.
  • success: Indicates whether the cancel request was successful. Possible values:

    • true: The cancel request was successful.
    • false: The cancel request failed. The webhook event includes a reason field with a short description of the problem. Review the reason, fix the issue if possible, and resubmit the cancel request.

For more information about the included fields, see the CANCELLATION webhook reference.

See also