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 this IP should be let through.

Validating payload with signature

Use POST /v1/admin/signature to create a secret.

Callbacks from Dintero will now include a header named Dintero-Signature, and your backend can now implement signature verification for this.

Example code for validating signature

To validate the signature received in the Dintero-Signature header

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

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]);
    assert.ok(
        // expire after 5 minutes
        timestamp < Math.floor(new Date().getTime() / 1000 + 5 * 60 * 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 recieved

Sometimes, small unforeseen difficulties might occur when implementing the signature check. For example, if you succesfully create a transaction from a checkout session but the signature check fails on the recieved 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.

1. Login to backoffice.dintero.com

2. Click on Payments

3. Choose a transaction that has a delivered callback.

We will be using an example transaction.

4. Scroll down to the bottom of the page until you find the Requests view.

If the Request view is not visible, no callbacks have been sent.

5. You can also expand each request and see further information.

For example, the URL and query parameters as well as the request and response object.