Build with the merchant API.
A versioned JSON interface for payment links, transaction status, balances and event delivery.
Issue a bill in three steps.
Create a merchant API key after approval, use your cash desk code to create a bill, then read the bill or receive a webhook when a payment status is available.
- Create an API key in Developer tools.
- Send a bill request with a unique idempotency key.
- Open the returned payment URL and verify the final status server-side.
POST /api/merchant/v1/bills/
Authorization: Bearer YOUR_API_KEY
X-Cash-Desk-Code: your-desk-uuid
Idempotency-Key: order-1042
Content-Type: application/json
{"amount_minor":45000000,"title":"Order #1042"}Authentication and safety
Keep API keys on your server. They are displayed once and stored as hashes.
Bearer key
Send Authorization: Bearer YOUR_API_KEY. A key can be scoped to a cash desk. Revoked keys stop working immediately.
Optional HMAC
Signed requests include a Unix timestamp and HMAC-SHA256 of the timestamp, method, path and raw-body hash. Signatures expire after five minutes and cannot be replayed.
Idempotency
Money-changing bill requests require Idempotency-Key. Retry with the same key and payload to receive the original result.
Available endpoints
| METHOD | PATH | PURPOSE |
|---|---|---|
| GET | /api/merchant/v1/health/ | Service health |
| GET | /me/ | Merchant and environment |
| GET | /cash-desks/ | Cash desk list |
| POST | /bills/ | Create a bill and payment URL |
| GET | /bills/{id}/ | Read status and payments |
| POST | /bills/{id}/cancel/ | Cancel an unpaid bill |
| POST | /bills/{id}/reissue/ | Rotate its payment URL |
| GET | /transactions/ | Recent transactions |
| GET | /balance/ | Recorded balance |
| GET | /stats/ | 7, 30 or 90 day totals |
| GET | /payment-methods/ | Method availability |
Paths without a full prefix are relative to /api/merchant/v1/. Amounts use integer tiyin: 100 tiyin = 1 UZS.
Webhooks and delivery
Use signed notifications to update your order system.
Events
Payment records emit payment.succeeded; refund records emit payment.refunded. Delivery attempts and status appear in Developer tools.
Verify before processing
Validate X-Nova-Signature over the raw body, timestamp and event ID with your one-time webhook secret. Handle the event ID idempotently.
Delivery requirements
Webhooks require a public HTTPS destination on port 443. Production destinations must be allowlisted. Keep your endpoint fast and return a success response after durable processing.