Для полноценного обмена данными с СПМ внешней системе необходимо использовать клиентскую часть для вызова программных интерфейсов СПМ и организующую взаимодействие между двумя системами в реальном времени. Такое взаимодействие осуществляется с помощью программных интерфейсов 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 | 
**Формат 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>
