The Reference Docs Developer Hub

Welcome to the Reference Docs developer hub. You'll find comprehensive guides and documentation to help you start working with Reference Docs as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Search results for "{{ search.query }}"

No results found for "{{search.query}}". Ask about it in support.

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 background color. 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 through 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 customer 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

Advanced Signup

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

Default Quantity

If you want to set the default quantity, 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":

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.

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:


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.

Internationalized Hosted Payment Pages

Hosted Payment Pages are available in twelve 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

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.