Atlas API

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:

Statussub_status
PROCESSINGSENT_TO_PROVIDER, POLLING_ABANDONED
FAILEDNOT_ENOUGH_BALANCE, NO_SCENARIO, NO_ROUTE, NO_WALLET, NO_BASE_CURRENCY, RATE_UNAVAILABLE, INVALID_FORMULA, ALL_ROUTES_FAILED, PROVIDER_DECLINED, CUSTOMER_BANNED
CANCELEDREJECTED_BY_OPERATOR, CANCELED_BY_MERCHANT, CANCELED_BY_PROVIDER
EXPIREDNOT_APPROVED_IN_TIME
COMPLETED, PARTIALLY_COMPLETEDnone — 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_abc123

which 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.

On this page