Step 9: Request a capture

Note before reading:
If you set the capture now flag to true in your authorize call, you can skip this step.

A capture represents the transfer of funds, for which the transaction was validated during authorisation, from the buyer to your account. To collect the funds, you must make an Capture API call for an Authorization object which is in state Open. Amazon Pay consideres charging in the moment the order is shipped to the buyer as the most customer friendly way to integrate and therefore recommends to implement Amazon Pay and the Capture API call accordingly.

A Capture object status of Completed indicates that the buyer has been successfully charged. In that moment, the money was transfered from the buyer to Amazon Pay and will be transfered to you on the next scheduled disbursement with the next settlement period.

Note: If you have issued a refund, that amount does not become available for capture again.

Capture-Procedure

Request a Capture by performing the following steps:

1. Check the Authorization

You can only capture against an Authorization that has the status Open. To make sure that the authorization still is in this state, please first always perform a GetAuthorizationDetails API call to get the current status. For more details about this API call click here. If it is Open, you can continue with the next step. Otherwise, you must request a new authorization after you made sure that the OrderReferenceObject is still in state Open.

2. Make a call to the Capture API

For a detailed list of the available parameters for this API call, go to the technical description of the Capture API call in the API reference guide.

3. Check the result of your capture request

When you capture within seven days after the authorization, it will be a synchronous APi call. That means you will get the result of your request in the response to the API call. If a capture is requested more than seven days from the date of authorisation, the Capture operation will return the Pending state. The object remains in Pending until Amazon Pay processes the request. The processing time varies and can be an hour or more. Two options exist to retrieve the result (the final state) of such an asynchronous authorization:

  • Instant Payment Notification (IPN)
    Amazon Pay will send you the result of the Capture by means of an http POST to a URL you specified in Amazon Seller Central. That happens as soon as the result becomes available. You must have an IPN-Handler implemented listing on that URL.
  • API Polling
    Periodically do a GetCaptureDetails API call until the state doesn't equal Pending anymore.

Make sure that you store the AmazonCaptureId. You will need it in case you do a refund later via the Amazon Pay API.

4. Handle the response according to the returned state and ReasonCode

You need to handle errors that may occur in the response to your API call. Especially when your Capture is in state Declined. Check the API reference for a full list of potential states and reason codes for Capture objects. Roughly expained, the handling of a Declined capture should be as follows:

  1. Check the state of the Authorization. If it is Open, try a new capture in two minutes.
  2. If the Authorization is not Open, check the OrderReferenceObject state. If that is Open, request a new authorization and request a capture on it.
  3. If neither the Authorization nor the OrderReferenceObject are in state Open you will not be able to make further captures for this order via Amazon Pay. Highlight the payment as failed in your backend and take the the actions according to your workflow.

For more information about error handling see Handling errors from Amazon Pay API calls.

Making a call to the Capture API 
     
$config = array (
  'merchant_id'   => 'YOUR_MERCHANT_ID', // Merchant/SellerID
  'access_key'    => 'YOUR_ACCESS_KEY', // MWS Access Key
  'secret_key'    => 'YOUR_SECRET_KEY', // MWS Secret Key
  'region'        => 'de',  
  'currency_code' => 'EUR'
);

$client = new \AmazonPay\Client($config)

$requestParameters = array();
//received from the response of the authorize call. Ending with -A123456
$requestParameters['amazon_authorization_id'] = $auth_id;
$requestParameters['capture_amount'] = '100.00';
$requestParameters['currency_code'] = 'EUR';     
//unique value, that will appear in your settlement reports to identify this capture
$requestParameters['capture_reference_id'] = uniqid('Capture-' . $order_reference_id);

$client = new \AmazonPay\Client($config)
$response = $client ->capture($requestParameters);
Making a call to the Capture API 

from pay_with_amazon.client import PayWithAmazonClient

client = PayWithAmazonClient(
  mws_access_key='YOUR_ACCESS_KEY',
  mws_secret_key='YOUR_SECRET_KEY',
  merchant_id='YOUR_MERCHANT_ID',
  region='de',
  currency_code='EUR')

response = client.capture(
  amazon_authorization_id,
  capture_reference_id,
  capture_amount
)
Making a call to the Capture API 

require 'pay_with_amazon'

merchant_id = 'YOUR_MERCHANT_ID'
access_key = 'YOUR_ACCESS_KEY'
secret_key = 'YOUR_SECRET_KEY'

client = PayWithAmazon::Client.new(
  merchant_id,
  access_key,
  secret_key,
  sandbox: true,
  currency_code: :eur,
  region: :de
)

client.capture(
  amazon_authorization_id,
  capture_reference_id,
  amount,
  currency_code
)

For more information

Alternate scenarios