Payment Webhooks - LauncX API

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 ) )`

Compute the HMAC-SHA256 of the raw request body bytes (all ten fields, exactly as received — do not re-serialize) using your Callback Secret, hex-encode it, and compare against 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.