Orders
An order is one payment by one customer. Your server creates it, the customer pays it, and we close it with a callback.
Create an order
POST /gw/v1/orders
| Field | Type | Required | Meaning |
|---|---|---|---|
amount | number | yes | What the customer pays, in currency. Must be greater than zero; two decimals are kept. |
currency | string | no | ISO 4217 code. Default RUB. Must be enabled on the platform, priceable, and allowed on the cash desk. |
rail | string | depends | Sbp, C2c or Phone. May be omitted when the cash desk allows exactly one rail; required when it allows several. |
orderRef | string | no | Your own identifier, up to 255 characters. Makes the call idempotent for one hour. |
notifyUrl | string | no | Callback URL for this order. Falls back to the cash desk's URL; one of the two is required. Validated: see below. |
successUrl | string | no | Where the payment page sends the customer after a successful payment. |
failUrl | string | no | Where the payment page sends the customer after a cancelled or expired order. |
backUrl | string | no | The "back to the shop" link used when the two above are not set. |
lifetimeMinutes | integer | no | How long the payment details stay valid, 1 to 1440. Default 15. |
operator | string | no | For the Phone rail only: MTS, Beeline, Megafon, Tele2, Yota. |
targetBank | string | depends | The bank the customer pays from, as a key from GET /gw/v1/banks. Required on a Monobank cash desk: the details then belong to exactly that bank, and payment.bank carries its key. On other methods it is passed to the provider as a preference. |
receipt | object | no | The payment receipt, { "fileName": "…", "contentBase64": "…" }. See Receipt with the order. |
Receipt with the order
Usually the receipt appears only after the customer paid, so it is sent with Add a receipt once the order exists. When it is already at hand as the order is created, it can go in the same call instead. The file travels base64-encoded inside the JSON, so it is signed with the rest of the body: no multipart and no separate upload.
POST /gw/v1/orders
{
"amount": 10000,
"currency": "RUB",
"rail": "C2c",
"orderRef": "your-order-42",
"receipt": { "fileName": "receipt.pdf", "contentBase64": "JVBERi0xLjQK…" }
}
The receipt is stored with the order and shown to the platform's reviewers, including on any
appeal opened for it later. receipts in the response and in GET /gw/v1/orders/{id} counts
what the order holds. Formats, size limit and error codes are those of
appeal receipts: pdf, jpg, jpeg, png, gif, webp, heic, mp4, mov, up
to 10 MB, content checked against the extension.
The file is checked first. A refused file answers 400 RECEIPT_* and creates no order, so the
call can be repeated as is with a good file. A repeat with the same orderRef returns the
existing order and adds the receipt it carries to it.
What we validate, in order
- The receipt, when sent:
RECEIPT_*codes, see above. - The merchant account is active and not blocked, else
MERCHANT_INACTIVE. - The cash desk is enabled by you, else
SHOP_INACTIVE; and not stopped by the platform, elseSHOP_STOPPED. - A callback URL exists, else
CALLBACK_URL_REQUIRED; and it passes the URL rules, elseINVALID_CALLBACK_URL. - The rail is resolvable:
RAIL_REQUIRED,INVALID_RAILorRAIL_NOT_ENABLEDotherwise. - The currency exists and is enabled, has a rate source, and is allowed on the cash desk:
INVALID_CURRENCY,CURRENCY_NOT_PAYABLE,CURRENCY_NOT_ENABLED. - A rate is available now, else
FX_RATE_UNAVAILABLE. The USD amount is computed. - The USD amount is within the cash desk limits, else
AMOUNT_BELOW_MINorAMOUNT_ABOVE_MAX. - No turnover limit is reached, else
TRAFFIC_LIMIT_REACHED. - If
orderRefwas seen for this cash desk in the last hour, the existing order is returned and nothing below runs. - The cascade looks for a provider. None found:
503 NO_AVAILABLE_METHOD, or400 MERCHANT_NOT_APPROVEDfor an account still under review.
Callback URL rules
The address must be an absolute https:// or http:// URL to a public host. We refuse
localhost, loopback, link-local, private ranges (10/8, 172.16/12, 192.168/16,
100.64/10), cloud metadata hosts, and any hostname that resolves to one of those. The check
runs when the order is created and again before every delivery, so a name that later points
inside a private network stops receiving callbacks.
Response
201 Created:
{
"status": "ok",
"result": {
"id": "ord_01M1P932FS0FQPNM3T63KM2XAT",
"orderRef": null,
"amount": "5000.00",
"currency": "RUB",
"settled": { "amount": "54.71000000", "currency": "USD", "rate": "91.40000000" },
"method": "Classic",
"rail": "Sbp",
"direction": "In",
"status": "Created",
"payment": {
"url": null,
"card": null,
"phone": "+79001234567",
"account": null,
"iban": null,
"upiId": null,
"holder": "I. IVANOV",
"bank": "Sberbank"
},
"commission": { "rate": "3.5000", "amount": "1.91485000", "currency": "USD" },
"credited": { "amount": "52.79515000", "currency": "USD" },
"receipts": 0,
"createdAt": "2026-09-04T15:05:00Z",
"expiresAt": "2026-09-04T15:20:00Z"
},
"traceId": "0HN7A9K2M4P1X"
}
commission is the platform's fee under your tariff, quoted at creation: rate is the
percentage, amount the fee in USD, and credited.amount is what lands on your balance once
the order completes, which is settled.amount minus the fee. The quote is recomputed at
completion against the tariff in force at that moment, so the two only differ if your tariff was
changed while the order was open.
payment holds what the customer needs, keyed by what the value is: phone for SBP and phone
transfers, card for card transfers (C2c, Kaspi, Uzcard, Humo), account for a Korean
bank account, iban for Turkey (Iban, Havale), upiId for India, url when the provider
hosts its own page. On Kaspi both card and phone are filled and belong to the same
recipient. Every key is always present; the ones the rail does not use are null. Show them
yourself, or send the customer to the payment page.
For Upi, the customer's bank gives them a UTR after the transfer. Our payment page asks for it
and stores it on the order; GET /gw/v1/orders/{id} returns it as payerReference. It is a
hint for matching the transfer, not a status: only the provider's confirmation completes an
order.
The rate is captured here
settled.rate is the number of units of currency per one USD, spread included, at the moment
of creation. It is never recalculated: however long the customer takes, the order settles at
this rate, and you are credited settled.amount minus the fee.
orderRef and idempotency
orderRef is your own identifier, up to 255 characters. Send it on every order and store our
id next to it.
For one hour per cash desk it also makes the call idempotent:
- a repeat while the order is open or paid returns the same order,
201, with its current status, so a retried request never creates a second payment; - a repeat once the order is cancelled or expired creates a new order, so a customer who comes back for the same purchase gets fresh payment details instead of the closed order;
- a repeat with a different amount or currency is refused with
409 ORDER_REF_CONFLICT: the reference already means something else; - a repeat that arrives while the first call is still choosing a provider is refused with
409 ORDER_IN_PROGRESS. The first call is still going to answer; nothing was created twice. Retry after a few seconds, orGET /gw/v1/orders/{orderRef}, and you get the order it made.
After the hour a repeat creates a new order.
Get an order
GET /gw/v1/orders/{id}
{id} is our ord_… id or your orderRef. When several orders share a reference, the newest
is returned.
{
"status": "ok",
"result": {
"id": "ord_01M1P932FS0FQPNM3T63KM2XAT",
"orderRef": "A-17",
"amount": "5000.00",
"currency": "RUB",
"settled": { "amount": "54.71000000", "currency": "USD", "rate": "91.40000000" },
"method": "Classic",
"rail": "Sbp",
"direction": "In",
"status": "Completed",
"subStatus": "SuccessfullyPaid",
"payment": { "url": null, "card": null, "phone": "+79001234567", "account": null, "iban": null, "upiId": null, "holder": "I. IVANOV", "bank": "Sberbank" },
"payerReference": null,
"commission": { "rate": "3.5000", "amount": "1.91485000", "currency": "USD" },
"credited": { "amount": "52.79515000", "currency": "USD" },
"cancelReason": null,
"receipts": 0,
"appeal": null,
"createdAt": "2026-09-04T15:05:00Z",
"expiresAt": "2026-09-04T15:20:00Z",
"finishedAt": "2026-09-04T15:07:41Z"
},
"traceId": "0HN7A9K2M4P1X"
}
commission and credited carry the quote from creation while the order is open and the final
split once it completes. You do not need to poll: the callback arrives on its own. GET is for
reconciliation and for support.
receipts is how many receipts the order holds. appeal is the order's latest
appeal, { "id": "apl_…", "status": "Open" }, or null when there is none.
Add a receipt after payment
The customer paid and shows you the receipt: send it to us right away, without waiting for the order to close.
POST /gw/v1/orders/{id}/receipts
{ "fileName": "receipt.pdf", "contentBase64": "JVBERi0xLjQK…" }
{id} is our ord_… id or your orderRef. The file is base64 inside the JSON and signed with
the body like any other request. Formats, size limit and 400 RECEIPT_* codes are those of
appeal receipts. The answer is 201 with the order as in
Get an order, receipts one higher. Several receipts can be sent, one per call.
What happens next depends on the order:
| Order | What the receipt does |
|---|---|
| Still open | Waits on the order. If the payment is confirmed, the order completes as usual. If the order expires or is cancelled without a credit, an appeal with the receipt opens by itself and you get the order.appealed callback. |
Canceled | Opens the appeal at once; the answer already shows status: "Dispute" and appeal. |
Dispute | Is added to the open appeal. |
Completed | Refused with 409 ORDER_ALREADY_COMPLETED, nothing is stored. |
So the appeal never has to wait for the timer: the receipt sent after payment is the claim, and the platform opens the appeal the moment the order closes without the money.
Cancel an order
POST /gw/v1/orders/{id}/cancel
{ "reason": "customer changed their mind" }
The body is optional; reason is stored on the order and shown in the cabinet. Only unpaid
orders can be cancelled: a Completed order answers 409 ORDER_ALREADY_COMPLETED. Cancelling an
already cancelled order is a no-op. A cancellation sends order.cancelled to your callback URL;
when the order holds a receipt, an appeal opens right after it.
Statuses
status | Meaning |
|---|---|
Created | Accepted; payment details issued; waiting for the customer. |
Payed | The provider reports a payment; the platform is confirming that the money landed. Not credited yet. |
Completed | Confirmed and credited to your balance. Terminal. |
Canceled | Closed without payment: expired, cancelled by you, or rejected. Terminal unless an appeal reopens it. |
Dispute | An appeal is open on this order. |
CompletedOnDispute | Reserved for an appeal outcome; today an accepted appeal completes the order as Completed. |
WaitingPayment | Reserved; not currently assigned. Treat like Created. |
subStatus adds detail: WaitingForPayment, WaitingAdminConfirmation, SuccessfullyPaid,
Cancelled, Expired. Branch on status; use subStatus for display.
Expiry
An order expires at expiresAt, lifetimeMinutes after creation. A worker checks every
200 milliseconds and cancels expired orders with subStatus: "Expired" and cancelReason: "expired", sending order.cancelled. A payment that arrives after expiry is not lost: the
provider's confirmation reaches us, support reconciles it, and the order completes with the
usual callback. If the customer says they paid after the timer ran out, open an
appeal.
Why an order sits in Payed
Payed means the provider said the customer paid, but the platform has not yet confirmed that
the funds arrived on its side. Live orders wait for that confirmation before the credit; the
callback comes with Completed. Sandbox orders skip the wait.