Hosted Payment Pages Setup Guide
- Overview
- Hosted Page Setup Guide
- Configure and Customize Hosted Pages
- Customer Management with Hosted Pages
- Testing
- Advanced Features
1. Overview
The quickest way to start accepting payments from your customers is with hosted payment pages. The hosted pages are customizable pre-made forms hosted by Cheddar where your customers can sign up for a subscription, enter their payment information, update their payment information, change their subscription, or cancel their subscription.
If you’d like to use your own payment pages or want to use advanced features like tracked items for usage-based billing, you should consider integrating with our API instead of using hosted pages. Some advanced features such as tracked items and one-time invoices are only available when you’re using the API.
2. Hosted Pages Setup Overview
You can set up a hosted page in a few minutes with very little technical expertise. Here's what you'll need to do to get your hosted pages up and running:
-
Optional: Check subscription status with Cheddar when customers login
-
Optional: Test hosted pages before going live
3. Configure and Customize Your Hosted Page
There are two places to create and customize your hosted page in your Cheddar dashboard. On the Integration step of your product account's Quick Setup, there are some basic config options and examples.
To fully customize your hosted page, select the Hosted Pages option in the Configuration drop down menu. The sections below go through all the customization options available there.
3.1 Subdomain
Your hosted payment page is enabled when you configure a subdomain. There’s a good chance your company name is available, so we recommend you try that first. If it isn’t available, let us know and we can check to see if it's actively being used.
3.2 Company Info
Use this section to include information about your company on the hosted page.
-
About the Company is a text area where you can write a few sentences explaining your product to your customers.
-
Address is your business address
-
Contact Number is your customer service phone number
-
Contact Email is your customer service email address
You can change company info in your Hosted Pages settings.
3.3 Theme
Here you can customize your hosted page's look and feel. You can upload your company logo, favicon, and create your own theme using the field for Custom CSS. This field can be used to input raw CSS that corresponds to the HTML in our hosted payment pages. Once you’ve configured your hosted page domain, you can find the existing stylesheet for the hosted page at https://yourdomain.chargevault.com/hosted/css/default.css.
If you need some help getting started, here’s a simple example of a customized hosted page. Feel free to copy and paste the following into the custom CSS section, then edit it to include your own colors, background, spacing, shadows, etc:
body, html {
height: 100%;
background-color: #c0c0c1;
display: flex;
flex-direction: column;
}
h1 {
text-align: center;
}
h2 {
color: #7ea230;
}
.container {
background: #c0c0c1;
flex: 1 0 auto;
}
.contentBox {
box-shadow: 0px 5px 3px rgba(51, 51, 51, 0.5);
border-top: 3px solid #7ea230;
background: white;
}
.planSelection select{
width: 100%;
}
.button {
background-color: #7ea230;
border-radius: 8px;
color: white;
}
.footer {
height: 70px;
width: 100%;
border-top: 3px solid #7ea230;
background-color: #414141;
flex-shrink: 0;
}
.copyright {
color: white;
}
Here’s what your page will look when you save your template with the CSS above:
You can find some excellent examples of more advanced CSS options here.
3.4 Form Fields
First Name, Last Name, and Email are always required.
These are the optional fields that you can choose to collect from your customers on the hosted payment page:
-
Contact Information: Company
-
Billing Information: Company
-
Billing Information: Address
-
Billing Information: City
-
Billing Information: State
-
Billing Information: Postal Code
-
Billing Information: Country
-
Billing Information: Card Code
You can configure these options and choose which ones are required in the Form Fields menu of your Hosted Pages settings.
Note that some of these fields may be required by your payment processor for card validation. If you’re using CheddarPay, for example, you’ll need to require the Country and Card Code fields. Check in with your payment processing provider to confirm which fields are required for customer sign up.
3.5 Return Locations
Return locations are where Cheddar will direct your customers after they’ve submitted the form on your hosted page. You can customize these locations depending on the action the customer takes on your hosted page:
New Customer Return URL (overrides referrer)
Customer Update Return URL (overrides referrer)
Customer Cancel Return URL (overrides referrer)
You can configure return locations in your Hosted Pages settings here.
3.6 Preferences
Several options are available for you to customize the behavior of the hosted pages, such as disabling the create and cancel pages.
You can see all the available options under your Hosted Pages Preferences.
3.7 Pricing Plan Configuration
You can choose which pricing plans your customers can view and select on your hosted page by using the active vs. inactive toggle in your pricing plans configuration. A pricing plan is active when the Active box is checked.
The only difference between active and inactive pricing plans is that active plans will appear in the plans dropdown on your hosted page whereas inactive plans will not. You can still subscribe customers to inactive pricing plans in the user interface or by passing in the plan code when you link a customer to the hosted page, customers just won't have the option to subscribe themselves to inactive plans on your hosted page.
3.8 Email Links
If you've enabled Customer Communications in your product account, your email notifications will automatically contain links to the hosted pages.
When hosted pages are enabled, the call to action button at the bottom of all email notification types will link customers to a hosted update page with information specific to their subscription.
4. Customer Management with Hosted Pages
While your customers' actions on your hosted page will affect their billing record in your Cheddar product account, they will not automatically provide the customer access to your system or services. Once you have your hosted page enabled, you’ll need to decide how to manage the process of updating customer records in your system when a customer is created, updated, or canceled via your hosted page. There are two methods:
-
Automatic Customer Management
-
Manual Customer Management
The automatic method involves passing Cheddar a customer code that’s generated by your application when a customer signs up so that the code stored in Cheddar matches a customer code stored in your system to identify the customer. This allows you to provide and control access to your system automatically. We recommend the automatic method for more seamless customer management.
The manual method is just that. When a customer signs up on the hosted page, you will need to manually update the customer account in your system to make sure that a customer is given access to your services. If you’re a startup or small company in need of a speedy integration, the manual method will work as a temporary solution, but we suggest transitioning to the automatic method or the API before you have a high volume of customers.
Below you’ll find more detail about to use both customer management methods with hosted pages for customer sign up, update, and cancellation.
4.1 Automatic Customer Management
With automatic customer management, you pass Cheddar a customer code that corresponds to their billing record in Cheddar. That way, you can easily associate a customer's account with their record in Cheddar.
4.1.1 Automatic Management: Sign up
To sign up a new customer using the automatic method, you’ll want to pass your customer code to the hosted page when you direct new customers to subscribe and enter their payment information. This is fairly simple to do, and can be summarized like this:
-
Create user in your system (form: first_name, last_name, user_name, password)
-
Redirect user to Hosted Payment Page (pass userID to Cheddar)
-
Customer fills out billing info, submits to Cheddar
-
Cheddar subscribes user, redirects to the new customer return URL you’ve configured (typically a login page)
Required Create Parameters
When you redirect the customer to the hosted create page, you'll need to include the following parameter in the URL:
| Name | Description |
|---|---|
| code | **Required** Your code for this customer. Limited to 36 characters. If not specified defaults to email address. |
Example Sign Up URL
<a href="https://yoursite.chargevault.com/create?code=yourcustomercode">SignUp</a>
Optional Parameters
In addition to customer code, use any of the parameters below to auto-populate the hosted update page form fields when you direct your customer to the create page:
| Name | Description |
|---|---|
| firstName | Limited to 20 characters |
| lastName | Limited to 20 characters |
| Valid email address. | |
| planCode | Your code for the pricing plan. |
| method | Billing method. Valid parameters are paypal and cc |
4.1.2 Automatic Management: Update
Customers can use the hosted update page to change their plans, update their billing information, or change their payment method.
To indicate to Cheddar which customer is making an update, you can provide a link that includes a unique Customer Key. A link that includes a Customer Key will direct the customer to a unique hosted update page that shows information specific to their subscription.
Generate a Customer Key
The Customer Key is a hash of the Customer Code and your Product Secret Key. You can find your Product Secret Key in Configuration. To generate a Customer Key, use the following method:
-
Concatenate the Customer Code, a pipe "|", and your Product Secret Key
-
Create an MD5 Sum of that string
-
The Customer Key is the first 10 characters of that string
Required Update Parameters
The key and code parameters are required, at a minimum.
| Name | Description |
|---|---|
| code | **Required** Your code for this customer. Limited to 36 characters. If not specified defaults to email address. |
| key | **Required** 10 alphanumeric character hash of the Customer Code and your Product Secret Key. |
Example Update URL
<a href="https://yoursite.chargevault.com/update?key=a1b2c3d4e6&code=yourcustomercode">Update your info</a>
PHP
substr(md5($customerCode . '|' . $productKey), 0, 10);
Ruby
Digest::MD5.hexdigest(customer_code + '|' + product_key)[0..9]
Optional Update Parameters
Use any of the parameters below to auto-populate the hosted update page form fields when you direct your customer to their update page.
| Name | Description |
|---|---|
| firstName | Limited to 20 characters |
| lastName | Limited to 20 characters |
| Valid email address. | |
| planCode | Your code for the pricing plan. |
| method | Billing method. Valid parameters are paypal and cc |
A popular update option is to use the planCode parameter to preselect a plan to encourage an upgrade (Upgrade to Pro) like so:
<a href="https://yoursite.chargevault.com/update?key=a1b2c3d4e6&code=yourcustomercode&planCode=GOLD">Update to Gold Plan</a>
If you don't want customers to be able to switch plans on the update page, you can check the "Disallow pricing plan change on create page when plan code parameter is passed in" option in your Hosted Pages / Preferences configuration.
4.1.3 Automatic Management: Cancel
Just like the update link, provide a link that includes a Customer Key to indicate to Cheddar which customer account is being canceled (see Generating Customer Key above for more details). A link that includes a Customer Key will direct the customer to a unique hosted cancel page that shows information specific to their subscription.
Required Cancel Parameters
| Name | Description |
|---|---|
| code | **Required** Your code for this customer. Limited to 36 characters. If not specified defaults to email address. |
| key | **Required** 10 alphanumeric character hash of the Customer Code and your Product Key. |
Example Cancel URL
<a href="https://yoursite.chargevault.com/cancel?key=a1b2c3d4e6&code=yourcustomercode">Cancel your account</a>
PHP
substr(md5($customerCode . '|' . $productKey), 0, 10);
Ruby
Digest::MD5.hexdigest(customer_code + '|' + product_key)[0..9]
4.1.4 Automatic Management: Checking Customer Status
You'll probably want to check to be sure your customer is “active” before giving them access to your system during each login. Here's a simple example of what that process looks like:
The typical way to do this is to hit the API to check customer data.
There is also a quick way to check customer status via an HTTP request:
Example Status URL
https://yoursite.chargevault.com/status?key=a1b2c3d4e6&code=yourcustomercode
The results of this request will return one of the following simple strings:
| Return | Description | Suggested Action |
|---|---|---|
| active | the customer is authorized, billing info valid | allowed to access system |
| canceled | customer is not authorized, card expired, billing info invalid, or self-canceled | no access, suggested message “You don't have access, please update your billing info” |
| pending | special kind of canceled status, post-signup during billing authorization we do not know if they are valid | no access (you can grant access if you want), suggested message "Your payment is being validated, please try again in a few minutes." |
If the customer does not exist, an HTTP response status of 404 is returned.
Required Status Parameters
| Name | Description |
|---|---|
| code | **Required** Your code for this customer. Limited to 36 characters. If not specified defaults to email address. |
| key | **Required** 10 alphanumeric character hash of the Customer Code and your Product Key. |
PHP
$status = file_get_contents('https://yoursite.chargevault.com/status?key=a1b2c3d4e6&code=yourcustomercode');
Ruby
uri = URI.parse("https://yoursite.chargevault.com/status?key=a1b2c3d4e6&code=yourcustomercode")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Get.new(uri.request_uri)
status = http.request(request).body
4.2 Manual Customer Management
The simplest method to subscribe a new customer is to provide a sign-up link on your website that directs the customer to the hosted create page. To give the customer access to your system after they’ve successfully signed up for a subscription on your hosted page, you’ll need to manually update your system.
4.2.1 Manual Management: Sign up
Provide a link on your website to the hosted payment create page like so:
Manual Process:
-
Customer clicks sign up link on your website and is directed to your Cheddar hosted page
-
Customer submits their contact and payment information on the hosted page
-
Cheddar subscribes user, redirects to the new customer return URL you’ve configured(usually your website)
Example Manual Sign Up URL
<a href="https://yoursite.chargevault.com/create">Sign Up!</a>
When the customer submits the form, their customer record and subscription will be created in Cheddar. Since you’re not passing Cheddar a customer code, we automatically generate one for you. Automatically generated codes will be the customer’s email address. If you’re planning on passing Cheddar a customer code that aligns with a user ID in your system, consider using automatic customer management instead.
To pre-populate any of the fields on the hosted create page when you direct your customers to subscribe and enter their payment information, you can use any of these optional parameters in the URL:
| Name | Description |
|---|---|
| firstName | Limited to 20 characters |
| lastName | Limited to 20 characters |
| Valid email address. | |
| planCode | Your code for the pricing plan. |
| method | Billing method. Valid parameters are paypal and cc |
4.2.2 Manual Management: Update
When your customers need to change their plans, update their billing information, or change their payment method, you'll need to manually update the customer’s Cheddar billing record through the Cheddar dashboard. Navigate to the customer’s profile in your Cheddar product account and select “Edit Subscription” to make updates.
If you’re using Cheddar’s built-in customer communication emails, your customers will also be able to update their data through links in those emails.
4.2.3 Manual Management: Cancel
When your customers need to cancel their subscription, you'll need to manually cancel your customers through your Cheddar dashboard. Navigate to the customer’s profile in your Cheddar product account and select “Edit Subscription”.
If you’re using Cheddar’s built-in customer communication emails, your customers will also be able to cancel their accounts through links in those emails.
5. Testing
While your product is in developer mode, you can simulate customer sign-ups, updates, cancellations, and transactions with your hosted page. Before you begin testing, navigate to the Quick Setup in your Cheddar product account and make sure you’ve configured pricing plans, selected a payment processor, and enabled your hosted page.
Note: Make sure to delete any test customers you create in your product account before going live, so that they aren’t included in your live account analytics.
5.1 Test: Sign up
Open your hosted payment page by visiting your hosted page configuration and selecting Open next to your subdomain name. This will direct you to the hosted create page. When your product account is live, this is the page where you’ll direct new customers to enter their payment information.
Start by selecting a pricing plan. Any pricing plan will do, but if you’d like to simulate a customer sign-up with an immediate transaction, select a pricing plan that you’ve configured to bill on sign-up.
Once a plan is selected, enter your test customer’s contact and payment information. If you have customer communications enabled and would like to receive an email notification for this test customer’s sign-up, use your own email address in the customer contact information section.
When entering a payment method, you can use a fake credit card number that passes the Luhn Algorithm format test. Below is a list of some examples that we like to use:
-
370000000000002 American Express
-
6011000000000012 Discover
-
5424000000000015 MasterCard
-
4111111111111111 Visa <===== Our favorite! It's so easy to remember.
You could also get a large set of numbers here.
You can use any expiration date, card name, and CVV number you choose. These fields are not evaluated (other than format and requirement) when your product is in developer mode.
Once you’ve entered information in all the contact information and required payment fields, hit Submit on the bottom of the hosted page and your new test customer will be created and subscribed to the plan you’ve selected.
To confirm, navigate back to your Cheddar dashboard. You should see a new sign-up in your activity stats. Go ahead and click on the new sign-up and you’ll be directed to the test customer’s Cheddar profile. The profile contains lots of useful information like contact details, current pricing plan, customer activity, invoice history, and more. The customer’s profile page also contains a link to the hosted update page for this specific customer.
5.2 Test: Update
From the customer’s Cheddar profile page, click the link that says “Customer's Update Page”. The update link contains a customer key, so this hosted update page will show information specific to this customer. You can then change the customer’s pricing plan, update their contact information, and update their payment information.
If you have email notifications enabled in your Cheddar product, the default update links in those emails will direct customers to their specific update page. If you’re using your own emails or need to direct customers to their update page from a link on your website, you can generate the link with the customer key using these directions.
5.3 Test: Cancel
To test cancellation, navigate to the customer’s Cheddar profile and select the link that says “Customer's Cancel Page”. The cancel link also contains a customer key, so this hosted cancel page will show information specific to this customer.
Once you’re on the hosted page, simply click the cancel link and the customer’s subscription will be suspended.
5.4 Test: Errors
If you’d like to see what your customers will experience if a sign-up or update fails because of a gateway error or decline response, Cheddar allows you to simulate error responses while you product account is in developer mode. In order to trigger the error simulation, the customer's billing postal code must be sent in the following format: 0XXXX, where XXXX is one of the AUXCODEs listed here.
See more about error simulation here.
6. Advanced Features
Some advanced features of Cheddar are only available via the API. Hosted Payment pages are designed primarily for basic payment processing, not for detailed usage tracking, promos, micro-billing, or other advanced features.
Here are two of the most powerful features of Cheddar's full API:
Tracked Items can be used for controlling access to features on your website, for micro-billing, for overages, and for discounts. They provide a great amount of flexibility in billing, and can only be accessed via the API. You can read the Pricing Plans Knowledge Base article to learn how to use them.
One-Time Invoices allow your customers to make real-time transactions. Some usages include selling digital goods, a shopping cart, or one-click purchases. They provide immediate feedback upon the success or failure of a payment. If you are selling something with immediate value that should only be available after you collect your money, One-Time Invoices are a great choice. You can learn how to implement them in our API documentation.