Антифрод API

Призначення протоколу

Протокол призначений для взаємодії з сервером антіфрода. Сервер обробляє запити і відправляє відповіді в форматі JSON. Запит відправляється через HTTP POST.

Дані передаються в кодуванні utf-8

Авторизація

Авторизація мерчанта грунтується на наступних параметрах: login, md5 хеш від пароля і ip-адреси мерчанта

Валідація транзакції

4.1.1 Запит

Назва поля	Опис	Тип	Обов'язкове
auth	авторизація	Auth	так
order	опис замовлення	Order	так
client	платник	Client	так
receiverClient	отримувач (для P2P переказів)	ReceiverClient	так
deliveryClient	отримувач	DeliveryClient	так
bankData	банковскі дані про транзакцію	BankData	так

ValidateTransactionRequest

{
auth: Auth,
order: Order,
client: Client,
receiverClient: ReceiverClient,
deliveryClient: DeliveryClient,
bankData: BankData
}

ValidateTransactionResponse

{
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	Нет

Примітка: параметри stastus, score передаються в разі значення параметра result дорівнює 10

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 або aviaData має бути обов'язковим

Order

{
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 не має бути пустим

AviaData

{
departureDate: 1414504000,
locationNumber: 2,
locationCodeN: { “KBP” , ”ABC” },
firstName: “Ivan”,
lastName: “Ivanov”,
reservationCode: “GF64234”
}

Інформація про кошик платежів

Название поля	Опис	Тип	Обов'язкове
quantity	кількість товару	Int	так
product	найменування товару	String(256)	так

Product

{
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	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	нет

Client

{
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	Email отримувача	String(40)	ні
country	країна в цифровому ISO 3166-1	String(3)	ні
city	місто	String(128)	ні
zipCode	індекс	String(10)	ні
state	штат(область)	String(128)	ні

DeliveryClient

{
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)	ні

ReceiverClient

{
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	так

BankData

{
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
}