2.2 Get payout status
Get payout status
GET /api/v1/payouts/{external_id}
Returns the current payout status for your external_id.
Shop routing: when using multiple shops, you can pass shop_code in the query. If shop_code is provided, the search is limited to that shop. If shop_code is omitted, the API searches only in the merchant's default active shop. If no default active shop is configured, the API returns 422.
Headers
| Parameter | Type | Required | Description |
|---|---|---|---|
| X-API-Key | string | Yes | API key. |
| X-Timestamp | string | Yes | Request time. |
| X-Signature | string | Yes | HMAC-SHA256(secret, timestamp + body) — for GET requests the body is empty. |
Path parameters
| Parameter | Type | Description |
|---|---|---|
| external_id | string | Payout identifier provided at creation. |
Query parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| shop_code | string | No | Shop code. If omitted, the lookup is performed only in the default active shop. |
Example
GET /api/v1/payouts/PAY-001?shop_code=shop-001
Response 200 (OK)
{
"id": 12345,
"external_id": "PAY-001",
"shop_code": "shop-001",
"status": "pending",
"amount": "1000.00",
"currency": "RUB",
"updated_at": "2025-12-05T10:00:00.000000Z"
}
If the shop status response schema exposes additional fields, they are returned under paymentData. Empty paymentData is omitted.
Response 404
{"message": "Payout not found"} — no payout with this external_id was found in the resolved shop scope.
Payout statuses
HTTP status responses use merchant-facing statuses. Internal processing states such as processing, waiting_api, processing_api, pay_error, and polling_expired are collapsed to pending in the REST API response.
| Status | Description |
|---|---|
| pending | Created or still in progress from the merchant point of view. |
| success | Completed successfully. |
| failed | Processing finished with an error. |
| canceled | The operation was canceled. |
| refunded | The payout was reversed or refunded after completion. |
| expired | The operation expired before completion. |
Status change notifications are sent to callback_url if it was provided at creation, or to the default webhook URL.