Step 7: Prepare to handle declined authorizations

You can help customers understand how to address their declined payment authorizations. Just indicate what they can do to resolve the issue by showing an appropriate message for each decline reason code.

When the Authorize operation call is declined, you see in the response one of four decline reason codes. Here's what each means and its impact on the state of the OrderReferenceObject (ORO).

Decline reason codes What it means
InvalidPaymentMethod InvalidPaymentMethod indicates that there was a problem with the payment method chosen. In this situation, the ORO moves to the Suspended state.
TransactionTimedOut TransactionTimedOut indicates that the Authorize operation call was not processed within the time period specified by you in the TransactionTimeout request parameter. The ORO remains in an Open state.
AmazonRejected AmazonRejected indicates that the Authorize operation call was declined because of a determination made by Amazon. The ORO is moved to a Closed state.
ProcessingFailure ProcessingFailure indicates that Amazon could not process the transaction because of an internal processing error. The ORO remains in an Open state.

The way your customer can resolve a declined authorization depends on the reason code and the customer's presence during authorization. Prepare to handle authorization declines depending on whether:

  • The buyer is still present and can respond immediately to problems and declined payments.
  • The buyer is not present and cannot immediately respond to declined payments.

Procedures

Authorization during checkout–buyer is present (synchronous authorization)

Flow diagram: Handling synchronous authorizations

Reason code: InvalidPaymentMethod declines

  1. Show the Amazon Pay Wallet widget on your page again. (For sample code that embeds the Wallet widget on your website, see Re-rendering Wallet widgets.
  2. Check the following:
    • Make sure you 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.
    • If you integrate without the Amazon Pay Addressbook widget, you create the ORO within the Wallet widget. When reusing the JavaScript code, make sure you remove the onOrderReferenceCreate: function(orderReference).
    • Each change of a payment method in the widget triggers the onPaymentSelect callback from the Wallet widget:

  3. Show a message like this near the Wallet widget:
    "That payment method was not accepted for this transaction. Please choose another."
  4. On the same page, show a button that lets the buyer confirm the new choice. Make sure that you only enable this button after the onPaymentSelect callback was triggered at least once. Clicking this button must at least:
    • Make a call to the ConfirmOrderReference API, changing the ORO state from Suspended to Open.
    • Make a call to the Authorize API, making sure to use a new, unique AuthorizationReferenceId. This only works when the ORO state is Open.
    Notes
    • Do NOT call the SetOrderReferenceDetails operation-this call will fail because the Order Reference object is not in a Draft state.
    • If you also show the Addressbook widget on the same page, make sure that in its JavaScript code you:
      • Put it in displayMode: "Read".
      • Remove the onOrderReferenceCreate: function(orderReference).
      • Include the amazonOrderReferenceId and set it to the ORO-ID for this transaction.

Reason code: ProcessingFailure declines

  1. Redirect the customer to the cart page.
  2. On the cart page, show a message like this: "Your payment was not successful. Please try another payment method."

Reason code: AmazonRejected declines

  1. End the session with Amazon Pay (for example, call the JavaScript function amazon.Login.logout() on a page where the Amazon Pay widgets.js is loaded).
  2. Redirect the customer to the cart page.
  3. On the cart page, show a message like this: "Your payment was not successful. Please try another payment method."

Reason code: TransactionTimedOut declines

If you can't handle pending orders or your business rules require you to know the result of an authorization instantly, decline the transaction following the AmazonRejected decline process above. To ensure the customer does not receive an order confirmation, call the CancelOrderReference API.

If you can handle pending orders, do this:

  1. Make an Authorize API call using a TransactionTimeout of 1440 and no less than 60. Although you can set it as low as 5 minutes (and increase it by multiples of 5), we recommend setting the maximum time for an asynchronous authorization.
  2. Make sure that you have a process in place (IPN handler or Polling) that correctly processes the result of this asynchronous authorization.
  3. Redirect the customer to the Thank you page.
  4. Show the message below: "Your transaction with Amazon Pay is currently being validated. Please be aware that we will inform you shortly as needed."

Authorization after checkout–buyer is absent (asynchronous authorization)

Flow diagram: Handling asynchronous authorizations

Reason code: InvalidPaymentMethod declines

  1. If the buyer is not present when you receive a decline, check the response parameter SoftDecline to determine whether it is a soft or a hard decline, and then do this:
    • For a soft decline: if the order reference is in an Open state and the SoftDecline parameter is true, you can submit an additional authorization attempt. To move the order reference to an Open state, use the ConfirmOrderReference operation, and then try another authorization later. If this additional authorization attempt doesn't succeed, go to step 2.
    • For a hard decline: contact your buyer as described in step 2 and ask them to update their payment method on their Amazon.com Your Account page.
  2. Send the buyer an email that contains the URL https://pay.amazon.com/jr/your-account/orders/{OrderReferenceId}.

Reason code: ProcessingFailure declines

Attempt another authorization request in one to two minutes. The order remains in an Open state.

Reason code: AmazonRejected declines

Decline the transaction, and then contact the buyer and ask them to choose another payment method. The order is moved to a Closed state.

Reason code: TransactionTimedOut declines

Attempt another authorization after increasing the TransactionTimeout parameter value in the Authorize call.

Testing your implementation

Simulate declined authorizations by using one of these preconfigured cards in the Sandbox environment. You can't simulate the ProcessingFailure error.

For information about asynchronous authorizations, see Step 6: Request an authorization.

In the case of asynchronous authorizations, regularly requesting the authorization details, either via the GetAuthorizationDetails API call (API polling) or via Instant Payment Notification (IPN), retrieves the actual result of the authorization. Using IPNs 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 that you provide in Seller Central. Because using IPNs is preferred, explanations below refer to IPN usage. If you can't or don't want to configure an endpoint to receive IPNs, you can use API polling instead.

Synchronous authorizations

Authorization state Authorization reason code Result / next step
Approved
Closed MaxCapturesProcessed You see this only when CaptureNow flag = true. This causes the authorization to immediately move to the Closed state with a reason code of MaxCapturesProcessed.
Open none The authorization was successful.
Declined
Declined InvalidPaymentMethod The card was declined. Re-render the Wallet widget.
Declined AmazonRejected Amazon has rejected the authorization. The order is moved to a Closed state, and you should decline the transaction.
Declined ProcessingFailure There was a processing error. Retry the authorization only if the order reference object is in the Open state.
Declined TransactionTimedOut If your system can't handle a pending payment status, ask the buyer to use an alternate payment method. Otherwise, make an asynchronous authorization request and respond affirmatively to the buyer.
Pending
Pending none Pending does not apply for a synchronous authorization call.

Asynchronous authorizations

Authorization state Authorization reason code Result / next step
Approved
Closed MaxCapturesProcessed The authorization was successful. Because the CaptureNow flag = true, a capture was initiated causing the authorization to move to a Closed state with a reason code of MaxCapturesProcessed.
Open none The authorization was successful.
Declined
Declined InvalidPaymentMethod The card was declined. Ask the buyer to visit pay.amazon.com to update their card information. After updating card information, make another Authorize call, or cancel the order.
Declined AmazonRejected Amazon has rejected the authorization. The order is moved to a Closed state, and you should decline the transaction.
Declined ProcessingFailure There was a processing error. Retry the authorization only if the order reference object is in the Open state.
Declined TransactionTimedOut You might not have specified enough time. Issue a new asynchronous authorization.
Pending
Pending none The authorization is still pending a definitive response. Check back later.

See also