Synchronous and asynchronous modes of the AuthorizeOnBillingAgreement operation
The AuthorizeOnBillingAgreement operation functions in two modes:
- In asynchronous mode, the AuthorizeOnBillingAgreement operation always returns a Pending status of the Authorization object in the synchronous response. You must listen for the Instant Payment Notification to obtain the final processing status (Open or Declined).
- In synchronous mode, the AuthorizeOnBillingAgreement operation always returns an Open or Declined status for the Authorization object in the response.
Choosing the mode of operation for the AuthorizeOnBillingAgreement operation depends on your business processes and technical systems.
Asynchronous mode
You can choose the asynchronous mode of operation by not specifying a value or by specifying a non-zero value to the TransactionTimeout request parameter of the AuthorizeOnBillingAgreement operation. For more information about the valid values for the TransactionTimeout request parameter, see Authorize in the Amazon Pay API reference guide.
The following code example shows how to enable the asynchronous mode on 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
&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
In the asynchronous mode of operation, you receive an initial Pending status of the Authorization object in the response to your AuthorizeOnBillingAgreement request, typically within 2-3 seconds. You receive the final processing status (Open or Declined) via Instant Payment Notification typically within 60 seconds. In rare cases, when Amazon Pay is manually investigating a transaction, you might not receive the final processing status notification for up to the TransactionTimeout value specified by you or for 24 hours if no TransactionTimeout value is specified.
We recommend using the asynchronous mode if your business processes and technical systems can hold a transaction for up to 24 hours. If you receive a Declined status of the authorization, you need to notify the buyer of the failed transaction and ask them to update the payment method on the Amazon Pay website, collect an alternative form of payment, or cancel the transaction based on the declined reason code. For more information about declined payments, including information about using the SoftDecline parameter to determine when it is possible to submit an additional authorization attempt, see Step 7: Prepare to handle declined authorizations.
By choosing this mode, you provide Amazon more time to investigate transactions, usually resulting in a lower authorization decline rate.
Synchronous mode
You can choose the synchronous mode of operation by setting the TransactionTimeout request parameter to 0.
The following code sample shows how to enable the synchronous mode on 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
&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=0
&Version=2013-01-01
&Signature=WlQ708aqyHXMkoUBk69Hjxj8qdh3aDcqpY71hVgEXAMPLE
In the synchronous mode of operation, you receive an Open or Declined status of the Authorization object in the response to your AuthorizeOnBillingAgreement request, typically within 6-8 seconds. If Amazon can't process the authorization synchronously, the operation returns a Declined status with a reason code of TransactionTimedOut.
We recommend using the synchronous mode if you have scenarios where you want to authorize and/or capture payments while the buyer is still on your site (for example, you want to offer a digital download or confirm an expedited delivery). In these cases, you might not be able to handle declines in an offline process.
By choosing this mode, you might observe a higher authorization decline rate because Amazon converts some Pending authorizations to Declined. You can determine these authorisation declines by checking for the TransactionTimedOut reason code.
Unlike in asynchronous mode, where you handle authorization declines through an offline process, in synchronous mode you can handle declines while the buyer is on your site. For more information, see Step 7: Prepare to handle declined authorizations.