X-Cart:Amazon Pay (formerly Pay with Amazon)

X-Cart 4.6.4or above

Overview

X-Cart's Amazon Pay (formerly Pay with Amazon) module provides an integration with Amazon Payments, a payment service that enables buyers to pay on your online store using the payment and shipping information already stored in their existing Amazon accounts. All the interaction of buyers with Amazon Payments takes place in embedded widgets, so that the buyers can complete the checkout process without ever leaving your website.

System requirements and installation

Amazon Pay is available as a built-in module with X-Cart versions 4.6.4 and later.
For X-Cart versions 4.6.2 and 4.6.3, it may be obtained and installed separately. See X-Cart:Amazon Pay module installation (X-Cart 4.6.2 - 4.6.3).

Getting started

1. Register your Amazon Payments account.
   The new Amazon Pay solution is packed with enhanced features. To benefit from it, you’ll need to register for a new Amazon Payments account.
   Sign up for FREE here if your business in based in the US, or here if your business is based in the UK, Germany, Luxembourg, the Netherlands, Sweden, Portugal, Hungary or Denmark.
   
   
2. Log in to Amazon's Seller Central at https://sellercentral.amazon.com to complete a few extra steps. If you’ve registered for multiple Amazon services, you’ll see a dropdown at the top of the page that lets you move between the different services.
   
   
   
3. Create a test account to use in Sandbox mode.
   Select "Amazon Payments Advanced (Sandbox View)" from the drop-down box at the top of the screen. Under "Integration" -> "Test Accounts", you can create test accounts for use in Sandbox mode. Sandbox mode can be used to make test purchases without processing an actual payment.
   
   
   
4. Set up your account
   Select "Amazon Payments Advanced (Production View)" from the drop-down box at the top of the screen. You’ll need to complete a tax interview and set up your bank account, even if you’ve already done so for an existing account. You’ll see a message and links to complete these steps on your home page when you switch to the Production View.
   
   
   
5. Get your account keys (These will need to be entered in X-Cart):
   • Under "Settings" -> "Integration Settings":
     

   • Your Merchant ID
     
     
     

   • Under "Integration" -> "MWS Access Key":

   • Your Access Key ID
   • Your Secret Access Key
     
     
     

   • Note: If you do not see your keys, you'll need to create new ones, which you do by clicking the link under "Create MWS Account":

   • Log in using your Seller Central account.
   • Select the "I want to access my own Amazon seller account with MWS" option.
   • Accept the license agreement.
   • Your keys will be set up in your account, you can ignore the IDs you see on the final page.
   • Go back to Seller Central (http://sellercentral.amazon.com) to the "MWS Access Key" page to see the keys you'll need to enter in X-Cart.
     
     

6. In a new browser tab or window, log in to the Admin interface of your X-Cart store. Copy the account keys from Seller Central and paste them into X-Cart on the Amazon Pay module configuration page. Specify the rest of the settings (Operation mode, Currency, Capture mode) as required and save the configuration. We recommend setting the Operation mode to "Test" first, so you can create some orders in Sandbox mode and see how it works. For more info on the module configuration settings, see:
   • Amazon Pay: Configuring the module.
     
     
7. In Seller Central, configure your instant notification settings (IPN):
   Under "Settings" -> "Integration Settings", enter your Merchant URL. The Sandbox and Production accounts each have separate values for this setting, so you must switch the view using the drop-down box at the top of the screen to set both. The URL you'll need to enter is httрs://<YOUR_XCART_STORE>/payment/amazon_pa_ipn_recv.php (HTTPS is required when you configure your IPN URL for the production account. HTTP is only allowed for testing since no private customer data is passed in test mode).
   
   
8. If you wish to use your own graphics (company logo) in the pop-up window where buyers will sign in to Amazon Payments, upload the image in Seller Central (This is called "Pop-up Window Banner" under "Settings" -> "Integration Settings"). Banner images must be 520 pixels wide by 50 pixels tall, and they must have no animation. Image files should be in .jpg or .gif format.
   
   
9. If using X-Cart version 4.7.7 or later, you will need to complete a few additional steps:
   a) Go to в https://sellercentral.amazon.com/gp/homepage.html
   b) Use the drop-down box at the top right-hand corner of the page to switch to Login with amazon.
   c) Create a new application: Click the button Register new application, provide the required information about your application (Name, Description, Privacy Notice URL and Logo Image) and click Save:
   
   
   d) Choose to configure your application's Web Settings:
   
   
   You will need to enter the Allowed JavaScript Origins and Allowed Return URLs URLs:
   
   
   The URLs for these fields can be obtained in the Amazon Pay module configuration section of your X-Cart store's Admin area - you simply need to copy and paste them. Click Edit, add the URLs and save the changes.
   
   After your application has been created and configured, you will find your Client ID in the Web Settings section of your application details:
   
   
   Copy this value and paste it into the Client ID field of the Amazon Pay module configuration settings in your X-Cart store's Admin area ('Main page :: Payment methods' page > 'Amazon Pay' tab; see Amazon Pay: Configuring the module.)
   
   
