Limitations

• Hosted Payment Pages don't support iframes due to PCI compliance and security requirements
• reCAPTCHA activates after three failed transaction attempts from the same IP address within a rolling 24-hour window

Definition

Key benefits

Key details

Look and feel

Personalize your Hosted Payment Pages with your brand. Choose between two design templates:

• Classic — A traditional, proven design that works everywhere.
• Modern — A responsive, mobile-optimized design with support for shipping address collection.
  To change your design, colors, or other styling, visit Hosted Page Settings in your Recurly account. For advanced customization beyond the UI settings, refer to the Recurly.js documentation.

Site subdomain

Your Hosted Payment Pages are served from a custom subdomain: :your_subdomain.recurly.com

Changing your subdomain requires all admins to sign in again for changes to take effect. To modify your subdomain, contact Recurly Support.

Accessing your pages

Each subscription plan has a unique Hosted Payment Page URL:

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

Replace :your_subdomain with your custom subdomain and :plan_code with your subscription plan's code.

Security with reCAPTCHA

Recurly uses reCAPTCHA to protect your pages from bot attacks and fraudulent activity. After three failed transaction attempts from the same IP address within a rolling 24-hour window, reCAPTCHA activates and presents customers with an "I'm not a robot" checkbox. Most legitimate users pass immediately. If reCAPTCHA can't confirm legitimacy, a distorted text challenge appears. Each additional failed attempt re-triggers the challenge.

Testing in Sandbox mode

Before going live, test your subscription flow in Sandbox mode using Recurly's test gateway and test credit card numbers. See the Test Gateway documentation for card numbers and test scenarios.

Collecting customer data

By default, Hosted Payment Pages collect first and last name, email address, billing address, and payment method. For advanced data collection — including company name, VAT number, and shipping address — use URL parameters to pre-populate fields or set defaults. See Advanced sign-up examples below.

Confirming sign-ups

After a successful subscription, redirect customers to a confirmation page. Pass the account and plan codes in the URL for clear confirmation details:

http://example.com/signup/success?account=ACCOUNT_CODE&plan=PLAN_CODE

Recurly automatically replaces ACCOUNT_CODE and PLAN_CODE with the new subscriber's values.

Google Analytics integration

Track your checkout funnel by connecting Google Analytics to your Hosted Payment Pages.

1. Go to Hosted Page Settings in Recurly.
2. Enter your Google Analytics tracking code.
3. Recurly automatically tracks visits and checkout conversions.

Multi-currency

Hosted Payment Pages automatically detect the customer's location and display the most appropriate currency. Customers can select a different currency before completing checkout.

To specify a currency manually, add a currency parameter to your URL:

https://:your_subdomain.recurly.com/subscribe/:plan_code?currency=EUR

If the specified currency isn't available, the account's default currency is displayed instead.

Language support

Hosted Payment Pages support 14 languages, detected automatically from the customer's browser settings: English, Danish, German, Spanish, French, Hindi, Japanese, Dutch, Portuguese, Russian, Turkish, Simplified Chinese, Swedish, and Polish.

Advanced sign-up examples

Use URL parameters to pre-populate fields, set defaults, and customize data collection without any additional integration work.

Set a default plan quantity

Pre-fill the quantity field for a plan using the quantity parameter:

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

Set default quantities for add-ons or items

Pre-fill quantities for add-ons or items using add_on_code and add_on_quantity parameters, separated by commas:

https://:your_subdomain.recurly.com/subscribe/gold?add_on_code=seats,support&add_on_quantity=3,2

This example sets "seats" to 3 and "support" to 2 for the gold plan.

Pass account code and username

When directing users from your application, include their account code and optionally their username:

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

• Account code — A URL-encoded unique identifier for the account (auto-incrementing ID, GUID, email, etc.). Required and must be unique in your Recurly account.
• Username — An optional identifier such as an online handle or email. Doesn't need to be unique.
  If no account code is specified, the customer's email address is used instead. If no username is specified, it remains blank. If the account code already exists and has an email on file, that email won't be overwritten.

Pre-populate name and email

Use first_name, last_name, and email parameters to pre-fill the sign-up form:

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

When including an account code with name and email:

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

Specify payment method order

Control the order payment methods appear using the payment_methods parameter:

https://example.recurly.com/subscribe/:plan_code?payment_methods[]=ach&payment_methods[]=credit_card

Methods are displayed in the order specified. Any additional payment methods available on your account follow in their default order. Available values (in default order): credit_card, ach, sepa, paypal, amazon.

Pre-populate a coupon code

Add a coupon code to the URL so it's pre-entered when customers land on your page:

https://example.recurly.com/subscribe/:plan_code?subscription[coupon_code]=10off

Configure Hosted Payment Pages

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

FAQs