Skip to content

Chapter 2 · API integration

Creating a payment with API v3

The POST /payments request, fields, response, idempotency and errors.

3 min read

On this page
  1. Basics
  2. Endpoints
  3. Create a payment
  4. Avoiding duplicates (Idempotency-Key)
  5. Cancel a payment
  6. List payments
  7. Errors
  8. Legacy API (v1/v2)

API v3 is a REST API: JSON requests and responses with standard HTTP status codes. Full documentation: https://mirpay.uz/api-docs.

Basics

  • Base URL: https://mirpay.uz/api/v3. HTTPS only.
  • Every request needs the header Authorization: Bearer sk_test_… (or sk_live_…).
  • Amounts are integers in sum: 250000 = 250,000 sum. Currency is always UZS.
  • Use your key on the server only — never call the API directly from a browser or a mobile app.
  • Rate limit: 300 requests per minute per key. Above that you get 429 with a Retry-After header.

Endpoints

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

Create a payment

  1. Send POST /api/v3/payments from your server.
  2. Redirect the customer to the checkout_url in the response.
  3. Check the result via the webhook (payment.succeeded) or 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"}
  }'
Field Required Description
amount yes Amount in sum, integer, from 1,000 to 100,000,000. In live mode the cashbox per-transaction and daily limits are also checked.
description yes Description, up to 255 characters. Shown to the customer on the checkout page.
order_id no Your order number, up to 128 characters. Uniqueness is not enforced.
return_url no Where the customer returns after a successful payment. https only in live mode.
cancel_url no Where the customer returns after a failed or canceled payment. Defaults to return_url.
expires_in no Payment lifetime in seconds. Live: 300–900 (default 900). Test: 300–86,400 (default 1,800).
metadata no Your own data: up to 20 keys, keys up to 40 characters, values up to 500 characters. Nested objects are not accepted.
currency no UZS only.

The response is 201 with a payment object:

{
  "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
}

Avoiding duplicates (Idempotency-Key)

Add an Idempotency-Key header to every create request (up to 255 characters, e.g. a UUID or your order number). If the response is lost, resend the request with the same key — no second payment is created and the original response is returned (Idempotent-Replayed: true). Keys are removed after 24 hours.

Cancel a payment

POST /api/v3/payments/{id}/cancel — only for a pending payment. Otherwise 400 payment_not_cancelable. API v3 has no refunds.

List payments

GET /api/v3/payments — newest first. Parameters: limit (1–100, default 10), starting_after, ending_before, filters status, order_id, created[gte], created[lte] (Unix seconds).

Errors

Errors always come back in the same shape:

{
  "error": {
    "type": "invalid_request_error",
    "code": "amount_too_small",
    "message": "...",
    "param": "amount",
    "doc_url": "https://mirpay.uz/api-docs#errors"
  },
  "request_id": "req_..."
}

Branch on type and code, not on the message text. Common codes:

Code Reason
parameter_missing A required parameter was not sent.
amount_too_small / amount_too_large The amount is outside the allowed range.
amount_limit_exceeded The cashbox per-transaction or daily limit would be exceeded (live).
url_invalid Invalid return_url / cancel_url (https only in live).
resource_missing Object not found, or it belongs to another cashbox or mode.
idempotency_key_reused This key was already used with a different request body.

Every response has an X-Request-Id header (req_…). Log it — when you contact support, we can find your request instantly by this ID.

Legacy API (v1/v2)

v1 and v2 integrations keep working unchanged. We recommend v3 for new integrations.

Was this article helpful?

Didn’t find an answer?

Send a request — a specialist will check your account and reply.