Создание платежа через API v3
Запрос POST /payments, поля, ответ, идемпотентность и ошибки.
На этой странице
API v3 — это REST API: JSON-запросы и ответы, стандартные HTTP-коды. Полная документация: https://mirpay.uz/api-docs.
Основные правила
- Базовый адрес:
https://mirpay.uz/api/v3. Только HTTPS. - В каждом запросе заголовок
Authorization: Bearer sk_test_…(илиsk_live_…). - Суммы — целые числа в сумах:
250000= 250 000 сум. Валюта толькоUZS. - Используйте ключ только на сервере — не вызывайте API напрямую из браузера или мобильного приложения.
- Лимит: 300 запросов в минуту на ключ. При превышении —
429и заголовокRetry-After.
Эндпоинты
POST /api/v3/payments — create a payment
GET /api/v3/payments/{id} — retrieve a payment
GET /api/v3/payments — list payments
POST /api/v3/payments/{id}/cancel — cancel a pending payment
GET /api/v3/balance — cashbox balance
Создание платежа
- Отправьте
POST /api/v3/paymentsсо своего сервера. - Перенаправьте покупателя на
checkout_urlиз ответа. - Проверьте результат по вебхуку (
payment.succeeded) или черезGET /api/v3/payments/{id}.
curl https://mirpay.uz/api/v3/payments \
-H "Authorization: Bearer sk_test_YOUR_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order-1001" \
-d '{
"amount": 250000,
"description": "Order #1001",
"order_id": "1001",
"return_url": "https://example.com/pay/return",
"cancel_url": "https://example.com/pay/cancel",
"metadata": {"customer_id": "42"}
}'
| Поле | Обязательно | Описание |
|---|---|---|
amount |
да | Сумма в сумах, целое число, от 1 000 до 100 000 000. В боевом режиме также проверяются лимит одной транзакции и дневной лимит кассы. |
description |
да | Описание, до 255 символов. Показывается покупателю на странице оплаты. |
order_id |
нет | Номер вашего заказа, до 128 символов. Уникальность не проверяется. |
return_url |
нет | Куда вернётся покупатель после успешной оплаты. В боевом режиме только https. |
cancel_url |
нет | Адрес после неуспешной или отменённой оплаты. По умолчанию — return_url. |
expires_in |
нет | Срок жизни платежа в секундах. Live: 300–900 (по умолчанию 900). Test: 300–86 400 (по умолчанию 1 800). |
metadata |
нет | Ваши данные: до 20 ключей, ключ до 40 символов, значение до 500 символов. Вложенные объекты не принимаются. |
currency |
нет | Только UZS. |
Ответ — 201 и объект payment:
{
"id": "test_6f1c2d3e-0000-0000-0000-000000000000",
"object": "payment",
"livemode": false,
"status": "pending",
"amount": 250000,
"currency": "UZS",
"description": "Order #1001",
"order_id": "1001",
"metadata": {"customer_id": "42"},
"checkout_url": "https://mirpay.uz/sandbox/pay/test_6f1c2d3e-0000-0000-0000-000000000000",
"return_url": "https://example.com/pay/return",
"cancel_url": "https://example.com/pay/cancel",
"card": null,
"failure": null,
"receipt_url": null,
"created_at": "2026-11-11T10:15:00+05:00",
"expires_at": "2026-11-11T10:45:00+05:00",
"paid_at": null,
"canceled_at": null
}
Защита от дублей (Idempotency-Key)
Добавляйте заголовок Idempotency-Key в каждый запрос на создание (до 255 символов, например UUID или номер заказа). Если ответ потерялся, повторите запрос с тем же ключом — второй платёж не создастся, вернётся исходный ответ (Idempotent-Replayed: true). Ключи удаляются через 24 часа.
Отмена платежа
POST /api/v3/payments/{id}/cancel — только для платежа в статусе pending. Иначе 400 payment_not_cancelable. Возвратов (refund) в API v3 нет.
Список
GET /api/v3/payments — сначала новые. Параметры: limit (1–100, по умолчанию 10), starting_after, ending_before, фильтры status, order_id, created[gte], created[lte] (Unix-секунды).
Ошибки
При ошибке ответ всегда имеет одинаковую форму:
{
"error": {
"type": "invalid_request_error",
"code": "amount_too_small",
"message": "...",
"param": "amount",
"doc_url": "https://mirpay.uz/api-docs#errors"
},
"request_id": "req_..."
}
Ветвите логику по type и code, а не по тексту message. Частые коды:
| Код | Причина |
|---|---|
parameter_missing |
Не передан обязательный параметр. |
amount_too_small / amount_too_large |
Сумма вне допустимого диапазона. |
amount_limit_exceeded |
Будет превышен лимит транзакции или дневной лимит кассы (live). |
url_invalid |
Неверный return_url / cancel_url (в live только https). |
resource_missing |
Объект не найден или принадлежит другой кассе / режиму. |
idempotency_key_reused |
Этот ключ уже использован с другим телом запроса. |
В каждом ответе есть заголовок X-Request-Id (req_…). Сохраняйте его — по нему мы быстро найдём ваш запрос, когда вы обратитесь в поддержку.
Старый API (v1/v2)
Интеграции v1 и v2 продолжают работать без изменений. Для новых интеграций рекомендуем v3.