Dynamic QR payment for a QR code printed on a POS receipt or shown on a cash-register screen, scanned by the customer in the Uzum Bank mobile application. Order creation and payment-link generation, order and payment status checks, fiscalization, reversal and cancellation.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/uzum-dynamic-qr"curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
openapi: 3.0.1
info:
title: Dynamic QR (QR CRM Scan Specification)
version: 1.0.0
x-logo:
url: https://uzumbank.uz/_nuxt/img/uzumbank-logo-light.f4c13a0.svg
href: /
description: >
**Dynamic QR** is a payment service that enables **QR code payments by
scanning a QR code printed on a POS receipt** using the Uzum Bank mobile
application.
#### ⚙️ Key features
- Order creation and generation of a payment link
- Client-side QR code payment
- Fiscalization and delivery of the receipt link
- Payment cancellation
- Order / payment status checks
#### 🚀 **Quick start**
- [Authentication](#section/Authentication)
- [Methods](#tag/Methods)
---
## Getting started
**To get started** with the Uzum Bank API, follow these steps:
1. Contact your Uzum Bank account manager to enable the service.
2. After the service is enabled, you will receive the following confidential
credentials required for authentication and API requests:
- **merchant_id** — a unique identifier of the merchant in the Uzum Bank system.
- **secret_key** — a unique key used for API authentication.
- **service_id** — a unique identifier of the branch or service location where the payment is processed.
- **merchant_service_user_id** — a unique identifier of the POS terminal or cashier within a specific branch. This parameter allows the system to identify the exact checkout where the request originates or the operation is performed.
These credentials are strictly confidential and must be used exclusively for
interacting with the Uzum Bank API.
3. Complete the API integration.
## Authentication
Authentication is performed using **merchant_service_user_id** and
**secret_key**. If you do not have this data, contact your Uzum Bank
manager.
When sending requests, you must include the following headers:
- **Authorization**: merchant_service_user_id:hash:timestamp
- **merchant_service_user_id** — unique identifier of the cash register or cashier within a specific branch.
- **hash** — the result of calculating the SHA1 hash of the string formed by concatenating timestamp and secret_key: sha1(timestamp + secret_key)
- **timestamp** — UNIX timestamp in milliseconds in the UTC+5 time zone (time for the region).
- **Content-Type**: application/json
**Request Example**
```
curl --location 'https://mobile.apelsin.uz/api/dynamic-qr/merchant/payment'
\
--header 'Authorization: 8461:964bd9d82f6f3c13052f205e92af508cdd7085cc:1727122154352' \
--header 'Content-Type: application/json' \
--data '{}'
```
### Required Headers
- `Authorization`
- `Content-Type`
- `Accept`
### Supported Content Types
- `application/json`
## Error Message
Methods only return HTTP status 200. If the request is successfully
processed, the result is returned with `error_code` = 0.
If an error occurs during request processing, the response is returned in
JSON format, containing an `error_code` (Integer type) and an
`error_message` (String type).
<br/><br/>
<strong> Examples of `error_code`:</strong>
Error Code | Description
-|-
0 | • success
400 | • missing one of the required fields
401 | • Format of Authorization in Header incorrect: <br/> • regex:
`(^\d*):([\da-f]{40}):(\d*$)` <br /> <br /> • One of them is not ACTIVE:
<br /> • `Merchant ID` <br /> • `Merchant service ID` <br /> • `Merchant
service user ID` <br /> <br /> • Incorrect `hash` <br /> <br /> •
`service_id` does not belong to the specified partner.
503 | • The service is not found or is not active.
<br/><br/>
<strong> Examples of `error_message`:</strong>
`null` -> no errors
`apelsin.pay.authorization.error` -> authorization is not successful
`apelsin.pay.service.not.working` -> bank service is not available
`apelsin.pay.fiscalization.service.not.working` -> the Fiscalization service
is not working
`apelsin.pay.unsupported.operation` -> invalid operation
`apelsin.pay.reverse.not.allowed` -> reverse is not allowed for the partner
`unsupported.fiscal.url` -> the link to fiscalization is incorrect
`order.not.found` -> the order is not found
`order.id.duplicated` -> retry payment `order_id`
`operation.not.found` -> the service is not active or not found
`external.service.unavailable` -> external service not available
`operation.failed` -> The operation is not successful
`operation.forbidden` -> if the card type is UNKNOWN, the service is blocked
for some types of cards, there is a problem with commission deduction
`operation.is.inProcess` -> no response received from processing
tags:
- name: Methods
description: >
QR CRM methods that are used to create an order, check the status of the
order and transfer links to the fiscal receipt and cancel payment
transactions.
paths:
/api/dynamic-qr/merchant/payment/create:
post:
summary: Create Order
description: |
Method for creating an order.
Endpoint: `/api/dynamic-qr/merchant/payment/create`
tags:
- Methods
operationId: create_order
requestBody:
$ref: '#/components/requestBodies/CreateOrderRequest'
responses:
'200':
$ref: '#/components/responses/CreateOrderResponse'
'401':
$ref: '#/components/responses/AuthErrorResponse'
/api/dynamic-qr/merchant/payment/status-by-order:
post:
summary: Check Order
description: |
Method for checking the status of the order.
Endpoint: `/api/dynamic-qr/merchant/payment/status-by-order`
tags:
- Methods
operationId: check_order
requestBody:
$ref: '#/components/requestBodies/CheckOrderRequest'
responses:
'200':
$ref: '#/components/responses/CheckOrderResponse'
'401':
$ref: '#/components/responses/AuthErrorResponse'
/api/dynamic-qr/merchant/payment/fiscal:
post:
summary: Fiscal
description: |
The method is used to transmit a link to a fiscalized check.
Endpoint: `/api/dynamic-qr/merchant/payment/fiscal`
tags:
- Methods
operationId: fiscal
requestBody:
$ref: '#/components/requestBodies/FiscalRequest'
responses:
'200':
$ref: '#/components/responses/FiscalResponse'
'401':
$ref: '#/components/responses/AuthErrorResponse'
/api/dynamic-qr/merchant/payment/reversal:
post:
summary: Reverse
description: |
The method is used to cancel payment transactions.
Endpoint: `/api/dynamic-qr/merchant/payment/reversal`
tags:
- Methods
operationId: reversal
requestBody:
$ref: '#/components/requestBodies/ReversalRequest'
responses:
'200':
$ref: '#/components/responses/ReversalResponse'
'401':
$ref: '#/components/responses/AuthErrorResponse'
/api/dynamic-qr/merchant/payment/cancel-order:
post:
summary: Cancel order
description: |
This method is for order cancellation.
Endpoint: `/api/dynamic-qr/merchant/payment/cancel-order`
tags:
- Methods
operationId: cancel_order
requestBody:
$ref: '#/components/requestBodies/CancelRequest'
responses:
'200':
$ref: '#/components/responses/CancelResponse'
'401':
$ref: '#/components/responses/AuthErrorResponse'
components:
requestBodies:
CreateOrderRequest:
description: |
Request fields
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateOrderRequest'
CheckOrderRequest:
description: |
Request fields
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CheckOrderRequest'
FiscalRequest:
description: |
Request fields
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/FiscalRequest'
ReversalRequest:
description: |
Request fields
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ReversalRequest'
CancelRequest:
description: |
Атрибуты запроса
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CancelRequest'
responses:
CreateOrderResponse:
description: |
Response fields
content:
application/json:
schema:
$ref: '#/components/schemas/CreateOrderResponse'
CheckOrderResponse:
description: |
Response fields
content:
application/json:
schema:
$ref: '#/components/schemas/CheckOrderResponse'
FiscalResponse:
description: |
Response fields
content:
application/json:
schema:
$ref: '#/components/schemas/FiscalResponse'
ReversalResponse:
description: |
Response fields
content:
application/json:
schema:
$ref: '#/components/schemas/ReversalResponse'
CancelResponse:
description: |
Атрибуты ответа
content:
application/json:
schema:
$ref: '#/components/schemas/CancelResponse'
AuthErrorResponse:
description: |
If an error occurred during authorization
schemas:
CreateOrderRequest:
type: object
properties:
amount:
description: |
Payment amount in tiyins.
type: integer
format: int64
example: 100000
order_id:
description: >
Unique sale number (Shopping Cart): The unique order number in the
partner's system.
The partner is responsible for ensuring the uniqueness of the
`order_id`.
If the `order_id` is not unique, the payment will not be processed.
type: string
example: a98dcb7e-5b6e-431d-b780-5fd7d93d7e3d
service_id:
description: |
Partner ID number in Uzum Bank.
type: integer
format: int64
example: 111
details:
description: |
Details of the order.
type: object
example:
fio: Laziz Djurayev
something: something value
required:
- amount
- order_id
- service_id
CreateOrderResponse:
type: object
properties:
payment_link:
description: |
The data for generating QR.
type: string
example: >-
https://www.apelsin.uz/open-service?serviceId=498615418&orderId=a98dcb7e-5b6e-431d-b780-5fd7d93d7e3d
error_code:
description: |
0 - Success
type: integer
format: int32
example: 0
required:
- payment_link
- error_code
CheckOrderRequest:
type: object
properties:
order_id:
description: |
Unique id of order.
type: string
example: a98dcb7e-5b6e-431d-b780-5fd7d93d7e3d
service_id:
description: |
Partner ID number in Uzum Bank.
type: integer
format: int64
example: 111
required:
- order_id
- service_id
CheckOrderResponse:
type: object
properties:
payment_id:
description: |
Transaction identifier in the bank's system.
type: string
example: c4f89d18-62b1-4b08-9256-3a8d7d60f28a
payment_status:
description: >
<br /> Transaction status:
`CREATED` - The operation was created.
`SUCCESS` - The operation is successful.
`FAILED` - The operation was not performed.
`HOLD` - The operation was created, but the transaction was not
received.
`REVERSE_PENDING` - Waiting for the transaction to be canceled.
`REVERSED` - Successful transaction cancellation.
`PARTIAL_CANCELLED` - Partial cancellation completed successfully.
`CANCELLED` - The Operation was cancelled.
type: string
enum:
- CREATED
- SUCCESS
- FAILED
- HOLD
- REVERSE_PENDING
- REVERSED
- PARTIAL_CANCELLED
- CANCELLED
example: SUCCESS
error_code:
description: |
0 - Success
type: integer
format: int32
example: 0
client_phone_number:
description: |
Client phone number
type: string
example: '998909090900'
processingReferenceNumber:
description: >
Processing reference number. This field is sent only when paying
with Uzcard, Humo, Visa Uzum Bank, or Visa Kapital Bank cards.
Otherwise, the value of this field will be `null`.
type: string
format: string
example: '000'
cardType:
description: >
Client bank card type (1 - corporate bank card, 2 - private bank
card).
type: integer
format: int32
example: 2
required:
- payment_id
- payment_status
- error_code
FiscalRequest:
type: object
properties:
payment_id:
description: |
Transaction identifier in the bank's system.
type: string
example: c4f89d18-62b1-4b08-9256-3a8d7d60f28a
service_id:
description: |
Partner ID number in Uzum Bank.
type: integer
format: int64
example: 111
fiscal_url:
description: >
Link to fiscal receipt.
May contain special symbols, in this case the Unscape operation is
necessary
type: string
example: http://…
required:
- fiscal_url
- service_id
- payment_id
FiscalResponse:
type: object
properties:
payment_id:
description: |
Transaction identifier in the bank's system.
type: string
example: c4f89d18-62b1-4b08-9256-3a8d7d60f28a
payment_status:
description: >
<br /> Transaction status:
`SUCCESS` - The operation is successful.
`FAILED` - The operation was not performed.
`HOLD` - The operation was created, but the transaction was not
received.
`REVERSE_PENDING` - Waiting for the transaction to be canceled.
`REVERSED` - Successful transaction cancellation.
`PARTIAL_CANCELLED` - Partial cancellation completed successfully.
type: string
enum:
- SUCCESS
- FAILED
- HOLD
- REVERSE_PENDING
- REVERSED
- PARTIAL_CANCELLED
example: SUCCESS
error_code:
description: |
0 - Success
type: integer
format: int32
example: 0
required:
- payment_id
- payment_status
- error_code
ReversalRequest:
type: object
properties:
service_id:
description: |
Partner ID number in Uzum Bank.
type: integer
format: int64
example: 111
payment_id:
description: |
Payment transaction ID.
type: string
example: c4f89d18-62b1-4b08-9256-3a8d7d60f28a
required:
- service_id
- payment_id
ReversalResponse:
type: object
properties:
payment_id:
description: |
Transaction identifier in the bank's system.
type: string
example: c4f89d18-62b1-4b08-9256-3a8d7d60f28a
payment_status:
description: |
<br/>Transaction status:
`REVERSE_PENDING` - Waiting for the transaction to be canceled.
`REVERSED` - Successful transaction cancellation.
type: string
enum:
- REVERSE_PENDING
- REVERSED
example: REVERSED
error_code:
description: |
0 - Success
type: integer
format: int32
example: 0
required:
- payment_id
- payment_status
- error_code
CancelRequest:
type: object
properties:
order_id:
description: |
Unique id of order.
type: string
example: a98dcb7e-5b6e-431d-b780-5fd7d93d7e3d
service_id:
description: |
Partner ID number in Uzum Bank.
type: integer
format: int64
example: 111
required:
- order_id
- service_id
CancelResponse:
type: object
properties:
payment_id:
description: |
Order id from the request.
type: string
example: a98dcb7e-5b6e-431d-b780-5fd7d93d7e3d
payment_status:
description: |
`CANCELLED` - order is cancelled.
type: string
example: CANCELLED
error_code:
description: |
0 - success
400 - error during cancellation if current status COMPLETED, EXPIRED
type: integer
format: int32
example: 0
error_message:
description: >
`this.order.has.already.be.paid.for` - order was already paid
(COMPLETED)
`order.id.is.expired` - order is expired (EXPIRED)
type: string
nullable: true
required:
- payment_id
- payment_status
- error_code