Developer HubSupportContactRecurly.comRequest a Demo

Amazon Pay (US, EU, UK)

Recurly supports Amazon Pay in the United States, Europe region and the United Kingdom.

Suggest Edits

Recurly offers more ways for your customer to transact, with trust and convenience of Amazon Pay. Amazon Pay makes it simple for hundreds of millions of Amazon customers to subscribe to your plans using information already stored in their Amazon account, without ever leaving your site. Recurly makes getting started quick and easy with your Recurly site.

NEW! Recurly now supports Amazon Pay in Europe and the United Kingdom. Learn more.

Note: Recurly's Amazon Pay integration does not currently support 3DS or PSD2.

650

Sign Up for Amazon

You will first need to sign up for an Amazon Pay account. You can sign up free online. If you already have an Amazon Pay account, you can simply login.

Once you sign up, you'll follow Amazon's Getting Started Guide that will walk you through completing your account configuration.

  1. Amazon Client ID - Set up your Amazon application that authenticates Amazon users on your site.
  2. API Access - Allows API calls to Amazon Marketplace Web Service (MWS) through Recurly using your MWS Access Keys.
  3. Integration - You'll want to use our library to help with your integration, which is explained below. API documentation from Amazon is also available.
  4. Subdomain - Add your Recurly subdomain to your Amazon allowed javascript origins. Read more about adding a website to an Amazon security profile.
  5. Testing - Validation of your Amazon Pay integration.
  6. Go Live - Once your testing is complete and you're ready to go live, you can switch your Amazon Pay account to Production.
2306

Setup in Recurly

After signing up for your Amazon Pay account, you can enable your Recurly site to accept Amazon Pay for recurring subscriptions.

To enable Amazon Pay for your Recurly site, follow the steps below:

  1. Log in to your Recurly account.
  2. Select the Payment Gateways section in the left-hand navigation.
  3. Select Amazon Pay from the list of payment service providers (Amazon Pay is currently only available in the US at this time).
  4. Have your Amazon MWS Access Key, Secret Access Key and Merchant ID (or "Seller ID") ready and enter
    those values on the form. See above image for assistance.
  5. Determine whether you want Recurly to set the Amazon address as your customer's Account Info. (An additional sub-option will override any existing address already saved for the Account Info if you choose to enable it.)
  6. Click Save Changes.
  7. Before proceeding test the connection by clicking the Test Configuration button. For Hosted Payment Pages, an Amazon Client ID is required and your Recurly subdomain must be added to Amazon's Security Profile.

Note: Sandbox Recurly accounts use Amazon Pay sandbox environment, so no transactions will be processed in sandbox. Amazon Pay credentials work in both Recurly sandbox and production accounts. When you’re ready to process live transactions just add your Amazon Pay credentials in your production Recurly account OR take your Recurly account into production mode.

1652

Amazon Instant Payment Notification Messages (IPN)

Recurly has enabled the use of Amazon Pay IPNs to notify you if a payment has been refunded successfully. Follow these steps to take advantage of this feature and start receiving updates regarding refunds. Once enabled, Recurly will receive the necessary information to update the refund transaction status.

When entering your Merchant URL within Amazon, enter the value:
https://callbacks.recurly.com/amazon/<MERCHANT_SUBDOMAIN>

📘

Note: If your Recurly site is hosted in our European Union (EU) data centers you will need to use https://callbacks.eu.recurly.com/amazon/<MERCHANT_SUBDOMAIN> instead of the above.

Integration

After setting up your Amazon Pay accounts and configuring your Recurly site, you're ready to add the Amazon Pay library to subscription checkout integration.

650

Recurly provides a free JavaScript plug-in library making it easy to add Amazon Pay into your flow. The interactions take place in in-line widgets that can be configured based on simple options. The only experience outside of your site is the initial Amazon login. After the customer logs in, they're directed back to your site to confirm the address and payment method in the Amazon widgets.

600

Simply include the JavaScript below in the document <head>.

<script src="pay-with-amazon.min.js"></script>

Also in the document <head>, invoke PayWithAmazon with your configuration.

var payWithAmazon = new PayWithAmazon({
    sellerId: 'ABC',
    clientId: 'XYZ',
    button: { id: 'pay-with-amazon', [type], [color] },
    addressBook: { id: 'address-book', [width], [height] },
    wallet: { id: 'wallet', [width], [height] },
    consent: { id: 'consent', [width], [height] }
    region: 'eu' // Possible values are 'eu' or 'uk'
});
  • Region is required to set the region as EU or UK. US is not required as it is the default region if no region is specified.

Then once the customer confirms their Amazon payment info to use for the subscription, the Amazon Billing Agreement ID (id) will be returned and can then be used with Recurly's create subscription API as the account's billing info.

Although Recurly.js is not required for integrating Amazon Pay with your Recurly account, Recurly.js offers many features such as pulling your plan and add-on information and a pricing module for previewing a purchase that enhance your checkout experience. Using Amazon Pay alongside Recurly.js v4 is recommended. 

<?xml version="1.0" encoding="UTF-8"?>
<subscription>
    <plan_code>gold</plan_code>
    <currency>USD</currency>
    <account>
        <account_code>customer</account_code>
        <billing_info>
            <amazon_billing_agreement_id>abc-xyz</amazon_billing_agreement_id>
            <first_name>John</first_name>
            <last_name>Doe</last_name>
        </billing_info>
    </account>
</subscription>

Case 1: Standard Subscription

This is a basic example of the standard settings for the Amazon Pay widgets. This would display the Amazon address, payment and consent widgets.

