Login and Pay with Amazon (Advanced Payment APIs) - extension for Magento¶

Extension features¶

• Pay with Amazon button in the shopping cart and in the 1st step of OnePage checkout
• Login with Amazon button on the customer login page
• Customization of Login and Pay with Amazon widgets from within Magento admin
• Support for payment authorizations, captures and refunds (also partial refunds)
• Supports Amazon Instant Payment Notifications
• Live & sandbox modes available
• Toolbox for simulating payment states in sandbox mode
• CSV-based event logger

Getting the extension¶

The extension can be installed via Magento Connect using following key: http://connect20.magentocommerce.com/community/Creativestyle_AmazonPayments.

Refer to the Installation section to get more details concerning installation procedure.

Changelog¶

Extension vendor¶

This extension has been developed by creativestyle GmbH in cooperation with Amazon Payments Europe S.C.A.

Creativestyle is an interactive agency with years of experience and origins in Germany. Our company is present in the e-commerce market since 2001. We focus on development and implementation of various Internet projects.

System requirements¶

Login and Pay with Amazon Magento extension requires you to have a valid Amazon Advanced Payments APIs account (refer to the Amazon Advanced Payments APIs account setup if you don’t have one yet) and a webserver running a Magento store instance with following conditions met:

• Magento CE (1.5, 1.6, 1.7, 1.8, 1.9) or EE (1.11, 1.12, 1.13, 1.14)
• cURL for PHP
• DOM / XML for PHP
• valid SSL certificate (for Login with Amazon and / or IPN handling)

Amazon Advanced Payments APIs account setup¶

Registering an Amazon Payments Account¶

• Go to:
  • DE merchants: https://payments.amazon.de/business/pre-registration-api
  • UK merchants: https://payments.amazon.co.uk/business/pre-registration-api
• Click Business and choose Setup options ‣ Advanced Payment APIs

• Click Sign up
• Go through the questionnaire to find out if you qualify for using Amazon Payments, then click Sign up now
• At the moment you cannot add your Advanced Payments APIs account to an existing Amazon merchant account. You have to register a new account specifically for the Advanced Payments APIs.
• Start registering a new account:
  • If you see the link Would you like to create a new account using a different e-mail address? Click here, please do so.
  • Enter a name for your business. In case this name is already taken, please choose a different one.
  • Enter an email address and a password. You should choose a role email address that will be read directly by the people responsible for the Amazon Payments integration. You should avoid general addresses like info@ that are only forwarded to the general administration.
  • Choose a secure password.

• Please fill in all requested information about your seller account, your contact information and your bank account or credit card data.
• Please be careful to provide exact and correct data. All information you provide will be verified by Amazon Payments, and incorrect information will delay the verification process.

• After providing all information there will be an identity check on the phone, where you will be asked to enter a PIN.

• Afterwards you can complete your registration

• After your account is registered you will be forwarded to your Seller Central account.
• Please be aware that you cannot fully use your account yet. First you have to provide your identity data, and then the account has to go through the verification process.

Entering identity data in Seller Central¶

To get the verification process started, please log in to Seller Central: https://sellercentral-europe.amazon.com/gp/homepage.html

For a combined account (Advanced Payments APIs added to an existing account), please make sure that you have selected the Amazon Payments – Production View in the drop down menu on the top.

At Settings ‣ Account Info please provide the requested missing information. Especially it is crucial to provide the ID information for all relevant persons.

Creating MWS access keys¶

You can generate your MWS access keys in Seller Central. Please go to Integration ‣ MWS Access Key

Log in again with your Amazon Payments account credentials

Make sure that you register the MWS Access Key for your own account.

Please read and accept the license agreement.

The AWS Access Key and the Secret Key among with the Merchant ID, will be presented to you on the next page. You can always review the key information in Seller Central on the Integration ‣ MWS Access Key page.

Registering application for Login with Amazon service¶

Login and Pay with Amazon work together to provide a great buyer experience. To use Login with Amazon you have to register the application (Magento extension) that will be allowed to access buyers accounts through your Amazon Payments seller account. Login with Amazon configuration settings can be accessed through Login with Amazon Seller Central page.

In the App Console register a new application by clicking the Register new Application button. The Register Your Application form will appear.

In the application details page, add basic details about your web site. These details will be used on your website and mobile apps (if applicable).

