Security Signature

High security mode adds additional protection to your customer self-support pages. An additional signature must be included in the URL of any page which includes or manages customer data. This signature verifies that the URL was generated by ChargeDesk (or your company). It also allows pages to expire after a set period of time. If you currently use Standard Security, find out more about migrating to High Security.

A signature is automatically added to URLs returned from the ChargeDesk API. You can also generate a signature on your server for linking directly to a self support page, or for using a self-support component. If you don't wish to generate a signature, you can use the self support landing page or embeddable Self-Support Sign In Component which will verify your customer by sending an email with a link to their self support page.

Page Expiration

When high security is enabled, self-support pages will expire. This includes links in email receipts and invoices. By default this time period is 7 days, but this setting can be changed from Setup > Customer Self-Support > Expire Pages.

The self support sign-in landing page will be shown by default to customers who's pages expire. This will allow the customers to enter their email address to be sent a verification email with a newly generated link to their self-support page included.

Secret Support Key

*A signature must be generated on a server and not in client side code.*

Please do not include your secret support key in client side JavaScript or apps as this will allow anyone to sign your support URLs themselves.

Generate a URL Signature

Generating a signature for a self-support page is a 2 step process. You need to know the URL of the page you are going to sign as well as your secret support key above to create the signature.

1. To generate the signed path, you should concatenate;

• The current time (seconds since epoch).
• The character .
• The URL you are signing. Don't include any parameters.

2. Now you have the signed path, you can create the final signature by concatenating;

• The the same timestamp used in the signed path.
• The character .
• A HMAC of the signed path using your secret support key above and the sha256 algorithm

This creates the final signature that you should append as a signature parameter to any secure support URL.

The following is example PHP code which shows how to sign a URL;

// Fill with keys for your company and customer
$secret_key = "{support_secret_key_for_your_company}"; // Never expose this secret key
$company_id = "{company_id}";
$customer_id = "{customer_id}";

// Function to generate a signature of a ChargeDesk support URL
function generateChargeDeskSignature($url, $secret_key) {
	// Save time in advance to ensure that it doesn't change while URL is being signed
	$signedTime = time();
	// 1. Concatenate time, . and the URL to create the signed path
	$signedPath = $signedTime.".".$url;
	// 2. Concatenate time, . the HMAC together to create final signature
	return $signedTime.".".hash_hmac("sha256", $signedPath, $secret_key);
}

// Build support URL
$url = "https://chargedesk.com/".rawurlencode((string)$company_id)."/customer/".rawurlencode((string)$customer_id)."/history";

// Generate signature
$signature = generateChargeDeskSignature($url, $secret_key);

// Append signature and any parameters to URL
$params = [
    "showFailed" => 1,
    "signature" => $signature,
];
$signedURL = $url."?".http_build_query($params);

// Print result
print "<a href='".$signedURL."'>See billing history</a>";

// Will output something like
// <a href='https://chargedesk.com/{company_id}/customer/{customer_id}/history?showFailed=1&signature=1234567890.aA1bB2cC3dD4eE5fF6gG7hH8iI9jJ0kK1lL2mM3nN4oO5pP6qQ7rR8sS9tT0uU1vV2wW3xX4yY5zZ6'>See billing history</a>

Generate an Embeddable Components Signature

Generating a signature for an Embeddable Components is the same process as for a self-support page as shown above, please review this section first. The main difference is that you need to know what format the embedded URL component will take. You can find this in the example code on the Embeddable Components page. Embeddable Components URLs will always end with /embed

The following is example PHP code which shows how to sign an embedded component;

// Fill with keys for your company and customer
$secret_key = "{support_secret_key_for_your_company}"; // Never expose this secret key
$company_id = "{company_id}";
$customer_id = "{customer_id}";
$embed_action = "history"; // Show billing history. Could be 'card' for updating the customer's default card on file.

// Function to generate a signature of a ChargeDesk support URL
function generateChargeDeskSignature($url, $secret_key) {
	// Save time in advance to ensure that it doesn't change while URL is being signed
	$signedTime = time();
	// 1. Concatenate time, . and the URL to create the signed path
	$signedPath = $signedTime.".".$url;
	// 2. Concatenate time, . the HMAC together to create final signature
	return $signedTime.".".hash_hmac("sha256", $signedPath, $secret_key);
}

// Build embedded URL
$embedUrl = "https://chargedesk.com/".rawurlencode((string)$company_id)."/customer/".rawurlencode((string)$customer_id)."/".rawurlencode((string)$embed_action)."/embed"; // Note the '/embed' at the end of this URL

// Generate signature
$signature = generateChargeDeskSignature($embedUrl, $secret_key);
?>
<script src="https://chargedesk.com/client.js"
    data-company="<?=    htmlspecialchars($company_id,   ENT_QUOTES) ?>"
    data-customer="<?=   htmlspecialchars($customer_id,  ENT_QUOTES) ?>"
    data-embed="<?=      htmlspecialchars($embed_action, ENT_QUOTES) ?>"
    data-signature="<?=  htmlspecialchars($signature,    ENT_QUOTES) ?>">
</script>