Initial Setup

This integration requires Aurora Commerce to setup the Amazon Pay Aurora Service for each site and each environment it is required. This is done via a request to your Account Manager, and they will require the following information:

• The url of the site to use the integration.

NOTE: A full Aurora update may also be required, this will depend on when the site in question last had a full Aurora update.

📘

The information in this document contains settings required for the Amazon Pay integration to function, there may be other settings and procedures required by Amazon for you to complete before your store can go live.

Aurora Backend Settings

Store > Settings > Payment Providers

This configuration controls whether Amazon Pay will be accepted as a payment type.

Store > Settings > Feeds > Microservice > Proxy Amazonpay

This configuration controls the visibility of the Amazon Pay Checkout:

Microservice Settings (Store > Microservice > Proxy Amazonpay)

This configuration controls the settings of the Amazon Pay service used by Aurora

Amazon Seller Central Setup

Login to your Amazon Seller Central account: https://sellercentral-europe.amazon.com/)

• Goto "Login with Amazon" (top menu)
• Update the following settings for Aurora:

Frontend Template Integration

Assets and Templates

A list of the templates and assets used in this integration and should be added to your site templates; see below sections for details on each asset/template.

Aurora Amazon Pay Javascript Library

Template Dependencies:

User Error Messages

Error messages are editable in Aurora Backend > Content > Site Text

Aurora Service Errors

User error messages from the Aurora payment service that can be translated, a default translation for "en" is provided.

Amazon Pay Errors

User error messages from the Amazon API that can be translated, a default translation for "en" is provided. See https://pay.amazon.com/es/developer/documentation/apireference/201753060 for further details.

New error types can be added using the "Part" format of "CheckoutPayment proxy-amazonpay Error: {ERROR_TYPE}".

Payment Error After Amazon Order Confirmed 

📘

Note most errors are handled via the above site text. If an error occurs after an order has been confirmed but the payment failed, only the payment widget will be shown to allow the customer to resolve the payment issue on the confirmed order. In this scenario the user may not change anything about the the order apart from the method of payment.

See screenshot below:

Implementation Note:

The error is triggered from the Aurora Amazon Javascript library (templates/example.com/_js/amazonpay.js) and calls "amazon_pay_config.addressbook_hide_callback". The default template "templates/example.com/checkout/external/amazon-setup.tpl.html" handles this by displaying the following html:

Default Error messages provide by Amazon

The following error messages are provided by Amazon for use when translating some of the standard error messages. The UK messages are already pre-populated into Aurora, you will need to add the other translations as needed for your site.

UK - English

IT - Italian

 DE - German

 ES - Spanish

FR - French

Modifications from default:

Basket Page - templates/example.com/basket/index.tpl.html

You may already have an existing basket template. To add the Amazon Pay checkout button, do the following modifications:

• Add the Aurora Amazon Pay javascript library:

{include file="\_includes/header.tpl.html" page\_js\_template="basket-paypal-credit,**amazonpay,amazonpay-ui**"}

OR if you load js libraries in the footer:

{include file="\_includes/footer.tpl.html" page\_js\_template="basket-paypal-credit,**amazonpay,amazonpay-ui**"}

This is relying on your "_includes/header.tpl.html" or "_includes/footer.tpl.html" including the the js libraries in the following manner:

{include\_js files="$page\_js\_template"}  

• Add the Amazon Pay checkout button:

{include file="basket/amazon-pay-button.tpl.html"}

Configuration

templates/example.com/checkout/external/amazon-config.tpl.html

You may wish to alter the default frontend configuration template:

<script language="javascript" type="text/javascript">
{literal}
var amazon_pay_config = amazon_pay_config || {}; 
{/literal}
amazon_pay_config.checkout_type = 'proxy-amazonpay';
amazon_pay_config.logging = false;
amazon_pay_config.currency = '{$currency_iso_chargeable}';
amazon_pay_config.language = '{$language_iso_selected}';
amazon_pay_config.url_prefix = '{if $language_iso}/{$language_iso}{/if}';
//see https://pay.amazon.com/uk/developer/documentation/lpwa/201952050
amazon_pay_config.button_type = 'PwA';
amazon_pay_config.button_size = 'medium';
amazon_pay_config.button_color = 'Gold';
amazon_pay_config.popup = true;
amazon_pay_config.msg_select_payment = 'Please select a payment method';
amazon_pay_config.msg_session_expired = 'Your session has expired. Please sign in again by clicking on the Amazon Pay Button.';
</script>

Events

Amazon Frontend Design Resources

• https://pay.amazon.com/uk/merchant
• https://pay.amazon.com/uk/merchant/tools
• https://login.amazon.com/

Amazon Sandbox Testing

Test User Accounts

These are created by accessing your account on https://sellercentral-europe.amazon.com/ > "Amazon Pay (Sandbox View)" > "Test Your Integration" > "create test buyer accounts"

Test Cards

The Amazon payment widget has various test cards for error scenarios: https://developer.amazon.com/docs/eu/amazon-pay-onetime/sample-addresses-and-payment-instruments.html

At time of writing, not documented on the above link are additional payment instruments for Secure Customer Authentication:

The following payment methods only work correctly with SCA turned on, if it is not turned on then all cards trigger the user to be redirected to the checkout with a generic error to change the payment option. Choosing a different card will then allow the user to complete the order.

Test Parameters

Amazon allow setting of testing parameters for scenario simulations, see https://developer.amazon.com/docs/eu/amazon-pay-onetime/sandbox-simulations.html

To use the test scenarios requires updating the Microservice settings "Debug 1 Name" and "Debug 1 Value" see table below for examples:

🚧

These settings apply to all sandbox payments made and so they should be removed immediately after use to avoid confusion on site testing, especially if a shared testing environment.

Troubleshooting

Customer Login Error

If you see the following after customer login:

Then you need to whitelist the website URL.

Place Order button does not allow the checkout form to submit

Note that a loading element with nested content is required to be present and hidden (display:none) in the checkout page to allow control of the checkout form submission.

The following element is an example from "templates/example.com/checkout/external/amazon-setup.tpl.html" (the definition of the class "checkout_loading_graphic" is in "templates/example.com/_css/checkout.css":

<div class="checkout_loading_graphic" ><img src="/templates/{$templates_dir}/_images/backgrounds/loading.gif" alt="" /></div>

Encountering  "Please supply a valid telephone number. It can only contain digits, hyphens or spaces." error after clicking "place order" Error after trying to place order

This error was due to the the phone number in the users' address not matching Aurora's validation requirements. Some possible options to resolve this issue:

• Review the test account used and whether the phone number format used is something that real users would use and needs to be supported.
• Override/customise the Aurora default phone validation see Aurora Backend > Store > Validation 
• Update the error message used to ask the user to create or amend their Amazon address via the Amazon widget/account management (this is not a simple/good user experience).