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 Advanced Billing know. It is used to generate unguessable URLs for the pages hosted by Advanced Billing that your customers may interact with - pages like Public Signup Pages and Self-Service Pages. Currently only the Self-Service Page takes advantage of these 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 | https://[subdomain].chargifypay.com/update_payment/[subscription.id]/[token] |
| Verify Bank Account | verify_bank_account | Bank account | https://[subdomain].chargifypay.com/verify_bank_account/[bank_account.id]/[token] |
Obtaining your Shared Key
A shared key, that is known only to you and Advanced Billing, 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 Advanced Billing.
Every Advanced Billing 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:
Your shared key is displayed prominently in your account settings
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]`
# => b59a09cc72Generating URLs
URLs follow the pattern:
https://[subdomain].chargifypay.com/[shortname]/[id]/[token]`So, a full URL for the Self-Service Page on the acme subdomain, using the values from the earlier example, would be:
https://acme.chargifypay.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 Advanced Billing.
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.chargifypay.com/update_payment/77/b59a09cc72
https://acme.chargifypay.com/update_payment/77-john-doe/b59a09cc72In 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