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    

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 offer two styles of Hosted Payment Pages; Classic and Modern. For more advanced configuration options, please look at Recurly.js, which offers fully customizable checkout forms that are hosted on your own site.

Selecting a Look and Feel

The style and other customizations of the Hosted Payment Page can be updated at anytime through your Hosted Page Settings page.

Classic vs. Modern

In April 2020, Recurly created a new style for the Hosted Payment Page, the Modern style. This progressive reveal payment page 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 at any time in Hosted Page Settings .

Site Subdomain

Your customers access their accounts through :your_subdomain.recurly.com. 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 :your_subdomain.recurly.com/subscribe/:plan_code (where :your_subdomain is your Recurly site and :plan_code the unique identifier created for this subscription plan).

Security

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.

Testing

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
  • 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 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":

https://:your_subdomain.recurly.com/subscribe/gold?quantity=5

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:

https://:your_subdomain.recurly.com/subscribe/:plan_code/:account_code/:username

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.

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

https://:your_subdomain.recurly.com/subscribe/:plan_code?account_code=:account_code&first_name=Verena&last_name=Example&email=verena%40example.com

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:

https://example.recurly.com/subscribe/gold?first_name=Verena&last_name=Example&email=verena%40example.com

Confirmation

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:

http://example.com/signup/success?account={{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 https://app.recurly.com/go/configuration/hosted_pages and enter your Google Analytics tracking code in the "Google Analytics" section.

Within Google Analytics, we recommend creating a custom goal (see https://support.google.com/analytics/answer/1032415?hl=en 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 subdomain.recurly.com, 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.

Multi-Currency

Hosted Payment Pages
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.

Verify this Editable Quantity setting in the Admin UI for the Hosted Pages to ensure it is setup consistently with your plans.

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

Updated 2 months ago

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.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.