Hold Payment

API Documentation: Hold Create & Hold Charge & Hold Dismiss

Ushbu API foydalanuvchi mablag‘iga vaqtinchalik hold qo‘yish va keyinchalik hold qilingan summani yechib olish imkonini beradi.

• Hold Create foydalanuvchi kartasida ko‘rsatilgan summani cheklangan muddatga band qiladi.
• Hold Charge hold qilingan summaning to‘liq qismini yoki undan kichik qismini yechib olib, to‘lovni amalga oshiradi.
• Hold Dismiss avval yaratilgan hold’ni bekor qiladi. Hold bekor qilingandan so‘ng band qilingan summa yechiladi va ushbu hold bo‘yicha boshqa yechim amalga oshirib bo‘lmaydi.

1. Hold Create

Method: POST
URL: BASE_URL/merchant/payment/hold/create/
Header:

Authorization: Bearer <ACCESS_TOKEN>

Request body

Field	Sample Data	Type	Required	Description
amount	1000	int	Yes	Summa SUM ko‘rinishida yuboriladi (1000 = 1,000 SUM)
userId	123	string	No	Merchant tomonidan berilgan foydalanuvchi identifikatori
account	{"field_name": "sample data"}	dict	No	Qo‘shimcha ma’lumot bo‘lmasa bo‘sh dict {} yuboring
cardId	9f877739-bc25-4f0f-a13f-ec485fd04250	string	Yes	Paylov tizimida yaratilgan Card ID
time	10	int	Yes	Hold muddati daqiqalarda. Maksimal qiymat: 40320 (28 kun)
externalId	externalId1	string	No	Tashqi identifikator. Maksimal uzunligi: 64 ta belgi
serviceId	9f877739-bc25-4f0f-a13f-ec485fd04250	string	No	To‘lov tizimi tomonidan taqdim etiladi

{
  "userId": "string",
  "cardId": "string",
  "amount": 10,
  "account": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "time": 10,
  "externalId": "string",
  "serviceId": "uuid"
}

Field	Type	Required	Description
userId	string	Yes	Foydalanuvchining noyob identifikatori
cardId	string	Yes	Hold uchun ishlatilayotgan kartaning noyob identifikatori
amount	integer	Yes	Hold qilinadigan summa (sum ko‘rinishida)
account	object	No	Account uchun qo‘shimcha xususiyatlarni o‘z ichiga oladi
account.additionalProp1	string	Optional	Maxsus account ma’lumoti
account.additionalProp2	string	Optional	Maxsus account ma’lumoti
account.additionalProp3	string	Optional	Maxsus account ma’lumoti
time	integer	Yes	Hold muddati daqiqalarda. Maksimal ruxsat etilgan qiymat 28 kun (40320 daqiqa)

Success response

{
  "result": {
    "transactionId": "uuid4"
  }
}

Field	sample_data	Type	Description
transactionId	uuid4	string	Tranzaksiyaning noyob identifikatori

2. Hold Charge

Method: POST
URL: /merchant/payment/hold/charge/
Header:

Authorization: Bearer <ACCESS_TOKEN>

Request body

{
  "transactionId": "string",
  "amount": 10
}

Field	Type	Required	Description
transactionId	string	Yes	Hold tranzaksiyasining noyob identifikatori
amount	integer	Yes	Hold ichidan yechib olinadigan summa

Success Response

{
  "result": {
    "transactionId": "string",
    "cardId": "string",
    "payedAt": "YYYY-MM-DD HH:mm:ss"
  }
}

Field	Type	Description
transactionId	string	Tranzaksiyaning noyob identifikatori
cardId	string	To‘lov amalga oshirilgan karta
payedAt	string	To‘lov amalga oshirilgan vaqt. Format: YYYY-MM-DD HH:mm:ss

3. Hold Dismiss

Ushbu API band qilingan mablag‘ni foydalanuvchiga qayta ochib berish kerak bo‘lganda ishlatiladi. Hold qilingan mablag‘ foydalanuvchi bank kartasida yana foydalanish uchun mavjud bo‘ladi.

Method: POST
URL: /merchant/payment/hold/dismiss/
Header:

Authorization: Bearer <ACCESS_TOKEN>

Request Body

{
  "transactionId": "string"
}

Field	Type	Required	Description
transactionId	string	Yes	Bekor qilinishi kerak bo‘lgan hold tranzaksiyasining noyob identifikatori

Success response

{
  "result": {
    "transactionId": "uuid",
    "status": "cancelled"
  }
}

Field	Type	Description
transactionId	string (UUID)	Bekor qilingan hold tranzaksiyasining noyob identifikatori
status	string	Tranzaksiya holati

HOLD Status

Method: GET
Endpoint: BASE_URL/merchant/payment/hold/status/
queryParams: externalId yoki transactionId

Example GET request with external id

Method: GET
URL: BASE_URL/merchant/payment/hold/status/?externalId=123
Header:

Authorization: Bearer <ACCESS_TOKEN>

Response

{
  "result": {
    "transactionId": "d1be13da-4355-4b27-956d-d83b87e013f1",
    "status": "cancelled",
    "cancelTime": "2025-02-03 11:13:42",
    "payedAt": null,
    "amount": 10,
    "serviceId": "d1be13da-4355-4b27-956d-d83b87e013f1"
  }
}

Result statuses

paid — muvaffaqiyatli tranzaksiya
cancelled — bekor qilingan tranzaksiya
hold — hold holatidagi tranzaksiya, agar hold muddati tugamagan bo‘lsa charge qilish mumkin
created — yaratilgan

Error response structure

{
  "error": {
    "code": "hold_not_found",
    "message": "hold_not_found"
  }
}

Error codes

hold_not_found
hold_time_expired
invalid_amount
field_not_valid
gateway_not_working
field_required
transaction_not_found