Hosted Account Management

Customer Access

Hosted Account Management has two settings, "Account Login" and "Guest View Only". This determines whether your customers can create logins and access the full portal or only see specific hosted invoices. Hosted Account Management is set to Guest View Only by default.

Account Login

Account Login will turn on the full Hosted Account Management portal for your customers. Once logged in, customers can view and manage their subscriptions, invoices, and billing information.

• Your Vanity URL will show a customer login page that includes a section to create an account.
• Customers can create an account and login using the email address that is their Account Info email address in your Recurly admin.
• There is a secret unique Hosted Account Management Login Token URL for each customer found under Edit Account in your Recurly admin. This link will automatically log in anyone with the link as the customer and should be protected such that only the customer has access to it. If the secret unique URL is exposed publicly, Recurly may revoke the secret token and issue a new one.

Your Recurly emails can be customized with the account_hosted_maintenance_url parameter. This places the Hosted Account Management Login Token URL in the email that the user can click on to enter their account directly. For more information on how modifying email templates works (and the available parameters) please visit our Email Templates documentation.

Guest View Only

Guest View Only leverages Hosted Account Management to provide a limited view of customer information without requiring the customer to login or have knowledge of a full account. Guest View exists for hosted invoice pages and the hosted billing info page.

Guest View

Guest View is a limited view of Hosted Account Management pages that can be used with both "Account Login" and "Guest View Only". Guest View allows merchants to provide a hosted version of a customer's invoice in an email message or a hosted billing information page for the customer to update their payment information. If "Account Login" is enabled, the customer will see the options to Login or Create an Account in the top right of the page.

Hosted Invoice Links

If Hosted Account Management is enabled, all Recurly email templates that mention a specific invoice include a secret unique link to the hosted version of the invoice. On the hosted invoice page, customers can download a PDF of their invoice.

Hosted Invoice Email Templates:

• New Subscription
• New Invoice - seen by sites with manual invoicing turned on
• Invoice Past Due - seen by sites with manual invoicing turned on
• Payment Confirmed
• Payment Declined
• Payment Refunded
• Payment Voided

Merchants can find the secret unique hosted invoice link for a specific invoice on the invoice page in their Recurly admin.

URL Structure: :your_subdomain.recurly.com/account/invoices/:invoice_number?ht=:hosted_login_token
(You can find the Hosted Token on the Edit Account page for the customer.)

❗️

Security Note

Keep this token and URL secret as it allows anyone to log in as the customer.

Hosted Billing Information

In the case where a customer needs to update their billing information and the merchant does not want to provide login access to Hosted Account Management, the merchant can turn on "Guest View Only" and provide the customer with a secret unique Guest View "Edit Billing Info" url. Merchants can find this url on the Edit Account page in their admin.

URL Structure: :your_subdomain.recurly.com/account/billing_info/edit?ht=:hosted_login_token
(You can find the Hosted Token on the Edit Account page for the customer. Keep this token secret as it allows anyone to log in as the customer.)

Customer Options

If Hosted Account Management is set to Account Login, merchants can turn on two additional options for their customers to access: cancel subscriptions and update their account email address.

Cancel subscriptions

This setting reveals a "Cancel" button to customers on all subscriptions in the Hosted Account Management portal. When customers cancel a subscription using this button, their subscription will be canceled but remain active until the end of their subscription term. Subscriptions that are currently paused, will be terminated immediately if canceled.

Update account email address

This setting reveals the option to "Edit Email" in the account dropdown a customer sees while logged into the portal. If the customer changes their email, it will update the Account Info email address in your Recurly admin.

Online Payments

Merchants on Recurly's Professional or Enterprise plan can use a feature called "Online Payments". Online Payments allows customers to pay for manual invoices with a credit card, PayPal, Amazon account, or ACH. Leveraging Hosted Account Management, Online Payments adds a "Make a Payment" button to the hosted invoice page. This payment button is visible in Guest View mode, as well as Account Login mode.

Recurly's email templates were recently updated to include a Guest View hosted invoice link when Hosted Account Management is enabled. Check to make sure you are using the latest version of your email templates. With this update, customers will see a link in their emails prompting them to view their invoice online. With "Online Payments" for manual invoices, this link will prompt them to "Pay your invoice online". Once on the hosted invoice page, they will see the "Make a Payment" button and can pay for the manual invoice with a credit card or PayPal account.

If the invoice includes a recurring subscription, the customer will see a checkbox to opt-in to using this payment method automatically for renewal payments. If they opt-in, the next invoice will not be manual and will bill the credit card or PayPal account automatically. If the customer does not opt-in, the next invoice will be manual and they can pay when they are ready via the hosted invoice page. Once the invoice is paid, the customer will see a success message and a Payment History section next to their invoice.

How to enable Online Payments
Go to the Hosted Page Settings page in your Recurly site and under Customer Options you will see a checkbox called "Pay invoices online". Enable this option and all unpaid hosted invoices will automatically have a "Make a Payment" button next to them. If you do not see the Make a Payment button, make sure your gateways are configured correctly.

See what your customers see!
To see what the hosted invoice with Online Payments looks like, issue a manual invoice. In your Recurly Admin, on the page for that specific invoice, you will see a button in the top right corner called "Hosted Invoice". Click this secret unique link and you will see the Guest View mode version of the customer's hosted invoice. Please note that this hosted invoice link is a live private page associated with your customer. Any actions performed will be live actions on the customer's account.

Branding Options

Hosted Account Management and Hosted Payment Pages use the same branding options. See our [Hosted Pages][10] article for details. One special option for Hosted Account Management is a logout redirect to a url of your choice. This url is your Company Website URL in Site Settings. If no url exists in this field, Hosted Account Management logouts will go to the login page.
[10]: /docs/hosted-pages

API

The account API also returns a parameter called hosted_login_token. This allows you to place a custom URL on your site that logs the user directly into their account (e.g., :your_subdomain.recurly.com/account/:hosted_login_token ). This is a more seamless integration option for your users. For more information regarding API, please visit the API doc here.

For example, when you query the API for a specific account, you will receive a XML document like the following:

<?xml version="1.0" encoding="UTF-8"?>
<account href="http://a_shop.recurly.com/v2/accounts/example_account_code">
  <adjustments href=" .. some url .. "/>
  <billing_info href=" .. some url .. "/>
  <invoices href=" .. some url .. "/>
  <subscriptions href=" .. some url .. "/>
  <transactions href=" .. some url .. "/>
  <account_code>example_account_code</account_code>
  <state>active</state>
  <username>joe</username>
  <email>[email protected]</email>
  <first_name>Joe</first_name>
  <last_name>Jones</last_name>
  <company_name>Recurly</company_name>
  <accept_language nil="nil"></accept_language>
  <hosted_login_token>1ab3f1ff4e1c7c49cdec7a404e91d154</hosted_login_token>
  <created_at type="datetime">2012-08-20T17:48:50Z</created_at>
</account>

The token is located at:

<hosted_login_token>1ab3f1ff4e1c7c49cdec7a404e91d154</hosted_login_token>

So in this case, the token is:

1ab3f1ff4e1c7c49cdec7a404e91d154

Then the hosted account management access url is:

a_shop.recurly.com/account/1ab3f1ff4e1c7c49cdec7a404e91d154

🚧

Be sure to keep this token and URL secret as it allows anyone with the link to access the account.