Оплата
Транзакция оплаты - это операция списания средств со счета пользователя в альтернативной платежной системе. Каждая платежная система устанавливает свои условия проведения операции оплаты и имеет собственный механизм списания средств.
Запрос
Для проведения оплаты отправьте POST
запрос на https://api.unonapay.com/beyag/transactions/payments
со следующими параметрами:
Параметр | Тип | Описание |
---|---|---|
request | object | |
amount * обязательный |
integer | Сумма в минимальных денежных единицах. Например, $32.45 должна быть отправлена как 3245. |
currency * обязательный |
string | Валюта транзакции в формате ISO-4217 alpha-3 code. Например, USD . |
description * обязательный |
string | Описание заказа. |
test | boolean | true или false |
expired_at | string | Время в формате ISO-8601, до которого действителен платеж. По умолчанию, бессрочно. Формат: YYYY-MM-DDThh:mm:ssTZD, где YYYY – год (например 2019), MM – месяц (например 02), DD – день (например 09), hh – часы (например 18), mm – минуты (например 20), ss – секунды (например 45), TZD – часовой пояс (+hh:mm или –hh:mm), например +03:00 для Минска. Если в указанный момент платёж всё ещё не будет оплачен, он будет переведён в статус expired . |
tracking_id | string | Внутренний идентификатор платежа (номер заказа или покупателя и т.д.) в системе торговца, по которому можно будет отследить платеж в поступившем уведомлении. В параметре может быть отправлено несколько значений, разделенных символом ; . Например: "cbe59142-90af-4aea-b5a5-5bf3f66cf3da;f7883cb9-0e26-43a7-beb7-4027cb55d1a6;4a6a89d5-6950-400f" . Если в запросе было передано более одного значения tracking_id , поиск транзакции в личном кабинете может быть осуществлен по любому из них. |
ip | string | IP-адрес клиента, производящего оплату в магазине торговца. |
language | string | Язык вашей страницы оформления заказа. Если параметр установлен и уведомление о транзакции по электронной почте включено, UnonaPay отправит письмо по электронной почте, язык текста которого будет соответсвовать значению параметра language . По умолчанию - en . Доступные значения параметра language . |
notification_url | string | URL, на который торговец будет получать уведомления об оплате. Если не указан, уведомления не высылаются. |
verification_url | string | URL, на который будут приходить запрос на подтверждение транзакции. Формат запроса на подтверждение аналогичен формату ответа транзакции. |
return_url * обязательный |
string | URL, на который будет возвращен плательщик после завершения операции в платёжной системе. |
iframe | boolean | Шлите true , если вы на вашем сайте используете оплату через iFrame. Внешняя платёжная система вернет шаблон, который подойдет для открытия в iFrame |
customer * условно обязательный |
object | Секция информации о покупателе. Проверьте описание платежного метода, чтобы узнать, необходимо ли передавать параметры данной секции. |
first_name | string(30) | Имя покупателя. |
last_name | string(30) | Фамилия покупателя. |
middle_name | string(30) | Отчество покупателя. |
string | Адрес электронной почты покупателя. | |
country | string | Страна покупателя в формате ISO 3166-1 alpha-2. |
city | string | Город покупателя. |
zip | string | Почтовый индекс покупателя. |
address | string | Адрес покупателя. |
phone | string | Номер телефона покупателя. |
birth_date | string | Дата рождения покупателя в формате ISO-8601 (YYYY-MM-DD ). |
device_id | string | Идентификационный номер устройства покупателя. |
id_number | string | Номер идентификационного документа покупателя. |
method | object | Набор параметров данной секции зависит от того, какую электронную платёжную систему планируется использовать. |
type * обязательный |
string | Имя платёжной системы или определённый способ оплаты, поддерживаемый подключенной платёжной системой. |
token | string | Токен type способа оплаты, который был получен в какой-то из предыдущих операций для осуществления быстрого платежа. |
additional_data | object | Секция, содержащая дополнительную информацию о платеже. |
contract | array | Массив, элементами которого могут быть параметры:recurring - UnonaPay вернет токен способа оплаты для осуществления последующих платежей без повторного ввода необходимых для type реквизитов платежа. |
receipt_text | array | Текст, который будет добавлен в письмо клиенту. Должен быть представлен как массив строк, например ["Первая строка", "Вторая строка"] . |
customer | object | Секция дополнительной информации о покупателе. Параметры секции зависят от того платежного метода, с помощью которого вы хотите принять оплату от покупателя. |
id * условно обязательный |
string | ID покупателя. Проверьте описание платежного метода, чтобы узнать, какое значение необходимо передать в этом параметре. |
browser | object | Секция параметров браузера клиента. |
user_agent * условно обязательный |
string | Cтрока агента пользователя текущего браузера. Соответствует параметру navigator.userAgent из JavaScript. Смотрите описание параметров платёжного метода, чтобы уточнить, является ли параметр обязательным. |
Пример запроса
{
"request":{
"amount":100,
"currency":"USD",
"description":"description",
"test": false,
"expired_at": "2025-01-01T15:00:00+01:00",
"tracking_id":"your_uniq_number",
"ip":"127.0.0.1",
"language":"en",
"notification_url":"https://merchant.ltd/notification",
"return_url":"https://merchant.ltd/return",
"customer":{
"first_name":"John",
"last_name":"Doe",
"middle_name": "Mid",
"country":"US",
"city":"Denver",
"zip":"96002",
"address":"1st Street",
"phone":"17777777777",
"device_id":"12312312321fff67"
},
"method":{
"type": ":method_name"
}
}
}
Ответ
Если запрос на оплату принят успешно, в ответ на него придет сообщение, содержащее в строковом виде JSON-объект с дополнительными информационными полями. Такое же сообщение будет отправлено после проведения оплаты в уведомлении на адрес, указанный в notification_url
. Полученный в ответе JSON-объект имеет единственный ключ transaction
, значением которого является другой JSON-объект со следующими полями:
Параметр | Тип | Описание |
---|---|---|
transaction | object | |
uid * обязательный |
string | UID обработанной транзакции. |
type * обязательный |
string | Тип транзакции. |
status * обязательный |
string | Статус обработанной транзакции. |
amount * обязательный |
integer | Сумма платежа в минимальных денежных единицах. |
currency * обязательный |
string | Валюта транзакции в формате ISO-4217 alpha-3 code. Например, USD . |
description * обязательный |
string | Описание платежа. |
created_at * обязательный |
string | Время создания транзакции в формате ISO-8601. |
updated_at * обязательный |
string | Время обновления транзакции в формате ISO-8601. |
method_type * обязательный |
string | Имя платёжной системы из запроса. |
receipt_url * обязательный |
string | Ссылка на квитанцию обработанной транзакции. |
{method name} | object | Набор параметров, специфичный для платёжной системы. |
type * обязательный |
string | Имя платёжной системы. |
token | string | Токен способа оплаты для быстрого совершения платежей в последующих операциях. |
qr_code | string | Ссылка на QR код для оплаты. |
payment | object | |
status * обязательный |
string | Статус обработанной транзакции. |
gateway_id * обязательный |
integer | Идентификатор внутреннего платежного шлюза. |
ref_id | string | Номер операции в платёжной системе. |
message | string | Сообщение от платёжной системы. |
bank_code | string | Код результата транзакции на стороне провайдера. |
rrn | string | Идентификатор транзакции на стороне провайдера, полученный от третьей стороны. |
message | string | Сообщение с результатом запроса. |
tracking_id | string | Значение параметра tracking_id из запроса. |
test | boolean | true или false . Транзакция будет тестовой при true |
language | string | Значение параметра language из запроса. |
paid_at | string | Дата проведения транзакции. |
billing_address | object | Информация о плательщике. |
first_name | string | Имя покупателя. |
middle_name | string | Отчество покупателя. |
last_name | string | Фамилия покупателя. |
country | string | Страна покупателя. |
city | string | Город покупателя. |
zip | string | Почтовый индекс покупателя. |
address | string | Адрес покупателя. |
phone | string | Номер телефона покупателя. |
customer | object | Секция информации о покупателе. |
ip | string | IP-адрес покупателя. |
string | email покупателя. | |
form | object | Элементы и атрибуты формы перенаправления на сайт платежной системы (форму с указанными полями и атрибутами необходимо предоставить пользователю для отправки): |
action | string | Атрибут action HTML-формы; |
method | string | Атрибут method HTML-формы; |
fields | array | Массив данных HTML-формы (каждый элемент массива - объект, список ключей которого см. ниже): |
type | string | Тип поля HTML-формы; |
name | string | Название поля HTML-формы; |
id | string | Идентификатор поля HTML-формы; |
value | string | Значение поля HTML-формы; |
additional_data | object | Секция, содержащая дополнительную информацию о платеже. |
В случае ошибки ответ на запрос будет иметь следующие параметры:
Параметр | Тип | Описание |
---|---|---|
message * обязательный |
string | Сообщение об ошибке; |
errors * обязательный |
object | Ассоциативный массив (объект) с ключами соответствующими типам ошибок (например system - системная ошибка): |
error.{key} * обязательный |
array | Массив сообщений об ошибке соответствующего типа. Если ошибка одна (как в примере) - массив будет состоять из одного элемента; |
Пример ответа
{
"transaction":{
"uid":"2-52671c8733",
"type":"payment",
"status":"successful",
"amount":100,
"currency":"USD",
"description":"Test transaction",
"created_at":"2024-06-11T12:04:59+03:00",
"updated_at":"2024-06-11T12:04:59+03:00",
"tracking_id":"tracking_id_000",
"message":"Successfully processed",
"test":true,
"method_type":":method_name",
"receipt_url": "https://online.unonapay.com/customer/transactions/2-52671c8733/11443f39ae75aa1f955a9c9283cd5045bfb0413b65d666f834a9da4e7d3926b5",
":method_name":{
"type":":method_name",
"token":"55524-1559836037-0-1800"
},
"payment":{
"status":"successful",
"gateway_id":85,
"ref_id":"777888",
"message":"The operation was successfully processed",
"bank_code": null,
"rrn": null
},
"customer":{
"ip":"127.0.0.1",
"email":"john@example.com"
},
"billing_address":{
"first_name":"John",
"last_name":"Doe",
"address":"1st Street",
"country":"US",
"city":"Denver",
"zip":"96002",
"phone":17777777777
}
}
}
Пример ответа с параметрами формы
{
"transaction":{
"status":"pending",
"type":"payment",
"uid":"8759cf84-e56d-44b7-a8ae-62640f6402c4",
"amount":1000,
"currency":"USD",
"description":"Order #123",
"tracking_id":"AB8923",
"created_at":"2024-12-07T14:21:24.420Z",
"expired_at":"2025-12-07T14:51:240Z",
"paid_at":"2024-12-07T14:40:120Z",
"test":true,
"method_type":":method_name",
"receipt_url": "https://online.unonapay.com/customer/transactions/2-52671c8733/11443f39ae75aa1f955a9c9283cd5045bfb0413b65d666f834a9da4e7d3926b5",
"language":"en",
"billing_address":{
"first_name": "Ivan",
"middle_name": "M",
"last_name": "Doe",
"country": "LV",
"city": "Riga",
"zip": "LV1024",
"address": "Brivibas str, 123",
"phone": "+372500000000"
},
"customer":{
"email":"ivan@example.com",
"ip":"127.0.0.7"
},
"payment":{
"ref_id":null,
"message":null,
"status":"pending",
"gateway_id":1,
"bank_code": null,
"rrn": null
},
":method_name":{
"type":":method_name",
"account":"myaccount@example.com",
},
"payment_form":{
"action":"https://pay.method-name.com",
"method":"GET",
"fields":[
{
"type":"hidden",
"name":"sid",
"id":"sid",
"value":"185737d3d7f665641ab339ea38dc06bc"
}
]
}
}
}
Пример ответа с ошибкой
{
"message": "Unknown 'method_name_new' payment method",
"errors": {
"system": [
"System error."
]
}
}
Пример HTML-формы на основе ответа
На основе ответа из примера выше необходимо сформировать и предоставить пользователю для отправки следующую HTML-форму:
<form id="payment-form" action="https://pay.method-name.com" accept-charset="UTF-8" method="get">
<input name="utf8" type="hidden" value="✓" />
<input type="hidden" name="sid" id="sid" value="185737d3d7f665641ab339ea38dc06bc" />
<input type="submit" name="submit" value="Оплатить">
</form>
Обратите внимание на то, что в ответе выше отсутствует параметры кнопки отправки формы (<input type="submit" name="submit" value="Оплатить">
) - её вам необходимо добавить самостоятельно в соответствии с дизайном вашего сайта и языковыми предпочтениями.