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 AuthorizeOnBillingAgreement 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 billing agreement.

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.

Note:  Your buyers might not be present when an authorization on a previously created billing agreement fails. In this scenario, follow the authorization after checkout–buyer is absent decline flow below. Also, make sure that you check for soft declines when the buyer is not present at the time of authorization.

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 Step 2: Add the AddressBook and Wallet widgets
2. Check the following:
• Make sure that you bind the Wallet widget to the current Billing Agreement ID by setting the amazonBillingAgreementId 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 onReady:function(billingAgreement).
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 ConfirmBillingAgreement API, changing the billing agreement state from Suspended to Open.
• Make a call to the AuthorizeOnBillingAgreement API, making sure to use a new, unique AuthorizationReferenceId. This only works when the ORO state is Open.
Notes
• Do NOT call the SetBillingAgreementDetails operation--this call will fail because the Billing Agreement 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 onReady: function(billingAgreement).
• Include the amazonBillingAgreementId and set it to the BillingAgreement-ID for this transaction.

Reason code: ProcessingFailure declines

1. Retry your request in one to two minutes.
2. If the retry doesn't succeed, ask the buyer to place the order again in a few minutes.

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 to attempt an asynchronous authorization:

1. Make an AuthorizeOnBillingAgreement 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."

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.

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 billing agreement is in an Open state and the SoftDecline parameter is true, you can submit an additional authorization attempt. To move the billing agreement to an Open state, use the ConfirmBillingAgreement 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.

Reason code: ProcessingFailure declines

Attempt another authorization request in one to two minutes. The billing agreement 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 billing agreement is moved to a Closed state.

Reason code: TransactionTimedOut declines

Attempt another authorization after increasing the TransactionTimeout parameter value in the AuthorizeOnBillingAgreement 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.

See also

Step 6: Request an authorization