Merchant API
Словарь терминов
XEZINE — универсальное решение для проведения оплаты от точки приема средств до поставщика товаров и услуг.
Заказ — поручение в XEZINE для сбора заданного количества средств в пользу поставщика товаров и услуг
Точка приема — дополнение к адресу url для конкретной операции
ПТУ – Поставщик товаров и услуг
Общая информация
Данная документация описывает протокол взаимодействия универсальной системы XEZINE, с точками предоставления товаров и услуг. Предназначается техническим специалистам и разработчикам точек предоставления услуг и товаров.
Протокол
Вся информация между точкой предоставления услуг и товаров передается посредством протокола HTTPS и 2048 битного шифрования.
Принцип работы
Для получения оплаты в пользу провайдера услуг или магазинов, необходимо предварительно создать заказ на сумму к оплате в системе XEZINE.
Все оговоренные заранее данные формируются в JSON запрос и подлежат кодированию base64 по стандарту rfc2045. Перед отправкой данных необходимо указать заголовок с типом данных. В данном случае
Content-Type: text/plain-text. В ответ REST-Like сервис возвратит JSON строку с ответом о результате выполнения запроса. Для отправки данных используется метод POST, для получения — GET. Отправка данных осуществляется путем передачи сформированного пакета base64 в теле запроса.
Успешность выполнения запроса определяется полем error в ответе на запрос. Если error=0 то запрос выполнен без ошибок. Если error=1 то имеются ошибки и следует смотреть код ответа (code) и описнаие (message).
Авторизация
Для прохождения авторизации в XEZINE, необходимо отправлять ключ в заголовке предоставленный со стороны XEZINE в каждый запрос к API.
Пример заголовка для авторизации:
Authorization: Bearer XezineKey
Создание заказа
Для создания заказа на оплату, необходимо отправить нижеследующие поля форматом JSON.
| Тип запроса | POST | |
| Точка запроса | /order/add | URL+точка приема |
| currency_code | varchar(3) | Код валюты заказа |
| amount | float | Сумма к оплате |
| vendor_ord_id | varchar(100) | Номер заказа |
| vendor_ord_date | Yyyy-MM-dd HH:mm:ss | Дата заказа |
| lifetime | int(11) | Время жизни заказа к оплате |
| vendor_ord_descr | varchar(255) | Описание заказа |
Пример запроса на отправку до преобразования в base64:
{
"currency_code":"AZN",
"amount":1.25,
"vendor_ord_id":"205",
"vendor_ord_date":"2018-11-01 00:10:25",
"lifetime": 125,
"vendor_ord_descr":"Test order"
}
Пример ответа на на запрос создания заказа:
{
"error": 0,
"code": 0,
"message": "Ok",
"payment_code": 18
}
В процессе создания заказа могут возникнуть ошибки в отправляемых данных. Ниже приведен пример ответа, когда данные отправлены неверно:
{
"error": 1,
"code": 4,
"message": {
"vendor_ord_id": [
"Used vendor_ord_id is already exist.Please use another one."
]
}
}
Просмотр заказа
Для просмотра созданного заказа на оплату, необходимо выполнить GET запрос.
Тип запроса | GET |
|
Точка запроса | /order/{vendor_ord_id} | URL+точка приема |
Пример ответа на на запрос проверки заказа:
{
"vendor_ord_id": "206",
"amount": "1.25",
"currency_code": "AZN",
"vendor_ord_date": "2018-11-01 00:10:25",
"lifetime": "360",
"vendor_ord_descr": "Test order",
"status": 1,
"paid": "0",
"payment_id": 18,
"error": 0,
"code": 0
}
Если заказ не найден, API вернет соответствующий ответ:
{
"error": 1,
"code": 3
}
Отмена заказа
Для отмены заказа на оплату, необходимо отправить нижеследующие поля форматом JSON.
Тип запроса | POST |
|
Точка запроса | /order/cancel | URL+точка приема |
vendor_ord_id | varchar(100) | Номер заказа |
Пример запроса на отправку до преобразования в base64:
{
"vendor_ord_id":"205",
}
Пример ответа на запрос отмены заказа:
{
"error": 0,
"code": 0,
"message": "Ok",
}
Поля ответов
error | int | Код ошибки. 0 — запрос выполнен успешно. 1 — возникли трудности, смотреть code |
code | int | Код ответа, описывающий состояние выполненного запроса |
message | text | Описание выполнения запроса |
vendor_ord_id | varchar(100) | Номер заказа в системе ПТУ |
amount | float | Сумма к оплате |
currency_code | varchar(3) | Код валюты, устанавливается на основе соглашения с XEZINE |
vendor_ord_date | Yyyy-MM-dd HH:mm:ss | Дата создания заказа у ПТУ |
lifetime | int | Время жизни заказа в секундах. По истечении данного периода заказ будет закрыт и прием средств будет остановлен |
vendor_ord_descr | text | Описание заказа предоставленное ПТУ |
status | int | Статус заказа в XEZINE |
paid | float | Оплаченная сумма |
payment_code | int | Номер к оплате через XEZINE. Представлен для отображения пользователю |
Коды ответов
1 | Неверный ключ вендора |
2 | Неверный код заказа вендора |
3 | Заказ не найден |
4 | Получены неверные данные |
5 | Выполнен неверный запрос |
