Amazon Pay API Integration

1 Creating Amazon Pay App And Adding Your Domain
2 Obtain Amazon Pay MID Credentials
3 Create Amazon Pay MID
4 Add Amazon Pay Widgets and JavaScript to Your Lander Code
5 Send Amazon Pay Parameters with Import Order API Call
6 Transaction Flow
7 Upsells
8 Enable Recurring Payments
9 Errors/Decline Messages

The Amazon Pay gateway does not work with Konnektive form code. This document is for a direct API integration only. To integrate Amazon with Konnektive form code, use this document.

Creating Amazon Pay App And Adding Your Domain

Log in to https://sellercentral.amazon.com
Go to Integration → Integration Central
Go to Manage client ID/store ID(s) section at the bottom of the page and click “Create new client ID/store ID” or click “View client ID/store ID(s)” and “Edit” to update existing app.
Add your lander domain to JavaScript origins and return URLs and create or update.

Obtain Amazon Pay MID Credentials

Log in to https://sellercentral.amazon.com
Go to Integration → MWS Access Key
Click the gold “Copy your keys” button at the top right
Copy the credentials shown in the popup.

Create Amazon Pay MID

In the CRM, go to Merchants->MID List
Click the green plus sign to create a new MID
Select Amazon Pay as Gateway field
Fill in copied credentials (merchant_id, access_key, secret_key, client_id, client_secret)
Fill in MID Title, Descriptor, MID #
Click “Create MID”

Add Amazon Pay Widgets and JavaScript to Your Lander Code

Sample Code from Amazon docs:

<head>
  <script type='text/javascript'>
    window.onAmazonLoginReady = function() {
      amazon.Login.setClientId('your Amazon Pay client_id');
    };
    window.onAmazonPaymentsReady = function() {
      //get parameters from the URL query string
      const urlParams = new URLSearchParams(window.location.search);
      //access_token will be returned in URL after customer has logged into Amazon
      //access_token needs to be sent in Import Order API calls as amazonAddressConsent parameter
      if(urlParams.has("access_token")) {
        const amazonAccessToken = urlParams.get("access_token");
        //get Amazon profile details: username, email address, userID
        //Send profileResponse.email as emailAddress parameter on Import Order API call
        //Parse profileResponse.name and send as firstName and lastName parameters on Import Order API call
        let profileResponse;
        $.ajax({
            async: false,
            type: "GET",
            // cors: true,
            headers: {
                "Authorization": "bearer "+amazonAccessToken 
            },
            url: "https://api.amazon.com/user/profile",
            success: function (result) {
                profileResponse = result;
            },
            error: function (xhr) {
                return xhr.status;
            }
        });
        showAddressBook();
        showWallet();
      } else {
         showButton();
      }
    };
  </script>
    <script async="async" src='https://static-na.payments-amazon.com/OffAmazonPayments/us/js/Widgets.js'>
  </script>
</head>

<body>
. . .
 <div id="AmazonPayButton">
 </div>
 <div id="addressBookWidgetDiv">
 </div>
 <div id="walletWidgetDiv">
 </div>
  ...
 <script type="text/javascript">
    function showButton(){
      var authRequest; 
      OffAmazonPayments.Button("AmazonPayButton", "your Amazon Pay merchant_id", { 
        type:  "TYPE (choose LwA or PwA)", 
        color: "COLOR (choose between Gold, LightGray, DarkGray)", 
        size:  "SIZE (choose between small, medium, large, x-large)", 

        authorization: function() { 
        loginOptions = {scope: "profile payments:widget payments:shipping_address", 
          popup: "true"}; 
        authRequest = amazon.Login.authorize (loginOptions, 
          window.location.href); 
        }, 
 
        onError: function(error) { 
          // your error handling code.
          // alert("The following error occurred: " 
          //        + error.getErrorCode() 
          //        + ' - ' + error.getErrorMessage());
        } 
     });
    }; 
   </script>
   <script>
   function showAddressBook() {
    new OffAmazonPayments.Widgets.AddressBook({
      sellerId: 'your Amazon Pay merchant_id',
      onOrderReferenceCreate: function(orderReference) {
        // Here is where you can grab the Order Reference ID.
        //send this in the Import Order API as the amazonOrderId parameter
        orderReference.getAmazonOrderReferenceId();
      },
      onAddressSelect: function(orderReference) {
        // Replace the following code with the action that you want
        // to perform after the address is selected. The
        // amazonOrderReferenceId can be used to retrieve the address
        // details by calling the GetOrderReferenceDetails operation.
  
        // If rendering the AddressBook and Wallet widgets
        // on the same page, you do not have to provide any additional
        // logic to load the Wallet widget after the AddressBook widget.
  
        // The Wallet widget will re-render itself on all subsequent
        // onAddressSelect events without any action from you.
        // We don't recommend that you explicitly refresh it.
      },
      design: {
        designMode: 'responsive'
      },
      onReady: function(orderReference) {
        // Enter code here that you want to be executed
        // when the address widget has been rendered.
      },
  
      onError: function(error) {
        // Your error handling code.
        // During development you can use the following
        // code to view error messages:
        // console.log(error.getErrorCode() + ': ' + error.getErrorMessage());
        // See "Handling Errors" for more information.
      }
    }).bind("addressBookWidgetDiv");
  }
