Embedded Action Verification

When handling a successful response from an embedded component, you have the option to verify that the response came from ChargeDesk. When performing a business action (such as unlocking an account, providing a digital product or creating an order) you should first verify the response came from ChargeDesk.

Secret Key

Response verification uses a HMAC signature created with a secret key for your company.

Keep your secret key safe and do not include it in client-side JavaScript. You should only perform response verification on your server.

Verify a Response

To verify a response came from ChargeDesk you need to use the secure_response parameter along with your secret key above. The secure_response contains to parts separated with a dash (-). The first part is a base 64 and json encoded version of the response. The second part is a HMAC which signs the first part using your secret key using the sha256 algorithm.

The following is example PHP code which shows verification process. Along with verifying the signature, we recommend checking the timestamp and passing a state through as well.

First we place an embed component in the page and generate a unique state which we can later verify.

<?php
// Generate a unique billing state for the session
if(!$_SESSION['billing-state']) {
    $_SESSION['billing-state'] = uniqid();
}
?>
<div id="generic-payment"></div>
<script src="https://chargedesk.com/client.js"></script>
<script>
    ChargeDesk.embed({
        id: "generic-payment", // ID of the HTML div
        company: "{company_id}",
        embed: "pay",
        successURL: "https://yourdomain.com/success?secure_response={secure_response}",
        options: {
            state: "<?= $_SESSION['billing-state'] ?>"
        }
    });
</script>

Now we can verify the response on the /success page.

$secure_response = explode("-", $_REQUEST['secure_response'])[0];
$secure_signature = explode("-", $_REQUEST['secure_response'])[1];
$verify_signature = hash_hmac(
    "sha256",
    $secure_response,
    "{secret_key}"
);
// Verify the signature matches the request
if($secure_signature !== $verify_signature) {
    die("Could not verify response.");
}
$response = json_decode((string)base64_decode($secure_response));
// Verify the response was not generated more than 10 mins ago (optional, but recommended)
if(time() - $response->timestamp > 600) {
    die("Sorry, this page has expired. Please try again.");
}
// Verify the response has the same state we saved for this session (optional, but recommended)
if($response->state != $_SESSION['billing-state']) {
    die("Sorry, this page is not valid. Please try again.");
}
// Ensure the state can't be reused
$_SESSION['billing-state'] = false;
// You can now use $response securely

After verifying the secure_response, you can decode the JSON object it contains and then use that to perform your business logic. Only use data from the decoded secure_response parameter and not other non-secure parameters.