Skip to main content

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: settled and debited.
  • If the payout fails, everything that was debited comes back, exactly once, and you get a payout.failed callback.
  • 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.

FieldRequired
amountyesWhat the customer receives, in currency.
currencynoISO 4217; RUB when omitted.
railyesc2c (card) or sbp (phone).
payoutRefyesYour id, unique per cash desk. It makes the call safe to retry (see below).
recipient.cardfor c2c16–19 digits; checked with the Luhn algorithm.
recipient.phonefor sbpA Russian mobile: +7…, 8… or ten digits.
recipient.holderyesThe recipient's full name as the bank holds it.
recipient.bankfor sbpThe bank the phone is registered with.
notifyUrlnoWhere 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}
statussubStatusMeaning
PendingAwaitingApprovalHeld for the platform's operator to approve.
PendingQueued, DispatchingBeing sent to a provider.
PendingProcessingByProviderA provider accepted it; the transfer is in progress.
PendingAwaitingReviewThe provider's answer was unclear (no answer, an error after the request). The amount stays debited while we confirm whether the transfer went through.
SuccessCompletedPaid out.
FailDeclinedByProviders, FailedAtProvider, RejectedByOperatorNot 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​

HTTPfault.codeWhat to do
403PAYOUTS_DISABLEDAsk support to enable payouts on the cash desk.
400PAYOUT_TARIFF_MISSINGAsk support to set a payout rate for this method.
400PAYOUT_REF_REQUIRED, PAYOUT_REF_INVALIDSend a payoutRef of up to 255 characters.
409PAYOUT_REF_CONFLICTThe payoutRef already names a different payout.
402INSUFFICIENT_BALANCEThe balance is below the amount plus commission.
400RAIL_REQUIRED, RAIL_NOT_SUPPORTEDUse c2c or sbp.
400CARD_INVALID, PHONE_INVALIDCheck the card or phone number.
400HOLDER_REQUIREDSend the recipient's name.
400BANK_REQUIRED, BANK_UNKNOWNSBP needs a bank from GET /gw/v1/banks.
403MERCHANT_NOT_APPROVEDUntil approval, payouts work on a test cash desk only.
404PAYOUT_NOT_FOUNDThe 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.