Self Service Pages

Every Chargify Subscription gets an automatically generated URL for a Self-Service Page that will only allow changes to that specific subscription. To get the URL for the Self-Service Page attached to any given Subscription, visit the Subscription index page by clicking the “Subscriptions” tab in the admin UI. You’ll find the link to the Subscription’s Self-Service Page inside the actions menu in each table row.

Below is an example of a Self-Service page that a customer will use to update their payment method.

There are a few ways for you, as the Merchant, to obtain the self service link. Additionally, there a few ways to have Chargify automatically provide your customers with the link.

  • Settings –> Retries & Dunning -> Add Message. Include the URL in your dunning emails by adding in any of your messages.

  • Settings –> Emails –> Edit Template. You can include the URL in your email templates by adding in any of your messages.

For a full list of what dynamic variables are available, please view our documentation here.

  • Via the Subscriptions tab –> Click a subscription -> Payment Details –> “Email Customer to Request Payment Update”. This will include a link to the self-service page.

  • Via the Subscriptions tab –> Click a subscription –> Actions –> “View self-service page.” This method will give the merchant the URL. They can then send a link to the customer manually through their own email account.

Customers may also update their payment information via the Billing Portal. You can read all about the Billing Portal here. The aforementioned instructions are important to point out, as not all Merchants choose to enable the Billing Portal.

For more information on Public Pages, please see our documentation here.

Self-Service Page URLs

If you choose to use the Self-Service 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 accessible via generated URLs are as follows:

Page Shortname Resource URI
Update Payment update_payment Subscription /update_payment/[]/[token]

Obtaining your Shared Key

A Shared Key, that is known only to you and Chargify, is used to generate and validate the Self-Service Page URLs. This allows you to create URLs that are “un-guessable”. 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 Self-Service 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 “Self-Service 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 Self-Service 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:


So, a full URL for the Self-Service Page on the acme subdomain, using the values from the earlier example, would be:

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:

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 request the Self-Service Page

Public Page Translations/Internationalization (i18n)

The Public Pages are 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.

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