When a payment changes state, LauncX POSTs a JSON callback to your registered URL from the outbound IPs.
Payload
| Field | Type | Notes |
|---|
orderId | string | Payment UUID. |
payerId | string | The playerId you supplied when creating the payment. |
status | string | PAID | EXPIRED | FAILED | PENDING. |
settlementStatus | string | PENDING | COMPLETED | FAILED. |
grossAmount | number | Original payment amount. |
feeLauncx | number | Platform fee charged. |
netAmount | number | grossAmount - feeLauncx. |
qrPayload | string | QRIS payload string. |
timestamp | string | RFC3339 UTC, e.g. 2026-06-15T08:42:11Z. |
nonce | string | Unique UUID per delivery (use for replay protection). |
{
"orderId": "9f2c1a4b-7c3e-4d9a-b8e2-3c1d5a6f0e21",
"payerId": "player-00123",
"status": "PAID",
"settlementStatus": "PENDING",
"grossAmount": 250000,
"feeLauncx": 1750,
"netAmount": 248250,
"qrPayload": "00020101021226680016ID.CO.QRIS.WWW...",
"timestamp": "2026-06-15T08:42:11Z",
"nonce": "a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d"
}
status reflects the payment lifecycle; settlementStatus tracks settlement independently (COMPLETED once settled, FAILED if the payment expired/failed, otherwise PENDING).
Verifying the signature
Each delivery includes an HMAC signature header:
| Header | Value |
|---|
X-Callback-Signature | hex( HMAC_SHA256( rawRequestBody, CallbackSecret ) ) |
X-Callback-Signature.
Delivery & retries
- Up to 4 attempts with backoff (immediate, 1s, 2s).
- Any
2xx response is treated as success; respond 2xx quickly and process asynchronously.
