Payouts, refunds and status lookups
What each is for, and when to poll versus wait for a webhook.
Payouts
POST /atlas/payout sends money to a recipient —
the reverse of a payment. It needs project, amount, currency and
external_id, plus whatever recipient details the payout method needs (card,
IBAN, crypto address, and so on — see the reference page).
external_id here isn't a convenience the way it is on a payment — it's your
idempotency key, and it's load-bearing: the platform debounces payout
creation on it. Sending the same external_id twice doesn't create a second
payout; it returns the one already on file, in whatever state it has since
reached.
The response tells you where the payout stands the moment it's created, not where it ends up:
{
"success": true,
"data": {
"id": "payout_abc123",
"status": "ROUTED",
"sub_status": "AWAITING_APPROVAL",
"external_id": "cashout-1042"
},
"timestamp": "2026-07-02T00:00:00.000Z"
}A payout this call just created is status: "ROUTED" in the common case — a
payout that fails outright during creation (no matching scenario, no usable
route, no wallet to debit, and a few others) ends the request as an error
instead (a 422, same shape as the payment case — see the reference page),
so that class of failure is never handed back as a success.
The exception is a project with auto_approve set: the approval a human
would otherwise give runs inline, in the same request, so the response can
carry the payout further than ROUTED before it ever reaches you —
APPROVED if approval committed but dispatch didn't run, PROCESSING if the
provider was reached, or even FAILED if dispatch itself failed after
approval. That FAILED still arrives as a 201, not a 422: the payout has a real
id and a real reason by then, and you're better served by both than by an
error. Don't assume ROUTED from a 2xx alone — read status (and, on
FAILED, sub_status) instead.
Insufficient wallet balance is a 400, not a 422, and its body doesn't
follow the usual error shape — no statusCode, no error:
{ "code": "NOT_ENOUGH_BALANCE_ERROR", "message": "Not enough balance." }That's a fixed contract, not a generic message — merchant integrations are
written against that exact string. The external_id you sent is freed
rather than consumed: the payout row is kept as a terminal FAILED record,
but it's excluded from the debounce lookup that runs on a repeat request, so
topping up the wallet and resending the same external_id creates a new
payout rather than returning the refused one.
sub_status narrows that down further — AWAITING_APPROVAL for a fresh
payout. In this create response it's always present as a key even though,
like redirect_url on a payment, it's an empty string for a status the state
machine pairs with none (CREATED, COMPLETED, PARTIALLY_COMPLETED). The
status lookup and the webhook below both do the opposite — they omit
sub_status entirely rather than send it empty — so don't carry an
assumption about the key being there from one response to the others.
Unless auto_approve carried it further in the create call, everything past
that — approval, dispatch to the provider, settlement — moves on a separate,
operator- and worker-driven path the POST /atlas/payout response doesn't
expose. Either way, settlement always does. To follow a payout past creation, poll
POST /atlas/payout/status: it takes
project plus exactly one of payout_id or external_id — sending neither
is refused, and so is sending both — and answers with the payout's current
amount, currency, status, created_at and updated_at, plus
sub_status, external_id and the gate_amount/gate_currency conversion
pair when the payout has them.
You don't have to poll, though. Send the optional callback_url field on
POST /atlas/payout and Atlas posts a signed
webhook to that URL as the payout resolves — the same delivery machinery that
carries a payment's callbacks, with the same retry ladder, the same 24-hour
ceiling and the same best-effort coalescing described on
Webhooks. Omit callback_url and nothing is delivered;
polling payout/status is then the whole of it.
A callback isn't reserved for outcomes: PROCESSING, COMPLETED,
PARTIALLY_COMPLETED, FAILED, EXPIRED and CANCELED each produce one —
PROCESSING marks the payout leaving your side for the provider, and isn't
final; the rest are how it ends up. CREATED, ROUTED and APPROVED don't
produce one, because they're internal steps on the way to dispatch and
nothing has happened to the money yet. CANCELED carries more weight here
than anywhere on the payment side: an operator can reject a payout, and since
you have no cancel endpoint to have called yourself, the webhook is the only
way you find out without polling for it.
The body is a payment's webhook body plus one field:
{
"id": "payout_abc123",
"external_id": "cashout-1042",
"amount": "50.00",
"currency": "USD",
"status": "FAILED",
"sub_status": "PROVIDER_DECLINED",
"updated_at": "2026-07-07T14:30:00Z",
"created_at": "2026-07-07T14:28:00Z",
"signature": "1401d5fba153df68975cab11bdedeb40c369f8c932c5f6473229fcf63cab0c2b"
}sub_status is that extra field, and it's the reason a payout webhook is
worth more than a bare status change: whichever of the delivered statuses
sent it, the detail arrives already attached, rather than needing a
follow-up call to find out. Each status has its own vocabulary — the same
one payout/status returns:
| Status | sub_status |
|---|---|
PROCESSING | SENT_TO_PROVIDER, POLLING_ABANDONED |
FAILED | NOT_ENOUGH_BALANCE, NO_SCENARIO, NO_ROUTE, NO_WALLET, NO_BASE_CURRENCY, RATE_UNAVAILABLE, INVALID_FORMULA, ALL_ROUTES_FAILED, PROVIDER_DECLINED, CUSTOMER_BANNED |
CANCELED | REJECTED_BY_OPERATOR, CANCELED_BY_MERCHANT, CANCELED_BY_PROVIDER |
EXPIRED | NOT_APPROVED_IN_TIME |
COMPLETED, PARTIALLY_COMPLETED | none — omitted from the body |
A FAILED payout, like the example below, arrives with PROVIDER_DECLINED
or whichever of that row's reasons applies — never REJECTED_BY_OPERATOR or
NOT_APPROVED_IN_TIME, which only ever accompany CANCELED and EXPIRED.
Like external_id, gate_amount and gate_currency, sub_status is
omitted entirely when it's empty rather than sent blank, so read it as an
optional key, not a guaranteed one.
The signature is built exactly as a payment's is: take the values of the
fields actually present (everything but signature), sort the values, join
them with |, and HMAC-SHA256 the result under your hex-decoded merchant
secret. For the body above, with secret (hex) a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6
— the same secret used in the webhooks example
— that's:
2026-07-07T14:28:00Z|2026-07-07T14:30:00Z|50.00|FAILED|PROVIDER_DECLINED|USD|cashout-1042|payout_abc123which produces the signature value in the body above. That's the webhook
rule, and it is not the rule for signing a request you send —
that one sorts field names, not values, and the two
produce different strings from the same data. Whatever you already wrote to
verify payment callbacks verifies these unchanged; your request signer does
not. See Verifying the signature.
Refunds
POST /atlas/refund refunds a payin you already
created, by its payin_id. description is the only other field, and it's
optional — free text explaining why.
A refund is idempotent too, like a payout — just keyed differently. A payout
debounces on the external_id you choose; a refund debounces on payin_id
itself, since a payin only ever needs one refund. Send the same payin_id
again and you get back the refund already on file, whatever its status,
rather than a second attempt. That includes a failed one: the lookup
doesn't distinguish by status, so resending the same payin_id after a
failed attempt returns that same failure again — it does not retry the
provider. If a refund fails, resending isn't the fix; get in touch about the
underlying payin before trying again.
The response is a refund status object, returned synchronously — you already
know the outcome from the 201:
{
"success": true,
"data": {
"id": "refund_1",
"reference_id": "payin_abc123",
"status": "processed",
"amount": "1.00",
"currency": "USD",
"provider_refund_id": "prov_1"
},
"timestamp": "2026-07-02T00:00:00.000Z"
}A payin that can't be refunded at all — it never completed, or its provider
doesn't support refunds — ends the request with a 422 rather than a refund
object; see the reference page for the rest of
those error cases. A provider that's asked and declines is different: the
request still succeeds (201), with a refund object whose status is
"failed" instead of "processed" — the same kind of object shown above,
not an error response. That's the failed refund the idempotency
paragraph above already refers to.
POST /atlas/refund/status looks that same
object up again later, by reference_id (the payin_id the refund was
created for). It signs just that one field — the canonical string is the bare
reference_id, nothing to join.
Payin status
POST /atlas/payin/status looks up a
payment's current state — the endpoint and its payin_id use the older name
for the same object — by project and exactly one of payin_id or
external_id; sending both, or neither, is a 400.
{
"success": true,
"data": {
"amount": "1.00",
"gate_amount": "1.00",
"currency": "USD",
"gate_currency": "USD",
"status": "completed",
"created_at": "2026-07-02T00:00:00.000Z",
"updated_at": "2026-07-02T00:00:00.000Z"
},
"timestamp": "2026-07-02T00:00:00.000Z"
}This lookup only covers recent history — the platform keeps a configurable
window, and a payin outside it comes back as a 404 indistinguishable from
one that never existed. It's a reconciliation tool, not an archive.
When to poll versus wait
For a payment, wait for the webhook. It's pushed to you the moment the
status changes, and coalescing means a stale status is dropped in favour of
one that's since overtaken it, so a delivery you do receive isn't behind
what Atlas already knows — see Webhooks. That
coalescing check is best-effort, and delivery itself can still be exhausted
by retries or the 24-hour ceiling, so treat the webhook as the primary
signal, not a guaranteed one: compare updated_at when you apply a status
rather than assuming arrival order, and reach for payin/status when you
have a specific reason to distrust that a webhook arrived at all — your
callback endpoint was down, you're reconciling after a deploy, or you want
to check on a payin before a webhook has had a realistic chance to arrive.
Polling it in a tight loop as your primary signal works against the same
coalescing check that makes the webhook usually-sufficient in the first
place, for no benefit.
For a refund, there's usually nothing to wait for — the create call's
response already carries the outcome. Use refund/status when you need to
look a refund up again from a different process, or after time has passed,
not as a follow-up to a refund call you just made.
For a payout, it depends on what you sent. If you supplied a callback_url,
treat it as you would a payment, with one difference: a payout's webhook can
arrive more than once before the payout is done. PROCESSING is delivered
too, and it isn't final — only COMPLETED, PARTIALLY_COMPLETED, FAILED,
EXPIRED and CANCELED are. Wait for one of those, not for the first
delivery, and use payout/status to reconcile when you have a specific
reason to doubt one turned up. If you didn't supply a callback_url,
payout/status is your only signal — poll it on a timer rather than in a
loop, since a payout waits on approval and dispatch before anything it
reports can change.