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_codevarchar(3)Код валюты заказа
amountfloatСумма к оплате
vendor_ord_idvarchar(100)Номер заказа
vendor_ord_dateYyyy-MM-dd HH:mm:ssДата заказа
lifetimeint(11)Время жизни заказа к оплате
vendor_ord_descrvarchar(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

Выполнен неверный запрос