Antifraud API

Protocol purpose

The protocol is intended for interaction with the antifraud server. Server processes the requests and sends the responses in JSON format. The request is to be sent through HTTP POST.

Data are to be transferred in coding utf-8

Authorization

The authorization of the merchant is based on the following parameters: login, md5 хеш from the password and ip-address of the merchant

Validation of transaction

4.1.1 Request

Field title	Description	Type	Mandatory
auth	Authorization	Auth	yes
order	Description of Order	Order	yes
client	Payer	Client	yes
receiverClient	Recipient (for P2P transfer)	ReceiverClient	no
deliveryClient	Recipient	DeliveryClient	no
bankData	bank transaction data	BankData	no

ValidateTransactionRequest

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

ValidateTransactionResponse

{
transactionId: 10245789,
reference: “HP232233”,
result: ”10”,
status: “OK”,
timestamp: 1414505799
}

Field title	Description	Type	Obligatory
transactionId	number of transaction in antifraud system	Int	Yes
reference	number of transaction of Internet-shop	String(32)	Yes
result	result of request performance	Int	Yes
status	transaction status	ENUM (OK, PENDING, FRAUD, UNKNOWN)	No
timestamp	date and time of response in UNIX-timestamp format	Int	Yes
score	score calculated for transaction	Int	No

Note: parameters status, score are to be transferred in case when value of result parameter is 10

5. Description of protocol elements

Authorization parameters

Field title	Description	Type	Mandatory
login	login of merchant	String(10)	Yes
passwordHash	MD5 Hash of the password	String(32)	Yes
verify		Boolean	Yes

Auth

{
login: “”,
passwordHash: “”,
verify: false
}

Information about order

Field title	Description	Type	Mandatory
product	array of products	Array	no
aviaData	data about air travel	AviaData	no
extraInfo	additional information	String(256)	yes
reference	transaction number of Online Store	String(32)	yes
timestamp	date and time of the order in the UNIX-timestamp format	Integer	yes
currency	currency in digital format ISO 4217	String(3)	yes
amount	Amount of payment	Decimal(12,2)	yes

Note: Field product or aviaData should be mandatory

Order

{
product: Array<Product>,
aviaData: AviaData,
extraInfo: “”,
reference: “HP232233”,
timestamp: 1414504233,
currency: “980”,
amount: 125.25
}

Information about air travel

Field title	Description	Type	Mandatory
departureDate	departure date in format UNIT-timestamp	Int	yes
locationNumber	the number of flight points (numerical value)	Int	yes
locationCodeN	airport code in the three-letter format	Array	yes
firstName	Passenger First Name	String(20)	yes
lastName	Passenger last Name	String(20)	yes
reservationCode	Ticket code	String(15)	yes

Note: one of the fields firstName and lastName should not be empty

AviaData

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

Information about the payment basket

Field title	Description	Type	Obligatory
quantity	quantity of products	Int	yes
product	names of products	String(256)	yes

Product

{
quantity: 1,
product: “пополнение счета Киевстар”
}

Information about the client that performed payment

Field title	Description	Type	Mandatory
address	Address	String(128)	no
city	City	String(128)	no
zipCode	postal code	String(10)	no
state	state/region	String(128)	no
country	Country in digital ISO 3166-1-Alpha 3	String(3)	yes
firstName	Client First Name	String(20)	yes
lastName	Client Last Name	String(20)	yes
email	Client Email	String(40)	yes
ip	ip-address from which the client came	String(15)	yes
phone	phone number in international format, example 380501234567	String(15)	yes
pan	Masked card number, from which payment was made	String(11)	yes
cardholderFirstName	Cardholder Name, as indicated on the card	String(40)	yes
cardholderLastName	Cardholder Last Name, as indicated on the card	String(40)	yes
machineId	device identifier	String(32)	no
inputCardHolderTime	The time spent by the user to enter the name of the card holder	Float	no
inputCardNumberTime	The time spent by the user to enter the card number	Float	no

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
}

Information about recipient

Field title	Description	Type	Mandatory
address	address	String(128)	no
firstName	First Name of the recipient	String(20)	no
lastName	Last Name of the recipient	String(20)	no
phone	Phone number in international format, example 380501234567	String(15)	no
email	Email получателя	String(40)	no
country	Country in digital ISO 3166-1	String(3)	no
city	City	String(128)	no
zipCode	postal code	String(10)	no
state	state/region	String(128)	no

DeliveryClient

{
address: ”пр. Гагарина, 103”,
firstName: “Иван”,
lastName: “Иванов”,
phone: “380501234567”,
email: “client@domen.ua”,
country: “804”,
city: ”Днепропетровск”,
zipCode: 49000,
state: “”
}

Information about recipient (for P2P transfers)

Field title	Description	Type	Mandatory
card	pan card of the recipient	String(11)	yes
firstName	First Name of the recipient	String(20)	no
lastName	Last Name of the recipient	String(20)	no
country	Country of residence of the recipient in digital ISO 3166-1	String(3)	no
address	recipient address	String(128)	no
zipCode	recipient postal code	String(8)	no

ReceiverClient

{
card:”412348-1234”,
firstName: “Иван”,
lastName: “Иванов”,
country: “804”,
address: ”пр. Гагарина, 103”,
zipCode: 49000
}

Information about the payment authorization in the bank

Field title	Description	Type	Mandatory
status	transaction status ()	ENUM (COMPLETE, REFUND, PENDING, AUTHORIZATION)	yes
timestamp	time of response in Bank in the format of UNIX-timestamp	Int	yes
approvalCode	Authorization code	String(6)	yes
payMethod	Payment method (visa, mc, maestro)	String(15)	yes
ecommInd	Type of transaction passing	String(15)	yes
responseCode	Bank response code	String(5)	yes
responseDesc	Description Bank response	String	yes

BankData

{
status: “COMPLETE”,
timestamp: 1414504000,
approvalCode: “34D3W”,
payMethod: “visa”,
ecommInd: ”moto”,
responseCode: ””,
responseDesc: “”
}

6. Possible responses

Code	Description
10	The request was successfully processed
100	Obligatory parameter is missing
101	Transaction with specified reference was not found
102	Transaction with specified reference already exists
103	Wrong value of parameter
200	Error of authorization
201	ECP checking failed
300	Service is temporary unavailable
400	Error in script performance
401	DB error
402	Transaction creation failed. Please, repeat request

Example requests and responses

Request:

{
"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": "Оплата принята"
}
}

Response:

{
"transactionId": 65214742,
"reference": "48521478",
"result": 10,
"status": "OK",
"timestamp": 1414505799
}