Step 6: Request an authorization

A call to the Authorize API reserves a specified purchase amount against the payment method that the buyer chooses during checkout and that is stored in the Order Reference object.

A successful Authorize results in the creation of an Authorize object with an AuthorizationStatus of Open. This lets you capture funds in the next step. The Authorize object remains in the Open state for 30 days, and you can make up to 25 authorizations 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 authorization could be declined by the payment processor. You also are 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 choosing synchronous mode, you might see a higher authorization decline rate, as Amazon Pay will convert some Pending authorizations to Declined. You can track these authorization declines by the ReasonCode TransactionTimedOut.

Note: In the case of an InvalidPaymentMethod decline, we set the SoftDecline parameter in the Authorization response to help you differentiate between a hard decline and a soft decline. In the case of a soft decline, you can submit an additional authorization attempt. For more information about soft declines, see 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:
    Element Value
    AuthorizationReferenceId This is a unique ID that you as the merchant create for authorizations. This is a different parameter than the AmazonAuthorizationId that is created by Amazon.
    SellerAuthorizationNote A description for the transaction that is shown in emails to the buyer and that appears only when CaptureNow is set to true.
    SoftDescriptor The description to be shown on the buyer's payment instrument statement if CaptureNow is set to true.
    TransactionTimeout 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 authorization that cannot be processed within the time limit is 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 receive the final status of the authorization request (for example, Open or Declined) via IPN.

    Synchronous Authorization API calls:

    The TransactionTimeout must be set to 0 (zero) minutes.

    The AuthorizationStatus always returns an Open or Declined status, typically within 15 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.
  2. Parse the response to determine the authorization was status. If the authorization status has a state of Open, the authorization was successful, and you can proceed with processing the order. For all other status combinations, use the information in Authorization states and reason codes to evaluate how to handle the declined authorization.
  3. For asynchronous authorizations, you can query details of the Authorization object by calling the GetAuthorizationDetails operation using the AmazonAuthorizationId that was returned in the authorization response.

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.

Making a call to the Authorize API 

client = PayWithAmazonClient(
  mws_access_key='YOUR_ACCESS_KEY',
  mws_secret_key='YOUR_SECRET_KEY',
  merchant_id='YOUR_MERCHANT_ID',
  region='na',
  currency_code='USD')

response = client.authorize(
  amazon_order_reference_id='AMAZON_ORDER_REFERENCE_ID',
  authorization_reference_id='MY_UNIQUE_AUTHORIZATION_ID',
  amount='1.00',
  seller_authorization_note='Authorization note.'
  capture_now=False)
Making a call to the Authorize Asynchronous 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='na',
  currency_code='USD')

response = client.authorize(
  amazon_order_reference_id='AMAZON_ORDER_REFERENCE_ID',
  authorization_reference_id='MY_UNIQUE_AUTHORIZATION_ID',
  amount='1.00',
  seller_authorization_note='Authorization note.',
  transaction_timeout=60,
  capture_now=False)
Making a call to the Authorize Synchronous 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='na',
  currency_code='USD')

response = client.authorize(
  amazon_order_reference_id='AMAZON_ORDER_REFERENCE_ID',
  authorization_reference_id='MY_UNIQUE_AUTHORIZATION_ID',
  amount='1.00',
  seller_authorization_note='Authorization note.',
  transaction_timeout=0,
  capture_now=True)
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: :usd,
  region: :na
)

amazon_order_reference_id = 'AMAZON_ORDER_REFERENCE_ID'
authorization_reference_id = 'test_authorize_1'
amount = 106

client.authorize(
  amazon_order_reference_id,
  authorization_reference_id,
  amount,
  seller_authorization_note: 'Lorem ipsum dolor',
  mws_auth_token: 'amzn.mws.4ea38b7b-f563-7709-4bae-87aeaEXAMPLE'
)
Making a call to the Authorize Asynchronous 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: :usd,
  region: :na
)

amazon_order_reference_id = 'AMAZON_ORDER_REFERENCE_ID'
authorization_reference_id = 'test_authorize_1'
amount = 94.50

client.authorize(
  amazon_order_reference_id,
  authorization_reference_id,
  amount,
  seller_authorization_note: 'Lorem ipsum dolor',
  transaction_timeout: 60,
  mws_auth_token: 'amzn.mws.4ea38b7b-f563-7709-4bae-87aeaEXAMPLE'
)
Making a call to the Authorize Synchronous API 

client.authorize(
  amazon_order_reference_id,
  authorization_reference_id,
  amount,
  seller_authorization_note: 'Lorem ipsum dolor',
  transaction_timeout: 0,
  mws_auth_token: 'amzn.mws.4ea38b7b-f563-7709-4bae-87aeaEXAMPLE'
)
Making a call to the Authorize Asynchronous API 

https://mws.amazonservices.com/OffAmazonPayments_Sandbox/2013-01-01
?AWSAccessKeyId=AKIAFBM3LG5JEEXAMPLE
&Action=Authorize
&AmazonOrderReferenceId=S23-1234567-1234567
&AuthorizationAmount.Amount=94.50
&AuthorizationAmount.CurrencyCode=USD
&AuthorizationReferenceId=test_authorize_1
&SellerAuthorizationNote=Authorization for Blue Shoes
&SellerId=YOUR_SELLER_ID_HERE
&SignatureMethod=HmacSHA256
&SignatureVersion=2
&Timestamp=2013-11-16T19:01:11Z
&TransactionTimeout=60
&Version=2013-01-01
&Signature=WlQ708aqyHXMkoUBk69Hjxj8qdh3aDcqpY71hVgEXAMPLE
Making a call to the GetAuthorizationDetails API 

POST /OffAmazonPayments/2013-01-01 HTTP/1.1
Content-Type: x-www-form-urlencoded
Host: mws.amazonservices.com
User-Agent:

AWSAccessKeyId=AKIAFBM3LG5JEEXAMPLE
&Action=GetAuthorizationDetails
&AmazonAuthorizationId=P01-1234567-1234567-0000001
&SellerId=YOUR_SELLER_ID_HERE
&SignatureMethod=HmacSHA256
&SignatureVersion=2
&Timestamp=2012-11-05T19:01:11Z
&Version=2013-01-01
&Signature=WlQ708aqyHXMkoUBk69Hjxj8qdh3aDcqpY71hVgEXAMPLE

See also

Alternate scenarios