Creating a payment with API v3
The POST /payments request, fields, response, idempotency and errors.
On this page
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_…(orsk_live_…). - Amounts are integers in sum:
250000= 250,000 sum. Currency is alwaysUZS. - 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
429with aRetry-Afterheader.
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
- Send
POST /api/v3/paymentsfrom your server. - Redirect the customer to the
checkout_urlin the response. - Check the result via the webhook (
payment.succeeded) orGET /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.