Amazon Pay - extension for OpenMage¶
Proudly provided by:
creativestyle is a leading e-commerce agency with offices in Germany and Poland. For more information, please visit https://www.creativestyle.de
Warning
Magento 1.x support has been dropped. Consider migration to OpenMage.
Overview¶
This extension provides an official integration of your OpenMage store with Amazon Pay service. They help your customers shop quickly, safely and securely. Your customers can pay on your website without re-entering their payment and address details. All Amazon transactions are protected by Amazon’s A-to-z Guarantee.
The extension is a pure payment solution. No item level is communicated to Amazon Payments and it allows you to manage your orders directly from OpenMage.
About Amazon Pay¶
Amazon Pay is an end-to-end payment solution that gives hundreds of millions of active Amazon customers a familiar, fast, and secure way to complete their purchase through your online store. Shoppers can use the address and payment information already stored in their Amazon account to check out - avoiding account creation or the need to re-enter their billing and shipping information. The performance is continually optimised by technology, learnings, and best practises from Amazon.
Key Benefits¶
Reduce friction with a payment process that customers trust and can complete in minimal clicks
Proactively notify customers when their order is on its way or has arrived with Amazon Alexa
Rest assured with advanced fraud protection technology backed by Amazon
Easily integrate Amazon Pay into your online store
Key Features¶
PSD2 compliant: Built-in support for strong customer authentication as required under PSD2
Delivery Notifications: Proactively alert customers on the arrival status of physical goods orders via Amazon Alexa
Multi-currency: Maintain the local currency experience across the shopping journey and help customers avoid currency conversion fees from their credit card issuer or bank
Amazon Sign-in: Reduce friction during account creation and sign-in by offering a fast and secure way for customers to authenticate through Amazon. Shoppers with an active Amazon account don’t need to login again
Automatic Decline Handling: Reduce lost sales with a consistent experience for customers to gracefully recover from a declined payment
Payment Protection Policy: Protection against fraud-related chargebacks (check User Agreement for more details)
Amazon Pay A-to-z Guarantee: Increase customer confidence to complete purchase in your online store with extra assurance on the timeliness of delivery and order quality
Getting the extension¶
You can install the extension either via Connect Manager or manually, downloading the installation package from Creativestyle connect channel.
Refer to the Installation section to get more details concerning installation procedure.
Extension features¶
Amazon Pay button in the shopping cart, in the 1st step of one page checkout and on the product page
Amazon Sign-in button on the customer login and registration page
Support for payment authorizations, captures and refunds (also partial refunds)
Supports Amazon Instant Payment Notifications
Live & sandbox modes available
JSON-based event logger
Multilanguage, available languages: en, de, fr, es, it
Multicurrency
Extension vendor¶
This extension has been developed by creativestyle GmbH in cooperation with Amazon Payments Europe S.C.A.
Creativestyle is an award-winning, pioneering e-commerce agency with more than 15 years of experience. Since 2001, they have been developing expertise in the field of technology and software solutions. With an 80 person team of experts consisting of certified specialists in the fields of design, development and management of innovative projects, they can guarantee a full range of services from consulting and planning, through concept and design, to technical implementation and subsequent project support.
Prerequisites¶
System requirements¶
Amazon Pay extension for OpenMage requires you to have a valid Amazon Payments account and a webserver running an OpenMage store instance with the following conditions met:
OpenMage 19.4.4 or higher
cURL for PHP
DOM / XML for PHP
valid SSL certificate
Important
This extension works with OpenMage 19.4.4 or higher. Please refer to Installing the extension on Magento lower than 1.9.4.0 to find out how to install it on the legacy versions of Magento.
Installation¶
Pre-installation steps¶
Create a backup of your shop before proceeding to install.
If your shop is using compilation (you can check it in ), disable it please before proceeding to install.
Installation process¶
Installation via Connect Manager¶
Go to and enter your admin credentials to get logged in.
In the Install New Extensions section paste the following extension key:
http://connect.creativestyle.de/Creativestyle_AmazonCheckout
and click Install button. Connect Manager will validate the key and check the extension dependencies and will display a pre-installation summary. Click Proceed button to start the installation.
After the successful installation, please click on Refresh button to refresh the list of the installed extensions and make sure that Amazon Pay is present on that list.
Proceed to the Post-installation steps.
Manual installation¶
Go to Creativestyle OpenMage connect channel and download the recent installation package of the extension. Unpack the downloaded file to your OpenMage root directory.
Tip
If you are using any VCS (git, svn, mercurial) for versioning your shop basecode, you can also commit the content of the downloaded file to the VCS repository and deploy it to your shop.
Proceed to the Post-installation steps.
Post-installation steps¶
If you’re using custom design theme, refer to the Templates customization section to find out how to adjust Amazon Pay templates to your needs.
Go to and flush OpenMage cache storage.
If you have disabled compiler in pre-installation stage, you can go now to , recompile and enable compiler again.
Logout from the OpenMage admin and login again.
Voila! The Amazon Pay extension shall be installed now. You can proceed to the Configuration followed by Frontend templates customization (if applicable).
Upgrade¶
Pre-upgrade steps¶
Create a backup of your shop before proceeding to upgrade.
If your shop utilises compilation (you can check it in ), disable it please before proceeding to upgrade.
Upgrade process¶
Go to and enter your admin credentials to get logged in.
Click Check for Upgrades button in the Manage Existing Extensions section. If the newest version of Amazon Pay is available, the Creativestyle_AmazonCheckout extension on the list will be highlighted with the yellow color. In the corresponding action dropdown list please select Upgrade to X.X.X (stable) option and click Commit changes button.
After the successful upgrade, please click on Refresh button to refresh the list of the installed extensions and assure that Amazon Chekout v2 (identified as Creativestyle_AmazonCheckout) was upgraded to the desired version.
Proceed to the Post-upgrade steps section.
Post-upgrade steps¶
Go to and flush Magento cache storage.
If you have disabled compiler in pre-installation stage, you can go now to , recompile and enable compiler again.
Configuration¶
After the successful installation you can proceed to the configuration. In OpenMage admin go to (or tab).
Available options are grouped into two main sections: Account credentials and Configuration (with Expert Mode subsection).
Account credentials¶
In this section you can define your Amazon Payments seller account credentials.
Payment Region, Merchant ID and Client ID¶
Fill out those fields with your Amazon Payments seller credentials. You can find them in the Amazon Seller Central.
Private Key and Public Key ID¶
Fill out those fields with the Private Key generated in Amazon Seller Central and the corresponding Public Key ID.
Advanced configuration¶
Operation mode¶
Sandbox mode has been designed to test the Amazon Pay service. In sandbox mode the selected payment method is not charged. In general, sandbox mode should be enabled for development and staging environments for testing and always has to be disabled for production environments. Never show the sandbox buttons and widgets to buyers in your live environment.
Payment Action¶
You can select the desired payment action taken after an order is placed. Available options are:
Authorize (default) - order reference creation is followed by automatic authorization request. Capture must be requested manually by creating an invoice with Capture online option selected.
Authorize & capture - order reference creation is followed by automatic authorization and capture request.
Expert Mode¶
Please click on the Expert Mode link to reveal the most advanced configuration options.
Display language¶
In this option you can select a language which will be used for displaying all elements (forms, widgets) generated by Amazon Pay. Selected language will be also used to localize emails sent by Amazon Payments to the customer after purchase.
Amazon Sign-in¶
Enable¶
By switching this option you can enable or disable Amazon Sign-in feature. Amazon Sign-in allows users to login to your shop using their Amazon username and password. The name, email address and user id is fetched from Amazon in order to facilitate the creation of an OpenMage account. Shipping and billing address will be retrieved as part of the checkout.
Enable¶
By switching this option you can enable or disable Amazon Pay. This option must be set to Yes if you want to provide payment service to your customers.
Display on Product Details Page¶
By switching this option you can enable or disable Amazon Pay button on the product details page. Amazon Pay button on the product details page allows the buyer to add the product to the cart and init the checkout with just one click.
Restrict packstation addresses¶
By enabling this option you will restrict delivery to the addresses identified as packstations.
Restrict PO box addresses¶
By enabling this option you will restrict delivery to the addresses identified as PO Boxes.
Communication¶
Store name¶
The value set for this option will appear as your store name on all email send by Amazon Pay.
Display name on bank account statement¶
Use this option to set the name of your store shown on the bank account statements. The maximum length of the value for this option is 16 chars.
Alexa Delivery Notifications¶
Enable Delivery Notifications¶
Alexa delivery notifications for Amazon Pay merchants allow you to pro-actively inform your customers if their order is on its way or has arrived.
Carrier codes¶
This option allows to map carriers from your shop to the Amazon Pay predefined carriers. Please use the Carrier codes form by selecting your available carriers and assign them to the matching one in the Amazon Pay carrier list.
Developer options¶
Enable logging¶
The Pay with Amazon extension comes with a dedicated logging mechanism. If this option is enabled all exceptions and API calls will be saved to the appropriate log file in var/log/amazonpayments/v2 directory in your OpenMage installation.
Allowed IPs (comma separated)¶
For testing or debugging purposes you can restrict access to Amazon Pay checkout in your shop to certain IP numbers only. Amazon Pay button will be shown only for the visitors coming from allowed IPs. You can set more than one allowed IP separated with commas.
Customization¶
Frontend templates¶
If you are using a custom design theme and would like to adjust the appearance of Amazon Pay templates, please complete the following steps (all paths are relative to the OpenMage root folder):
Warning
Never edit the default template or skin files directly as they can be (and surely will be) overwritten when upgrading this extension to a newer version. Edit their copies only as described below.
Create folders:
app/design/frontend/YOURPACKAGE/YOURTHEME/template/creativestyle/amazonpaymentsskin/frontend/YOURPACKAGE/YOURTHEME/creativestyle/cssskin/frontend/YOURPACKAGE/YOURTHEME/creativestyle/imagesOn Unix-like (Linux, BSD) servers you can achieve this by running following commands, please remember to replace
YOURPACKAGEandYOURTHEMEwith the real names of your theme:$ cd /path/to/your/OpenMage $ mkdir -p app/design/frontend/YOURPACKAGE/YOURTHEME/template/creativestyle/amazonpayments $ mkdir -p skin/frontend/YOURPACKAGE/YOURTHEME/creativestyle/css $ mkdir -p skin/frontend/YOURPACKAGE/YOURTHEME/creativestyle/images
Clone the following files:
app/design/frontend/base/default/layout/amazonpayments.xmlapp/design/frontend/base/default/template/creativestyle/amazonpayments/*skin/frontend/base/default/creativestyle/css/amazonpayments.cssskin/frontend/base/default/creativestyle/images/*On Unix-like (Linux, BSD) servers you can achieve this by running following commands, please remember to replace
YOURPACKAGEandYOURTHEMEwith the real names of your theme:$ cd /path/to/your/OpenMage $ cp app/design/frontend/base/default/layout/amazonpayments.xml app/design/frontend/YOURPACKAGE/YOURTHEME/layout/amazonpayments.xml $ cp app/design/frontend/base/default/template/creativestyle/amazonpayments/* app/design/frontend/YOURPACKAGE/YOURTHEME/template/creativestyle/amazonpayments/* $ cp skin/frontend/base/default/creativestyle/css/amazonpayments.css skin/frontend/YOURPACKAGE/YOURTHEME/creativestyle/css/amazonpayments.css $ cp skin/frontend/base/default/creativestyle/images/* skin/frontend/YOURPACKAGE/YOURTHEME/creativestyle/images/*
After cloning the above files to your theme folders, you can adjust the design by editing the appropriate files (HTML templates, CSS stylesheets and layout file). You can enable Template Path Hints to find out the names of the template files used by the extension in particular steps of the checkout process (in OpenMage admin, within selected store view scope: ).
Note
Please note that the ID attributes of all HTML tags must be preserved, otherwise changes to the corresponding JS scripts must be applied (do not try to change it unless you know what are you doing).
Basic appearance of rendered Amazon Pay widgets (button color and size of all widgets) can be set in the Amazon Pay extension settings (), see configuration-common-appearance-settings, configuration-login-appearance-settings and configuration-pay-appearance-settings for more details.
Amazon Pay logo¶
If you want to place the Amazon Pay logo in your shop to let your customers know you’re using payment services provided by Amazon Pay, you can find a download link of marketing tools here: * UK: https://payments.amazon.co.uk/merchant/tools * DE: https://payments.amazon.de/merchant/tools
To complement the logos you should mention Amazon Pay under your listing of supported payment methods.
Amazon Sign-in¶
Amazon Sign-in allows users to login to your shop using their Amazon user name and password. All available data needed for creating an account or placing an order in your OpenMage shop (including name, email address, and zip code) are fetched automatically from customer’s Amazon account.
Requirements¶
Amazon Sign-in service requires you to have a valid Amazon Payments account and OpenMage store with a valid SSL certificate installed and properly configured in your shop. By “installed and properly configured SSL certificate” it is meant that your webserver is configured to serve pages via HTTPS protocol, Base URL config option is set to the HTTPS-based URL and in section of OpenMage settings.
Amazon Sign-in button¶
The Amazon Sign-in button appears in several places in the shop:
on the customer login page,
on the customer registration page.
You can also place the Amazon Sign-in button in any place you like by including following statement in the template file:
<div data-lpa-role="login-button"></div>
Pressing the Amazon Sign-in button launches the Amazon authentication window, where the customer is asked for his Amazon account e-mail address and password.
After a successful login the customer is redirected to the user area in your shop.
Note
When the customer uses the Amazon Sign-in for the first time in your shop and account with the same e-mail address already exists in your shop, he will be asked to enter his shop password to match both shop and Amazon accounts. Moreover, if you require additional data from your customers which cannot be provided by Amazon (like date of birth or gender), the customer will be asked for those data in a dedicated form, that appears after the first use of Amazon Sign-in button.
Order & payment workflow¶
The Amazon Pay extension follows the standard OpenMage order and payment workflow, and thus processing Amazon Pay payments doesn’t differ significantly from other payment methods available in OpenMage, making it easy to handle. The most important difference, comparing to the standard OpenMage orders, is delayed access to the billing address, which is backfilled later in the synchronization process after the successful authorization.
All Amazon Pay objects (ChargePermission, Charge and Refund) are reflected in corresponding payment transactions in OpenMage, which are connected with appropriate document entities provided by the OpenMage, (invoices for captures, credit memos for refunds).
Amazon Pay button¶
The Amazon Pay button appears in several places in the shop:
on the shopping cart page,
in the 1st step of the default One Page Checkout,
in the sidebar cart widget.
You can also place the Amazon Pay button in any place you like by including following statement in the template file:
<div data-lpa-role="pay-button"></div>
Pressing the Amazon Pay button launches the Amazon Payments authentication window, where the customer is asked for his Amazon account e-mail address and password.
After a successful login the customer is redirected to the Amazon Pay checkout page in your shop.
Placing an order¶
The Amazon Pay checkout form consists of 4 steps arranged within a single page (unlike OpenMage default checkout, which uses accordion for showing and hiding particular steps of the checkout). These steps are: shipping address (provided by Amazon Pay), payment method (provided by Amazon Pay), shipping method and order review (handled by default OpenMage checkout templates). All fields in the form (shipping address, payment method and shipping method) are pre-filled, which means that in very basic scenario customer can finish the checkout with just one click. Unfortunately, pre-filling doesn’t apply to the terms and conditions checkbox (if used at all) and can raise the number of required clicks, which, however, doesn’t affect the easiness and user-friendliness of the Amazon Pay payment method.
Note
The value selected in each checkout step is saved in a separate AJAX call. When the checkout form shows up for the first time, depending on the internet connection speed and the web-server’s response time, it may take up to few seconds until Place order button gets active and can be clicked by the customer.
After selecting the desired shipping address, payment method, shipping method and pressing Place order button (preceded by accepting terms and conditions if needed), the customer is redirected to the success page. Amazon Pay uses the default OpenMage success page, which means there’s no need to add any tracking scripts or additional page layout elements that you use in default OpenMage checkout and want also use in Amazon checkout, all features implemented additionally on the OpenMage success page shall also appear on Amazon checkout success page.
The created order will be transferred to Amazon and will appear in your OpenMage admin in Pending (by default) or Processing (if you are using synchronous authorization) state.
Note
You may notice in the OpenMage admin that the billing address may be incorrect at this point (as mentioned in the introduction to this chapter). That’s true if the billing differs from the shipping data. The billing address will be updated as soon as authorization is confirmed by Amazon Pay. Keep also in mind that the billing address is available only for the sellers that provided a valid VAT number in Amazon Seller Central.
Multicurrency support¶
Amazon Pay extension supports multicurrency payments on the website level. Website is the top level organizational unit in OpenMage, it may share customer accounts, shipping and payment methods. To offer multicurrency support that is provided by Amazon Pay service in your OpenMage shop, you have to create a separate website for each currency you plan to offer in your shop, with the selected currency set as a base currency in OpenMage settings.
By default the base currency is set globally in OpenMage, to make it available on the website level, please go to and set its value to Website.
Next go to and set its value to the selected currency for each of the websites you created previously to offer multicurrency support for your customers. The website configuration scope can be changed by selecting appropriate entry in the Current Configuration Scope dropdown list in the top right corner of the configuration page.
Note
Please note, that multicurrency support in the extension doesn’t use Display Currency setting, which may be set on the store view level. Display currency is used just for the storefront presentation purposes and doesn’t play any role in further order post-processing, because all transactions are processed using base currency. Such a behavior is implemented in OpenMage core classes and Amazon Pay extension do not break this rule.
Capturing the payment amount¶
After a successful authorization, you can capture funds against the authorization. Payment Action option in the extension settings allows to switch between manual and automatic capture mode. For Manual authorization actions the capture is triggerd by creating manually an invoice for the order in the OpenMage admin. For Authorize & capture action, the capture is requested automatically as soon as authorization is confirmed by Amazon Pay.
Manual capture¶
To capture the order amount, you must create an invoice first. To create an invoice, login to the OpenMage admin, open the order for which you want to capture the amount and click the Invoice button located in the top buttons rows. Please make sure that the order you want to process has been successfully authorized, which basically means that it is in Processing state.
After clicking the Invoice button, a new invoice form will appear with most of the crucial data (like products quantity) already filled in. You can adjust some invoice fields if needed. At this point you can create a shipment as well, by checking Create Shipment checkbox and adding a tracking number if needed. Before submitting the form, please make absolutely sure that Amount selectbox is set to Capture online and press Submit Invoice button. A new invoice and a new shipment (if checked Create Shipment checkbox) will be created for the order and the capture request is sent to Amazon Pay.
Warning
To collect the funds that were authorized, you must capture the amount within 30 days of a successful authorization (two days in Sandbox mode). We strongly recommend that you capture funds within seven days of authorization to reduce the likelihood of declines (within 7 days the a successful captures is guaranteed). In case your fulfilment process exceeds 30 days, consider using the Manual authorization as payment action in the configuration and authorize the payment later in any suitable time (typically in the week before the shipping) before the shipping.
Note
Partial captures are not supported by the extension at this moment.
The capture status, similar to authorizations, will be updated either via IPN message or via data polling, see workflow-synchronizing-order-data for more details.
Automatic capture¶
In this mode the capture is requested automatically after the successful authorization. Also the invoice that covers all ordered items is created automatically. Post-request processing (capture status synchronization) is carried the same way as in capture invoked manually from OpenMage backend.
Refunding order items¶
The order, which payment has been captured for, can be refunded either fully or partially. Refunds are made against the invoices and thus having a paid invoice assigned to the order is a necessary condition that has to be met to refund any order item. Refunds in OpenMage are recorded as credit memos, so for requesting a refund with Amazon Payments you should create a credit memo first. To create a credit memo login to the OpenMage admin, open the order you want refund, click Invoices tab on the right, select an invoice you want to refund and click on it.
A preview of the selected invoice will appear. Make sure that you are on the single invoice preview page and click the Credit Memo button.
A new credit memo form will appear with most of the crucial data (like products quantity to be refunded) already filled in. If you want to refund the invoice partially (i.e. only a part of the invoiced items) adjust the product quantities to be refunded (set 0 for items that shall not be refunded) and click Update Qty’s button to update refund totals. You can also set the refunded items back to stock by checking Return to Stock checkbox. Next choose if you want to refund shipping costs or apply any refunds adjustment and fill in the appropriate fields. Next before submitting the credit memo form, double check that you have Refund button available and click it. A credit memo will be created and a refund will be requested with Amazon Payments. Its status will be updated either via IPN or data polling, depending on the update method selected in the extension settings.
Warning
For the successful refund (recorded in OpenMage and requested (!) with Amazon Pay) always use Refund button available on the new credit memo form invoked from the single invoice preview page. If you click Credit Memo button directly on the order page you will be redirected to the new credit memo form with Refund offline button only, which admittedly will record credit memo in OpenMage, but surely won’t call refund request at Amazon Payments gateway. If in any case you will get a credit memo with Refund offline button only then surely something had to go wrong and you should stop the refund process immediately and start it from the beginning following the above guideline.
Cancelling an order¶
For a variety of reasons it sometimes becomes necessary to cancel an order. To cancel an order and notify Amazon Pay about the payment cancellation:
Please make sure the amount of the order you want to cancel hasn’t been captured yet,
Go to and select the order that you would like to cancel by clicking the Edit button on its respective row,
Click Cancel in order page to remove this order.
Frequently Asked Questions¶
Is Amazon Pay extension compatible with Magento 1.x?
Amazon Pay extension is implemented for and tested against OpenMage platform, which is a community-driven successor of Magento 1.x, thus, it is very likely that this extension works properly on Magento 1.x as well. Please note that the official support for Magento 1.x has been dropped, so the extension may be used on Magento 1.x on the merchant’s sole risk and no support will be provided in case of platform incompatibilities.
Troubleshooting¶
Installing the extension on Magento lower than 1.9.4.0¶
Amazon Pay extension doesn’t work out of the box with Magento lower than 1.9.4.0 because of the unsupported version of phpseclib that comes with those Magento versions. However, it is possible to upgrade phpseclib and start using Amazon Pay extension. To do so, please follow the steps:
Identify your Magento version (it’s visible in the footer in Magento admin panel).
Check which security patches you have installed in your Magento shop by running the following command in the root directory of your Magento installation:
cat app/etc/applied.patches.list
Go to Magento 1.x Patches page, find your Magento version and compare the patches which are installed in your Magento shop with the ones required for your version.
Install all missing required patches, next download and install PHP 7 compatibility patch.
Now your Magento is ready to use Amazon Pay extension. Go to Installation section and install the extension.