Pay

---

Метод: POST

Эндпоинт: /api/agent/v2/unregistered-pay

Авторизация

Нужно передавать jwt token в заголовках (headers):

Authorization: Bearer <access_token>
Content-Type: application/json

---

Тело запроса - PayRequest

{
  "billId": 987654321,
  "amount": 10000,
  "type": "UZCARD", // UZCARD, HUMO
  "params": {
    "otp": "123456"
  }
}

Поля тела запроса

Поле	Обязательное	Тип	Описание
billId	Да	Number	Идентификатор чека из ответа /api/agent/v2/unregistered-check
amount	Да	Number	Сумма платежа
params.otp	Да	String	OTP код, который отправлен клиенту

При отсутствии любого из обязательных полей сервер выбросит Payment parameters are missing → HTTP 400.

---

Формат ответа - SimpleBillResponse

{
  "id": 987654321,
  "billId": 987654321,
  "recipientId": 123456,
  "recipientShortName": "UMS MOBILE",
  "sessionId": "SESS-20251107-001",
  "amount": 10000,
  "account": "998901234567",
  "currency": 860,
  "extId": "AGT-00112233",
  "requestTime": "2025-11-07T10:30:02Z",
  "responseTime": "2025-11-07T10:30:04Z",
  "responseText": "Оплата успешно проведена",
  "success": true,
  "status": "SUCCESS",
  "data": {
    "paymentId": "PAY-20251107-0001",
    "providerInfo": "UMS",
    "amount": 10000,
    "currency": 860
  },
  "statusCode": 0,
  "statusMessage": "SUCCESS",
  "gatewayName": "SOME_GATEWAY",
  "sender": {
    "id": "CARD-8600",
    "name": "Humo / Uzcard",
    "account": "860012******1234"
  },
  "receiver": {
    "id": "UMS",
    "name": "UMS MOBILE",
    "account": "998901234567"
  }
}

Поля ответа при успешной оплате

Поле	Тип	Значение из примера
id	Number	987654321
billId	Number	987654321
recipientId	Number	123456
recipientShortName	String	"UMS MOBILE"
sessionId	String	"SESS-20251107-001"
amount	Number	10000
account	String	"998901234567"
currency	Number	860
extId	String	"AGT-00112233"
requestTime	Instant	"2025-11-07T10:30:02Z"
responseTime	Instant	"2025-11-07T10:30:04Z"
responseText	String	"Оплата успешно проведена"
success	Boolean	true
status	String	"SUCCESS"
data.paymentId	String	"PAY-20251107-0001"
data.providerInfo	String	"UMS"
data.amount	Number	10000
data.currency	Number	860
statusCode	Number	0
statusMessage	String	"SUCCESS"
gatewayName	String	"SOME_GATEWAY"
sender.id	String	"CARD-8600"
sender.name	String	"Humo / Uzcard"
sender.account	String	"860012******1234"
receiver.id	String	"UMS"
receiver.name	String	"UMS MOBILE"
receiver.account	String	"998901234567"

Возможные статусы

• SUCCESS — оплата успешно проведена.

• CHECKING — OTP не подтверждён (неверный/истёкший код или недоступен провайдер), требуется повторная попытка.

• FAILED — нарушены предусловия (нет логина в токене, отсутствуют params/code, не найден успешный чек по billId) или бизнес-ошибка оплаты.

---

Коды ответов

• 200 OK — бизнес-результат в теле (SimpleBillResponse) со статусами SUCCESS / FAILED / CHECKING.

• 400 Bad Request — невалидное тело запроса (провал валидации @Valid), непереданны или забыты нужные параметры.

• 401 Unauthorized — токен отсутствует/просрочен, нужно заново обратится к нужным api что бы взять access/refresh token.

• 403 Forbidden — недостаточно прав, нужно запросить права у админа.

Примечание: предикатные/бизнес-ошибки (нет успешного CHECK, нет params, не найден логин и т.д.) в доменной логике возвращаются как 200 OK со статусом FAILED в JSON.

---

Примеры

Успешный ответ (200):

{
  "id": 987654321,
  "success": true,
  "status": "SUCCESS",
  "responseText": "Оплата успешно проведена",
  "data": {
    "billId": 987654321,
    "recipientId": 123456,
    "recipientShortName": "UMS MOBILE",
    "sessionId": "SESS-20251107-001",
    "amount": 10000,
    "account": "998901234567",
    "currency": 860,
    "extId": "AGT-00112233",
    "requestTime": "2025-11-07T10:30:02Z",
    "responseTime": "2025-11-07T10:30:04Z",
    "paymentId": "PAY-20251107-0001",
    "providerInfo": "UMS",
    "gatewayName": "SOME_GATEWAY"
  },
  "sender": {
    "id": "CARD-8600",
    "name": "Humo / Uzcard",
    "account": "860012******1234"
  },
  "receiver": {
    "id": "UMS",
    "name": "UMS MOBILE",
    "account": "998901234567"
  }
}

Неверный / истёкший OTP

{
  "billId": 987654321,
  "success": false,
  "status": "CHECKING",
  "responseText": "OTP verification failed: invalid or expired code",
  "data": {
    "errorCode": "OTP_VERIFY_FAILED"
  }
}

Не найден успешный чек перед оплатой

{
  "billId": 987654321,
  "success": false,
  "status": "FAILED",
  "responseText": "Success check bill not found"
}

Нет логина в токене

{
  "billId": 987654321,
  "success": false,
  "status": "FAILED",
  "responseText": "Username not found"
}

Параметры платежа отсутствуют

{
  "billId": 987654321,
  "success": false,
  "status": "FAILED",
  "responseText": "Payment parameters are missing"
}

Ошибка валидации тела (400 Bad Request)

{
  "error": "BAD_REQUEST",
  "message": "Validation failed for object='payRequest'. Field error in object='payRequest' on field='billId': rejected value=null"
}

---

Схема

Client → API: POST /v2/unregistered-pay
API → validateOtp(payRequest)
API → debit() // uzcard, humo
API → pay(...)

---

Частые ошибки и советы

• INVALID_PARAMS — проверьте recipientId, account, amount, params.phone.

• CHECK_FAIL из-за OTP — повторите попытку, проверьте доступность провайдера и корректность телефона.

• Success check bill not found — выполните успешный /v2/unregistered-check и используйте возвращённый billId.