Hosted payment pages

Merchants can start subscribing their users with a minimal effort using Recurly Hosted Payment Pages. Combined with Account Management Pages, your entire user experience can be handled in a PCI compliant, easy-to-use interface.

Look and Feel

Hosted Payment Pages can be configured with your company logo (PNG, JPG, or GIF; 256 KB maximum) and a custom accent color.

We also offer two different styles of Hosted Payment Pages: Classic and Modern. The Modern style offers a progressive-reveal payment page that is better optimized for mobile screens and offers the ability to (optionally) capture a Shipping Address when processing payment. Merchants may select either style and can update their customizations at any time via the Hosted Page Settings page.

For more advanced configuration options, please look at Recurly.js, which offers fully customizable checkout forms that are hosted on your own site.

Site Subdomain

Your customers access their accounts through This subdomain can be changed at anytime by contacting our Support team and is visible within your Site Settings page. You will need to log out and log back in to see the changed subdomain.

Accessing Hosted Payment Pages

Each subscription plan has its own Hosted Payment Page. You can access the hosted page for each plan at (where :your_subdomain is your Recurly site and :plan_code the unique identifier created for this subscription plan).


To protect Merchants from malicious bots that may attack your site, we’ve implemented reCAPTCHA (Completely Automated Public Turing test to tell Computers and Humans Apart) on all Hosted Payment Pages.

reCAPTCHA is a CAPTCHA-like system designed to establish that a computer user is human. The reCAPTCHA service supplies subscribing websites with images of words that are hard to read for optical character recognition (OCR) software. The subscribing websites present these images for humans to decipher as CAPTCHA words, as part of their normal validation procedures. They then return the results to the reCAPTCHA service, which validates the entry.

CAPTCHA is enabled by default on the Hosted Payment Pages. Accounts (Customers) will be presented and required to verify the distorted text after 3 failed transactions from using the same IP address within a rolling 24 hour period and will be prompted again for any subsequent failed transactions.


While a site is in Sandbox mode, merchants can use Recurly's test gateway with a series of test credit card numbers to walk through the subscription signup process and work with test accounts. Please see our Test Gateway documentation for more information on the credit card types available.

Signup Basics

At a minimum, you will need to collect a customer's name, email address, and billing information. You can adjust your address requirements in your Site Settings configuration.

Beyond the basic required fields, you may update your hosted pages to request the following additional data from your users:

  • Company Name
  • Phone Number
  • VAT Number
  • Editable Quantities
  • Coupon Codes
  • Gift Card Redemption Code
  • Shipping Address (Modern style only)

Advanced Signup

Your hosted page URL can be configured to automatically pass a number of variables into the form:

Default Plan Quantity

If you want to set the default Plan quantity for a subscription, you may append a "quantity" parameter to the URL. For example, use the following URL to set the quantity to 5 for a plan with plan code "gold":

Default Quantity for Add-ons and Items

If you want to set the default quantity for an add-on or item associated with the plan, you may append an "add_on_code" and "add_on_quantity" parameter to the URL. For example, use the following URL for the gold plan to set the quantity of "seats" to 3 and "support" to 2.,support&add_on_quantity=3,2

Account Code & Username

If you are directing the user from your web application, you should customize the URL to submit the account code and optionally the username. The hosted payment page parameters are:

The account code should be a URL-encoded version of the unique ID you use to identify an account. This might be an auto-incrementing ID, a GUID, their email address, etc. The username optionally identifies the user. The username might be their online handle or email address. Usually the username is the username or email address required for the user to log into your application.

Account codes are unique within your Recurly account; usernames are not.

If you do not specify an account code, the user's email address will be used as the account code. If you do not specify a username, it will be left blank.

If you do specify an account code for which there is already an existing account and that account has an email address defined, that existing email address will not be changed.

Note: If you include an account code and email, first, or last name, you must pass this value in the following format:

First Name, Last Name & Email

You may also pre-populate the subscription form by passing first_name, last_name, and email parameters in the URL. Here's an example:

Payment Method Ordering

If you would like to display your payment methods a specific order, you may do so using the payment_methods URL parameter. This parameter is structured as an array. For example:[]=ach&payment_methods[]=credit_card

Your payment page will display available payment methods in this order first. If there are more payment methods available that aren't specified in this parameter, then the remaining payment methods will proceed in their default order.

Possible values, in their default order, are credit_card, ach, sepa, paypal, and amazon.


The Success Redirect URL is the URL the user will be redirected to upon successful completion of the signup process and is configured on the subscription plan. Recurly will display a confirmation page that automatically directs the customer to your success URL.

Optionally, Recurly can return the plan code and account code in the URL. If you rely on these parameters, be sure to use the API to verify the new plan code to prevent URL tampering. Here's an example return URL:{{account_code}}&plan={{plan_code}}

Both {{account_code}} and {{plan_code}} will be replaced with the new subscriber's account code and plan code, respectively.

Google Analytics

Recurly offers a Google Analytics integration that allows you to track funnel conversions through your hosted payment pages. A page hit is recorded with each visit to your hosted payment page, and another page hit is recorded if the customer subscribes and reaches your confirmation page.

To configure Google Analytics in Recurly, visit and enter your Google Analytics tracking code in the "Google Analytics" section.

Within Google Analytics, we recommend creating a custom goal (see for instructions) by adding the appropriate confirmation page URL (ie; the URL your customers are directed to after subscribing). This will communicate to Google Analytics that the goal (subscribing/checkout) has been completed.

Please note:

  1. The subscription will be associated with, there is no cross domain tracking.

  2. Our Google Analytics integration does not track information around recurring payments. Only visits to your hosted payment pages and completed checkouts.


If you accept multiple currencies, the hosted payment pages will default to the most appropriate currency for your customer, based on their country. The customer's country is determined with an automatic geo-IP address lookup. The customer may select a different currency before completing the order. If the most appropriate currency is not available, we will use your default currency.

Internationalized Hosted Payment Pages

Hosted Payment Pages are available in fourteen different languages. Languages are displayed to your customers based on their Internet browser's language preferences. The supported languages are:

  1. English
  2. Danish
  3. German
  4. Spanish
  5. French
  6. Hindi
  7. Japanese
  8. Dutch
  9. Portuguese
  10. Russian
  11. Turkish
  12. Chinese
  13. Swedish
  14. Polish