Hosted Payment Pages Setup Guide

Table of Contents

1. Overview
2. New Customer: create
   1. Manual Customer Management
   2. Automatic Customer Management
   3. Useful Parameters
3. Edit Customer: update
   1. Useful Parameters
4. Cancel Customer: cancel
   1. Useful Parameters
5. Checking Customer Status
   1. Useful Parameters
6. Advanced API Features
7. Advanced Configuration

1. Overview

Hosted Payment Pages let you avoid the hassles of PCI compliance, and start billing your customers immediately. You can sign up new customers, allow customers to upgrade and update their information, cancel customers, and easily check the status of a customer's account at login. Advanced API features such as Tracked Items and One Time Invoices can also be integrated.

2. New Customer: Create

There are two different ways to create a new customer via hosted payment pages. The fastest way, using Manual Customer Management, is to provide a single link, and then provide access to your system manually. The best way is to pass some user data to the hosted payment page from your system. This allows you to provide and control access to your system automatically.

2.1 Manual Customer Management

The simplest method to subscribe a new customer is to use a single sign-up link (or button) and let them enter their billing information on the hosted page. If you have multiple pricing plans, the customer will choose their plan on the hosted page.

Example 2.1.1

<a href="https://yoursite.chargevault.com/create">Sign Up!</a>

Note: Simply subscribing a customer does not provide them access to your system or services. Using the Manual method, you will have to provide them access to your system manually.

If you have multiple plans you may want to present them as options on your sell page. You can pass these options into your links with the planCode parameter as such:

Example 2.1.2

<a href="https://yoursite.chargevault.com/create?planCode=GOLD">Sign up for Gold</a>

The payment page returned by that link will pre-select the plan you have passed in the URL. If you don't want customers to be able to switch plans on this 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.

You can pass additional user data to the hosted page using parameters to populate fields so your customer won't have to:

Example 2.1.3.

<a href="https://yoursite.chargevault.com/create?code=14825&firstName=John&lastName=Smith&email=john@smith.com">Sign Up</a>

2.2 Automatic Customer Management

We recommend that you pass CheddarGetter a customer code (the user id from your system) to keep things organized. If you don't, it will default to their email address. This is fairly simple to do, and can be summarized like this:

1. Create user in your system (form: first_name, last_name, user_name, password)
2. Redirect user to Hosted Payment Page (pass userID to CheddarGetter)
3. Customer fills out billing info, submits to CheddarGetter.
4. CheddarGetter subscribes user, redirects to your system (typically a login page)
5. Check status (see section 5)

2.3 Useful Parameters

Name	Description
code	Your code for this customer. Limited to 36 characters. If not specified defaults to email address.
firstName	Limited to 20 characters
lastName	Limited to 20 characters
email	Valid email address.
planCode	Your code for the pricing plan.
method	Billing method. Valid parameters are paypal and cc

3. Edit Customer: Update

Sometimes your customers will want to update their data. They may want to cancel or change their plans, update their address or billing information, or change credit cards.

If you're using Manual Customer Management, you'll be updating your customers through the CheddarGetter.com Customer interface. Your customers will also be able to update their data through links in their emails.

If you're using Automatic Customer Management, you can provide a link that includes 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:

1. Concatenate the Customer Code, a pipe "|", and your Product Secret Key
2. Create an MD5 Sum of that string
3. The Customer Key is the first 10 characters of that string

PHP

substr(md5($customerCode . '|' . $productKey), 0, 10);

Ruby

Digest::MD5.hexdigest(customer_code + '|' + product_key)[0..9]

You can also get a Customer Key via the API.

Example 3.0.1

The key and code parameters are required, at a minimum.

<a href="https://yoursite.chargevault.com/update?key=a1b2c3d4e6&code=yourcustomercode">Update your info</a>

Example 3.0.1

If you want to preselect a plan to encourage an upgrade (Upgrade to Pro)

<a href="https://yoursite.chargevault.com/update?key=a1b2c3d4e6&code=yourcustomercode&planCode=GOLD">Update to Gold Plan</a>

3.1 Useful 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 Secret Key.
firstName	Limited to 20 characters
lastName	Limited to 20 characters
email	Valid email address.
planCode	Your code for the pricing plan.
method	Billing method. Valid parameters are paypal and cc

4. Cancel Customer: Cancel

Sometimes your customers will want to cancel their accounts.

If you're using Manual Authorization, you'll be canceling your customers through the CheddarGetter.com Customer interface. Your customers will also be able to cancel their accounts through links in their emails.

If you're using Automatic Authorization, you can provide a link that includes a Customer Key. The Customer Key is a hash of the Customer Code and your Product Key. You can find your Product Key in Configuration. To generate a Customer Key, use the following method:

1. Concatenate the Customer Code, a pipe "|", and your Product Secret Key
2. Create an MD5 Sum of that string
3. The Customer Key is the first 10 characters of that string

PHP

substr(md5($customerCode . '|' . $productKey), 0, 10);

Ruby

Digest::MD5.hexdigest(customer_code + '|' + product_key)[0..9]

You can also get a Customer Key via the API.

Example 4.1

<a href="https://yoursite.chargevault.com/cancel?key=a1b2c3d4e6&code=yourcustomercode">Cancel your account</a>

4.2 Useful 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.

5. 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. 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 5.0.1

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

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
http.verify_mode = OpenSSL::SSL::VERIFY_NONE
request = Net::HTTP::Get.new(uri.request_uri)
status = http.request(request).body

5.1 Useful 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.

6. Advanced Features

Some advanced features of CheddarGetter 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 CheddarGetter'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. In addition to a subscription plan, in lieu of a subscription plan. 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 can prove very useful. You can learn how to implement them in our API documentation.

7. Advanced Configuration

The Hosted Payment Pages are completely customizable to match your brand. You're probably familiar with the basic config options in the quick-start wizard. However, there are additional options in the advanced configuration page

7.1 Subdomain

Your Hosted Payment Page is enabled when a subdomain is chosen. Try your company name, chances are it's available. If not, let us know and we'll see if it's really being used.

7.2 Company Info

• 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 E-mail is your customer service email address

Change Company Info

7.3 Theme

Here you can customize your page's look and feel. Upload your company logo and favicon, then choose one of our pre-designed color themes to match your aesthetic. Or, feel free to create your own theme using our color picker by clicking "Create New Theme"

For the advanced designers, there is also a field for Custom CSS. This field can be used to input raw CSS that corresponds to the HTML in our hosted payment pages.

Advanced Theme Options

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

Change Form Field Options

7.5 Return Locations

New Customer Return URL (overrides referer)

Customer Update Return URL (overrides referer)

Customer Cancel Return URL (overrides referer)

Change Return Locations

7.6 Preferences

Several options are available for you to customize the behavior of the hosted pages including but not limited to disabling the create and cancel pages.

Change Preferences

View Plans and Pricing   or   Get Started with CheddarGetter now →