Handle Callbacks
A Callback is a signed POST from VoltPay to your server. It is what you credit from.
The request
Section titled “The request”POST /your/callback HTTP/1.1Content-Type: application/jsonUser-Agent: gateway-callback/1Gateway-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.
Verify the signature
Section titled “Verify the signature”Gateway-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256(signing secret, "<t>.<raw body>")>- Read the body as raw bytes, before any JSON parsing.
- Refuse the request if
tis more than 5 minutes from your clock. - Compute the HMAC-SHA256 of
t + "." + raw bodywith your signing secret (gcs_…). - Compare it with every
v1in constant time. Accept if one matches.
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);});package voltpay
import ( "crypto/hmac" "crypto/sha256" "encoding/hex" "strconv" "strings" "time")
// VerifyCallback reports whether header, the Gateway-Signature header, signs body with// secret, the Callback Endpoint's signing secret (gcs_…), within five minutes of now.// body is the request body exactly as it arrived, before any JSON parsing.func VerifyCallback(body []byte, header, secret string, now time.Time) bool { var stamp string var signatures []string for _, part := range strings.Split(header, ",") { key, value, _ := strings.Cut(part, "=") switch key { case "t": stamp = value case "v1": signatures = append(signatures, value) } } unix, err := strconv.ParseInt(stamp, 10, 64) if err != nil || now.Sub(time.Unix(unix, 0)).Abs() > 5*time.Minute { return false }
mac := hmac.New(sha256.New, []byte(secret)) mac.Write([]byte(stamp + ".")) mac.Write(body) expected := mac.Sum(nil) for _, signature := range signatures { given, err := hex.DecodeString(signature) if err == nil && hmac.Equal(given, expected) { return true } } return false}body, err := io.ReadAll(http.MaxBytesReader(w, r.Body, 1<<20))if err != nil || !voltpay.VerifyCallback(body, r.Header.Get("Gateway-Signature"), secret, time.Now()) { http.Error(w, "bad signature", http.StatusUnauthorized) return}<?php
/** * Verifies a VoltPay Callback. $rawBody is the request body exactly as it arrived * (file_get_contents('php://input')); $header is the Gateway-Signature header; * $secret is the Callback Endpoint's signing secret (gcs_…). */function voltpay_verify_callback(string $rawBody, string $header, string $secret, ?int $now = null): bool{ $timestamp = ''; $signatures = []; foreach (explode(',', $header) as $part) { [$key, $value] = array_pad(explode('=', $part, 2), 2, ''); if ($key === 't') { $timestamp = $value; } elseif ($key === 'v1') { $signatures[] = $value; } } if (!ctype_digit($timestamp) || abs(($now ?? time()) - (int) $timestamp) > 300) { return false; }
$expected = hash_hmac('sha256', $timestamp . '.' . $rawBody, $secret); foreach ($signatures as $signature) { if (hash_equals($expected, strtolower($signature))) { return true; } } return false;}$raw = file_get_contents('php://input');$header = $_SERVER['HTTP_GATEWAY_SIGNATURE'] ?? '';if (!voltpay_verify_callback($raw, $header, getenv('VOLTPAY_SIGNING_SECRET'))) { http_response_code(401); exit;}$event = json_decode($raw, true);import hashlibimport hmacimport time
def verify_callback(raw_body: bytes, header: str, secret: str, now: float | None = None) -> bool: """Verifies a VoltPay Callback.
raw_body 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_...). """ timestamp = "" signatures = [] for part in header.split(","): key, _, value = part.partition("=") if key == "t": timestamp = value elif key == "v1": signatures.append(value) if not timestamp.isdigit(): return False if abs((time.time() if now is None else now) - int(timestamp)) > 300: return False
expected = hmac.new(secret.encode(), timestamp.encode() + b"." + raw_body, hashlib.sha256).hexdigest() return any(hmac.compare_digest(expected, signature.lower()) for signature in signatures)# Flask: request.get_data() returns the raw bytes.@app.post("/voltpay/callback")def voltpay_callback(): if not verify_callback(request.get_data(), request.headers.get("Gateway-Signature", ""), SIGNING_SECRET): abort(401) event = request.get_json() return "", 200Check 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.
Handle it
Section titled “Handle it”- Answer any
2xxwithin 10 seconds. Do slow work afterwards. - Expect duplicates. Deduplicate events by
id. Credit each Payment once, by its Paymentid. - Act on the state, not the event name. Credit when
data.payment.statusisconfirmed. A retried event carries the Payment as it is now. - Credit
data.payment.amount, what arrived, notrequested_amount. - Check
modeif one server receives live and test Callbacks.
Events
Section titled “Events”| 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 |
Retries
Section titled “Retries”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.
The Callback Endpoint
Section titled “The Callback Endpoint”Each API Key has one Endpoint: a URL and a signing secret, under Developers in the Merchant Panel.
- The URL must be
httpson 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
v1values. - Deliveries lists every attempt for 90 days. Resend sends one again.
- Send test Callback sends a signed
testevent, once.