Amazon Pay and Login with Amazon integration guide

Step 6: Request an Authorization

A call to the Authorize API creates an Authorization Object and triggers Amazon Pay to try to reserve a specified purchase amount against the payment method that the buyer chose during checkout. The result of the success of this attempt will be returned to you – later or immediately, depending on other parameters in your request – by means of the State and Reason Code of the Authorization object. Find more details on the states and their transitions in States and Reason Codes in the Amazon Pay API reference guide.

A successful Authorization is indicated by the state Open of the Authorization Object. This lets you capture funds in the next step. The Authorization Object will remain in the Open state for 30 days. A capture call against an open authorization always causes a state transition to Closed. For multiple captures on the same Order Reference, you can make up to 10 successful authorizations, as long as the Order Reference object state is Open.

In some situations, you might need to make an adjustment and increase the total amount that you charge the buyer for an order that they placed on your website. For example, the buyer might call in to your customer service center and ask to upgrade their shipping option. For more information, see "Charging more than the original order amount" section in Handling payment for post-purchase order modifications.

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 authorization could be declined by the payment processor. In addition, you will be charged a transaction fee. You should authorize either for 1.00 € or for the amount that you plan to capture.

Asynchronous vs. synchronous Authorization API calls

The mode that you choose 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 ask 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 authorization decline rate, as it provides more time to Amazon Pay to investigate transactions.
  • Synchronous: Use the synchronous mode if you want to authorize 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 selecting synchronous mode, you might observe a higher authorization decline rate, as Amazon Pay converts some Pending authorizations to Declined. You can track these authorization declines by using the ReasonCode: TransactionTimedOut.

Highly important: Make sure that you implement proper decline handling, as described in Handling declined authorizations.

Procedure

Request an authorization by doing this:

  1. Make a call to the Authorize API. Set the following values in the Authorize request:
    • AmazonOrderReferenceId
    • AuthorizationReferenceId
    • AuthorizationAmount
    • SellerAuthorizationNote (optional)
    • TransactionTimeout (optional)
    • CaptureNow (optional)
    • SoftDescriptor (optional)

    For more details about these parameters and the API call itself, see the technical description of the Authorize API call in the API reference guide.

    Note: The values of the parameters AuthorizationReferenceId, SellerAuthorizationNote, and SoftDescriptor values appear in your settlement reports.

  2. Get Authorization Details (Optional)
    You can query details of the Authorization object by calling the GetAuthorizationDetails operation using the AmazonAuthorizationId that was returned with the authorization response. This can be required in all integration scenarios, but is mandatory when you use API polling instead of IPNs to get the result of an asynchronous authorization.

Note: You must implement error handling with your API calls, and you must test the results of the API response. For more information, see Handling errors from Amazon Pay API calls.

VAT registered sellers – Obtaining the Billing Address

If you are a VAT registered seller and if your Amazon Seller registration contains your VAT information, 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 Open state, or Closed 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 authorizations in a Pending or Declined state.

To obtain either the AuthorizationStatus or the buyer's billing address, call the GetAuthorizationDetails operation. The following code sample includes the billing address in the response:

<GetAuthorizationDetailsResponse xmlns="https://mws-eu.amazonservices.com/schema/OffAmazonPayments/2013-01-01">
  <AuthorizationDetails>
    <AmazonAuthorizationId>
      SD0-3878800-6705015-A078460
    </AmazonAuthorizationId>
    <AuthorizationAmount>
      <CurrencyCode>EUR</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>EUR</CurrencyCode>
      <Amount>0.00</Amount>
    </AuthorizationFee>
    <AuthorizationReferenceId>AuthReference7883758</AuthorizationReferenceId>
    <AuthorizationStatus>
      <State>Open</State>
      <LastUpdateTimestamp>2012-12-10T19:01:11Z</LastUpdateTimestamp>
    </AuthorizationStatus>
    <CaptureNow>false</CaptureNow>
    <CapturedAmount>
      <CurrencyCode>EUR</CurrencyCode>
      <Amount>0.00</Amount>
    </CapturedAmount>
    <CreationTimestamp>2012-12-10T19:01:11Z</CreationTimestamp>
    <ExpirationTimestamp>2013-01-10T19:10:16Z</ExpirationTimestamp>
    <SellerAuthorizationNote>Authorize Test</SellerAuthorizationNote>
  <AuthorizationDetails>
  <ResponseMetadata>
    <RequestId>b4ab4bc3-c9ea-44f0-9a3d-67cccef565c6</RequestId>
  </ResponseMetadata>
</GetAuthorizationDetailsResponse>

See also

Alternate scenarios


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.