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.
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
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.
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:
- Check the state of the Authorization. If it is Open, try a new capture in two minutes.
- If the Authorization is not Open, check the OrderReferenceObject state. If that is Open, request a new authorization and request a capture on it.
- 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.
For more information
- The Capture section in the Amazon Pay API Reference Guide
- The Capture States and Reason Codes section in the Amazon Pay API Reference Guide
- Capturing funds 30 days after authorisation
- The "Partially fulfilling an order" section in Handling payment for post-purchase order modifications