</script>
<script>
function showWallet(){
  new OffAmazonPayments.Widgets.Wallet({
    sellerId: 'your Amazon Pay merchant_id',
    onPaymentSelect: function(orderReference) {
      // Replace this code with the action that you want to perform
      // after the payment method is chosen.

      // Ideally this would enable the next action for the buyer
      // including either a "Continue" or "Place Order" button.
    },
    design: {
      designMode: 'responsive'
    },

    onError: function(error) {
      // Your error handling code.
      // During development you can use the following
      // code to view error messages:
      // console.log(error.getErrorCode() + ': ' + error.getErrorMessage());
      // See "Handling Errors" for more information.
    }
  }).bind("walletWidgetDiv");
}
</script>
   . . .
   <script type="text/javascript">
     document.getElementById('Logout').onclick = function() {
       amazon.Login.logout();
     };
   </script>

</body>

For more information on adding Amazon Pay widgets and Javascript visit https://developer.amazon.com/docs/amazon-pay-onetime/add-a-button.html

Send Amazon Pay Parameters with Import Order API Call

Send these parameters during Import Order API call

paySource: “AMAZON”
amazonBillerId: ID of Amazon Pay MID in the CRM (found on the MID List page)
amazonAddressConsent: access_token returned to your checkout page via the URL by Amazon
amazonOrderId: obtained in the AddressBook onOrderReferenceCreate function with orderReference.getAmazonOrderReferenceId();

Transaction Flow

Customer clicks Amazon-generated Amazon Pay button on checkout page.

New window pops up for customer to log into Amazon

Customer returned to checkout page with access_token in URL query string.

access_token is used with Amazon profile API to obtain the firstName, lastName, and emailAddress parameters to send on Import Order API call. Send profileResponse.email as emailAddress parameter on Import Order API call. Parse profileResponse.name and send as firstName and lastName parameters on Import Order API call.

Call functions to display the Amazon AddressBook and Wallet widgets.

Obtain Amazon Order Reference ID to send on Import Order API call as amazonOrderId parameter in the AddressBook onOrderReferenceCreate function with orderReference.getAmazonOrderReferenceId();

Customer chooses shipping address and payment method from Amazon-generated widgets.

Import Order with parameters: paySource=AMAZON, amazonBillerId, amazonOrderId, amazonAddressConsent (access_token).

Upsells

Repeat JavaScript process on your upsell page and send amazonBillerId, amazonOrderId, amazonAddressConsent on Import Upsale API call.

Enable Recurring Payments

Follow the same integration steps as for one-time payments above and replace the Amazon AddressBook and Wallet widget code and add the Consent widget code as follows:

<script>
  new OffAmazonPayments.Widgets.AddressBook({
    sellerId: 'your Amazon Pay merchant_id',
    agreementType: 'BillingAgreement',
     
    onReady: function(billingAgreement) {
      var billingAgreementId = billingAgreement.
      getAmazonBillingAgreementId();
    },
    onAddressSelect: function(billingAgreement) {
      // Replace the following code with the action that you want to perform
      // after the address is selected.
      // The amazonBillingAgreementId can be used to retrieve
      // the address details by calling the GetBillingAgreementDetails operation.
      // If rendering the AddressBook and Wallet widgets on the same page, you
      // should wait for this event before you render the Wallet widget for
      // the first time.
      // The Wallet widget re-renders itself on all subsequent
      // onAddressSelect events without any action from you. We don't
      // recommend that you explicitly refresh it.
    },
    design: {
      designMode: 'responsive'
    },
    onError: function(error) {
      // your error handling code
    }
  }).bind("addressBookWidgetDiv");
</script>

<script>
  new OffAmazonPayments.Widgets.Wallet({
    sellerId: 'your Amazon Pay merchant_id',
    // amazonBillingAgreementId obtained from the AddressBook widget
    amazonBillingAgreementId: amazonBillingAgreementId,
    onPaymentSelect: function(billingAgreement) {
      // Replace this code with the action that you want to perform
      // after the payment method is selected.
    },
    design: {
      designMode: 'responsive'
    },
    onError: function(error) {
      // your error handling code
    }
  }).bind("walletWidgetDiv");
</script>

For more information on adding Amazon Pay widgets and Javascript visit https://developer.amazon.com/docs/amazon-pay-automatic/add-address-and-wallet-widgets.html

The customer will be required to check the “Use my selected payment method for future purchases and payments to this merchant” box in the Amazon-generated consent widget to complete the purchase.

Send the amazonBillingAgreementId as the amazonOrderId parameter on your Import Order API call.

Errors/Decline Messages

Below you will find common errors that other users have encountered when using Amazon Pay.

Error	Cause	Fix

Error	Cause	Fix
InvalidPaymentMethod	The customer’s payment method inside Amazon is no longer valid.	Customer must ensure that all payment methods inside their Amazon account are valid.