Amazon Pay and Login with Amazon integration guide

Handling declined authorizations

If the Authorize operation call is declined, you must take the right actions depending on the reason code (attribute in response: ReasonCode) that is provided with the decline.

In the case of a synchronous authorisation, you see the result of the authorisation attempt (status Open if successful and Declined if not) and also the ReasonCode in the response for your API call.

In the case of an asynchronous authorisation, this response always returns the status Pending.

The actual result of the authorisation can be retrieved either by regularly requesting the authorisation details by means of the GetAuthorizationDetails API call (API polling) or via Instant Payment Notification (IPN). The latter is the more elegant way and ensures that you retrieve the result as early as possible. IPNs are brought to you by an http-POST from Amazon Pay to a URL you provide in the Seller Central (see Details on IPNs and IPN-handling). The explanations below refer to the IPN usage because it is the preferred integration method. If you can't or don't want to configure an endpoint to receive IPNs, you can use API polling instead.
Listed below are the reason codes and recommendations for addressing them.

Synchronous mode

Figure 1: Handling synchronous authorizations
(Click to enlarge)

This section describes the individual ReasonCodes you can get for a declined authorization and how you should handle them. In addition, Figure 1 provides a detailed view on the flow of actions during a synchronous authorization, including all instructions on how to react on the result of your authorization request. The diagram is also available for download as PDF.

InvalidPaymentMethod

InvalidPaymentMethod indicates that there was a problem with the payment method chosen. In this situation, the order reference moves to the Suspended state, and an Instant Payment Notification (IPN) will be sent to you if you have configured IPNs. (Note: The SoftDecline parameter also appears in the IPN notification of AuthorizationNotification.) Check the response parameter SoftDecline to determine whether it is a soft or a hard decline. Amazon recommends that you do this:

  • For a soft decline, the SoftDecline parameter is true and you can submit an additional authorization attempt when the order reference is in an Open state. To move the order reference to an Open state, use the ConfirmOrderReference operation, and then try another authorization later. If retries don't result in a successful response, we recommend that you contact your buyer and have them update their payment method on their Your Account page on Amazon.com.
  • If the transaction (or authorization) failure is not a soft decline, the SoftDecline parameter will be false. Within your purchase flow on your website, show an error message to notify the buyer that the payment method they chose was declined and to request that the buyer update the payment method in the wallet on your site.
  • Redisplay the Amazon Pay payment method widget on your page. (For sample code that embeds the Wallet widget on your website, see Step 4: Add the AddressBook and Wallet Widgets.)
    Make sure to bind the Wallet widget to the current Order Reference ID by setting the amazonOrderReferenceId value when rendering. When you do, Amazon Pay marks the previously chosen payment method as Declined.
    You can provide text indicating that the buyer can click the Declined link to update their payment information for that payment method or to choose an alternate payment method from the widget.
    Figure 2: Wallet Widget after Declined Authorization
    The screenshot in Figure 2 shows an example of a decline message that is displayed to the buyer if the Wallet widget is properly rendering the decline information.
  • After the buyer updates their payment method or chooses a new payment method, Amazon triggers the onPaymentSelect callback from the Payment widget.
  • The buyer might click several payment methods in the widget before making the final selection.

    When the buyer has made the final selection by clicking the Place Order, Update, or similar button as per the UX flow, call the ConfirmOrderReference API. This moves the Order Reference from the Suspended to the Open state.
    Do NOT call the SetOrderReferenceDetails operation, as the Order Reference object is not in a Draft state and you can no longer set additional attributes.
    You will receive an Instant Payment Notification indicating the status change or you might call GetOrderReferenceDetails to retrieve the updated order status.

  • When the order is in the Open state, you might attempt a new authorization using the Authorize API.
    The buyer receives an email similar to the one shown in the Buyer-facing email content that you can provide section.

AmazonRejected

AmazonRejected indicates that the Authorize operation call was declined because of a determination made by Amazon. The order is moved to a Closed state, and you should decline the transaction.

ProcessingFailure

ProcessingFailure indicates that Amazon could not process the transaction because of an internal processing error. Retry your request in one to two minutes. The order remains in an Open state. If the retry does not succeed, ask the buyer to place the order in a few minutes.

TransactionTimedOut

TransactionTimedOut indicates that Amazon could not process your request within 8 seconds and that the authorization request has been declined.

Usually a buyer action, such as retrying with a new order or updating the payment instrument, cannot fix this decline reason. You can either retry in asynchronous mode (the order remains open) or cancel the transaction for the buyer.

Asynchronous mode

InvalidPaymentMethod

InvalidPaymentMethod indicates that there was a problem with the payment method chosen. In this situation, the order reference moves to the Suspended state, and an Instant Payment Notification (IPN) will be sent to you if you have configured IPNs. (Note: The SoftDecline parameter also appears in the IPN notification of AuthorizationNotification.) Check the response parameter SoftDecline to determine whether it is a soft or a hard decline. Amazon recommends that you handle this scenario with the assumption that the buyer has already left the website. Do this:

  • On a soft decline, the SoftDecline parameter will be true, and you can submit an additional authorization attempt at a later moment. If retries don't result in a successful response, we recommend that you contact your buyer and have them update their payment method, as described below.
  • If the transaction (or authorization) failure is not a soft decline, the SoftDecline parameter will be false. Contact the buyer, either by email or by phone, and have them update the payment method.

    You can send an email to the buyer that contains a URL that lets the buyer sign in to their order directly and update the payment method.

    The URL contains the following elements:

    https://pay.amazon.de/mn/your-account/
    apa?action=renderOrderDetails&contractId=<order reference number>

    Here is a sample URL:

    https://pay.amazon.de/mn/your-account/
    apa?action=renderOrderDetails&contractId=P01-99999-9999999

    Alternately, you can have the buyer visit the Amazon Pay website, look up their order, and update the payment method by following the instructions on the web page.

  • After the buyer updates the payment method, the Order Reference object moves from the Suspended state to the Open state. Amazon Pay then sends you an Instant Payment Notification and the buyer receives an email similar to the one shown in the Buyer-facing email content that you can provide section.

AmazonRejected

AmazonRejected indicates that the Authorize operation call was declined because of a determination made by Amazon. The order is moved to a Closed state, and you should decline the transaction.

ProcessingFailure

ProcessingFailure indicates that Amazon could not process the transaction because of an internal processing error. Retry your request in one to two minutes. The order remains in an Open state. If the retry doesn't succeed, ask the buyer to place the order in a few minutes.

TransactionTimeout

TransactionTimedOut indicates that the Authorize operation call was not processed within the default timeout period of 24 hours or within the time period specified by you in the TransactionTimeout request parameter. If you are receiving a high number of declines because of this code, try adjusting the timeout value.

If the transaction is retried in asynchronous mode, it's important that your buyer understand that the order is taking longer than normal to process, but it has been submitted. The buyer should not attempt to submit the order again.

Typical flow for handling soft declines

When you have called the Authorize API for a customer order and have received an InvalidPaymentMethod reason code with the SoftDecline parameter set to true, you have the option to reauthorise.

First, before re-authorising, you need to reset the order to the Open state. You do this by calling the ConfirmOrderReference API.

When that has been done and the order object is in the Open state, you can call the Authorize API again.

This process can be repeated three times after the initial authorisation decline, if necessary.


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.