Hosted Page Integration

Chargify offers a hosted/white label signup page for all of our customers. The hosted page allows you to integrate with the Chargify platform without having to worry about collecting credit card information or writing custom code yourself. You can point your customers to a unique URL on the Chargify site and we will securely handle subscription signup and payment processing.

If you need information on configuring the look, feel, and behavior of your Hosted Payment Page, please see Hosted Page Settings.

To use hosted signup pages with the Beanstream gateway, you must enable billing address collection from within the Hosted Page Settings.

Accessing any hosted payment page will log you out of your Chargify account. This is necessary for security reasons. If you would like to test your hosted payment pages without being logged out, please copy the links and open them in another browser.

Each Product has its own hosted signup page page and unique URL. You can find the URLs for these pages on your product overview screen, in the box labelled “Hosted Signup Page URL”.

For more information on the full set of URLs available, see Hosted Page URLs, below.

Hosted Payment Page Signup Flow

  1. Provide your potential Customers with a link to the Hosted page for the Product you would like to offer them. Note that you have the option to pass in some data to pre-populate the form or variables that are sent to Chargify – see Hosted Page Settings: Pre-populating Data
  2. The customer fills out their credit card details and other requested or required information (the information collected by the Hosted Payment Form is controlled by the Product Options) and presses the submit button
    1. If the customer enters information incorrectly or their credit card is declined, they are notified within the Hosted Payment Page and given a chance to make corrections
    2. If the customer enters information correctly and their credit card is accepted (or is not required) then they are redirected either to:
      1. a Chargify-hosted receipt page
      2. the page identified by the Return URL you provided in the Product Options
  3. If you use a Return URL and Return URL parameters, you can capture information about the signup within your Return URL page to change your own application state (however you’ll probably want to verify this information via our API to avoid susceptibility to URL-hacking). The Return URL and Return URL parameters are how you can be synchronously notified of a signup. This is the best way to learn about a signup via the hosted page in real time.
  4. You can also observe Webhooks to change your application state based on the signup. Webhooks are asynchronous events, so you probably do not want to block your user from completing a signup on your end until you receive the Webhook. See Webhooks are Asynchronous

Hosted Page URLs

If you choose to use the Chargify-hosted pages, you can programmatically generate some of the URLs for the pages so that you may easily embed the links within your own site or emails.

The pages that are (or will be) accessible via generated URLs are as follows:

Page Shortname Resource URI
Signup Coming soon… Product (can be obtained from UI, as described above)
Update Payment update_payment Subscription /update_payment/[subscription.id]/[token]

Obtaining your Shared Key

A Shared Key, that is known only to you and Chargify, is used to generate and validate the hosted page URLs. This allows you to create URLs that are “unguessable”. However, anyone with the URL will be able to visit the page. If you require a stronger authorization scheme, you should not distribute URLs for the hosted pages, and instead use our API to integrate your app with Chargify.

Every Chargify Site has a unique Shared Key. You may obtain your key by visiting the “Settings” tab for the Site in which your are interested:

The Shared Key is shown in the section titled “Hosted Page URLs”:

Generating Tokens

URLs are constructed, and later verified, via a secret token. This token is the first 10 characters of the SHA-1 hex digest of a specially constructed message. In pseudo-code:

token = SHA1(message)[0..9]

The message is a concatenation of the page “shortname”, the resource’s ID, and the Site’s Shared Key. The message parts are joined using double dashes (—). Consider the Update Payment page for a subscription with ID ‘77’ and a Shared Key of ‘1234’:

message = "update_payment--77--1234"

Putting it all together:

token = SHA1("update_payment--77--1234")[0..9]
# => b59a09cc72

Generating URLs

URLs follow the pattern:

https://[subdomain].chargify.com/[shortname]/[id]/[token]

So, a full URL for the Update Payment page on the `acme` subdomain, using the values from the earlier example, would be:

https://acme.chargify.com/update_payment/77/b59a09cc72

Resource IDs

The required value for [id] in the URL is available via the `id` parameter in a response from our API. This ID is a unique value assigned to resources by Chargify.

Token Length

You may pass a token that is longer than 10 characters; however, we only verify that the first 10 characters of your token match the expected token.

Pretty IDs

You may pass more information in the [id] parameter, as long as that information is proceeded by a dash (-). For example, the following two URLs access the same payment update page:


https://acme.chargify.com/update_payment/77/b59a09cc72
https://acme.chargify.com/update_payment/77-john-doe/b59a09cc72

In this example, we’re adding the customers name to the subscription ID, making it more “personal”. Just make sure that anything you add to the URL is in fact composed of URL-safe characters.

URL Validity

A “404 Not Found” response will be returned if the URL is not valid. Invalid URLs can result from either of the following:

  • The resource ID does not identify a valid resource for the given Site
  • The token does not match the expected token for the page shortname and ID
  • Using POST instead of the correct GET verb to initially get the hosted page

Components

Quantity and On/Off Components can be configured to appear on the hosted page. To enable a component on the hosted page, check the ‘Allow customers to add this component on the hosted signup page’ when creating or editing a component. Components with ‘Stairstep’ pricing schemes are not currently supported on the hosted page.

Once enabled, components will appear in a ‘Configure Your Plan’ section on the hosted page in a div with the class name of ‘component_configuration’. (Note that this name may change in the future).

Hosted Page Translations/Internationalization (i18n)

The hosted page is only offered in English at this time. If you would like to add translations to page content, you may do so by writing javascript that replaces on-page content with your own content via Custom Javascript. Adding Custom Javascript is documented in Hosted Page Settings.

Translating Javascript Generated Content

Even though you can translate on-page content by replacing text on the page, there is still an issue where you will not have access to content that we generate via Javascript and add to the page later. Examples of this kind of content are:

  • The alert box that pops up when the Terms & Conditions are not acknowledged
  • The label on the submit button that changes as a result of a click (i.e. from “Submit” to “Processing…”)

We have provided a mechanism for you to add translations for this javascript-generated content. To your Custom Javascript, you may add translations by extending `chargifyHostedPageDictionary`.

$.extend(chargifyHostedPageDictionary, {
  // The alert pop up when agreement to terms is required but not checked:
  'alert.must-agree-to-terms':         'You must agree to the Terms and Conditions',

  // The default value for the Billing/Shipping State selector after choosing a new country:
  'form.address-state.blank-label':    'Please select',

  // The replacement value for the submit button text once it is clicked:
  'form.submit-button.disabled-label': 'Processing...'
});

Shown above is the default text from our default dictionary. If I wanted to translate the content to another language, say “Pirate”, I could:

$.extend(chargifyHostedPageDictionary, {
  "alert.must-agree-to-terms": "Arr matey, agree to mine terms or walk the plank",
  'form.address-state.blank-label':    'Select yer state, swashbuckler',
  'form.submit-button.disabled-label': 'Shiver your timbers...'
});