Handling errors from Amazon Pay widgets

As discussed in Step 3: Add a button widget, you can configure the Button, AddressBook, and Wallet widgets to notify you of error conditions. These widgets send error notifications if certain integration errors are made.

The following code sample shows how you can read the errorCode and errorMessage that are associated with the error. These error codes help you debug your integration more quickly and, if logged, can notify you of potential issues on your production site.

 
<label>Debug error code     :</label>
<div id="errorCode"></div>

<label>Debug error message  :</label>
<div id="errorMessage"></div>

<div id="addressBookWidgetDiv">
</div>

<script>
  new OffAmazonPayments.Widgets.AddressBook({
    sellerId: 'YOUR_SELLER_ID_HERE',
    onOrderReferenceCreate: function(orderReference) {
      // Here is where you can grab the Order Reference ID.
      orderReference.getAmazonOrderReferenceId();
    },
    design: {
      designMode: 'responsive'
    },
    onError: function(error) {
      document.getElementById("errorCode").innerHTML = error.getErrorCode();
      document.getElementById("errorMessage").innerHTML = error.getErrorMessage();
    }

// The following are two examples of error handling code

    onError: function(error) {
      if(error.getErrorCode() == 'ITP') {
        // take no action -- allow interaction with widgets -- remove spinner/overlay if any
        return;
      }
      if(error.getErrorCode() == 'BuyerSessionExpired') {
        // take an action to move the customer to regular checkout, perhaps reroute to cart page
        window.location.href = '//my.ecommerce-shop.com/cart'; // send to the page which has a Amazon Pay Widgets(Button)
      }
    }
  }).bind("addressBookWidgetDiv");
</script>  
    

The following table lists the various error codes that are returned from the Amazon Pay widgets and the corresponding error message that the buyer sees within the widget body:

Error code Description Error message shown to the buyer
AddressNotModifiable You cannot modify the shipping address when the order reference is in the given state. You cannot change the shipping address for this order. Please contact the merchant for assistance.
BuyerNotAssociated The buyer is not associated with the given order reference. The buyer must sign in before you render the widget. This session is not valid. Please re-start the checkout process by clicking the Amazon Pay button.
BuyerSessionExpired The buyer's session with Amazon has expired. The buyer must sign in before you render the widget. Your session has expired. Please sign in again by clicking the Pay with Amazon button.
InvalidAccountStatus Your merchant account is not in an appropriate state to execute this request. For example, it has been suspended or you have not completed registration. If the error happened when showing the Button widget, the widget doesn't appear. There is no error message shown to the buyer. If the error happened when showing the AddressBook or Wallet widgets, the buyer sees this message:

We're sorry, but there's a problem processing your payment from this website. Please contact the merchant for assistance.
InvalidOrderReferenceId The specified order reference identifier is invalid. We're sorry, but there's a problem processing your payment from this website. Please contact the merchant.
InvalidParameterValue The value assigned to the specified parameter is not valid. If the error happened when showing the Button widget, the widget doesn't appear. There is no error message shown to the buyer. If the error happened when showing the AddressBook or Wallet widgets, the buyer sees this message:

We're sorry, but there's a problem processing your payment from this website. Please contact the merchant for assistance.
InvalidSellerId The merchant identifier that you have provided is invalid. Specify a valid SellerId. If the error happened when showing the Button widget, the widget doesn't appear. There is no error message shown to the buyer. If the error happened when showing the AddressBook or Wallet widgets, the buyer sees this message:

We're sorry, but there's a problem processing your payment from this website. Please contact the merchant for assistance.
ITP The buyer must give Amazon Pay permission to use cookies to verify their identity and securely complete transactions. Amazon Pay renders a rescue widget to get buyer permission to use cookies. When this widget is first rendered or refreshed after buyer action, the onError callback is triggered with the errorCode of ITP.

The merchant should not take action when the onError callback returns the ITP errorCode. The buyer uses the Amazon Pay rescue widget to grant permission and return to the merchant's normal checkout flow.

If the buyer chooses not to grant Amazon Pay permission to use cookies, the onError callback returns the BuyerSessionExpired errorCode.
MissingParameter The specified parameter is missing and must be provided. If the error happened when showing the Button widget, the widget doesn't appear. There is no error message shown to the buyer. If the error happened when showing the AddressBook or Wallet widgets, the buyer sees this message:

We're sorry, but there's a problem processing your payment from this website. Please contact the merchant for assistance.
PaymentMethodNotModifiable You cannot modify the payment method when the order reference is in the given state. You cannot change the payment method for this order. Please contact the merchant for assistance.
ReleaseEnvironmentMismatch You have tried to render a widget in a release environment that doesn't match the release environment of the Order Reference object. The release environment of the widget and the Order Reference object must match. We're sorry, but there's a problem processing your payment from this website. Please contact the merchant for assistance.
StaleOrderReference The specified order reference was not confirmed in the allowed time and is now canceled. You cannot associate a payment method and an address with a canceled order reference. Your session has expired. Please sign in again by clicking the Amazon Pay button.
AddressBookWidgetNotApplicable The Amazon AddressBook Widget cannot be rendered because the useAmazonAddressBook parameter has been set to false for the specified order reference. We're sorry, but there's a problem processing your payment from this website. Please contact seller for assistance.
BuyerNotEligible The buyer cannot use the merchant account. You cannot use the username and password associated with your merchant account. Please use a different buyer account.
UnknownError There was an unknown error in the service. We're sorry, but there's a problem processing your payment from this website. Please contact the merchant.