Перейти к содержимому

Глава 2 · API-интеграция

Создание платежа через API v3

Запрос POST /payments, поля, ответ, идемпотентность и ошибки.

3 мин чтения

На этой странице
  1. Основные правила
  2. Эндпоинты
  3. Создание платежа
  4. Защита от дублей (Idempotency-Key)
  5. Отмена платежа
  6. Список
  7. Ошибки
  8. Старый API (v1/v2)

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

Создание платежа

  1. Отправьте POST /api/v3/payments со своего сервера.
  2. Перенаправьте покупателя на checkout_url из ответа.
  3. Проверьте результат по вебхуку (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.

Статья была полезной?

Не нашли ответ?

Отправьте обращение — специалист проверит ваш аккаунт и ответит.