Для полноценного обмена данными с СПМ внешней системе необходимо использовать клиентскую часть для вызова программных интерфейсов СПМ и организующую взаимодействие между двумя системами в реальном времени. Такое взаимодействие осуществляется с помощью программных интерфейсов SOAP, которые предоставляются СПМ. Обмен данными ведется по протоколу HTTPS с доверительными SSL сертификатами. Для получения доступа к программным интерфейсам необходима авторизация с использованием наименования учетной записи (логина) и пароля.
Для корректной работы с веб-сервисами по защищенному TLS-соединению необходимо иметь на своей стороне в хранилище доверенных корневых сертификатов следующие сертификаты:
- корневой сертификат от Comodo: COMODO RSA Certification Authority (https://support.comodo.com/index.php?/Default/Knowledgebase/Article/View/969/108/root-comodo-rsa-certification-authority-sha-2);
- корневой сертификат от GlobalSign: GlobalSign Root CA R1 (https://www.globalsign.com/repository/ca-certificates/).
Перед началом работы следует проверить наличие этих сертификатов в хранилище и добавить их в случае необходимости.
Доступ к программным интерфейсам (API) осуществляется по адресу https://afs-api.paysecure.ru/antifraudapi.
WSDL для реализации протокола SOAP клиента можно получить по адресу https://afs-api.paysecure.ru/antifraudapi?wsdl.
При передаче внешней системой данных о платежной операции в СПМ для анализа на мошенничество возможны два варианта использования СПМ.
- Внешняя система собирает все данные по платежной операции, после чего передает их для анализа в СПМ путем вызова SOAP процедуры проверки операции check со всеми обязательными и известными вспомогательными параметрами. В этом случае возможно использование всех видов анализа платежной операции, имеющихся в СПМ.
- Внешняя система обращается к СПМ несколько раз за одну операцию по мере накопления данных о заказе, покупателе и его платежном средстве. При этом каждый раз осуществляется вызов процедуры проверки операции check со всеми обязательными и известными на текущий момент параметрами, и возможно использование только тех имеющихся в СПМ видов анализа, для которых достаточно данных. Такой вариант работы предполагает, что каждый последующий вызов должен дополнять предыдущий. Если при очередном вызове будет отсутствовать один из необязательных параметров, которых присутствовал в предыдущем вызове, то в базе данных СПМ значение этого параметра будет удалено. Это означает, что в каждом вызова должны содержаться все известные параметры по платежной операции.
После того, как на стороне внешней системы принято решение об авторизации платежа или о его отклонении, внешняя система обязана уведомить о своем решении СПМ, вызвав процедуру изменения статуса операции setStatus. После вызова этой процедуры любые попытки внести изменения по данной платежной операции через процедуру проверки check будут игнорироваться без каких-либо проверок, при этом каждый раз будет возвращаться текущий фрод-статус платежа.
Для получения информации о выставленном СПМ фрод-статусе платежа, для которого внешней системой уже были переданы параметры, используется процедура getFraudStatus.
Для регистрации мерчантов на стороне СПМ внешняя система может использовать сервис отсылки данных по мерчанту – процедуру setMerchantData. Эта же процедура применяется для синхронизации данных мерчанта при изменении наименования или E-mail адреса мерчанта во внешней системе.
При передаче данных по платежной операции передается идентификатор мерчанта из внешней системы, которому принадлежит этот платеж. Если такой мерчант не был зарегистрирован в СПМ на момент передачи данных о платеже и в СПМ для текущей внешней системы настроено автоматическое создание мерчанта по платежу, то СПМ добавит в свою базу запись с новым мерчантом и отошлет уведомление об этом во внешнюю систему. Внешняя система обрабатывает полученное уведомление и отсылает данные по мерчанту, используя процедуру setMerchantData.
Если плательщики осуществляют платежи с использованием web-страниц внешней системы, то на той web-странице, после которой последует проверка платежа в СПМ, желательно разместить вызов следующего JavaScript-кода СПМ:
<script
type="text/javascript">
window.collect_afs_data_func = function() {
try {
var url = "https://afs-api.paysecure.ru/antifraudapi/rest/afs_data_collector.js?outSystemId=...&outPaymentId=...";
var method = "GET";
var xhr = window.XMLHttpRequest ? new XMLHttpRequest() : new XDomainRequest();
if ("withCredentials" in xhr) {
xhr.open(method, url, true);
} else if (typeof XDomainRequest !="undefined") {
xhr = new XDomainRequest();
xhr.open(method, url);
} else {
xhr = null;
}
if (xhr) {
xhr.onreadystatechange=function() {
if (xhr.readyState==4 || xhr.readyState=="complete") {
try {
eval(xhr.responseText);
} catch (e) {alert(e);}
}
};
try {
xhr.withCredentials = true;
} catch (e) {
}
xhr.send('');
}
} catch (e) {
alert(e);
}
};
if (window.addEventListener) {
window.addEventListener('load', function(){window.collect_afs_data_func(); }, false);
} else if (window.attachEvent) {
window.attachEvent('onload', function(){window.collect_afs_data_func();});
}
</script>
При этом необходимо присваивать параметрам outSystemId и outPaymentId в url соответствующие значения идентификаторов (см.табл."Обязательные поля CheckPaymentParams").
Процедура проверки платежной операции
Наименование процедуры проверки платежной операции - check.
Входные параметры
Единственным входным параметром, который передается внешней системой в СПМ для анализа платежной операции, является параметр params, который представляет собой структуру данных с именем CheckPaymentParams.
Обязательные поля CheckPaymentParams
Обязательные поля параметра передаются как простые типы данных (целочисленные, строковые, логические).
Обязательные поля CheckPaymentParams
Поле | Описание | Тип |
outPaymentId | Идентификатор платежной операции во внешней системе | Целочисленный (15) |
outSystemId | Идентификатор внешней системы | Целочисленный (15) |
outMerchantId | Внешний идентификатор мерчанта | Целочисленный (15). |
domainId | Код приложения/сервиса внешних систем из соответствующего справочника СПМ. | Целочисленный (15) |
paymentTypeId | Тип платежа | Целочисленный (15) Целочисленный код из справочника СПМ, см. табл." Типы платежей". |
Типы платежей
Наименование | Код |
e-commerce | 1 |
MO/TO | 2 |
POS | 3 |
Необязательные поля CheckPaymentParams
При передаче параметра также предусмотрено использование необязательных полей.
Если внешняя система обращается к СПМ несколько раз за одну операцию по мере накопления данных о заказе, покупателе и его платежном средстве, то при повторных вызовах уже переданные ранее поля опускать запрещается. Поля, по которым у клиента нет информации, передаются в виде пустых (null) значений.
Необязательные поля CheckPaymentParams
Поле | Описание | Тип |
paymentAttributes | Список из структур | |
clientAttributes | Данные браузера клиента, выполняющего платеж | Список из структур |
httpAttributes | Заголовки http-запроса браузера клиента к внешней системе при проведении операции | Список из структур |
serverAttributes | Переменные среды окружения | Список из структур |
timeOut | Время ожидания ответа от сервера СПМ (в мс). Если значение не указано, используется значение по умолчанию – 10 секунд. Если указано отрицательное значение, то проверка на максимальное время ответа не используется. Примечание. Имеется возможность отключить принудительное оповещение внешней системы об установленном фрод-статусе платежа в том случае, если время обработки этого платежа превысило максимально допустимое. Настройка осуществляется с помощью сотрудников службы технической поддержки. По умолчанию оповещение осуществляется. | Целое число |
sendNotification | Необходимость принудительного оповещения внешней системы об установленном фрод-статусе данной платежной операции по окончании работы процедуры check. По умолчанию оповещение не отправляется. | Логический (true, false) |
paymentStatus | Структура данных |
Структуры в описании полей CheckPaymentParams
Структура | Описание | Тип |
name | Наименование параметра | Строковый, инвариантен к регистру |
booleanValue | Заполняется, если параметр имеет логический тип данных | Логический (true, false) |
doubleValue | Заполняется, если параметр имеет числовой тип данных | Числовой |
stringValue | Заполняется, если параметр имеет строковый тип данных | Строковый |
intValue | Заполняется, если параметр имеет целочисленный тип данных | Целое число |
dateValue | Заполняется, если параметр имеет тип данных дата | Дата |
При заполнении необязательных полей нужно учитывать их тип (указан в спецификации) и заполнять соответствующие параметры структуры. В противном случае заданные значения будут игнорироваться.
Данные по операции (paymentAttributes)
Данные по операции
Поле | Описание | Тип |
Meannumber | Зашифрованный номер платежного средства1, должен передаваться в виде строки: "IR_TOKEN=<необратимый токен PAN> BIN=<6 первых цифр PAN> POST==<4 последних цифры PAN>". Альтернативная возможность передавать номер платежного средства в незашифрованном виде в настоящий момент существует, но в будущем будет исключена. | Строковый (70 символов) |
meanTypeGroup | Группа по типу платежного средства: 1 – карта (значение по умолчанию), 2 – электронный кошелек. | Целочисленный (1) |
meanType | Тип электронного кошелька (обязательный параметр для кошельков), используемые типы электронных кошельков представлены в дополнительной таблице «Типы электронных кошельков» . | Строковый (3 символа) |
OutAmount | Сумма платежа в оригинальной валюте | Числовой (15,2) |
OutCurrencyCode | Буквенный код валюты платежа в соответствии с ISO 42 17 | Строковый (3 символа) |
BillNumber | Номер счета из внешней системы | Строковый (30 символов) |
OrderNumber | Номер заказа платежной операции | Строковый 128 символов) |
Email-адрес покупателя | Строковый (128 символов) | |
Firstname | Имя покупателя | Строковый (70 символов) |
Middlename | Отчество покупателя | Строковый (70 символов) |
Lastname | Фамилия покупателя | Строковый (70 символов) |
Regioncode | Код региона покупателя | Строковый (8 символов) |
Regionname | Наименование региона | Строковый (70 символов) |
City | Город | Строковый (70 символов) |
Countrycode | Код страны в соответствии с ISO 3166 alpha-2 | Строковый (2 символа) |
Address | Почтовый адрес | Строковый (256 символов) |
Postcode | Почтовый индекс | Строковый (25 символов) |
Phone | Номер телефона | Строковый (20 символов) |
Workphone | Номер рабочего телефона | Строковый (20 символов) |
Mobilephone | Номер мобильного телефона | Строковый (20 символов) |
Cardholder | Держатель карты | Строковый (130 символов) |
Bankname | Наименование банка-эмитента | Строковый (100 символов) |
Acquirer | Уникальное наименование эквайера в пределах внешней системы | Строковый (10 символов) |
Date | Дата проведения платежа в UTC (GMT-0) или же с указанием часового пояса. Если не указано, то берется текущая дата. | Дата |
Expiredate | Дата окончания действия банковской карты (месяц, год) | Дата |
BillingNumberTag | Тип биллингового номера, в пользу которого производится оплата: номер мобильного телефона, номер договора на оказание услуг связи и т.д. В настоящий момент для активации доступны следующие типы биллингов:
| Строковый (10 символов) |
BillingNumber | Биллинговый номер (Billing number), в пользу которого производится оплата. | Строковый (50 символов) |
TwoStepSchema | Двустадийная схема оплаты. Если не указано, то false – одностадийная схема оплаты без подтверждения. | Логический (true, false) |
Дополнительные поля авторизации для платежей по картам American Express | ||
billingPostalCode | Индекс предприятия связи покупателя | Строковый (9 символов) |
billingAddress | Адрес покупателя | Строковый (20 символов) |
billingFirstName | Имя покупателя | Строковый (15 символов) |
billingLastName | Фамилия покупателя | Строковый (30 символов) |
billingPhoneNumber | Номер телефона покупателя | Строковый (10 символов) |
billingEMailAddress | Адрес E-mail покупателя | Строковый (60 символов) |
TestMode | Режим тестирования. Платеж является тестовым. | Логический (true, false) |
RecurringIndicator | Режим рекуррентного платежа | Логический (true, false) |
usedCSC | Использовался ли Card Secure Code | Логический (true, false) |
3DSecAuthresult | Результат авторизации по 3DSecure (Y - успешно, N - неуспешно, A - Attempt, U –неизвестно) | Строковый (1 символ) |
AirData | XML с описанием дополнительных параметров, определенных для авиаперевозчиков2 | Текст |
BookingData | XML с описанием дополнительных параметров по бронированию и оплате гостиниц3 | Текст |
3DSecAuthrequired | Результат проверки вовлеченности карты (1 – вовлечена, 0 – не вовлечена, -1 – неизвестно, null – все остальное) | Числовой (1) |
1Для использования сервиса необратимой токенизации от компании Assist необходимо обратиться в службу технической поддержки (support@assist.ru).
Выделенные в таблице жирным шрифтом поля являются обязательными для запуска методов математического моделирования. Дополнительно выделенные в таблице подчеркиванием поля являются желательными для качественной работы методов математического моделирования.
Типы электронных кошельков
Тип кошелька | Наименование кошелька |
WM | WebMoney |
EP | EasyPay |
QW | QIWI |
QB | QIWIBeeline |
QM | QIWIMts |
QF | QIWIMegafon |
MB | Mobicon |
YM | YandexMoney |
2Формат XML с дополнительными полями для авиаперевозчиков:
<ad_pnr>
<pnrdate>...</pnrdate> <!-- datetime 8 -->
<email>...</email> <!-- varchar 128 -->
<language>...</language> <!-- varchar 5 -->
<phoneb>...</phoneb> <!-- varchar 32 (рабочий)-->
<phone>...</phone> <!-- varchar 32 (личный)-->
<phonem>...</phonem> <!-- varchar 32 (мобильный)-->
<airline_rec_loc>...</airline_rec_loc> <!-- varchar 16 (как правило=Record_locator)-->
<record_locator>...</record_locator> <!-- varchar 16 (как правило=PNR)-->
<traveler_id>...</traveler_id> <!-- varchar 16 (код покупателя)-->
<air_amount_1>...</air_amount_1> <!-- money 8 (Сумма в ориг. валюте)-->
<air_amount_2>...</air_amount_2> <!-- money 8 (Сумма в валюте оплаты)-->
<air_amount_with_serv_1>...</air_amount_with_serv_1> <!-- money 8 -->
<air_amount_with_serv_2>...</air_amount_with_serv_2> <!-- money 8 -->
<air_amount_without_tax_1>...</air_amount_without_tax_1> <!-- money 8 -->
<air_amount_without_tax_2>...</air_amount_without_tax_2> <!-- money 8 -->
<air_currency_code_1>...</air_currency_code_1> <!-- varchar 5 -->
<air_currency_code_2>...</air_currency_code_2> <!-- varchar 5 -->
<delivery_type>...</delivery_type> <!-- varchar 16 (код получения)-->
<agent_code>...</agent_code> <!-- varchar 16 (код агента)-->
<charge_type>...</charge_type> <!-- varchar 16 (код агента)-->
<ticket_number>...</ticket_number> <!-- varchar 14 (номер билета транз)-->
<restr_ticked_ind>...</restr_ticked_ind> <!-- varchar 1 (Restricted Ticked Indicator)-->
<add_field1>...</add_field1> <!-- varchar 255 (Позиционная расш. запись)-->
<add_field2>...</add_field2> <!-- varchar 255 (Позиционная расш. запись)-->
<number>...</number><!-- varchar 16 (pnr number)-->
<number>...</number><!-- varchar 16 (pnr number)-->
...
<segment> <!-- маршрут -->
<airline_code>...</airline_code> <!-- varchar 5 (код компании)-->
<airline_name>...</airline_name> <!-- varchar 64 (наим. компании)-->
<cabin>...</cabin> <!-- varchar 5 (класс)-->
<flight_number>...</flight_number> <!-- varchar 16 (Номер рейса)-->
<flight_time>...</flight_time> <!-- varchar 12 (Время полета)-->
<itinerary_numb>...</itinerary_numb><!-- int 4 (порядк.номер направления)-->
<orig_numb>...</orig_numb> <!-- int 4 (порядк.номер)-->
<equipment_code>...</equipment_code><!-- varchar 16 (класс)-->
<stop_over_code>...</stop_over_code><!-- varchar 1 (Признак остановки)-->
<from>
<date>...</date> <!-- varchar 50 (время вылета)-->
<code>...</code> <!-- varchar 5 (код аэропорта вылета)-->
<name>...</name> <!-- varchar 64 (название аэропорта вылета)-->
<terminal>...</terminal><!-- varchar 5 (терминал вылета)-->
<country>...</country><!-- varchar 64 (страна вылета)-->
<state>...</state> <!-- varchar 64 (штат страны вылета)-->
<city>...</city> <!-- varchar 64 (город вылета)-->
</from>
<to>
<date>...</date> <!-- varchar 50 (время прилета)-->
<code>...</code> <!-- varchar 5 (код аэропорта прилета)-->
<name>...</name> <!-- varchar 64 (название аэропорта прилета)-->
<terminal>...</terminal><!-- varchar 5 (терминал прилета)-->
<country>...</country> <!-- varchar 64 (страна прилета)-->
<state>...</state> <!-- varchar 64 (штат страны прилета)-->
<city>...</city> <!-- varchar 64 (город прилета)-->
</to>
</segment>
<segment> <!-- маршрут -->
...
</segment>
...
<traveler> <!-- пассажир -->
<orig_numb>...</orig_numb> <!-- int 4 (порядк.номер)-->
<first_name>...</first_name> <!-- varchar 32 -->
<last_name>...</last_name> <!-- varchar 32 -->
<passenger_name>...</passenger_name> <!-- varchar 64 -->
<rbd>...</rbd> <!-- varchar 5 (Классы бронирования)-->
<status>...</status> <!-- varchar 32 (Статус)-->
<ticket_number>...</ticket_number> <!-- varchar 14 (номер билета пассажира)-->
</traveler>
<traveler> <!-- пассажир-->
...
</traveler>
...
<child>
<orig_numb>...</orig_numb> <!-- int 4 -->
<first_name>...</first_name> <!-- varchar 32 -->
<last_name>...</last_name> <!-- varchar 32 -->
</child>
<child>
...
</child>
...
</ad_pnr>
3Формат XML с дополнительными полями по бронированию и оплате гостиниц:
<data>
<email>...</email> <!-- varchar 128 (email алрес покупателя) -->
<from>
<date>...</date> <!-- varchar 14, формат YYYYMMdd HH:mm (дата приезда) -->
</from>
<to>
<date>...</date> <!--varchar 14, формат YYYYMMdd HH:mm (дата отъезда) -->
</to>
<traveler> <!--traveler-->
<orig_numb>...</orig_numb> <!-- int 4 (количество гостей) -->
<first_name>...</first_name> <!-- varchar 32 (имя гостя) -->
<last_name>...</last_name> <!-- varchar 32 (фамилия гостя) -->
<traveler_name>...</traveler_name> <!-- varchar 64 (полное имя гостя) -->
</traveler>
<traveler>...</traveler> <!—следующий гость-->
...
</data>
Данные клиента (clientAttributes)
Данные клиента
Поле | Описание | Тип |
Cookie | Значение уникального идентификатора пользователя в платежном сервисе внешней системы, который соответствует указанному domainId | Строковый (16 символов) |
SystemLanguage | Код языка операционной системы покупателя | Строковый (5 символов) |
BrowserLanguage | Код языка веб-браузера | Строковый (5 символов) |
UserLanguage | Код языка покупателя | Строковый (5 символов) |
TimeZone | Смещение времени в часовом поясе покупателя относительно GMT в минутах. Например, для GMT +2 в часах значение в минутах + 120. | Числовой (5) |
ConnectionType | Тип соединения по HTTP | Строковый (16 символов) |
JsVer | Версия интерпретатора Java script. | Строковый (16 символов) |
LocalTime | Местное время клиента | Строковый (128 символов) |
ScreenRes | Разрешение экрана у клиента | Строковый (16 символов) |
ScreenPixelDepth | Глубина цветов экрана у клиента | Числовой (15) |
BrowserName | Название браузера клиента | Строковый (255 символа) |
CookiesEnabled | Есть поддержка Cookie и они включены в браузере клиента | Логический (true, false) |
JavaEnabled | Есть поддержка Java script и интерпретатор включен. | Логический (true, false) |
BrowserStylesheetsEnabled | Поддержка css стилей. | Логический (true, false) |
BrowserPlatform | Наименование платформы, на которой работает браузер клиента | Строковый (64 символов) |
Processor | Название процессора на клиентской машине. | Строковый (16 символов) |
Latitude | Географическая координата широты, определяющая положение плательщика на поверхности Земли. Указывается в градусах. Например, 55.755831 | Числовой (3,7) |
Longitude | Географическая координата долготы, определяющая положение плательщика на поверхности Земли. Указывается в градусах. Например, 37.617673 | Числовой (3,7) |
Device | Описание электронного устройства пользователя, через которое он совершает оплату. | Строковый (50) |
DeviceUniqueID | Уникальный номер электронного устройства пользователя (UDID, IMEI, MEID, ESN или IMSI). | Строковый (50) |
Application | Название приложения, через которое производится оплата | Строковый (50) |
ApplicationVersion | Версия приложения, через которое производится оплата | Строковый (25) |
MacAddress | Mac адрес сетевого устройства пользователя | Строковый (17) |
AndroidID | Идентификатор Android устройства | Строковый (20) |
AccountLifetimeDays | Срок существования учетной записи в днях | Числовой (5) |
OrdersNumber | Количество заказов с момента регистрации | Числовой (7) |
LastBuyDays | Количество дней с момента последней покупки | Числовой (5) |
LastChangePwdDate | Дата и время последней смены пароля пользователя | Дата |
IsFirstBuy | Признак первой покупки клиента | Логический (true, false) |
TotalOrdersAmount | Общая сумма покупок | Числовой (15,2) |
CurrentSessionTime | Время сессии клиента. Время, прошедшее с момента логина до момента формирования заказа в минутах. | Числовой (5) |
Выделенные в таблице жирным шрифтом поля являются желательными для качественной работы методов математического моделирования.
HTTP заголовки (httpAttributes)
HTTP заголовки
Поле | Описание | Тип |
AcceptLanguage | Заголовок Accept Language http-запроса. | Строковый (128 символов) |
UserAgent | Заголовок User Agent http-запроса. | Строковый (255 символов) |
Accept | Заголовок Accept http-запроса. | Строковый (255 символов) |
Referer | Заголовок Referer http-запроса. | Строковый (255 символов) |
Forwarded | Заголовок Forwarded http-запроса. | Строковый (16 символов) |
XForwardedFor | Заголовок XForwarded-For http-запроса. | Строковый (16 символов) |
Via | Заголовок Via http-запроса. | Строковый (128 символов) |
Переменные окружения сервера (serverAttributes)
Переменные окружения сервера
Поле | Описание | Тип |
RemoteAddress | IP-адрес клиента. | Строковый (16 символов) |
ServerProtocol | Переменная окружения Server_Protocol. | Строковый (16 символов) |
HostName | Имя хоста клиента. | Строковый (70 символов) |
В случае превышения указанной длины полей параметра процедура закончится неуспешно (код результата работы вызванной процедуры будет отличен от нуля). Исключение составляют только HTTP заголовки. В случае превышения длины HTTP заголовков они будут принудительно укорочены до указанной длины, после чего процедура продолжит работу.
Выходные параметры
Результатом работы процедуры всегда является ответ в виде объекта типа getAFSResult, содержащий данные о проверке платежа в случае успешного выполнения процедуры (код результата ее работы RetCode равен нулю) или не содержащий данные о проверке платежа в случае неуспешного выполнения процедуры (код результата ее работы RetCode не равен нулю).
Выходные параметры процедуры check
Параметр | Описание | Тип |
FraudStatus | Код фрод-статуса проверяемой операции. | Числовой (15) |
ReasonDescription | Описание причины выставления фрод-статуса проверяемой операции . | Строковый (100 символов) |
ReasonId | Код причины выставления фрод-статуса. | Числовой (15) |
RetCode | Результат выполнения процедуры. | Целочисленный (10) |
Description | Произвольный комментарий к результату выполнения процедуры. | Строковый (2000 символов) |
Коды результатов выполнения процедуры check
Код | Описание |
0 | Операция прошла успешно, ошибок нет. |
2 | Ошибка авторизации внешней системы. |
3 | Указан неправильный идентификатор мерчанта. |
6 | Указан неправильный идентификатор типа платежа. |
7 | Указан неправильный идентификатор приложения/сервиса внешней системы или же данное приложение/сервис в СПМ не соответствует указанной внешней системе. |
8 | Превышено выделенное время обработки платежа. При этом обработка платежа в СПМ будет продолжена, но запрос от внешней системы будет прерван и внешней системе будет отослан только данный код ошибки. |
1 | Другая ошибка при выполнении операции. |
Одновременная проверка нескольких платежных операций
Наименование процедуры одновременной проверки нескольких платежных операций - checkArray.
Входные параметры
Входные параметры процедуры checkArray
Параметр | Описание | Тип |
Params | Массив структур данных, каждый элемент которого представляет собой структуру CheckPaymentParams. | Массив структур данных |
waitResults | Параметр указывает, стоит ли дожидаться окончания проверки всех платежей, либо метод вернет ответ (пустой) сразу после создания задач по обработке платежей. Переданные данные по платежам обрабатываются в параллельных потоках, что уменьшает общее время обработки. | Логический (true, false) |
Выходные параметры
Результатом работы процедуры является ответ в виде массива объектов типа getAFSResult. Ответ содержит данные о проверке платежей (коды RetCode), если задано ожидание проверки всех платежей. Ответ не содержит данные о проверке платежей (коды RetCode равны нулю), если не задано ожидание проверки всех платежей. Подробности.
Процедура передачи данных по 3DS транзакциям
Наименование процедуры передачи данных по 3DS транзакциям - set3DSecData. Вызов этой процедуры следует осуществлять после вызова процедуры checkPayment для данного платежа.
Входные параметры
Все параметры данной процедуры являются обязательными.
Входные параметры процедуры set3DSecData
Параметр | Описание | Тип |
outPaymentId | Идентификатор платежной операции во внешней системе. | Числовой (15) |
outSystemId | Идентификатор внешней системы. | Числовой (15) |
authResult | Результат авторизации по 3DSecure (Y - успешно, N - неуспешно, A - Attempt, U –неизвестно). | Строковый (1 символ) |
authRequired | Результат проверки вовлеченности карты (1 – вовлечена, 0 – не вовлечена, -1 – неизвестно, null – все остальное). | Числовой (1) |
Выходные параметры
Результатом работы процедуры является текущий фрод-статус платежа, который можно использовать для принятия решения о дальнейших действиях над платежом.
Выходные параметры процедуры set3DSecData
Параметр | Описание | Тип |
FraudStatus | Код фрод-статуса проверяемой операции . | Числовой (15) |
ReasonDescription | Описание причины выставления фрод-статуса проверяемой операции. | Строковый (100 символов) |
ReasonId | Код причины выставления фрод-статуса . | Числовой (15) |
RetCode | Результат выполнения процедуры. | Целочисленный (10) |
Description | Произвольный комментарий к результату выполнения процедуры. | Строковый (2000 символов) |
Коды результатов выполнения процедуры set3DSecData
Код | Описание |
0 | Операция прошла успешно, ошибок нет. |
2 | Ошибка авторизации внешней системы. |
4 | Указан несуществующий идентификатор платежа. |
1 | Другая ошибка при выполнении операции. |
Процедура получения фрод-статуса операции
Наименование процедуры получения фрод-статуса платежной операции - getFraudStatus. Вызов этой процедуры следует осуществлять после вызова процедуры checkPayment для данного платежа.
Входные параметры
Все параметры данной процедуры являются обязательными.
Входные параметры процедуры getFraudStatus
Параметр | Описание | Тип |
outPaymentId | Идентификатор платежной операции во внешней системе. | Числовой (15) |
outSystemId | Идентификатор внешней системы. | Числовой (15) |
Выходные параметры
Результатом работы процедуры всегда является ответ в виде объекта типа getAFSResult, содержащий данные о проверке платежа в случае успешного выполнения процедуры (код результата ее работы RetCode равен нулю) или не содержащий данные о проверке платежа в случае неуспешного выполнения процедуры (код результата ее работы RetCode не равен нулю).
Выходные параметры процедуры getFraudStatus
Параметр | Описание | Тип |
FraudStatus | Код фрод-статуса проверяемой операции . | Числовой (15) |
ReasonDescription | Описание причины выставления фрод-статуса проверяемой операции. | Строковый (100 символов) |
ReasonId | Код причины выставления фрод-статуса. | Числовой (15) |
RetCode | Результат выполнения процедуры. | Целочисленный (10) |
Description | Произвольный комментарий к результату выполнения процедуры. | Строковый (2000 символов) |
PaymentParameters | Список возвращаемых параметров платежа | Список из структур: name — название параметра (строка, регистр не важен); booleanValue — заполняется, если значение параметра имеет логический тип (true, false); doubleValue — заполняется, если значение параметра имеет числовой тип; stringValue — заполняется, если значение параметра имеет строковый тип; intValue — заполняется, если значение параметра имеет целочисленный тип; dateValue — заполняется, если значение параметра имеет тип дата. |
Список возвращаемых параметров платежа PaymentParameters
Параметр | Описание | Тип |
date | Дата платежа, если она была передана от внешней системы. Иначе дата получения данных по платежу в СПМ. | Дата |
calculateAmount | Пересчитанная сумма платежа в основной валюте СПМ. | Числовой |
outAmount | Переданная от внешней системы сумма платежа. | Числовой |
outCurrencyCode | Код валюты, в которой была передана сумма платежа. | Строковый |
Email плательщика. | Строковый | |
phone | Телефон плательщика. | Строковый |
mobilePhone | Телефон плательщика. | Строковый |
cardNumberMask | Номер банковской карты плательщика (первые 6 и последние 4 цифры). | Строковый |
cardType | Тип банковской карты, определенный в СПМ по номеру карты. | Строковый |
cardSubType | Подтип банковской карты, определенный в СПМ по номеру карты. | Строковый |
cardholder | Держатель карты. | Строковый |
cardBankCountry | Страна банка эмитента, определенная по номеру карты. | Строковый |
cardBank | Название банка эмитента, определенное по номеру карты. | Строковый |
expiredate | Дата окончания действия банковской карты. | Дата |
acquirer | Уникальное название эквайера в переделах внешней системы. | Строковый |
cookie | Значение уникального идентификатора плательщика, переданное внешней системой. | Строковый |
ip | IP-адрес покупателя. | Строковый |
ipCountry | Страна, определенная по IP-адресу покупателя. | Строковый |
billNumber | Номер счета из внешней системы. | Строковый |
orderNumber | Номер заказа из внешней системы. | Строковый |
outStatus | Статус операции в соответствии со справочником СПМ. | Числовой |
outStatusName | Название статуса операции. | Строковый |
fraudStatus | Числовой | |
reasonId | Числовой | |
testMode | Тестовый режим. | Логический |
usedCSC | Использовался ли Card Secure Code. | Логический |
3DSecAuthresult | Результат авторизации по 3DSecure (Y - успешно, N - неуспешно, A - Attempt, U – неизвестно). | Строковый |
3DSecAuthrequired | Результат проверки вовлеченности карты (1 – вовлечена, 0 – не вовлечена, -1 – неизвестно, null – все остальное). | Числовой |
recurringIndicator | Режим рекуррентного платежа. | Логический |
billingPostalCode | BillingData. Индекс предприятия связи покупателя. | Строковый |
billingAddress | BillingData. Адрес покупателя. | Строковый |
billingFirstName | BillingData. Имя покупателя. | Строковый |
billingLastName | BillingData. Фамилия покупателя. | Строковый |
billingPhoneNumber | BillingData. Телефон покупателя. | Строковый |
billingEMailAddress | BillingData. E-mail покупателя. | Строковый |
customer | ФИО покупателя. | Строковый |
customerCountry | Страна, указанная покупателем. | Строковый |
customerRegion | Регион, указанный покупателем. | Строковый |
customerCity | Город, указанный покупателем. | Строковый |
customerAddress | Адрес, указанный покупателем. | Строковый |
clientSystemLanguage | Код языка операционной системы покупателя. | Строковый |
clientLocalTime | Местное время клиента. | Строковый |
clientUserLanguage | Код языка покупателя. | Строковый |
clientBrowserLanguage | Код языка веб-браузера покупателя. | Строковый |
clientBrowserPlatform | Наименование платформы, на которой работает браузер покупателя. | Строковый |
clientJsBrowserName | Название браузера покупателя. | Строковый |
clientJsVersion | Версия интерпретатора Java script. | Строковый |
clientTimeZone | Смещение времени в часовом поясе покупателя относительно GMT в минутах. Например, для GMT +2 в часах значение в минутах + 120. | Строковый |
clientCookieEnabled | Есть поддержка Cookie и они включены в браузере покупателя. | Логический |
clientJavaEnabled | Есть поддержка Java script и интерпретатор включен. | Логический |
clientConnectionType | Тип соединения по HTTP. | Строковый |
clientProcessor | Название процессора на компьютере покупателя. | Строковый |
clientScreenRes | Разрешение экрана на компьютере покупателя. | Строковый |
clientScreenPixelDepth | Глубина цветов экрана на компьютере покупателя. | Числовой |
clientStylesheetsEnabled | Поддержка css стилей. | Логический |
httpAccept | Заголовок Accept http-запроса. | Строковый |
httpAcceptLanguage | Заголовок Accept Language http-запроса. | Строковый |
httpReferer | Заголовок Referer http-запроса. | Строковый |
httpServerProtocol | Переменная окружения Server_Protocol. | Строковый |
httpUserAgent | Заголовок User Agent http-запроса. | Строковый |
hostname | Имя хоста покупателя. | Строковый |
Коды результатов выполнения процедуры getFraudStatus
Код | Описание |
0 | Операция прошла успешно, ошибок нет. |
2 | Ошибка авторизации внешней системы. |
4 | Указан несуществующий идентификатор платежа. |
1 | Другая ошибка при выполнении операции. |
Процедура изменения статуса операции
Наименование процедуры изменения статуса платежной операции - setStatus.
Входные параметры
Единственным входным параметром, который передается внешней системой в СПМ для изменения статуса платежной операции, является параметр params, который представляет собой структуру данных с именем SetPaymentStatusParams.
Поля SetPaymentStatusParams
Поле | Описание | Тип |
outPaymentId | Идентификатор платежной операции во внешней системе. | Числовой (15) |
outSystemId | Идентификатор внешней системы. | Числовой (15) |
outStatus | Статус операции в соответствии со справочником СПМ . | Числовой (15) |
timeOut | Время ожидания ответа от сервера СПМ в мс. Если не указано, то используется значение по умолчанию (10 с). Если указано значение, меньшее или равное 0, то проверка на предельное время ожидания не используется. | Числовой (15), необязательный параметр |
approvalCode | Код выполнения операции в процессинговом центре. Каждый процессинговый центр использует собственные коды. | Строковый (12) |
psDate | Дата обработки платежной операции в процессинговом центре. Время передается в UTC (GMT-0) или же с указанием часового пояса. | Дата и время |
responseCode | Код результата платежа от процессингового центра. | Строковый (70) |
responseComment | Расшифровка кода результата платежа от процессингового центра. | Строковый (128) |
externalTransactionID |
или
| Строковый (50) |
meanNumber | Передается номер кошелька, если он не был доступен для передачи при вызове процедуры Check. | Строковый (70) |
meanTypeGroup | Группа по типу платежного средства: 1 – карта (значение по умолчанию), 2 – электронный кошелек. | Целочисленный (1) |
meanType | Тип электронного кошелька (обязательный параметр для кошельков), используемые типы электронных кошельков представлены в дополнительной таблице «Типы электронных кошельков» . | Строковый (3 символа) |
reasonId | Причина выставления статуса операции. | Целочисленный (15) |
reasonComment | Комментарий к причине выставления статуса. | Строковый (400 символов) |
Выделенные жирным шрифтом поля являются обязательными.
Причины выставления статуса актуальны для тех операций, которые неуспешно закончились до проведения авторизации.
Причины выставления статуса операции
Наименование | Код | Расшифровка |
Превышение времени ожидания ввода данных | 1 | Пользователь не закончил ввод персональных данных, выбор платежного средства, ввод данных платежного средства за отведенное на платеж время. |
Отказ от оплаты | 2 | В процессе проведения оплаты плательщик явно нажал на кнопку отмены и отказался продолжать оплату. |
Превышены лимиты | 3 | Один из установленных лимитов мерчанта не позволяет провести этот платеж. |
Операция заблокирована черным списком | 4 | Черный список по IP плательщика или по платежному средству мерчанта не позволяет провести платеж. |
Операция заблокирована фильтром. | 5 | Один из активных белых или остальных черных списков мерчанта не позволяет провести платеж или карта не участвует в промоакции. |
Превышение времени ожидания 3DS | 6 | Плательщик не завершил 3DS авторизацию (на стороне ACS) за отведенное на это время. |
3DS результат N | 7 | Плательщик не прошел 3DS авторизацию. |
3DS результат U | 8 | В ходе проведения 3DS авторизации возникла ошибка. |
Ошибка настроек | 9 | Ошибки, связанные с невозможностью провести платеж в связи с настройками мерчанта или системы (нет подходящего процессинга, не можем провести такую валюту, ошибки OneClick, и т.д.). |
Техническая ошибка | 10 | На стороне внешней системы произошла ошибка (общие, системные и прочие технические ошибки процессе подготовки к проведению оплаты). |
Выходные параметры
Результатом работы процедуры всегда является ответ, содержащий код результата ее работы и закодированное описание результата в случае успешного выполнения процедуры (код результата RetCode равен нулю) или не содержащий данные о проверке платежа в случае неуспешного выполнения процедуры (код результата ее работы RetCode не равен нулю).
Выходные параметры процедуры setStatus
Параметр | Описание | Тип |
RetCode | Результат выполнения процедуры. | Целочисленный (10) |
Description | Произвольный комментарий к результату выполнения процедуры. | Строковый (2000 символов) |
Коды результатов выполнения процедуры setStatus
Код | Описание |
0 | Операция прошла успешно, ошибок нет. |
2 | Ошибка авторизации внешней системы. |
4 | Указан несуществующий идентификатор платежа. |
5 | Указан некорректный код статуса операции |
8 | Превышено выделенное время обработки платежа. При этом обработка статуса платежа в СПМ будет продолжена, но запрос от внешней системы будет прерван и внешней системе будет отослан только данный код ошибки. |
1 | Другая ошибка при выполнении операции. |
Процедура передачи данных по мерчанту
Наименование процедуры передачи данных по мерчанту - setMerchantData.
Входные параметры
Все параметры данной процедуры, кроме параметра Email, являются обязательными.
Входные параметры процедуры setMerchantData
Параметр | Описание | Тип |
outSystemId | Идентификатор внешней системы. | Числовой (15) |
outMerchantId | Идентификатор мерчанта во внешней системе. | Числовой (15) |
merchantName | Наименование мерчанта. | Строковый (128 символов) |
merchantEmail | E-mail адрес мерчанта | Строковый (64 символа), необязательный параметр |
isOnMonitoring | Подлежат ли мониторингу платежи по данному мерчанту | Логический (true, false) |
categoryId | Идентификатор категории мерчанта из справочника категорий | Числовой (15) |
mcc | Идентификатор категории мерчанта (MCC - Merchant Category Code) | Строковый (4) – четырех-значный цифровой код |
Результатом процедуры является обновление всех указанных параметров для мерчанта с данным идентификатором. Если в базе СПМ не найден мерчант с данным идентификатором из внешней системы, то в базе будет создана новая запись.
Категории мерчантов
Код | Название |
19 | Книги, Видео, CD |
20 | Билеты в театр, кино, на концерты |
21 | Игорный бизнес |
22 | Цветы, подарки, парфюмерия |
23 | Искусство, коллекционные модели, награды |
24 | Службы знакомств |
25 | Программное обеспечение |
26 | Интернет и хостинг решения, кабельное TV |
27 | Обучение / конференции / форумы |
28 | Бытовая техника и электроника |
29 | Информационно - консультационные услуги |
30 | Компьютеры и комплектующие |
31 | Продукты питания |
32 | Средства массовой информации |
34 | Разное |
35 | Автозапчасти |
36 | Бронирование авиа и ж/д билетов, гостиниц, туров, машин |
37 | Библиотеки |
38 | Товары для красоты и здоровья |
39 | Одежда и обувь |
40 | Товары для дома / Мебель |
41 | Табачные изделия |
43 | Переводческие услуги |
44 | Благотворительность |
46 | Фото и полиграфия |
47 | Связь и телефония |
48 | Охранные системы |
49 | Он-лайн игры |
50 | Файлы для скачивания (Музыка, фильмы, передачи, книги) |
51 | Спорт и туризм |
52 | Ювелирные изделия, часы |
53 | Аукционы |
54 | Коммунальные и прочие платежи |
55 | Реклама |
56 | Страхование |
57 | Авиакомпании |
58 | Гостиницы |
59 | Купоны/сертификаты |
77 | Агрегаторы |
78 | Товары для детей |
97 | Онлайн трейдинг |
98 | Работа/рекрутинг/фриланс |
Выходные параметры
Результатом работы процедуры всегда является ответ, содержащий код результата ее работы и закодированное описание результата в случае успешного выполнения процедуры (код результата RetCode равен нулю) или не содержащий данные о проверке платежа в случае неуспешного выполнения процедуры (код результата ее работы RetCode не равен нулю).
Выходные параметры процедуры setMerchantData
Параметр | Описание | Тип |
RetCode | Результат выполнения процедуры. | Целочисленный (10) |
Description | Произвольный комментарий к результату выполнения процедуры. | Строковый (2000 символов) |
Коды результатов выполнения процедуры setStatus
Код | Описание |
0 | Операция прошла успешно, ошибок нет. |
2 | Ошибка авторизации внешней системы. |
1 | Другая ошибка при выполнении операции. |