Prerequisites

• A Recurly account.
• An Amazon Pay Seller account with https://api.recurly.com/ allow-listed in Amazon.
• A webhook endpoint configured in your Amazon Integration Settings — see Enabling IPN notifications / webhooks below.
• Integration requires Recurly.js or Hosted Payment Pages (HPP).
• Currently supported in the US; Europe and UK support coming soon.

Limitations

• Shipping addresses cannot be retrieved from Amazon in V2. Shipping address details must be provided to Recurly separately.
• The Amazon Pay V2 sandbox does not fully support testing 3DS flows.

Definition

Key details

Regional support

Recurly supports Amazon Pay in the US, as well as the UK and Europe. Within the UK and Europe, 3DS and multi-currency are supported through Recurly.js.

Europe

EUR, AUD, GBP, DKK, HKD, JPY, NZD, ZAR, SEK, CHF, and USD.

United Kingdom

GBP, EUR, AUD, DKK, HKD, JPY, NZD, ZAR, SEK, CHF, and USD.

Setup

Sign up for an Amazon Pay Seller account

To use Amazon Pay, you'll need an Amazon Pay Seller account. Signing up is free. If you already have one, log in to your existing account.

After signing up, follow Amazon's Getting Started Guide to complete your account configuration:

Enabling IPN notifications / webhooks

Set up your webhook endpoint in Amazon Seller Central before adding the gateway in Recurly.

https://callbacks.recurly.com/amazon_v2/YOUR_MERCHANT_SUBDOMAIN

Add the gateway in Recurly

Amazon Pay V2 uses a redirect-based authorization flow to securely obtain processing credentials.

Integration

Once your Amazon Pay account is configured and your Recurly site is set up, integrate Recurly.js into your subscription checkout flow.

Amazon Pay V2 is built into Recurly.js. Interactions follow the standard Recurly.js flow, with the initial Amazon login as the only step that takes customers off your site. After login, customers confirm their payment details and a Charge Permission ID is returned to Recurly and tokenized via Recurly.js. That token is then passed to Recurly's create subscription API as the account's billing information.

For detailed implementation steps, see the Amazon Pay V2 Recurly.js documentation.

Setting the Amazon Pay region

For EU and UK transactions, you must specify a region code in your Recurly.js request (options.region). If you omit the region, transactions default to US settings — including USD as the currency — which causes declines on one-time transactions, initial subscriptions, and renewals. See the Amazon Pay V2 Recurly.js documentation for implementation details.

Handling 3DS and PSD2 (UK and EU)

UK and EU merchants must incorporate 3DS into their checkout flow to comply with Strong Customer Authentication (SCA) and PSD2 requirements. Amazon Pay V2 uses standard Recurly.js 3DS behaviors. If you're already handling this in your Recurly.js setup, no changes are needed. If not, see the 3DS behaviors in Recurly.js documentation.

Handling shipping addresses

Amazon Pay V2 does not currently support retrieving shipping addresses from Amazon. For transactions involving physical shipments, prompt customers to enter their shipping address separately before completing checkout.

Merchant and buyer data

Recurly sends the following additional data to Amazon on subscriptions and transactions:

• Merchant DBA as Seller Store Name
• Transaction description as Buyer Notes — the plan name for subscriptions, or the invoice/item description for one-time charges

Subscription management

When a customer checks out with Amazon Pay, they authenticate with their Amazon credentials and confirm their payment details, granting a Charge Permission ID for the subscription. Recurly stores this ID along with relevant Amazon account details and uses it automatically for subsequent renewals.

Customers and merchants can both update billing information:

• Amazon — Customers can update or cancel their Charge Permission ID directly from their Amazon account.
• Recurly — Use the update billing info API to apply a new Amazon Charge Permission ID or switch to a different payment method. Customers must re-authenticate through Amazon to update billing via Recurly.js.

Amazon references in Recurly admin

In the Recurly Admin panel under Billing Info on an Account Details page, you can view Amazon Pay transaction details for customer service and reporting, including:

• Charge Permission ID
• Capture Amount
• Transaction Status (at Amazon)
• Creation, updated, and expiration timestamps
• Charge ID
• Currency code
• Capture Now indicator

Testing your implementation

To test transactions, use a secondary Amazon account — transactions cannot be processed through your own Seller Central account.

Migrating from Amazon Pay V1

Amazon Pay V1 used external widgets, a separate library, and Billing Agreement IDs. V2 integrates directly into Recurly.js — no external library or widgets are needed, and Billing Agreement IDs are replaced by Charge Permission IDs.

For a full migration guide, see the Amazon Pay V2 Recurly.js documentation.

Existing V1 subscriptions can transition to V2 automatically when the V2 gateway is activated, unless a specific gateway code was assigned — in that case, a script update is required after activation. HPP one-time and initial subscription transactions switch to V2 automatically once V2 is enabled.

FAQs