Предназначение протокола
Протокол предназначен для взаимодействия с сервером антифрода. Сервер обрабатывает запросы и отправляет ответы в формате 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
}
