Self-Service Page URLs

This section of your Site’s settings contains your Site’s Shared Key. Your Site’s “Shared Key” is a value that only you and Chargify know. It is used to generate unguessable URLs for the pages hosted by Chargify that your customers may interact with - pages like Public Signup Pages and Self-Service Pages.

Note: currently only the Self-Service Page takes advantage of these new, programmatic URLs.

The Shared Key is combined with other known values to create a message. That message is then encoded using the SHA-1 algorithm to generate a digest. A portion of that digest becomes a “token” that is used to authenticate the URL. (SHA-1 produces a 40 character digest, but we only check the first 10)

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]
Verify Bank Account verify_bank_account Bank Account /verify_bank_account/[]/[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