Validating callbacks

Opening firewalls for callbacks

Callbacks from checkout sessions will be sent from one of these IPs:

34.241.230.119
34.242.13.162

If you’re using a firewall, traffic from these IPs should be let through. These IPs apply to session callbacks. To receive account-wide event notifications instead, see Webhooks.

Validating callbacks with signature

Use POST /v1/admin/signature to create a secret. The following callbacks from Dintero will then include a header named Dintero-Signature, and your backend can verify it: The signature secret belongs to the account your access token was issued for. Sandbox (T prefix) and production (P prefix) accounts are separate, so create one secret on each account and store them separately in your backend. The account ID is also part of the signed payload. See Sandbox vs production. Callbacks from Dintero will include a header named Dintero-Signature, and your backend can now implement signature verification for this.

The session callback (url.callback_url)
The shipping address callback (express.shipping_address_callback_url)
The discount codes callback (express.discount_codes.callback_url)

The signature covers the timestamp, account ID, HTTP method, hostname, path, and sorted query parameters of the callback URL. It does not cover the request body.

Example code for validating signature

To validate the signature received in the Dintero-Signature header

Note that spaces in query parameters must be encoded with + (not %20) before the signature is created
The query parameters must be sorted

For the shipping address and discount codes callbacks, method is POST, and the URL is the callback URL exactly as you set it on the session.

JavaScript

const assert = require("node:assert/strict");
const crypto = require("node:crypto");
const account_id = "T12345678";
const secret = "apikeysecret";

const createSignature = (requestUrl, method, timestamp) => {
    const dataUrl = new URL(requestUrl);
    const { hostname, pathname } = dataUrl;

    const params = dataUrl.searchParams;
    params.sort();

    const query = params.toString();
    const payload =
        `${timestamp}\n${account_id}\n${method}` +
        `\n${hostname}\n${pathname}\n${query}`;
    const signature = crypto
        .createHmac("sha256", secret)
        .update(payload, "utf8")
        .digest("hex");
    return `t=${timestamp},` + `v0-hmac-sha256=${signature}`;
};

const verifySignature = (signatureHeader, method, requestUrl) => {
    const parts = signatureHeader.split(",");
    const timestamp = parseInt(parts[0].split("=")[1]);
    const now = Math.floor(new Date().getTime() / 1000);
    assert.ok(
        // reject callbacks older than 5 minutes
        now - timestamp < 5 * 60,
    );

    const trusted = Buffer.from(
        createSignature(requestUrl, method, timestamp),
        "ascii",
    );
    const untrusted = Buffer.from(signatureHeader, "ascii");
    assert.ok(crypto.timingSafeEqual(trusted, untrusted));
    console.log("signature valid");
};

How to view the callback sent and received

Sometimes, small unforeseen difficulties might occur when implementing the signature check. For example, if you successfully create a transaction from a checkout session but the signature check fails on the received callback, this might be for you. To provide a better overview of the request sent and response received, the Backoffice platform offers a view at the bottom of each individual transaction page. This view includes any callbacks sent and received.

Customization

Distribution & Channels

Settlements & Reports

Testing

Security

SDKs

Opening firewalls for callbacks

Validating callbacks with signature

Example code for validating signature

How to view the callback sent and received

​Opening firewalls for callbacks

​Validating callbacks with signature

​Example code for validating signature

​How to view the callback sent and received

​1. Login to backoffice, then follow this interactive slide-show

Opening firewalls for callbacks

Validating callbacks with signature

Example code for validating signature

How to view the callback sent and received

1. Login to backoffice, then follow this interactive slide-show