Step 8: Request a capture
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
- Set the following parameters in your request:
AmazonAuthorizationId // the id that you obtained with the authorization CaptureReferenceId // must be globally unique within your account CaptureAmount // can be lower than but must not exceed the authorized amount SellerCaptureNote (optional) // occurs in the email Amazon Pay sends to your customer SoftDescriptor (optional) // shown on the buyer's payment instrument statement
- 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.
- 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
- 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
Copyright © 2009-2017 Amazon.com, Inc. or its affiliates. Amazon and Amazon.com are registered trademarks of Amazon.com, Inc. or its affiliates. All other trademarks are the property of their respective owners.