10. If you disabled the Amazon Pay module in X-Cart after installation, enable (activate) it:
    
    • Amazon Pay: Activating and deactivating the module
11. Test your setup in Sandbox mode. You can use the test account you set up earlier. We recommend trying out both your customer-facing checkout flow as well as order management to get a feel for how orders are processed.
12. Once you’re ready to go live with your Amazon Pay module, configure the module to production mode by setting its Operation mode to "Live" and you should be ready to go.
13. Order Management
    You manage orders entirely within X-Cart’s order management interface, as you would with a standard credit card payment gateway. There's no need to process the orders via Amazon's Seller Central website as with Checkout by Amazon.

Activating and deactivating the module

If the module Amazon Pay is installed, but not active, you can enable (activate) it.

To enable the module:

1. Go to the Modules section of your store's Admin area (Settings menu->Modules). This opens the list of your store's installed modules.
2. Locate the entry for the Amazon Pay module and select the respective check box on the left.
3. Click Apply changes. The module will be enabled.

It is possible to temporarily disable (deactivate) the installed Amazon Pay module. Deactivation stops the module from operation, but it does not remove any settings you made to the module configuration nor clear any data that was generated during the period that the module was in operation. If you wish to completely remove all the data related to using the module, you need to uninstall it. See Amazon Pay: Uninstallation for more info.

To disable the module:

1. Go to the Modules section of your store's Admin area (Settings menu->Modules).
2. Locate the entry for the Amazon Pay module and unselect the respective check box on the left.
3. Click Apply changes. The module will be disabled.

Configuring the module

After the module has been installed and enabled, it needs to be configured.

To configure the module:

1. Open the module configuration section. Use one of the following methods:
   • In the Modules section of your store's Admin area (Settings menu->Modules), locate the entry for 'Amazon Pay' module and click the Configure link next to it:
     
     
     OR:
     
   • In the Payment methods section of your store's Admin area (Settings menu->Payment methods), click the 'Amazon Pay' tab:
     
     
     The Amazon Pay module configuration section looks similar to the following (The actual set of settings available on the page will differ depending on the version of X-Cart being used; the screenshot below corresponds to X-Cart version 4.7.7):
     
     
     
2. Adjust the module configuration settings:
   • Operation mode: Use this to switch between the Sandbox and Production modes for the Amazon Payments Advanced integration.
   • Amazon Seller ID: Enter your Merchant ID from your Seller Central account.
   • Access Key ID: Enter your Access Key ID from your Seller Central account.
   • Secret Access Key: Enter your Secret Access Key from your Seller Central account.
   • Client ID (The field is available in X-Cart versions 4.7.7 and later): Enter your Client ID.
   • Region (The field is available in X-Cart versions 4.7.7 and later): Enter the region of your Amazon Pay account.
   • Currency: Select your currency.
   • Capture mode: Specify the desired capture mode ("Authorization then capture" or "Immediate Charge"). The "Authorization then capture" mode means that, when your buyer submits their order on checkout, you only get an Authorization on the payment method they selected, but not charge the buyer until you fulfill the order. To actually charge the funds you have authorized, you need to manually capture the payment amount by clicking the Capture button on the details page of the respective order in your X-Cart store. "Immediate Charge" means that, when buyer submits their order on checkout, the payment is both Authorized and Captured at the same moment.
     
     Note: The Amazon Payments policy states that you charge your buyer when you fulfill their order. For physical goods, the order is considered fulfilled when the goods are shipped. For digital goods and services, the order is considered fulfilled when the goods or services are delivered to the buyer. If you want to charge your buyer before you ship, you must contact the Amazon Payments team for approval.
   • Type of authorization request (The field is available in X-Cart versions 4.6.4 and later): Specify the type of request you wish to use. If Asynchronous is chosen, Amazon Pay will have to send a request to the Merchant URL before the order status can be set to Processed. If Synchronous is chosen, the appropriate order status will be set straight away, without Amazon Pay sending requests to the Merchant URL.
3. Click Apply changes.
   This is it. Now your module has been configured.

Customer experience

In the Customer area of your X-Cart store, in all the locations from which buyers can initiate the checkout process using the standard X-Cart's Checkout button, the Amazon Pay module adds another button: Amazon Pay.

Here's what it looks like on "Your cart" page:

