Merchant API (1.0.0)
Download OpenAPI specification:Download
Merchant API allows partners to accept payments through the Uzum Bank mobile application. When a customer pays for a service, Uzum Bank sends webhooks to your server — HTTP POST requests containing payment data.
To integrate, implement webhook handlers on your side and generate responses according to this specification.
⚙️ Key features
- Payment eligibility check
- Payment transaction creation (initiation)
- Transaction confirmation
- Transaction cancellation
- Transaction status checks
🚀 Quick start
The payment process consists of three stages:
- Verifying the possibility of the payment
- Creating a transaction
- Confirming the transaction
After selecting a service and providing the required details, such as an account number, the user proceeds to the payment verification stage. At this stage, Uzum Bank triggers the check webhook on the partner's side to confirm the feasibility of processing the payment. The data required to complete the payment is passed in the params object.
.
If the payment verification confirms the possibility of processing the payment, Uzum Bank triggers the create webhook to create a transaction.
.
After successfully creating the transaction, Uzum Bank debits the funds from the user's payment instrument and credits them to your settlement account. Uzum Bank then triggers the confirm webhook to confirm the transaction. You must process this request, provide the service to the user, and generate a response.
.
If a server error occurs on the partner's side or a timeout happens while processing the request, Uzum Bank triggers the status webhook to check the transaction status. This call will be repeated (up to 10 attempts) until the status CONFIRMED or FAILED is received.
A transaction can be in one of three states.
.
If you do not receive the transaction confirmation request within 30 minutes of its creation, the transaction is considered unsuccessful. In this case, set the transaction status to FAILED on your side.
Uzum Bank uses the HTTPS protocol to deliver webhooks to the partner. Requests are sent via the POST method in application/json format, and responses are also expected in application/json format.
Authorization is done via the HTTP Authorization header, which must be present in every request. The header is generated using the "Basic" scheme and user credentials encoded in base64 format: Authorization: Basic <user credentials>. The user credentials, including the username and password, are provided by our team.
To form the header:
- Create a string from the username and password, separated by a colon, for example:
"myLogin:myPassword"; - Encode the string in base64, the result might be
YWxhZGRpbjpvcGVuc2VzYW1l; - Insert the result into the header; make sure there is a space between the word
"Basic"and the encoded credentials.
The header will look like:
| Header | Value |
|---|---|
| Authorization | Basic YWxhZGRpbjpvcGVuc2VzYW1l |
These are the requests that Uzum Bank sends to the partner during the payment process according to the Merchant API protocol.
Verifying Payment Possibility Webhook
The /check webhook is used to verify the possibility of processing a payment and to retrieve additional information about the payment or the user.
Authorizations:
Request Body schema: application/jsonrequired
JSON object with request parameters.
| serviceId required | integer <int64> Service ID for which the payment is being made. |
| timestamp required | integer <int64> Time of request (Unix timestamp in milliseconds). |
| params required | object An object with additional payment properties, such as the account number |
Responses
Request samples
- Payload
{- "serviceId": 101202,
- "timestamp": 1698361456728,
- "params": {
- "account": 123456789
}
}Response samples
- 200
- 400
{- "serviceId": 101202,
- "timestamp": 1698361457021,
- "status": "OK",
- "data": {
- "account": {
- "value": "123456789"
}, - "fio": {
- "value": "Ivanov Ivan Ivanovich"
}
}
}Creating Payment Transaction Webhook
The /create webhook is used to create a payment transaction in the partner's system.
Authorizations:
Request Body schema: application/jsonrequired
JSON object with request parameters.
| serviceId required | integer <int64> Service ID for which the payment is being made. |
| timestamp required | integer <int64> Time of request (Unix timestamp in milliseconds). |
| transId required | string <uuid> Transaction ID of the payment created in Uzum Bank. |
| params required | object An object with additional payment properties, such as the account number |
| amount required | integer <int64> Payment amount in tiyin (the smallest currency unit). |
Responses
Request samples
- Payload
{- "serviceId": 101202,
- "timestamp": 1698361456728,
- "transId": "5c398d7e-76b6-11ee-96da-f3a095c6289d",
- "params": {
- "account": 123456789
}, - "amount": 2500000
}Response samples
- 200
- 400
{- "serviceId": 101202,
- "transId": "5c398d7e-76b6-11ee-96da-f3a095c6289d",
- "status": "CREATED",
- "transTime": 1698361458054,
- "data": {
- "account": {
- "value": "123456789"
}, - "fio": {
- "value": "Ivanov Ivan Ivanovich"
}
}, - "amount": 2500000
}Confirming Payment Transaction Webhook
The /confirm webhook is used to confirm the payment transaction after the service has been successfully paid for.
Authorizations:
Request Body schema: application/jsonrequired
JSON object with request parameters.
| serviceId required | integer <int64> Service ID for which the payment is being made. |
| timestamp required | integer <int64> Time of request (Unix timestamp in milliseconds). |
| transId required | string <uuid> Transaction ID of the payment created in Uzum Bank. |
| paymentSource required | string <enum> Payment source indicator: UZCARD, HUMO, VISA, MASTERCARD, VISA_DOMESTIC, MASTERCARD_DOMESTIC, INSTALLMENT, CASHBACK, ACCOUNT, WALLET, VISAUZS, UZUM_DEBIT_VISA. |
| tariff | string <string>
|
| processingReferenceNumber | string <string> 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 |
| phone required | string <string> Client phone number. |
| cardType | integer <int32> Client bank card type (1 - corporate bank card, 2 - private bank card). |
Responses
Request samples
- Payload
{- "serviceId": 101202,
- "timestamp": 1698361456728,
- "transId": "5c398d7e-76b6-11ee-96da-f3a095c6289d",
- "paymentSource": "INSTALLMENT",
- "tariff": "003",
- "processingReferenceNumber": "000",
- "phone": "998901234567",
- "cardType": 2
}Response samples
- 200
- 400
{- "serviceId": 101202,
- "transId": "5c398d7e-76b6-11ee-96da-f3a095c6289d",
- "status": "CONFIRMED",
- "confirmTime": 1698361458054,
- "data": {
- "account": {
- "value": "123456789"
}, - "fio": {
- "value": "Ivanov Ivan Ivanovich"
}
}, - "amount": 2500000
}Cancelling Payment Transaction Webhook
The /reverse webhook is used to cancel a payment transaction in the partner's system.
Authorizations:
Request Body schema: application/jsonrequired
JSON object with request parameters.
| serviceId required | integer <int64> Service ID for which the payment is being made. |
| timestamp required | integer <int64> Time of request (Unix timestamp in milliseconds). |
| transId required | string <uuid> Transaction ID of the payment created in Uzum Bank. |
Responses
Request samples
- Payload
{- "serviceId": 101202,
- "timestamp": 1698361456728,
- "transId": "5c398d7e-76b6-11ee-96da-f3a095c6289d"
}Response samples
- 200
- 400
{- "serviceId": 101202,
- "transId": "5c398d7e-76b6-11ee-96da-f3a095c6289d",
- "status": "REVERSED",
- "reverseTime": 1698361458054,
- "data": {
- "account": {
- "value": "123456789"
}, - "fio": {
- "value": "Ivanov Ivan Ivanovich"
}
}, - "amount": 2500000
}Checking Payment Transaction Status Webhook
The /status webhook is used to check the status of a payment transaction in the partner's system.
Authorizations:
Request Body schema: application/jsonrequired
JSON object with request parameters.
| serviceId required | integer <int64> Service ID for which the payment is being made. |
| timestamp required | integer <int64> Time of request (Unix timestamp in milliseconds). |
| transId required | string <uuid> Transaction ID of the payment created in Uzum Bank. |
Responses
Request samples
- Payload
{- "serviceId": 101202,
- "timestamp": 1698361456728,
- "transId": "5c398d7e-76b6-11ee-96da-f3a095c6289d"
}Response samples
- 200
- 400
{- "serviceId": 101202,
- "transId": "5c398d7e-76b6-11ee-96da-f3a095c6289d",
- "status": "CONFIRMED",
- "transTime": 1698361458054,
- "confirmTime": 1698361458054,
- "reverseTime": null,
- "data": {
- "account": {
- "value": "123456789"
}, - "fio": {
- "value": "Ivanov Ivan Ivanovich"
}
}, - "amount": 2500000
}