Step 7: 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 remains 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.

Note: Make sure that you implement proper decline handling, as described in Step 7: Prepare to handle 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:
    For a detailed list of the available parameters for this API call, go to 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.
    Making a call to the Authorize 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();
$requestParameters['amazon_order_reference_id'] = $order_reference_id;
// unique value, that will appear in your settlement reports to identify this authorization
$requestParameters['authorization_reference_id'] = uniqid('Authorization-' . $orderId);  
//has to be the same amount, you confirmed in the step before
$requestParameters['authorization_amount'] = $authorization_amount;
$requestParameters['transaction_timeout'] = $timeout_in_seconds;
$requestParameters['capture_now'] = true;         

$client = new \AmazonPay\Client($config)
$response = $client ->authorize($requestParameters);
    Making a call to the Authorize 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.authorize(
  amazon_order_reference_id=amazon_reference_id,
  authorization_reference_id=authorize_reference_id,
  authorization_amount=charge_amount,
  seller_authorization_note=charge_note,
  transaction_timeout= timeout_in_seconds,
  capture_now=True,
  merchant_id=your_merchant_id
)
    Making a call to the Authorize 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.authorize(
  amazon_order_reference_id,
  authorization_reference_id : authAmount,
  amount : amount,
  transaction_timeout : timeout_in_seconds,
  capture_now : true
)
    2. 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.</li>
  2. 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.
  3. 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 Authorization 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>
     S02-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>

Note: The currency code in every API request must be consistent throughout an Order Reference object.

See also