Skip to content

Handle Callbacks

A Callback is a signed POST from VoltPay to your server. It is what you credit from.

POST /your/callback HTTP/1.1
Content-Type: application/json
User-Agent: gateway-callback/1
Gateway-Signature: t=1793980802,v1=9f2c…
{
"id": "evt_01J9…",
"type": "payment.confirmed",
"created_at": "2026-11-06T13:10:02Z",
"mode": "live",
"data": {
"payment": {
"id": "pay_6f1c…",
"status": "confirmed",
"checkout_id": "chk_01J9…",
"reference": "ORDER-1042",
"requested_amount": "50.00",
"amount": "49.0037",
"match_result": "under",
"network": "tron",
"coin": "usdt",
"tx_hash": "8f3a…",
"fee": "1.029078"
}
}
}

The body is shortened here. The API reference lists every field.

Gateway-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256(signing secret, "<t>.<raw body>")>
  1. Read the body as raw bytes, before any JSON parsing.
  2. Refuse the request if t is more than 5 minutes from your clock.
  3. Compute the HMAC-SHA256 of t + "." + raw body with your signing secret (gcs_…).
  4. Compare it with every v1 in constant time. Accept if one matches.
verify.ts
import { createHmac, timingSafeEqual } from "node:crypto";
/**
* Verifies a VoltPay Callback. `rawBody` is the request body exactly as it arrived,
* before any JSON parsing; `header` is the Gateway-Signature header; `secret` is the
* Callback Endpoint's signing secret (gcs_…). Returns false for anything to refuse.
*/
export function verifyCallback(rawBody: string | Buffer, header: string, secret: string, now = Date.now() / 1000): boolean {
let timestamp = "";
const signatures: string[] = [];
for (const part of header.split(",")) {
const [key, value = ""] = part.split("=", 2);
if (key === "t") timestamp = value;
if (key === "v1") signatures.push(value);
}
if (!/^\d+$/.test(timestamp) || Math.abs(now - Number(timestamp)) > 300) return false;
const expected = createHmac("sha256", secret).update(`${timestamp}.`).update(rawBody).digest();
return signatures.some((signature) => {
const given = Buffer.from(signature, "hex");
return given.length === expected.length && timingSafeEqual(given, expected);
});
}
// Express: take the body raw on this route only.
app.post("/voltpay/callback", express.raw({ type: "application/json" }), (req, res) => {
const header = req.get("Gateway-Signature") ?? "";
if (!verifyCallback(req.body, header, process.env.VOLTPAY_SIGNING_SECRET!)) return res.sendStatus(401);
const event = JSON.parse(req.body.toString("utf8"));
res.sendStatus(200);
});

Check your own code against this vector. Every example above is tested against it.

Input Value
Signing secret gcs_test_secret
Raw body {"id":"evt_1"}
Header t=1793980802,v1=7557486b97b75edc43c89b69295a55744315b465832e7ccb52746ea6c9cac27a

It verifies with your clock at 1793980802, and fails with another secret, a changed body, or a clock more than 300 seconds away.

  • Answer any 2xx within 10 seconds. Do slow work afterwards.
  • Expect duplicates. Deduplicate events by id. Credit each Payment once, by its Payment id.
  • Act on the state, not the event name. Credit when data.payment.status is confirmed. A retried event carries the Payment as it is now.
  • Credit data.payment.amount, what arrived, not requested_amount.
  • Check mode if one server receives live and test Callbacks.
Event When Default
payment.confirmed A Payment is confirmed. The one you must handle. Always on
payment.reversed A confirmed Payment disappeared from the chain. On
payment.seen A transfer matched but is not Final. Never credit from it. Off
checkout.expired A Checkout expired unpaid. Off
balance.low The Available Balance fell below your threshold. On
balance.empty New live Checkouts are being refused. On
test A Member pressed Send test Callback. When asked

A failed delivery is retried after about 10 seconds, 30 seconds, 1 minute, 5 minutes, 15 minutes, 30 minutes and 1 hour, then every 3 hours, for 3 days.

  • A Payment always gets its Callback, whatever your balance.
  • Down for longer? List what you missed with GET /v1/payments.

Each API Key has one Endpoint: a URL and a signing secret, under Developers in the Merchant Panel.

  • The URL must be https on a public host. Redirects are not followed.
  • Rotate secret issues a new secret. For 24 hours both sign every Callback, so the header carries two v1 values.
  • Deliveries lists every attempt for 90 days. Resend sends one again.
  • Send test Callback sends a signed test event, once.