in the "Minicart" widget:

and in the "Add to cart" popup:

Once the Amazon Pay button is clicked, a pop-up window titled "Amazon Payments: Sign In" is displayed where the buyer is asked for their Amazon Payments account email address and password:

(As you can see in the screenshot above, you can add your company logo in the buyer authentication pop-up window. This can be done by uploading your own banner image on the "Settings" -> "Integration Settings" page in Seller Central).

After the buyer successfully authenticates, they find themselves on a special checkout page in X-Cart which has two Amazon widgets embedded in it: the AddressBook widget (the "Address Book" section) where the buyer can select a shipping address from their Amazon Payments account or add a new one and the Wallet widget (the "Payment Method" section) where the buyer can select a payment method from their Amazon Payments account:

Note that the buyer stays on your store's site throughout the checkout process, without ever being redirected to Amazon.

After selecting a shipping address and a payment method from their account, the buyer selects a shipping method. X-Cart uses the information provided by the customer to calculate the shipping cost and taxes. Then the buyer places the order using the Submit order button. This sends a payment request to Amazon.

After submitting the order, the buyer sees X-Cart's standard order confirmation page ("Congratulations! Your order has been successfully placed") displaying the order invoice with all the required information (The payment method is shown as "Amazon Pay", and the order status is "Queued").

In a few minutes, after Amazon processes the payment request, Amazon sends a notification, called an Instant Payment Notification (IPN), to notify your store about the final status of the request. As a result, the order status in your store is updated to one of the following:

• "Pre-Authorized" (= successful authorization, possible in "Authorization then capture" capture mode);
• "Processed" (= successful authorisation and capture, possible in "Immediate Charge" capture mode);
• "Failed" (= transaction declined).

Appropriate order notifications are then sent to the email addresses of the buyer and the store's orders department in accordance with your store's "General settings :: Email notifications options" configuration. When the payment's status in Amazon Payments transitions as a part of the payment process (for example, when you capture a previously authorized amount or issue a refund), appropriate notifications are sent as well.

Admin experience

In your store's Admin area, orders that were placed by customers using Amazon Pay can be identified by the name of the payment method specified in the order details ("Amazon Pay"). The order details page for such orders includes a section titled "Amazon Pay available order actions". Depending on the order status, this section may include the following buttons:

• Capture and Void: These buttons are displayed when "Authorization then capture" mode is used, and the order is in the "Pre-Authorized" status. The Capture button allows you to collect payment from the buyer after the respective payment amount has been authorized. The Void button allows you to void the authorization.
  
  
  
• Refund: This button allows you to refund the payment if you already captured funds. It is displayed when the order is "Processed" or "Completed".
  
  
  
• Refresh status: This button is displayed if Instant Payment Notification with the results of processing the payment on the side of Amazon Payments was not received by the store. This may be the case if IPN was not configured or was not working for some reason at the time of the transaction. The Refresh status button provides a workaround solution allowing you to obtain information on the current status of the payment in Amazon Payments and to synchronize the status of the order in X-Cart with it. When you click this button, your store sends a request to Amazon Payments; after a response from Amazon is received, the status of the order in X-Cart is updated appropriately, and the respective buttons for available order actions ("Capture" and "Void", or "Refund") get displayed in the "Amazon Pay available order actions" section.
  
  
  

At the moment, X-Cart's Amazon Pay integration supports Authorize, Capture, Void and Refund operations only for the sum equalling the original order amount. Changes to the original authorization amount, partial captures and partial refunds are not supported. In situations calling for transactions with amounts that are more or less than the original order amount, we recommended cancelling the original order and working with the customer to place the order again. For example, if, after receiving an order, you find out that some of the items in the order have gone out of stock and cannot be fulfilled, you should Void or Refund the transaction and ask the customer to re-submit the order.

Amazon Pay FAQ

Q: Is there a way to see detailed Amazon requests logs?

A: To enable debug mode, edit this file: modules/Amazon_Payments_Advanced/config.php and add the following code anywhere in that file: define('AMAZON_PA_DEBUG', 1);

After that, detailed Amazon requests and replies will be written into "var/log" folder

Q: After an upgrade, Amazon Pay no longer works. What could be wrong?

A: If you have upgraded to X-Cart version 4.7.7 or later, the problem is likely related to the change in our Amazon Pay integration. Starting with this version, your X-Cart store needs to have a Client ID to be able to interact with your Amazon account properly. To obtain a Client ID, you will need to create and set up a new Amazon application. Also, to ensure the proper functioning of Amazon Pay, you will need to configure a couple of additional settings in your Login with Amazon account. For details, see point 9 of the "Amazon Pay: Getting started" instructions above.

See also:

• Amazon Payments