С биллинговой системой
Схема работы Uzcard/Humo
Схема работы Кошелька OSON
Схема работы международных кошельков
Первый вариант: С переходом на страницу OSON
Для интегрирации, необходимо отправить POST запрос на нижеуказанный URL с параметрами: POST "{base_url}/api/invoice/create/"
Авторизация
Required - обязательный параметр
Optional - не обязательный параметр
Параметр авторизации указывается в заголовке запроса Headers
| Параметр | Тип | Описание |
|---|---|---|
| HEADER "token: MjM6RmRnZD***" | Required | Уникальный секретный ключ мерчанта, предоставляется со стороны OSON. |
Важно! Не передавайте секретный токен третьим лицам!
Body запроса
| Параметр | Тип | Описание |
|---|---|---|
| "merchant_id": 12345 | Required | Уникальный ID мерчанта, предоставляется со стороны OSON |
| "transaction_id": "893794793973" | Required | Уникальный идентификатор счета в системе мерчанта (не более 36 символов) |
| "phone": "998981234567" | Optional | Номер телефона пользователя, на который выставляется счет |
| "user_account": "user@mail.com" | Required | Идентификатор пользователя в системе мерчанта |
| "amount": 5000.00 | Required | Сумма счета, округленная до 2 знаков после запятой в меньшую сторону |
| "currency": "UZS" | Required | Валюта. "UZS" |
| "comment": "Оплата заказа №51" | Optional | Комментарий к счету (не более 128 символов) |
| "return_url": "http://merchant.site.uz/return_URL" | Optional | URL на который следует перенаправить покупателя после завершения оплаты |
| "lifetime": 30 | Optional | Время жизни платежа с момента создания (в минутах). / default 10days / min 30, max 14400 |
Ответ на запрос Resp:
| Параметр | Описание |
|---|---|
| "error_code": 0 | Уникальный ID мерчанта, предоставляется со стороны OSON |
| "message": "Success" | Детальное описание ошибки |
| "status": "REGISTRED" | Статус данного платежа |
| "transaction_id": "893794793973" | Уникальный идентификатор счета в системе мерчанта |
| "bill_id": 33936 | Уникальный идентификатор счета |
| "pay_url": "https://pay.oson.uz/checkout/123456789123456" | Ссылка для переадресации пользователя на созданную платежную форму |
После получения этого ответа, он отправляется на ссылку в pay_url где клиент платит. Потом, интернет магазин перенаправляется на return_url
Для получение статус платежа нужно отправить POST запрос на данный URL POST "POST "{base_url}/api/invoice/status/"
| Параметр | Тип | Описание |
|---|---|---|
| HEADER "token: MjM6RmRnZD***" | Required | Уникальный секретный ключ мерчанта, предоставляется со стороны OSON. |
Body запроса
| Параметр | Описание |
|---|---|
| "merchant_id": 15 | Уникальный ID мерчанта |
| "transaction_id": "123456789" | Уникальный идентификатор счета в системе мерчанта (не более 36 символов) |
Ответ на запрос Resp:1
| Статусы счетов | Описание |
|---|---|
| "status": "REGISTRED" | Статус данного платежа |
| "transaction_id": "123456789" | Уникальный идентификатор счета в системе мерчанта |
| "bill_id": 6104 | Уникальный идентификатор счета |
| "pay_url": "https://pay.oson.uz/checkout/123456789123456" | Ссылка для переадресации пользователя на созданную платежную форму |
| "error_code": 0 | Код ошибки |
| "message": "Success" | Детальное описание ошибки |
| Статусы счетов | Описание |
|---|---|
| UNDEF | Счет выставлен, ожидает оплаты |
| PAID | Счет оплачен |
| DECLINED | Счет отклонен |
| ON_PROGRESS | Счёт в процессе оплаты |
| PAY_ERROR | Ошибка при оплате счёта |
| EXPIRED | Время жизни счета истекло. Счет не оплачен |
| RETURNED | Полный возврат суммы пользователю |
Второй вариант: Модальное окно на сайте магазина
<form action="{api}" id="oson_form" method="POST">
<div class="osonPay">
<!-- to change button color change class (oson_dark_btn) to (oson_light_btn) -->
<button class="osonOpen oson_dark_btn" type="submit">Oson Pay</button>
</div>
</form>
<script type="text/javascript" src="https://pay.oson.uz/assets/btn_invoice/cdn.js"></script>
{api} API URL который интернет-магазина принимает при POST запросе, этот API URL должен возвращать ответ в json формате и он должен вернуть следующие параметры:
{ "status" : 1, "pay_url" : "https://pay.oson.uz/checkout/123456789123456", "error_text" : "" }
Статусы (для кнопки)
- 1 = Успешно
- 9 = Ошибка
Вы получите URL-адрес в (pay_url) из "{base_url} / api / invoice / create /", который мы предоставили выше.
в случае успеха (pay_url) обязательно должен прийти Если есть ошибка (error_text) обязательно должна прийти
Уведомления об оплате счета
Уведомление о платеже отправляются только по HTTPS протоколу.
Уведомление представляет собой входящий POST-запрос на notify_url, предоставляемый мерчантом:
Тело запроса содержит JSON данные счета (UTF-8):
{
"status": "DECLINED",
"transaction_id": "12345",
"bill_id": 6115,
"signature": "1f6df66ecf41280a6c66fc2076db19862dcc0f4c6bd76a7ab811feddc05ae2d8"
}
После получения входящего уведомления необходимо проверить подлинность уведомления.
Для этого используется механизм цифровой подписи.
Подпись уведомления отправляется в параметре "signature".
Алгоритм проверки подписи:
Объединить значения параметров в одну строку с разделителем ":"
parameters = {transaction_id}:{bill_id}:{status}
Вычислить хэш алгоритмом хэширования sha256:
signature = sha256( sha256( {secret_token}:{merchant_id} ):{parameters} )
Если в ответе код состояния HTTP отличается от 200 (OK), это интерпретируется как ошибка мерчанта.