A charge or payout moves through a set of statuses from creation to a terminal state. Gozem-channel operations are approved in the app and can resolve quickly; PSP-channel operations (flooz-tg, yas-tg) return a pending acknowledgement and settle asynchronously. Either way, the reliable way to learn the outcome is a webhook — do not poll on a tight loop. The status on the transaction always holds the current state.
Charge statuses
| Status | Meaning | Terminal | Webhook event |
|---|---|---|---|
PENDING |
Created; awaiting payer approval or PSP confirmation | No | — |
COMPLETED |
Funds settled into your merchant account | Yes | money.charge.completed |
FAILED |
The provider or wallet rejected the charge | Yes | money.charge.failed |
CANCELLED |
Payer cancelled, or the charge expired before approval | Yes | money.charge.cancelled |
Payout statuses
| Status | Meaning | Terminal | Webhook event |
|---|---|---|---|
PENDING |
Accepted or in flight with the provider | No | — |
COMPLETED |
Funds delivered to the beneficiary | Yes | money.payout.completed |
FAILED |
The provider rejected the payout | Yes | money.payout.failed |
CANCELLED |
Cancelled before execution | Yes | money.payout.cancelled |
REVERSED |
Funds returned after an initial completion (rare; PSP-driven) | Yes | money.payout.reversed |
Webhooks fire on terminal states only. A create call returns a reference; use the matching GET endpoint to read the current state at any time as a fallback or for reconciliation.
Webhook events
Only charges and payouts emit webhooks, and only when they reach a terminal state. The read-only endpoints (transaction-details, account) do not emit events, so the delivery and retry behaviour below applies solely to charge and payout notifications.
Configure your webhook URL and subscribe to these events in the Partner Portal. Each event’s data object carries the transaction — identifiers, amount, channel, and status.
Charge: money.charge.completed, money.charge.failed, money.charge.cancelled
Payout: money.payout.completed, money.payout.failed, money.payout.cancelled, money.payout.reversed
Delivery and verification
The general handling advice in the platform Webhooks guide applies — respond 2xx quickly, process in the background, and de-duplicate. But the Money API uses its own signature scheme and retry cadence (below), which differ from the platform defaults, so verify against these headers:
| Header | Description |
|---|---|
X-Gozem-Event-Id |
Unique event id — de-duplicate on it. |
X-Gozem-Timestamp |
Unix time in milliseconds, as a string. |
X-Gozem-Signature |
HMAC-SHA256 for verification (below). |
Recompute and compare in constant time:
expected = HMAC_SHA256(webhook_secret, X-Gozem-Timestamp + "." + raw_body)Verify against the raw request body (not a re-serialized copy), and reject if the signature mismatches or the timestamp is more than 5 minutes old.
Retries
A non-2xx response is retried with exponential backoff — 1m, 5m, 15m, 1h, 6h, 24h (up to 6 attempts). This is the Money API’s own schedule and is longer than the platform default of three short retries. Events may therefore arrive more than once and out of order; handle them idempotently on X-Gozem-Event-Id and trust the transaction’s own timestamps over arrival order. Failed deliveries can be inspected and replayed from the Partner Portal.