• Name Shown to Users. This is the name displayed on the consent screen when the users agree to share the information with your web site. This name applies to Android, iOS, and website versions of your application.
• Description. A description of your web site for Login with Amazon users.
• Privacy Notice URL. The Privacy URL is the location of your company privacy policy. It is also displayed on the consent screen. This link is displayed to users when they first login to your application (for example: http://www.example.com/privacy.html).
• Logo Image File. This logo will represent your business or website on Amazon. The logo will be displayed as a 150x150 pixel image; if you upload a file of a different size, it will be scaled to fit.

When you are finished, click Save to save your changes.

Add a Website to your Application¶

• From the Application screen, click Web Settings. You will automatically be assigned values for Client ID, which identifies your website.

• To add Allowed JavaScript Origins to your application, click Edit.

An origin is the combination of protocol, your Magento shop domain name and port (for example: https://www.example.com:8443). Allowed origins must use the HTTPS protocol. If you are using a default port (443) you need only include the domain name of your shop (for example: https://www.example.com).

Adding your domain here allows the SDK for JavaScript to communicate with your Magento shop directly during the login process. Web browsers normally block cross-origin communication between scripts unless the script specifically allows it.

To add more than one origin (in case you are running domain based multi-store Magento installation and all stores are using the same Amazon Payments seller account), click Add Another.

Note

To use Login with Amazon with your Magento shop, you MUST specify an allowed JavaScript origin.

Where to find the required credentials to configure the Magento extension¶

The Magento extension requires you to enter information about your Amazon Payments account. You will need to enter:

• Merchant ID (aka Merchant Number, Händlernummer, Händler-ID)

Note

The Merchant Token IS NOT Merchant ID.

• AWS Access Key (aka AWS Access Key ID, AWS-Zugangsschlüssel, AWS Zugangsschlüssel-ID)
• Secret Key (aka AWS Secret Key, geheimer Schlüssel)

You can find this information in your Amazon Payments seller account in Seller Central.

Merchant ID¶

You can find the Merchant ID in Seller Central at Settings ‣ Integration Settings

AWS Access Key / Secret Key¶

You can find the AWS Access Key and the Secret Key in Seller Central at Integration ‣ MWS Access Key

Client ID¶

You can find the Client ID of your application in Seller Central at Login with Amazon ‣ App Console by clicking Web Settings from the Application screen.

Pre-installation steps¶

• Create a backup of your shop before proceeding to install.
• If your shop is using compilation (you can check it in System ‣ Tools ‣ Compilation), disable it please before proceeding to install.

Installation process¶

• Go to System ‣ Magento Connect ‣ Magento Connect Manager and enter your admin credentials to get logged in.
• In the Install New Extensions section enter Login and Pay with Amazon extension key obtained from Magento Connect and click Install button.
• Installation will start and after successful install it will show a message. Optionally, you can click on Refresh button to see if Login and Pay with Amazon (identified as Creativestyle_AmazonPayments) is listed on list of the installed extensions.
• 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 Login and Pay with Amazon templates to your needs.
• Go to System ‣ Cache Management and flush Magento cache storage.
• If you have disabled compiler in pre-installation stage, you can go now to System ‣ Tools ‣ Compilation, recompile and enable compiler again.
• Logout from the Magento admin and login again.

Voila! The Login and Pay with Amazon extension shall be installed now. You can proceed to the Configuration followed by Frontend templates and Email templates customization (if applicable).

Amazon Payments Account¶

In this section you can define your Amazon Payments seller account credentials.

General Settings¶

In this section you can enable or disable the Pay with Amazon service and define basic settings of the extension.

Login with Amazon¶

In this section you can configure Login with Amazon service.

Email Options¶

Common Appearance Settings¶

In this section you can set size (width and height) of the Amazon widgets used in the checkout process.

Appearance Settings for Login and Pay with Amazon¶

These settings apply to the design (type, size and color) of the buttons, both Pay with Amazon and Login with Amazon, when Enable Login with Amazon option is set to “Yes”, therefore they become irrelevant if you don’t use Login with Amazon service, you may be interested then in Appearance Settings for standalone Pay with Amazon.

Appearance Settings for standalone Pay with Amazon¶

These settings apply to the design (size and color) of the Pay with Amazon button when Enable Login with Amazon option is is set to “No”, therefore they become irrelevant if you use Login with Amazon service, Appearance Settings for Login and Pay with Amazon are applied then.

Developer options¶

Frontend templates¶

If you are using a custom design theme and would like to adjust the appearance of Login and Pay with Amazon templates, please complete the following steps (all paths are relative to the Magento root folder):

• Create folders:

  app/design/frontend/YOURPACKAGE/YOURTHEME/template/creativestyle/amazonpayments skin/frontend/YOURPACKAGE/YOURTHEME/creativestyle/css skin/frontend/YOURPACKAGE/YOURTHEME/creativestyle/images

  On Unix-like (Linux, BSD) servers you can achieve this by running following commands, please remember to replace YOURPACKAGE and YOURTHEME with the real names of your theme:

  $ cd /path/to/your/Magento
  $ 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.xml app/design/frontend/base/default/template/creativestyle/amazonpayments/* skin/frontend/base/default/creativestyle/css/amazonpayments.css skin/frontend/base/default/creativestyle/images/*

  On Unix-like (Linux, BSD) servers you can achieve this by running following commands, please remember to replace YOURPACKAGE and YOURTHEME with the real names of your theme:

  $ cd /path/to/your/Magento
  $ 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 Magento admin, within selected store view scope: System ‣ Configuration ‣ Developer ‣ Debug).

Basic appearance of rendered Amazon widgets (button color and size of all widgets) can be set in the Pay with Amazon extension settings (System ‣ Configuration ‣ Amazon Payments), see Common Appearance Settings, Appearance Settings for Login and Pay with Amazon and Appearance Settings for standalone Pay with Amazon for more details.

Amazon Payments logo¶

If you want to place the Amazon Payments logo in your shop to let your customers know you’re using payment services provided by Amazon Payments refer to the following guidelines:

• logos:
  • UK: https://payments.amazon.co.uk/business/material#payment-marks-graphics
  • DE: https://payments.amazon.de/business/material#payment-marks-graphics
• button placement:
  • UK: https://payments.amazon.co.uk/business/material#button-guidelines
  • DE: https://payments.amazon.de/business/material#button-guidelines

To complement the logos you should mention Amazon Payments under your listing of supported payment methods.

Email templates¶

Magento provides an easy-to-use mechanism for adjusting email templates’ appearance and content. If you want to customize the emails that are sent by the extension, go to System ‣ Transactional Emails in your Magento admin and follow the instructions:

On the Transactional Emails list press Add New Template button and the form will appear. In the Load default template section choose Amazon authorization declined from the Template dropdown, change Locale, if needed, which will be used for the loaded template pattern (Pay with Amazon extension provides 3 locales: German, English UK and English US, for any other locale selected, the english (US) template will be loaded) and press Load Template button.

Fields in Template Information section will be filled out with the data taken from the default email template. Please fill in the missing name of your modified email template in the Template Name input, adjust Template Content and Template Styles to your needs and save your work by pressing Save Template button. The new template shall appear on the Transactional Emails list.

The newly created email template can be used now, you can switch to it in the extension settings, see: Declined Payment Email Template.

Pay with Amazon button¶

The Pay with Amazon 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 Pay with Amazon button in any place you like by including following statement in the template file:

<?php echo Mage::helper('amazonpayments')->getPayWithAmazonButton(); ?>

Pressing the Pay with Amazon 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 checkout page in your shop.

Placing an order¶

The Pay with Amazon checkout form consists of 4 steps arranged within a single page (unlike Magento default checkout, which uses accordion for showing and hiding particular steps of the checkout). These steps are: shipping address (handled by Amazon’s address book widget), payment method (handled by Amazon’s wallet widget), shipping method and order review (handled by default Magento 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 Pay with Amazon payment method.

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. Pay with Amazon uses the default Magento success page, which means there’s no need to add any tracking scripts or additional page layout elements that you use in default Magento checkout and want also use in Amazon checkout, all features implemented additionally on the Magento success page shall also appear on Amazon checkout success page.

The created order will be transferred to Amazon and will appear in your Magento admin in Pending state.

Payment authorization¶

An authorization can be requested after the order data is successfully transferred to Amazon. Depending on the value you’ve selected for Payment Action option it can be processed in several ways. For Authorize and Authorize & capture actions it will be requested automatically as soon as order is placed in your shop and successfully transferred to Amazon. The requested authorization will be therefore either confirmed or declined by Amazon either via IPN message or via data polling, see Synchronizing order data to get more details. The order, for which a payment authorization has been confirmed changes its state to Processing, an order email confirmation is sent to the customer (if not disabled in the extension settings, see Send order confirmation) and you can start the fulfilment process.

Manual authorization¶

In case you ship ordered items after 30 days or more you have to select Manual authorization as a payment action. It will stop Magento from requesting an authorization automatically and let you make an authorization request manually from the Magento admin at any suitable time. To manually invoke an authorization, login to the Magento admin, open the order you want authorize payment for and click the Authorize payment button placed in the top buttons rows.

Next post-request processing (authorization confirmation or decline) is processed in the same way as in automatic authorization (through polling or IPN).

Capturing the payment amount¶

After a successful authorization, you can capture funds against the authorization. The capture, similar to the authorization, can be requested in two modes: manual and automatic. By default you should capture the order amount at the moment you ship the ordered items by creating an invoice. You are only allowed to enable automatic capture if you sell digital goods or you ship items the same day they are ordered. Moreover you have to be white-listed by Amazon Payments. Contact Amazon Payments if you want to use this option.

Payment Action option in the extension settings allows to switch between manual and automatic capture mode. For Manual authorization & Authorization actions the capture is triggerd by creating manually an invoice for the order in the Magento admin. For Authorize & capture action, the capture is requested automatically as soon as authorization is confirmed by Amazon Payments.

Manual capture¶

To capture the order amount, you must create an invoice first. To create an invoice, login to the Magento 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 Payments.

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 Synchronizing order data for more details.

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 Magento 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 Magento 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.

Cancelling an order¶

For a variety of reasons it sometimes becomes necessary to cancel an order. To cancel an order and notify Amazon about the payment cancellation:

• Please make sure the amount of the order you want to cancel hasn’t been captured yet,
• Go to Sales ‣ Orders 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.

Synchronizing order data¶

How to create Sandbox test account¶

To use the sandbox environment, you need to create specific test accounts for the sandbox environment.

• Login into Seller Central.
• Choose the menu Integration ‣ Test accounts.

• Click on Create a new test account.

• Fill in the form using a valid email address. The account can be used immediately after the account creation.

• Add other delivery addresses to the test account (optional).

Installation¶

I have successfully installed Login and Pay with Amazon extension, but when I try to go to the configuration page System ‣ Configuration ‣ Amazon Payments I am getting: 404 Not Found error.

It’s a Magento bug, the ACL list is not reloaded after the new extension is installed. To solve this issue please logout from the Magento admin and next login again.

It is stated that the extension is compatible with Magento 1.5, but when I try to place an order I am getting an exception: Invalid method Mage_Sales_Model_Order_Payment::lookupTransaction().

Magento 1.5 doesn’t provide public wrapper for _lookupTransaction() method of order payment model, which is commonly used by Pay with Amazon extension. To fix this issue we have prepared a compatibility pack that rewrites current sales/order_payment model. You can install it via Magento Connect, to do so go to System ‣ Magento Connect ‣ Magento Connect Manager, enter your admin credentials to get logged in, in the Install New Extensions section enter http://connect20.creativetest.de/Creativestyle_AmazonPaymentsCompatibilityPack key and click Install button.

Frontend¶

How can I disable Pay with Amazon for certain products?

There are few extensions available for disabling payment methods on-the-fly based on the desired conditions. We recommend to install and use Rico Neitzel’s PaymentFilter for Products and Customer Groups, which Pay with Amazon has been successfully tested against.

Pay with Amazon button doesn’t show up in the cart after the extension is installed and set up.

Lack of Pay with Amazon button in the cart is usually caused by one of the following reasons:

• incorrect Merchant ID set (double check if you don’t have any whitespaces in your Merchant ID),
• incorrect Marketplace set,
• your Amazon seller account is either blocked or not activated (you can check status of your account in Amazon Seller Central).

You can check validity of the provided Amazon Payments credentials using Validate Amazon Payments account button available in the extension settings. In case you are sure you have Merchant ID and Marketplace correctly set, check if any of the following extensions is installed and enabled in your shop and follow the instructions:

• Mxperts_NoRegion
• FME_Ajaxaddtocart

Those extensions replace default checkout.cart block with own ones. The replaced block doesn’t include checkout buttons defined previously. To bring the Pay with Amazon button back, find appropriate layout file:

• noregion.xml for Mxperts_NoRegion extension,
• ajaxaddtocart.xml for FME_Ajaxaddtocart extension

in your theme folder (or in the default theme folder) and modify checkout.cart.methods and / or checkout.cart.top_methods blocks by adding following code:

<block name="checkout.cart.methods" as="methods" type="core/text_list" translate="label">
    (...)
    <block type="amazonpayments/pay_button" name="checkout.cart.methods.amazonpayments_pay.bottom" before="-">
        <action method="setIdSuffix"><value>div</value></action>
        <action method="setEnableOr"><value>1</value></action>
    </block>
</block>
(...)
<block name="checkout.cart.top_methods" as="top_methods" type="core/text_list" translate="label">
    (...)
    <block type="amazonpayments/pay_button" name="checkout.cart.methods.amazonpayments_pay.top" before="-">
        <action method="setIdSuffix"><value>top</value></action>
        <action method="setEnableOr"><value>1</value></action>
    </block>
</block>

Event logs¶

The Pay with Amazon extension provides a convenient logging system. It is disabled by default, but you can enable it in the extension settings, refer to the Enable logging section for more details.

Contact support¶

In case neither studying the FAQ nor the event logs reviewing resulted in solving your issue you can submit a support ticket on http://creativeticket.de site.