Amazon Pay

Before you begin

Which integration to use

Amazon Pay Checkout V2 is the current integration and the one to connect. The original Amazon Pay integration has been deprecated since December 2023 — it still runs for merchants already using it, but it is closed to new connections, and Amazon has said Checkout v1 is supported only through 2026. If your store is still on the older integration, move to Checkout V2.

Accepting donations, or selling alcohol, tobacco or higher-risk products?

Check that what you sell meets Amazon's acceptable use policy before you start. Amazon does not allow donations, alcohol or tobacco products, among other restrictions. If you are unsure whether your business type is supported, ask Amazon Pay support.

Check with Amazon about your sales velocity

Some merchants hit errors accepting payments for larger amounts, because of Amazon's sales velocity limits. This is outside Foxy's control, but it is worth raising with Amazon if you take large orders or expect a spike.

Per-customer billing limits

Amazon limits the monthly charges a new seller can make against a customer's stored payment details. See Amazon's policy for the limits and how to request an increase.

How to set it up

Checkout V2 is connected through Amazon rather than by pasting credentials in by hand.

1. 1

   Sign in to the legacy Foxy admin at admin.foxycart.com and open the payments page. Amazon Pay is connected from the legacy admin, not from admin.foxy.io.

2. 2

   If your store has multiple payment sets, make sure the correct one is active.

3. 3

   Tick Accept payments using your Amazon Pay Checkout V2 account.

4. 4

   Click Connect to Amazon Pay. You are sent to Amazon to sign in or register.

5. 5

   Sign in as the primary account holder on the Amazon Pay account.

6. 6

   Work through Amazon's flow to the end. Amazon returns you to the Foxy admin with your Merchant ID, Client ID and MWS Auth Token filled in automatically.

7. 7

   Save.

Amazon's flow looks like new-account onboarding even when your Amazon Pay account already exists. That is expected. Leaving it early to look for a dashboard cancels the connection and nothing is sent back to Foxy.

If the Connect button will not accept your account

Click Enter Manually and supply the same three values from Seller Central: Merchant ID, Client ID and MWS Auth Token. Manual entry produces exactly the same connection the Connect button does — it is a supported fallback, not a workaround.

Worth checking before you retry:

• You are signing in as the primary account holder rather than a user account created under Seller Central. User accounts often cannot authorise a third-party connection.

• Amazon Pay itself is registered and approved on the account. A Seller Central account on its own is not enough; the two are registered separately.

• The account is a US account.

Allowlist your checkout domain

1. 1

   Sign in to Seller Central.

2. 2

   Select Login with Amazon from the drop-down at the top of the page.

3. 3

   Select your store under Applications on the left.

4. 4

   Under Web Settings, click Edit.

5. 5

   Add your Foxy checkout domain to Allowed JavaScript Origins. If your checkout is at https://yourstore.foxycart.com/checkout, the value is https://yourstore.foxycart.com/.

6. 6

   Add each domain the site uses by clicking Add Another.

Set up instant payment notifications

Instant payment notifications (IPN) let Foxy know about delayed payment status changes at Amazon.

1. 1

   Sign in to Seller Central.

2. 2

   Go to Integration Settings under the Settings menu.

3. 3

   Make sure you are on your production account, not sandbox. On sandbox you will see "Sandbox" in the upper left, under the Amazon logo.

4. 4

   For Integrator URL, enter https://YOUR-STORE-DOMAIN/ipn.php. If your store domain is mystore.foxycart.com, the URL is https://mystore.foxycart.com/ipn.php. If you use a custom SSL subdomain such as secure.mystore.com, it is https://secure.mystore.com/ipn.php.

Testing

When you first open the sandbox environment through Seller Central, Amazon recommends setting up test buyer accounts. These can be adjusted to cover most cases, including shipping addresses that break one of your own business rules. Configure them in Seller Central under the Integration tab, then Test Accounts.

Troubleshooting

About the MWS Auth Token field

Amazon retired the Marketplace Web Service (MWS) API, so a field labelled "MWS Auth Token" on a current integration looks wrong, and Amazon support may tell you those tokens no longer work. The field is still correct here. Amazon Pay's current API uses a token in the same MWS format for a different purpose — solution provider delegated access, which is what authorises Foxy to act on your Amazon Pay account's behalf. It is not left over from the retired API.

"We're sorry" error

If you get an error in the popup after entering your credentials, click Show Details. You will usually see:

Error Summary
400 Bad Request
The domain on which you are using the JavaScript SDK has not been whitelisted for your application.

Your Login with Amazon configuration does not match your domain. Follow the allowlisting steps above and make sure the value in Allowed JavaScript Origins matches the secure URL the Amazon Pay button appears on. If the button was clicked from https://yourstore.foxycart.com/cart, the value should be https://yourstore.foxycart.com.

Suspended merchant agreements

If a subscription has been suspended because a payment method was declined, the customer needs to update their payment details in their Amazon Pay account. Send them to Amazon's instructions for bringing the agreement back to an open state.

Notes

Subscriptions migrate on their own. Existing Amazon Pay subscriptions move to Checkout V2 automatically once V2 is connected. They keep the same billing agreement, you do not need to recreate them, and your customers are not asked to re-authorise anything.

Transaction status. An Amazon Pay transaction may not process instantly, so at the time the initial transaction is processed Foxy does not yet know whether it was approved. Transactions are recorded as pending and updated when Amazon confirms the result. Each status change sends a datafeed to your endpoint, if configured, with a status node containing pending, approved or rejected.