Payouts
A payout sends money from your balance to your customer: to a card (c2c) or by SBP to a phone
(sbp). Support enables payouts per cash desk and sets their rate in the desk's tariff; until
both are in place a payout is refused with PAYOUTS_DISABLED or PAYOUT_TARIFF_MISSING.
How the money moves
- When a payout is accepted, its amount converted to USD plus the commission leaves your
balance at once. The response shows both:
settledanddebited. - If the payout fails, everything that was debited comes back, exactly once, and you get a
payout.failedcallback. - Credits from sandbox orders cannot fund a live payout.
- A payout from a test cash desk runs the whole flow through the sandbox but moves no money.
Send a payout
POST /gw/v1/payouts
{
"amount": 8000,
"currency": "RUB",
"rail": "c2c",
"payoutRef": "W-1042",
"recipient": { "card": "2200 1234 5678 9012", "holder": "IVAN IVANOV" },
"notifyUrl": "https://example.com/hooks/payouts"
}
By SBP: "rail": "sbp" and "recipient": { "phone": "+7 916 123-45-67", "holder": "IVAN IVANOV", "bank": "sberbank" },
with the bank from GET /gw/v1/banks.
| Field | Required | |
|---|---|---|
amount | yes | What the customer receives, in currency. |
currency | no | ISO 4217; RUB when omitted. |
rail | yes | c2c (card) or sbp (phone). |
payoutRef | yes | Your id, unique per cash desk. It makes the call safe to retry (see below). |
recipient.card | for c2c | 16–19 digits; checked with the Luhn algorithm. |
recipient.phone | for sbp | A Russian mobile: +7…, 8… or ten digits. |
recipient.holder | yes | The recipient's full name as the bank holds it. |
recipient.bank | for sbp | The bank the phone is registered with. |
notifyUrl | no | Where the result is posted; the cash desk's URL when omitted. |
A 201 returns the payout:
{
"id": "pay_01M6…",
"payoutRef": "W-1042",
"status": "Pending",
"subStatus": "Queued",
"amount": 8000.00,
"currency": "RUB",
"settled": { "amount": 100.00, "currency": "USD", "rate": 80.00 },
"commission": { "rate": 2.0, "amount": 2.00, "currency": "USD" },
"debited": { "amount": 102.00, "currency": "USD", "refunded": false },
"rail": "C2c",
"recipient": { "destination": "2200 •••• 9012", "holder": "IVAN IVANOV", "bank": null },
"failureReason": null,
"test": false,
"createdAt": "2026-11-02T10:15:00Z",
"finishedAt": null
}
The card or phone always comes back masked.
Retrying safely
Send the same payoutRef again with the same amount, currency and recipient and you get the
same payout back with 200 — never a second transfer. The same payoutRef with different terms
is refused with 409 PAYOUT_REF_CONFLICT. Use a new payoutRef for a new payout, including
after one failed.
Follow it
GET /gw/v1/payouts/{id or payoutRef}
status | subStatus | Meaning |
|---|---|---|
Pending | AwaitingApproval | Held for the platform's operator to approve. |
Pending | Queued, Dispatching | Being sent to a provider. |
Pending | ProcessingByProvider | A provider accepted it; the transfer is in progress. |
Pending | AwaitingReview | The provider's answer was unclear (no answer, an error after the request). The amount stays debited while we confirm whether the transfer went through. |
Success | Completed | Paid out. |
Fail | DeclinedByProviders, FailedAtProvider, RejectedByOperator | Not paid out; the debit was returned. |
AwaitingReview never turns into a refund on its own: returning money for a transfer that did
reach the customer would pay them twice. An operator settles it, and the callback follows.
The result
When the payout settles, a callback is posted, signed and retried exactly like order callbacks:
{
"event": "payout.completed",
"id": "pay_01M6…",
"payoutRef": "W-1042",
"status": "Success",
"subStatus": "Completed",
"amount": { "value": "8000.00", "currency": "RUB" },
"settled": { "value": "100.00000000", "currency": "USD", "rate": "80.00000000" },
"commission": { "rate": "2", "value": "2.00000000", "currency": "USD" },
"debited": { "value": "102.00000000", "currency": "USD", "refunded": false },
"method": "Classic",
"rail": "C2c",
"failureReason": null,
"occurredAt": "2026-11-02T10:16:12Z"
}
payout.failed carries "status": "Fail", "refunded": true and the reason in failureReason.
The recipient's card or phone is never part of a callback.
Errors
| HTTP | fault.code | What to do |
|---|---|---|
| 403 | PAYOUTS_DISABLED | Ask support to enable payouts on the cash desk. |
| 400 | PAYOUT_TARIFF_MISSING | Ask support to set a payout rate for this method. |
| 400 | PAYOUT_REF_REQUIRED, PAYOUT_REF_INVALID | Send a payoutRef of up to 255 characters. |
| 409 | PAYOUT_REF_CONFLICT | The payoutRef already names a different payout. |
| 402 | INSUFFICIENT_BALANCE | The balance is below the amount plus commission. |
| 400 | RAIL_REQUIRED, RAIL_NOT_SUPPORTED | Use c2c or sbp. |
| 400 | CARD_INVALID, PHONE_INVALID | Check the card or phone number. |
| 400 | HOLDER_REQUIRED | Send the recipient's name. |
| 400 | BANK_REQUIRED, BANK_UNKNOWN | SBP needs a bank from GET /gw/v1/banks. |
| 403 | MERCHANT_NOT_APPROVED | Until approval, payouts work on a test cash desk only. |
| 404 | PAYOUT_NOT_FOUND | The payout does not belong to this cash desk. |
In the sandbox
A test cash desk sends its payouts to the sandbox. Open the payout in the cabinet's Payouts page and press Paid out or Failed to settle it the way a provider would; the callback follows as it would in production.