Appeals
Only a Canceled order can be appealed: one that expired or was cancelled without a credit.
While an order is still open the provider may confirm it any moment, so an appeal on it is
refused with 409 ORDER_STILL_OPEN. There is no need to wait for the expiry, though: send the
receipt to the open order with
POST /gw/v1/orders/{id}/receipts, and if the order
closes without a credit the appeal opens by itself. If the payment is confirmed while an appeal
is open, the order completes and the appeal closes as accepted on its own.
An appeal is for one situation: the customer paid, but the order closed without a credit. It opens a review by the platform; when accepted, the order is completed and credited as usual.
When to open one
Most appeals do not need to be opened by hand: a receipt sent to the order after payment turns into an appeal by itself when the order closes without a credit. Opening one directly is for the cases below, after the order is already closed.
- The order expired or was cancelled, and the customer shows a receipt for the transfer.
- The customer paid a different amount, or paid after the timer ran out.
- The provider reported a failure, but the money left the customer's account.
Do not open an appeal for an order that is simply still waiting: it has not been closed yet, and the callback will come. And do not open one to ask a question; that is what support is for.
Open an appeal
POST /gw/v1/appeals
{
"orderId": "ord_01M1P932FS0FQPNM3T63KM2XAT",
"reason": "the customer sent 5000 RUB at 14:32 to the phone shown",
"evidenceUrl": "https://example.com/receipts/a-17.png"
}
orderId is our id or your orderRef. reason and the receipt are optional, but a review
without a receipt takes longer and is more likely to be rejected.
The receipt can be sent two ways, or both:
receipt: the file itself, base64-encoded in the JSON body. It is signed like any other request body, so no multipart and no separate upload step. See Receipt files.evidenceUrl: a link the reviewer can open; several can be separated by semicolons.
POST /gw/v1/appeals
{
"orderId": "ord_01M1P932FS0FQPNM3T63KM2XAT",
"reason": "the customer sent 5000 RUB at 14:32 to the phone shown",
"receipt": { "fileName": "receipt-A-17.pdf", "contentBase64": "JVBERi0xLjQK…" }
}
Response 201:
{
"status": "ok",
"result": {
"id": "apl_01M27P9BYTMMVR8RPGB1K7VEAX",
"orderId": "ord_01M1P932FS0FQPNM3T63KM2XAT",
"orderRef": "A-17",
"status": "Open",
"amount": { "value": "54.71000000", "currency": "USD" },
"reason": "the customer sent 5000 RUB at 14:32 to the phone shown",
"receipts": 1,
"comment": null,
"slaDueAt": "2026-09-05T15:07:41Z",
"createdAt": "2026-09-04T15:07:41Z",
"resolvedAt": null
}
}
Rules:
- Only a
Canceledorder can be appealed. An order still waiting for payment answers409 ORDER_STILL_OPEN, a credited one409 ORDER_ALREADY_COMPLETED. - One open appeal per order. A repeat returns the existing appeal with
201, so a retried request cannot open two. A receipt sent with the repeat is added to that appeal. receiptscounts the receipts the reviewer has, files and links together.- Opening an appeal moves the order to
Disputeand sendsorder.appealedto your callback URL. amountis the settlement amount of the order at the time of the appeal, fixed even if rates move later.
The same appeal can be opened from the order page in the cabinet, where receipts are uploaded as files (several at once) and a link can go with them.
Add a receipt to an open appeal
An appeal opened without a receipt, or one where the customer found a better screenshot later,
takes more files while it is Open:
POST /gw/v1/appeals/{id}/receipts
{ "fileName": "screenshot.png", "contentBase64": "iVBORw0KGgo…" }
{id} is the apl_… id. The answer is 201 with the appeal, receipts now one higher.
Receipts accumulate; a second file does not replace the first. A decided appeal answers
409 APPEAL_CLOSED.
Receipt files
| Formats | pdf, jpg, jpeg, png, gif, webp, heic, mp4, mov |
| Size | up to 10 MB before encoding |
fileName | required; its extension sets the type |
contentBase64 | standard base64; a data:…;base64, prefix is accepted |
The content is checked against the extension: a renamed file is refused. Errors, all 400:
| Code | Meaning |
|---|---|
RECEIPT_REQUIRED | contentBase64 is missing |
RECEIPT_FILENAME_REQUIRED | fileName is missing |
RECEIPT_ENCODING | contentBase64 is not valid base64 |
RECEIPT_FORMAT | the extension is not one of the formats above |
RECEIPT_CONTENT | the content does not match the extension |
RECEIPT_EMPTY, RECEIPT_TOO_LARGE | empty, or over 10 MB |
Nothing is opened when the receipt is refused, so the request can simply be repeated with a good file. Receipts are seen only by the platform's reviewers.
Check an appeal
GET /gw/v1/appeals/{id}
{id} is the apl_… id. The shape is the same as above.
| Status | Meaning |
|---|---|
Open | Under review. slaDueAt is the platform's target for a decision, 24 hours by default. |
Accepted | The payment was confirmed. The order completes and is credited; order.completed follows. |
Rejected | The payment was not found. The order stays cancelled with cancelReason: "appeal rejected"; order.cancelled follows. The reviewer's comment says why. |
Cancelled | Reserved. Appeals are not withdrawn today; ask support if one was opened by mistake. |
The cabinet's Appeals page shows the same list with the reviewer's reply, the number of receipts, and flags appeals past their target time. An appeal still under review has an Attach receipt button there, the cabinet's way of adding a file later.
How appeals affect routing
Open appeals count against the provider that served the order. A provider with ten or more open appeals is paused for everyone until they are resolved down to seven. This protects the whole platform from a provider that stops confirming payments; it also means a wave of unfounded appeals can pause a healthy channel. Open appeals when a customer actually paid.