Step 6: Request an authorisation
A call to the Authorize API reserves a specified purchase amount against the payment method that is selected by the buyer during checkout, which is stored in the Order Reference object.
A successful Authorize results in the creation of an Authorize object with an AuthorizationStatus of Open. This allows you to capture funds in the next step. The Authorize object will remain in the Open state for 30 days, and you can make up to 10 authorisations on an Order Reference object in an Open state.
Note: Validating a credit card by making an authorize API call for an amount less than £1.00 is not a best practice, and the authorisation could be declined by the payment processor. You also are charged a transaction fee. You should authorise either for £1.00 or for the amount that you plan to capture.
Asynchronous vs. synchronous authorisation API calls
The mode that you select for calling the Authorize API depends on your business requirements:
- Asynchronous — Use the asynchronous mode if you want to charge for an item when it is shipped. Use this mode if your system can hold an order for up to 24 hours. Because the final processing status is not available in real time, you can show an order confirmation page to the buyer immediately after confirming the order to Amazon. If the Authorize has a status of Declined, you need to notify the buyer of the failed transaction and request that they update the payment method from the Amazon Pay website, collect an alternative form of payment, or cancel the order based on the declined reason code. The asynchronous mode usually results in a lower authorisation decline rate, as it provides more time to Amazon Pay to investigate transactions.
- Synchronous — Use the synchronous mode if you want to authorise and/or capture payments while the buyer is still on your site. For example, use synchronous mode if you want to offer a digital download or confirm an expedited delivery. By choosing synchronous mode, you might observe a higher authorisation decline rate, as Amazon Pay will convert some Pending authorisations to Declined. You can track these authorisation declines by using the ReasonCode TransactionTimedOut.
Note: In the case of an InvalidPaymentMethod decline, we set the SoftDecline parameter to help you differentiate between a hard decline and a soft decline. In the case of a soft decline, you can submit an additional authorisation attempt. For more information about soft declines, see Step 7: Prepare to handle declined authorisations.
Request an authorisation by doing this:
- Make a call to the Authorize API.
Set the following values in the Authorize request:
This is a unique ID that you as the merchant create for authorisations. This is a different parameter than the AmazonAuthorizationId that is created by Amazon.
A description for the transaction that is shown to the buyer in emails and that appears only when CaptureNow is set to true.
The description to be shown on the buyer's payment instrument statement if CaptureNow is set to true.
Asynchronous Authorization API calls:
The TransactionTimeout must be set to a value from a minimum of 5 minutes to a maximum of 1440 minutes (the default value), in multiples of 5 minutes.
An authorisation that cannot be processed within the time limit will be declined with a reason code of TransactionTimedOut.
The AuthorizationStatus response element is always set to Pending when using the asynchronous flow. When processed by Amazon, you will receive the final status of the authorisation request (for example, Open or Declined) via IPN.
Synchronous Authorization API calls:
The TransactionTimeout must be set to 0 (zero) minutes.
The AuthorizationStatus will always return an Open or Declined status, typically within 6 to 8 seconds.
Note: The SellerAuthorizationNote and SoftDescriptor values appear in the buyer's Funds Authorized email and account status, the buyer's payment instrument, and your settlement and transaction reports.
- Parse the response to determine the authorisation status. If the authorisation status has a state of Open, the authorisation was successful and you can proceed with processing the order. For all other status combinations, use the information in Authorisation states and reason codes to evaluate how to handle the declined authorisation.
- For asynchronous authorisations, you can query details of the Authorization object by calling the GetAuthorizationDetails operation using the AmazonAuthorizationId that was returned in the authorisation response.
Note: You must implement error handling with your API calls and test the results of the API response. For more information, see Handling errors from Amazon Pay API calls.
Obtaining the billing address
It is possible to get the buyer's billing address after a successful call to the Authorize operation.
If the AuthorizationStatus of the Authorize object is in the OpenClosed with the MaxCapturesProcessed reason code, the billing address will be available in the AuthorizationBillingAddress element of the Authorize and the GetAuthorizationDetails response.
The billing address is not available for authorisations in a Pending or Declined state.
To obtain either the AuthorizationStatus or the buyer's billing address, call the GetAuthorizationDetails operation. The following code example includes the billing address in the response:
<GetAuthorizationDetailsResponse xmlns="https://mws-eu.amazonservices.com/schema/OffAmazonPayments/2013-01-01"> <AuthorizationDetails> <AmazonAuthorizationId> P01-1234567-1234567-A012345 </AmazonAuthorizationId> <AuthorizationAmount> <CurrencyCode>GBP</CurrencyCode> <Amount>100.00</Amount> </AuthorizationAmount> <AuthorizationBillingAddress> <AddressLine1>87 Terrick Rd</AddressLine1> <City>EILEAN DARACH</City> <CountryCode>GB</CountryCode> <Name>Amber Kelly</Name> <PostalCode>IV23 2TW</PostalCode> </AuthorizationBillingAddress> <AuthorizationFee> <CurrencyCode>GBP</CurrencyCode> <Amount>0.00</Amount> </AuthorizationFee> <AuthorizationReferenceId>AuthReference7883758</AuthorizationReferenceId> <AuthorizationStatus> <State>Open</State> <LastUpdateTimestamp>2012-12-10T19%3A01%3A11Z</LastUpdateTimestamp> </AuthorizationStatus> <CaptureNow>false</CaptureNow> <CapturedAmount> <CurrencyCode>GBP</CurrencyCode> <Amount>0.00</Amount> </CapturedAmount> <CreationTimestamp>2012-12-10T19%3A01%3A11Z</CreationTimestamp> <ExpirationTimestamp>2013-01-10T19:10:16Z</ExpirationTimestamp> <SellerAuthorizationNote>Authorize Test</SellerAuthorizationNote> <AuthorizationDetails> <ResponseMetadata> <RequestId>b4ab4bc3-c9ea-44f0-9a3d-67cccef565c6</RequestId> </ResponseMetadata> </GetAuthorizationDetailsResponse>
Note: The currency code in every API request must be consistent throughout an Order Reference object.
- Authorize section in the Amazon Pay API reference guide
- Authorize states and reason codes section in the Amazon Pay API reference guide
- "Setting the order reference details" section in Step 5: Set purchase details and confirm the purchase
- Step 7: Prepare to handle declined authorisations
- Authorise and capture in one step
- "Charging more than the original order amount" section of Handling payment for post-purchase order modifications
Copyright © 2009-2019 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.