API docs v1
Aggregator API · v1

Settlements

Verify signed settlement callbacks, preserve decimal amounts, and recover failed deliveries safely.

On this page

For system boundaries, an architecture diagram and failure-test scenarios, read the wallet settlement architecture guide. This page is the callback contract; the architecture guide explains how to design your receiver around it.

Callback management#

Configure an HTTPS callback URL and signing secret in Workspace Settings before real-money launch. The gateway sends JSON settlements to your callback. It maps member_account to your original player username.

json
{
  "game_uid": "737",
  "game_round": "round-123",
  "member_account": "player-1001",
  "bet_amount": 10,
  "win_amount": 5,
  "credit_amount": 995,
  "serial_number": "settle-unique-123",
  "game_name": "Example game"
}

Verify the signature#

x-callback-signature is sha256= followed by the hexadecimal HMAC-SHA256 of the exact delivered body bytes, using your callback signing secret. Verify before JSON parsing or business processing. Do not reserialize the body to compute the signature.

js
import { createHmac, timingSafeEqual } from 'node:crypto';

// rawBody is the untouched request Buffer; signature is the header string.
function verifyCallback(rawBody, signature, secret) {
  if (!/^sha256=[a-f0-9]{64}$/.test(signature ?? '')) return false;
  const expected = createHmac('sha256', secret).update(rawBody).digest();
  const received = Buffer.from(signature.slice(7), 'hex');
  return received.length === expected.length && timingSafeEqual(received, expected);
}

Other headers include x-callback-timestamp (milliseconds), x-callback-attempt, and x-callback-delivery. The HMAC covers the body only; these headers are not part of its input. Use the body serial_number as your financial deduplication key. The delivery header may encode that identifier as a hash for header safety.

Decimal precision and ordering#

bet_amount, win_amount, and credit_amount are JSON numbers. The gateway retains decimal values with up to 20 integer digits and 10 fractional digits. Use a lossless JSON/decimal parser and decimal storage; ordinary JavaScript JSON.parse converts numbers to binary floating point and can lose precision.

credit_amount is the authoritative player balance after the round. Do not reconstruct it from bet minus win. Associate it with the correct player, game currency, round, and session. The body may omit currency or session information; retain your launch records for reconciliation.

Handle each serial_number once, including concurrent duplicate delivery. Persist the event and wallet/bookkeeping update atomically, or durably enqueue it before returning HTTP 2xx. A duplicate already accepted should receive 2xx without applying funds again. Do not overwrite a newer balance with an older out-of-order snapshot; reconcile ordering from your records rather than assuming arrival order. Optional free_spin_bonus, timestamps, and game metadata are provider-dependent.

Delivery recovery#

Use the callback investigation checklist to check signatures, duplicate events, ordering, and unknown outcomes before attempting recovery.

Inspect Callback Deliveries for the event, amount, delivery state, and retry eligibility. Delivery is bounded to three total attempts, not unlimited automatic retries.

StateAction
deliveredReceiver returned 2xx; do not replay the financial update
failed / rejectedResolve the cause and use an eligible portal retry after confirming receiver deduplication
receivedAn undispatched first attempt may be eligible for recovery
forwardingDelivery is in progress; do not start another attempt
unknownReconcile your receiver ledger by serial_number with support before recovery

Manual retry requires callback-management permission and recent authentication with MFA. Delivered events, unknown outcomes, in-flight deliveries, and exhausted attempts cannot be blindly retried. Workspace state, callback configuration, and stored payload checks also apply.

Return 2xx promptly after durable acceptance. A timeout after dispatch can mean your receiver accepted the event even though the gateway did not see the acknowledgement.