Important: This integration has been deprecated. Amazon Pay will continue to support this version but it will not be updated with new features. New integrations should use Amazon Pay Checkout.

Step 6: Request an authorization

Now that you have confirmed the Billing Agreement object and it is in the Open state, you can start the process of collecting the payment. To process payment, you must get an authorization on the payment method that the buyer chose during checkout by calling the AuthorizeOnBillingAgreement operation. An authorization is always tied to an Order Reference. The AuthorizeOnBillingAgreement operation is a convenience operation that creates an Order Reference and then submits an authorization for you. The Order Reference inherits the payment method and shipping address information from the billing agreement. The Order Reference appears as a line item to the buyer when signed in on the Amazon Pay website.

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 are charged a transaction fee. You should authorize either for €1.00 or for the amount that you plan to capture.

The following example shows how to call the AuthorizeOnBillingAgreement operation:

 
https://mws-eu.amazonservices.com/OffAmazonPayments_Sandbox/2013-01-01 ?AWSAccessKeyId=AKIAJKYFSJU7PEXAMPLE 
&Action=AuthorizeOnBillingAgreement 
&AmazonBillingAgreementId=C01-1234567-1234567 
&AuthorizationAmount.Amount=10 
&AuthorizationAmount.CurrencyCode=EUR 
&AuthorizationReferenceId=test_authorize_1 
&MWSAuthToken=amzn.mws.4ea38b7b-f563-7709-4bae-87aeaEXAMPLE
&SellerId=YOUR_SELLER_ID_HERE
&SellerAuthorizationNote=ForNovemberOrder 
&SellerOrderAttributes.SellerOrderId=testSellerOrderId 
&SellerOrderAttributes.StoreName=testStore 
&SellerOrderAttributes.CustomInformation=ExampleInformation 
&InheritShippingAddress=true 
&SignatureMethod=HmacSHA256 
&SignatureVersion=2 
&Timestamp=2012-10-03T19%3A01%3A11Z 
&TransactionTimeout=60 
&Version=2013-01-01 
&Signature=WlQ708aqyHXMkoUBk69Hjxj8qdh3aDcqpY71hVgEXAMPLE

For more information about the AuthorizeOnBillingAgreement operation, including the request parameters and response elements, see Authorize in the Amazon Pay API reference guide.

The Authorization object

With Amazon Pay, an Authorization object represents the availability of funds in the payment method(s) associated with the Billing Agreement object. At any time, an Authorization object can be in one of the following four states:

Pending - The AuthorizeOnBillingAgreement operation functions in two modes: synchronous and asynchronous. The Pending status applies only if you choose the Asynchronous mode. For more information, see Synchronous and Asynchronous modes of the AuthorizeOnBillingAgreement operation. In Asynchronous mode, Amazon doesn't process your authorizations in real time. The Authorization object is always in the Pending state when you first submit the authorization request. You receive a synchronous response from the AuthorizeOnBillingAgreement operation that indicates this status. The Authorization object remains in the Pending state until it is processed by Amazon. The processing time varies and can be a minute or more. After processing is complete, Amazon notifies you of the final processing status. For more information about how to receive the final authorization status, see Getting the authorization status.
Open - The Authorization object is in the Open state as soon as the payment method is successfully authorized. You can now request a capture against this authorization for up to 30 days.
Declined - The Authorization object is in the Declined state when Amazon declines the authorization request. Note: You have the option to set the SoftDecline parameter to help you differentiate between a hard decline and a soft decline when an authorization returns a reason code of InvalidPaymentMethod. In the case of a soft decline, you can submit an additional authorization attempt. For more information, see Step 7. Prepare to handle declined authorizations.
Closed - The Authorization object can be in this state for a variety of reasons, including:
- The object was in the Open state for 30 days in Production mode and two days in Sandbox mode.
- You have completed a capture for the full or a partial amount against the open authorization. Amazon Pay allows only one capture against a single authorization. An authorization is closed immediately after your capture request is processed successfully.
- You have marked the authorization as Closed.
- You have marked the Billing Agreement object as Canceled.
- Amazon has closed the authorization.

Getting the authorization status

Note: This step is required if you are using the asynchronous mode of operation for the AuthorizeOnBillingAgreement operation.

The response to the AuthorizeOnBillingAgreement call includes the AuthorizationStatus response element, which is always set to Pending if you have selected the asynchronous mode of operation. You will later receive the final status of the authorization request (for example, Open or Declined) from Amazon Pay through the Instant Payment Notification service. For more information about the Instant Payment Notification service, see Synchronizing your systems with Amazon Pay.

You then have the option to query details of the Authorization object by calling the GetAuthorizationDetails operation using the AmazonAuthorizationId that was returned with the authorization response. You will also need this unique identifier to capture funds against a successful authorization. For more information, see GetAuthorizationDetails in the Amazon Pay API reference guide.

Wait times for authorization

After you have successfully submitted the AuthorizeOnBillingAgreement operation, you have 30 days to capture funds against the authorization in Production mode before it is automatically closed. In Sandbox mode you have only two days to capture funds.

You can use the TransactionTimeout parameter in the AuthorizeOnBillingAgreement request to specify the maximum time that you are willing to wait for an authorization to process. Any authorizations that are not processed in this time (that remain in the Pending state) are declined by Amazon Pay. You receive a declined message through the Instant Payment Notification service with a reason code of TransactionTimedOut.

If you set the TransactionTimeout to 0, then the operation always returns an Open or Declined status for the authorization. In this case, any authorization that cannot be processed synchronously is declined with a reason code of TransactionTimedOut. For more information, see Synchronous and asynchronous modes of the AuthorizeOnBillingAgreement operation.

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 Open state or Closed with the MaxCapturesProcessed reason code, the billing address is 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>Schutzstraße 123</AddressLine1>
      <City>Frankfurt</City>
      <CountryCode>DE</CountryCode>
      <Name>Max Mustermann</Name>
      <PostalCode>60596</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>