var payWithAmazon = new PayWithAmazon({
    sellerId: 'ABC',
    clientId: 'XYZ',
    button: { id: 'pay-with-amazon', type: 'large', color: 'DarkGray' },
    addressBook: { id: 'address-book', width: 400, height: 260 },
    wallet: { id: 'wallet', width: 400, height: 260 },
    consent: { id: 'consent', width: 400, height: 140 }
});

Case 2: No Address Widget

You may want to streamline your checkout experience if you are selling only digital goods and do not require an account address. In this case, you can remove the Amazon address widget.

var payWithAmazon = new PayWithAmazon({
    sellerId: 'ABC',
    clientId: 'XYZ',
    button: { id: 'pay-with-amazon', type: 'large', color: 'DarkGray' },
    wallet: { id: 'wallet', width: 400, height: 260 },
    consent: { id: 'consent', width: 400, height: 140 }
});

Check out the GitHub repository for more details on the usage and other available customization options.

Subscription Management

When adding Amazon Pay to your subscription checkout, your customer will first be prompted to log in using their Amazon credentials. After being authenticated, their securely stored address and payment information will be presented for them to confirm the billing agreement for the subscription plan.

Once the subscription is confirmed, the billing agreement (and relevant Amazon info) is stored for the customer with Recurly. On the following subscription renewal cycle, the same billing agreement consented to by your customer will be used to bill the subscription automatically.

600

Customers may modify their billing agreement (such as changing payment method or canceling) either from Amazon or through Recurly.

  • On the Amazon side, a customer can log into Amazon and update the payment method used for the billing agreement associated with the subscription plan. The customer can also cancel the billing agreement from their Amazon account.
  • On the Recurly side, you can update the billing info with a new Amazon Billing Agreement ID using this JS library as well as another payment method, like a credit card or PayPal. This can be done using the update billing info.
  • Recurly supports Amazon's CloseBillingAgreement API, see Amazon documentation. This API will notify Recurly when a user closes the billing agreement within Amazon, Recurly can be notified and clear out the billing agreement, since it is no longer valid. This is a recommended best practice from Amazon. This feature is behind a feature flag. Contact support to enable this feature.
    ** This action taken by the user will appear on the account page within the activity feed.

Amazon shipping address

When creating new subscriptions paid for by Amazon Pay, customers can enter a shipping address. Recurly can save that Amazon shipping address to the Recurly Account Address and/or the Recurly Shipping Address. You just have to select the appropriate gateway configurations:

853

If you select to have the Amazon address saved to the Recurly Shipping Address, then in addition to saving the address as a shipping address, we will also associate the shipping address with the new subscription so that the invoice is correctly using the shipping address to calculate taxes (if applicable) and the shipping address will appear on the invoice. Read more about shipping addresses.

If the Amazon address entered matches exactly an existing shipping address on the account in Recurly, we won't create a duplicate address. Rather, we will use the existing shipping address and associate it with the new subscription.

Handling Customer Names

Recurly currently requires both a first and last name to save a shipping address and/or submit a transaction. Amazon just requires a single name and may not contain a separate last name. If a first name and last name are entered by the customer, then Recurly will use the entered names. If not entered, Recurly will try to grab their first and last names from Amazon. If Amazon does not return a last name, then an error will occur. If this occurs, we recommend prompting the user to enter a first and last name.

Amazon References in Recurly Admin

In your Recurly Admin, you can reference Amazon Pay being used for an account under the Billing Info section on an Account Details page. There you can reference the Amazon Billing Agreement ID for any customer service scenarios.

700

Amazon Pay support in Europe and the United Kingdom.

Recurly supports transacting in the following regions/currencies:

  • Europe region via Euro
  • United Kingdom via Pounds

To integrate with Amazon Pay in Europe and the UK, there are a few differences specific to these integrations. To set up your account follow these steps outlined below noting the specific differences regarding credentials and setting the billing region.

Credentials: The Amazon Pay EU/UK integration uses the delegated auth model to sign transaction requests. Instead of using a merchant access key, secret key, and Seller/Merchant ID as Recurly does for Amazon Pay US to sign requests, Recurly now uses the Seller/Merchant ID and an MWS Auth token to sign the requests for EU/UK.

Sign Up for Amazon in EU/UK

You will first need to sign up for an Amazon Pay account. You can sign up for an EU or UK account. If you already have an Amazon Pay account, you can simply sign into your Amazon Pay account. After your account has been created, then:

  1. Go to “Settings” > “User Permissions”
  2. Select “Visit Manage Your Apps”
  3. Select “Authorise new developer”
  4. Enter the “Developer’s Name” and “Developer ID”
    a. “Developer’s Name”: can be any value
    b. “Developer ID”: obtain your Developer ID from your Amazon Representative
  5. Agree to the MWS terms of service

Adding the Gateway

The Amazon Pay EU / UK gateways are unique gateway integrations. Add each gateway following the steps outlined above, and use your new MWS auth token.

Setting the Amazon Pay Region

Region Code Merchants need to pass a specific region code with the Amazon Pay billing agreement for EU/UK transaction requests. Without setting the region on the billing info, Recurly would default these account currencies to USD. Furthermore, any subsequent one time transactions, initial subscription transactions, and subscription renewals via the Recurly API will result in possible declines as the transaction may not be routed to the desired Amazon Pay region. See the dev docs.

Additional Notes

  1. Amazon Pay billing agreements are only valid within the specific region that they were originally created. If you would like to switch regions for an end user, you will need to generate a new billing agreement in the updated region.

Updated over 1 year ago