Призначення протоколу
Протокол призначений для взаємодії з сервером антіфрода. Сервер обробляє запити і відправляє відповіді в форматі 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 | Нет |
5. Опис елементів протоколу
Параметри авторізаціі
| Назва поля | Опис | Тип | Обов'язкове |
| login | login мерчанта | String(10) | так |
| passwordHash | MD5 хеш пароля | String(32) | так |
| verify | Boolean | так |
Auth
{
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: 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) | так |
{
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
}