Search docs

Are you looking for test card numbers?

Would you like to contact support?

Start searching Adyen's documentation...

  Documentation

Manual capture

Learn how to use manual capture for point of sale payments.

When a point of sale payment is Approved it is processed in two steps:

  1. Authorisation: The card is verified with the issuer, and the funds are reserved for the transaction.
  2. Capture: The reserved funds are settled to your merchant account.

By default, these steps occur simultaneously.

Depending on your business model, you may prefer to capture point of sale payments manually. This lets you settle funds, for example:

  • On fulfillment: You capture the payment when an order is shipped.
  • On return: When the shopper returns unwanted items from an order, you capture the payment for the items they keep.

An authorisation can also be cancelled. This releases the funds back to a shopper, and can be used in case of issues shipping an order, or when a shopper returns their whole order.

To use manual capture, your order management system needs to be able to generate a capture request when an order has been fulfilled or returned.

Alipay and WeChat Pay do not support manual captures, and payments are captured immediately.

Before you begin

Before enabling manual capture, make sure that you have:

  1. Set up webhook notifications. The result of a capture or cancel request is provided asynchronously. We inform you whether a request is successful with a webhook notification.
  2. Generated an API Key. You need this to make manual capture requests, and to cancel authorisations.

    If you are using cloud-based communications, you can use the existing API Key you use for Terminal API calls.

Enable manual capture

By enabling manual capture, payment requests made with your merchant account result in an authorisation. To settle a payment, you need to make an explicit capture request.

We recommend capturing a payment within 7 days of it being authorised. After this time, an authorisation may be cancelled by the issuer - releasing the funds back to the shopper.

To enable manual capture:

  1. Log in to your Customer Area.
  2. Switch to your merchant account.
  3. Navigate to Account > Settings.
  4. For the POS Capture Delay, select manual.
  5. Click Submit.

Manual capture is now enabled for this merchant account. Payments will only be captured when you make a capture request.

If you no longer want to use manual capture, select immediate as the POS Capture Delay, or select a capture delay.

Capture payment

Once you have enabled manual capture, you can capture a payment using the pspReference returned in its payment response.

You can request either a full or partial capture, but multiple partial captures are not supported.

To capture a payment:

  • Make a /capture API call, specifying:

    • content-type: application/json.
    • x-api-key: Your API key.
    • merchantAccount: Your merchant account name.
    • modificationAmount: The currency and value being captured.
      To capture the full amount, specify a value equal to the requestedAmount you authorised in the payment request.
      To make a partial capture, specify a value less than the requestedAmount you authorised in the payment request. The remainder is released back to the shopper's card.

      For calls to the /capture endpoint, the value is represented in minor units (without a decimal point).

    • originalReference: The pspReference of the authorisation being captured.

      This was returned in the originalResponse when you made the payment request.

    The example below shows how you would capture a 10.99 EUR payment authorisation that has the pspReference 981517998282382C.

    curl -H "content-type:application/json" -H "x-api-key:YOUR_API_KEY" -X POST --data-binary '{  
       "merchantAccount": "YOUR_MERCHANT_ACCOUNT",
       "originalReference": "981517998282382C",
       "modificationAmount": {  
          "currency": "EUR",
          "value": 1099
       }
    }' --url https://pal-test.adyen.com/pal/servlet/Payment/v46/capture

If the capture request is successfully received the response contains:

  • response: [capture-received]
  • pspReference: Our unique identifier for this capture request.

    This is different to the pspReference of the authorisation.

Payment captures are performed asynchronously, and we inform you whether a capture request is sent for processing with a webhook notification. If the capture is successfully sent for processing, this notification contains:

  • eventCode: CAPTURE
  • originalReference: The pspReference of the authorisation.
  • pspReference: Our unique identifier for this capture request.
  • success: true

    If success is false then your capture request failed. Review the reason you received in the notification, fix the issue, and resubmit the capture request again.

Cancel authorisation

Once you have enabled manual capture, you can cancel an authorisation using the pspReference returned in its payment response.

To cancel an authorisation:

  • Make a /cancel API call, specifying:

    • content-type: application/json.
    • x-api-key: Your API key.
    • merchantAccount: Your merchant account name.
    • originalReference: The pspReference of the authorisation being cancelled.

      This was returned in the originalResponse when you made the payment request.

    The example below shows how you would cancel an authorisation that has the pspReference 981517998282382C.

    curl -H "content-type:application/json" -H "x-api-key:YOUR_API_KEY" -X POST --data-binary '{  
      "merchantAccount": "YOUR_MERCHANT_ACCOUNT",
      "originalReference": "981517998282382C",
    }' --url https://pal-test.adyen.com/pal/servlet/Payment/v46/cancel

If the cancel request is successfully received the response contains:

  • response: [cancel-received]
  • pspReference: Our unique identifier for this cancel request.

    This is different to the pspReference of the authorisation.

Cancel requests are performed asynchronously, and we will let you know whether the authorisation is successfully cancelled with a webhook notification. If the cancel request is successful, the notification contains:

  • eventCode: CANCELLATION
  • originalReference: The pspReference of the cancelled authorisation.
  • pspReference: Matches the pspReference in the /cancel API response.
  • success: true

    If success is false then your cancel request failed. Review the reason you received in the notification, fix the issue, and resubmit the cancel request again.

Capture failed notifications

Although rare, a capture can fail after it is sent for processing. When this happens you receive a notification containing:

  • eventCode: CAPTURE_FAILED
  • originalReference: The pspReference of the authorisation.
  • pspReference: Our unique identifier for this failed capture request.

The example below is of an authorisation with the pspReference 981517998282382C, that failed to capture.

{
  "live":"false",
  "notificationItems":[
    {
      "NotificationRequestItem":{
        "amount":{
          "currency":"EUR",
          "value":1099
        },
        "eventCode":"CAPTURE_FAILED",
        "eventDate":"2019-05-20T15:30:00+02:00",
        "merchantAccountCode":"YOUR_MERCHANT_ACCOUNT",
        "originalReference":"981517998282382C",
        "paymentMethod":"mc",
        "pspReference":"991540215241817C",
        "reason":"Capture Failed",
        "success":"true"
      }
    }
  ]
}

This can occur within a few days of a capture request, and is usually due to a technical issue. We will attempt to resolve the issue, and automatically resubmit the capture request.

In most cases we can resolve the issue, and settle the funds to your account shortly after. When this happens you receive a notification containing:

  • eventCode: CAPTURE
  • originalReference: The pspReference of the authorisation.
  • pspReference: Our unique identifier for this successful capture request.
  • success: true
  • reason: Transaction Recaptured

We will not be able to capture a payment if the shopper:

  • Asked their bank to revoke the authorisation.
  • Closed their account.

You can find an overview of failed captures in your payment accounting report.

See also