Предназначение протокола
Протокол предназначен для взаимодействия с сервером антифрода. Сервер обрабатывает запросы и отправляет ответы в формате JSON. Запрос отправляется через HTTP POST.
Данные передаются в кодировке utf-8
Авторизация
Авторизация мерчанта основывается на следующих параметрах: login, md5 хеш от пароля и ip-адреса мерчанта
Валидация транзакции
4.1.1 Запрос
Название поля | Описание | Тип | Обязательное |
auth | авторизация | Auth | да |
order | описание заказа | Order | да |
client | плательщик | Client | да |
receiverClient | получатель (для P2P переводов) | ReceiverClient | нет |
deliveryClient | получатель | DeliveryClient | нет |
bankData | банковкие данные о транзакции | BankData | нет |
{
auth: Auth,
order: Order,
client: Client,
receiverClient: ReceiverClient,
deliveryClient: DeliveryClient,
bankData: BankData
}
{
transactionId: 10245789,
reference: “HP232233”,
result: ”10”,
status: “OK”,
timestamp: 1414505799
}
Название поля | Описание | Тип | Обязательное |
transactionId | номер транзакции в системе антифрода | Int | Да |
reference | номер транзакции интернет магазина | String(32) | Да |
result | результат выполнения запроса | Int | Да |
status | статус транзакции | ENUM (OK, PENDING, FRAUD, UNKNOWN) | Нет |
timestamp | дата и время ответа в формате UNIX-timestamp | Int | Да |
score | Расчитаный score для транзакции | Int | Нет |
Примечание : параметры status, score передаётся в случае значения параметра result равно 10
5. Описание элементов протокола
Параметры авторизции
Название поля | Описание | Тип | Обязательное |
login | login мерчанта | String(10) | Да |
passwordHash | MD5 хеш пароля | String(32) | Да |
verify | Boolean | Да |
{
login: “”,
passwordHash: “”,
verify: false
}
Информация о заказе
Название поля | Описание | Тип | Обязательное |
product | массив продуктов | Array | нет |
aviaData | данные об авиаперелёте | AviaData | нет |
extraInfo | дополнительная информация | String(256) | да |
reference | номер транзакции интернет магазина | String(32) | да |
timestamp | дата и время заказа в формате UNIX-timestamp | Integer | да |
currency | валюта в цифровом формате ISO 4217 | String(3) | да |
amount | сумма платежа | Decimal(12,2) | да |
Примечание : поле product или aviaData должно быть обязательным
{
product: Array<Product>,
aviaData: AviaData,
extraInfo: “”,
reference: “HP232233”,
timestamp: 1414504233,
currency: “980”,
amount: 125.25
}
Информация об авиаперелете
Название поля | Описание | Тип | Обязательное |
departureDate | дата вылета в формате UNIT-timestamp | Int | да |
locationNumber | количество точек перелета (численное значение) | Int | да |
locationCodeN | код аэропорта в трехбуквенном формате | Array | да |
firstName | имя пассажира | String(20) | да |
lastName | фамилия пассажира | String(20) | да |
reservationCode | код билета | String(15) | да |
Примечание : одно из полей firstName и lastName должно быть непустым
{
departureDate: 1414504000,
locationNumber: 2,
locationCodeN: { “KBP” , ”ABC” },
firstName: “Ivan”,
lastName: “Ivanov”,
reservationCode: “GF64234”
}
Информация о корзине платежей
Название поля | Описание | Тип | Обязательное |
quantity | количество товара | Int | да |
product | наименование товара | String(256) | да |
{
quantity: 1,
product: “пополнение счета Киевстар”
}
Информация о клиенте, совершившим платеж
Название поля | Описание | Тип | Обязательное |
address | адрес | String(128) | нет |
city | город | String(128) | нет |
zipCode | индекс | String(10) | нет |
state | штат(область) | String(128) | нет |
country | страна в цифровом ISO 3166-1-Alpha 3 | String(3) | да |
firstName | имя клиета | String(20) | да |
lastName | фамилия клиента | String(20) | да |
| Email клиента | String(40) | да |
ip | ip-адрес, с которого заходил клиент | String(15) | да |
phone | номер телефона в международном формате, например 380501234567 | String(15) | да |
pan | маскированый номер карты, с которой была оплата товара | String(11) | да |
cardholderFirstName | имя владельца карты, как указано на карте | String(40) | да |
cardholderLastName | фамилия владелька карты, как указано на карте | String(40) | да |
machineId | Идентификатор устройства | String(32) | нет |
inputCardHolderTime | Время, потраченное пользователем на ввод имени владельца карты | Float | нет |
inputCardNumberTime | Время, потраченное пользователем на ввод номера карты | Float | нет |
{
address: ”пр. Гагарина, 103”,
city: ”Днепропетровск”,
zipCode: 49000,
state: “”,
country: “804”,
firstName: “Иван”,
lastName: “Иванов”,
email: “client@domen.ua”,
ip: “77.120.11.12”,
phone: “380501234567”,
pan: “412348-1234”,
cardholderFirstName: “IVAN”,
cardholderLastName: “IVANOV”,
inputCardHolderTime: 125.15,
inputCardNumberTime: 35.47
}
Информация о получателе
Название поля | Описание | Тип | Обязательное |
address | адрес | String(128) | нет |
firstName | имя получателя | String(20) | нет |
lastName | фамилия получателя | String(20) | нет |
phone | номер телефона в международном формате, например 380501234567 | String(15) | нет |
| Email получателя | String(40) | нет |
country | страна в цифровом ISO 3166-1 | String(3) | нет |
city | город | String(128) | нет |
zipCode | индекс | String(10) | нет |
state | штат(область) | String(128) | нет |
{
address: ”пр. Гагарина, 103”,
firstName: “Иван”,
lastName: “Иванов”,
phone: “380501234567”,
email: “client@domen.ua”,
country: “804”,
city: ”Днепропетровск”,
zipCode: 49000,
state: “”
}
Информация о получателе (для P2P переводов)
Название поля | Описание | Тип | Обязательное |
card | pan карты получателя | String(11) | да |
firstName | имя получателя | String(20) | нет |
lastName | фамилия получателя | String(20) | нет |
country | страна проживания получателя в цифровом ISO 3166-1 | String(3) | нет |
address | адрес получателя | String(128) | нет |
zipCode | почтовый индекс получателя | String(8) | нет |
{
card:”412348-1234”,
firstName: “Иван”,
lastName: “Иванов”,
country: “804”,
address: ”пр. Гагарина, 103”,
zipCode: 49000
}
Информация об авторизации платежа в банке
Название поля | Описание | Тип | Обязательное |
status | статус тразнкции () | ENUM (COMPLETE, REFUND, PENDING, AUTHORIZATION) | да |
timestamp | время транзакции в банке в формате UNIX-timestamp | Int | да |
approvalCode | код авторизации | String(6) | да |
payMethod | способ оплаты (visa, mc, maestro) | String(15) | да |
ecommInd | тип прохождения транзакции | String(15) | да |
responseCode | код ответа банка | String(5) | да |
responseDesc | описание ответа банка | String | да |
{
status: “COMPLETE”,
timestamp: 1414504000,
approvalCode: “34D3W”,
payMethod: “visa”,
ecommInd: ”moto”,
responseCode: ””,
responseDesc: “”
}
6. Возможные ответы
Код | Описание |
10 | Запрос успешно обработан |
100 | Не хватает обязательного параметра |
101 | Транзакция с указанным reference не найдена |
102 | Транзакция с указанным reference уже существует |
103 | Неверное значение параметра |
200 | Ошибка авторизации |
201 | ЭЦП не прошла проверку |
300 | Сервис временно не доступен |
400 | Ошибка выполнения скрипта |
401 | Ошибка БД |
402 | Не удалось создать транзакцию. Повторите запрос |
Пример запросов и ответов
{
"auth": {
"login": "test",
"passwordHash": "098f6bcd4621d373cade4e832627b4f6",
"verify": false
},
"order": {
"aviaData": {
"departureDate": 1414504000,
"locationCodeN": [ "KBP" ],
"locationNumber": 1,
"firstName": "Ivan",
"lastName": "Ivanov",
"reservationCode": "FG78393GZ"
},
"product": [
{
"quantity": 1,
"product": "Велосипед"
},
{
"quantity": 2,
"product": "Зеркала к велосипеду"
}
],
"extraInfo": "Дополнительная информаци о заказе",
"reference": "48521478",
"timestamp": 1414504233,
"currency": "980",
"amount": 125.05
},
"client": {
"address": "ул. Гагарина, д. 11",
"city": "Киев",
"zipCode": "32014",
"state": "киевская",
"country": "804",
"firstName": "Иван",
"lastName": "Иванов",
"email": "ivanov@gmail.com",
"ip": "77.120.98.36",
"phone": "38050123457",
“pan”: “440588-2222”,
"cardholderFirstName": "IVAN",
"cardholderLastName": "IVANOV",
“timezone”: 0,
“machineId”: “”
},
"receiverClient": {
"card": "4123451234",
"firstName": "Петр",
"lastName": "Петров",
"country": "804",
"address": "ул. Заводская, д.78/54",
"zipCode": "49102"
},
"deliveryClient": {
"address": "ул. Космонавтов, д. 11, кв. 44",
"firstName": "Геннадий",
"lastName": "Чебурашкин",
"phone": "380671324567",
"email": "g.cheb@mail.ru",
"country": "804",
"city": "Харьков",
"zipCode": "37201",
"state": "харьковская"
},
"bankData": {
"status": "COMPLETE",
"timestamp": 1414504000,
"approvalCode": "451973",
"payMethod": "visa",
"ecommInd": "3ds",
"responseCode": "10",
"responseDesc": "Оплата принята"
}
}
{
"transactionId": 65214742,
"reference": "48521478",
"result": 10,
"status": "OK",
"timestamp": 1414505799
}