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).


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:

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.

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