Для полноценного обмена данными с СПМ внешней системе необходимо использовать клиентскую часть для вызова программных интерфейсов СПМ и организующую взаимодействие между двумя системами в реальном времени. Такое взаимодействие осуществляется с помощью программных интерфейсов 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 соответствующие значения идентификаторов (см.табл.4.1.1.1).
4.1. Процедура проверки платежной операции
Наименование процедуры проверки платежной операции - check.
4.1.1. Входные параметры
Единственным входным параметром, который передается внешней системой в СПМ для анализа платежной операции, является параметр params, который представляет собой структуру данных с именем CheckPaymentParams.
Обязательные поля CheckPaymentParams
Обязательные поля параметра передаются как простые типы данных (целочисленные, строковые, логические).
Таблица 4.1.1.1 – Обязательные поля CheckPaymentParams
Поле | Описание | Тип |
outPaymentId | Идентификатор платежной операции во внешней системе | Целочисленный (15) |
outSystemId | Идентификатор внешней системы | Целочисленный (15) |
outMerchantId | Внешний идентификатор мерчанта | Целочисленный (15). |
domainId | Код приложения/сервиса внешних систем из соответствующего справочника СПМ. | Целочисленный (15) |
paymentTypeId | Тип платежа | Целочисленный (15) Целочисленный код из справочника СПМ, см. табл.4.1.1.2. |
Таблица 4.1.1.2 – Типы платежей
Наименование | Код |
e-commerce | 1 |
MO/TO | 2 |
POS | 3 |
Необязательные поля CheckPaymentParams
При передаче параметра также предусмотрено использование необязательных полей.
Если внешняя система обращается к СПМ несколько раз за одну операцию по мере накопления данных о заказе, покупателе и его платежном средстве, то при повторных вызовах уже переданные ранее поля опускать запрещается. Поля, по которым у клиента нет информации, передаются в виде пустых (null) значений.
Таблица 4.1.1.3 – Необязательные поля CheckPaymentParams
Поле | Описание | Тип |
paymentAttributes | Данные по операции (см. табл.4.1.1.5) | Список из структур |
clientAttributes | Данные браузера клиента, выполняющего платеж | Список из структур |
httpAttributes | Заголовки http-запроса браузера клиента к внешней системе при проведении операции | Список из структур |
serverAttributes | Переменные среды окружения | Список из структур |
timeOut | Время ожидания ответа от сервера СПМ (в мс). Если значение не указано, используется значение по умолчанию – 10 секунд. Если указано отрицательное значение, то проверка на максимальное время ответа не используется. Примечание. Имеется возможность отключить принудительное оповещение внешней системы об установленном фрод-статусе платежа в том случае, если время обработки этого платежа превысило максимально допустимое. Настройка осуществляется с помощью сотрудников службы технической поддержки. По умолчанию оповещение осуществляется. | Целое число |
sendNotification | Необходимость принудительного оповещения внешней системы об установленном фрод-статусе данной платежной операции по окончании работы процедуры check. По умолчанию оповещение не отправляется. | Логический (true, false) |
paymentStatus | Данные по изменению статуса операции (подробнее см.п.4.4.1.) | Структура данных |
Таблица 4.1.1.4 – Структуры в описании полей CheckPaymentParams
Структура | Описание | Тип |
name | Наименование параметра | Строковый, инвариантен к регистру |
booleanValue | Заполняется, если параметр имеет логический тип данных | Логический (true, false) |
doubleValue | Заполняется, если параметр имеет числовой тип данных | Числовой |
stringValue | Заполняется, если параметр имеет строковый тип данных | Строковый |
intValue | Заполняется, если параметр имеет целочисленный тип данных | Целое число |
dateValue | Заполняется, если параметр имеет тип данных дата | Дата |
При заполнении необязательных полей нужно учитывать их тип (указан в спецификации) и заполнять соответствующие параметры структуры. В противном случае заданные значения будут игнорироваться.
· Данные по операции (paymentAttributes)
Таблица 4.1.1.5 – Данные по операции
Поле | Описание | Тип |
Meannumber | Зашифрованный номер платежного средства*, должен передаваться в виде строки: "IR_TOKEN=<необратимый токен PAN> BIN=<6 первых цифр PAN> POST==<4 последних цифры PAN>". Альтернативная возможность передавать номер платежного средства в незашифрованном виде в настоящий момент существует, но в будущем будет исключена. | Строковый (70 символов) |
meanTypeGroup | Группа по типу платежного средства: 1 – карта (значение по умолчанию), 2 – электронный кошелек. | Целочисленный (1) |
meanType | Тип электронного кошелька (обязательный параметр для кошельков), используемые типы электронных кошельков представлены в дополнительной таблице «Типы электронных кошельков» на стр.11. | Строковый (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 символов) |
Fax | Номер факса | Строковый (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 с описанием дополнительных параметров, определенных для авиаперевозчиков** | Текст |
BookingData | XML с описанием дополнительных параметров по бронированию и оплате гостиниц*** | Текст |
3DSecAuthrequired | Результат проверки вовлеченности карты (1 – вовлечена, 0 – не вовлечена, -1 – неизвестно, null – все остальное) | Числовой (1) |
*Для использования сервиса необратимой токенизации от компании Ассист необходимо обратиться в службу технической поддержки (support@assist.ru).
Выделенные в таблице жирным шрифтом поля являются обязательными для запуска методов математического моделирования. Дополнительно выделенные в таблице подчеркиванием поля являются желательными для качественной работы методов математического моделирования.
Типы электронных кошельков
Тип кошелька | Наименование кошелька |
WM | WebMoney |
EP | EasyPay |
QW | QIWI |
QB | QIWIBeeline |
QM | QIWIMts |
QF | QIWIMegafon |
MB | Mobicon |
YM | YandexMoney |