Для полноценного обмена данными с СПМ внешней системе необходимо использовать клиентскую часть для вызова программных интерфейсов СПМ и организующую взаимодействие между двумя системами в реальном времени. Такое взаимодействие осуществляется с помощью программных интерфейсов SOAP, которые предоставляются СПМ. Обмен данными ведется по протоколу HTTPS с доверительными SSL сертификатами. Для получения доступа к программным интерфейсам необходима авторизация с использованием наименования учетной записи (логина) и пароля.

Для корректной работы с веб-сервисами по защищенному TLS-соединению необходимо иметь на своей стороне в хранилище доверенных корневых сертификатов следующие сертификаты:

Перед началом работы следует проверить наличие этих сертификатов в хранилище и добавить их в случае необходимости.

Доступ к программным интерфейсам (API) осуществляется по адресу https://afs-api.paysecure.ru/antifraudapi.

WSDL для реализации протокола SOAP клиента можно получить по адресу https://afs-api.paysecure.ru/antifraudapi?wsdl.

При передаче внешней системой данных о платежной операции в СПМ для анализа на мошенничество возможны два варианта использования СПМ.

  1. Внешняя система собирает все данные по платежной операции, после чего передает их для анализа в СПМ путем вызова SOAP процедуры проверки операции check со всеми обязательными и известными вспомогательными параметрами. В этом случае возможно использование всех видов анализа платежной операции, имеющихся в СПМ.
  2. Внешняя система обращается к СПМ несколько раз за одну операцию по мере накопления данных о заказе, покупателе и его платежном средстве. При этом каждый раз осуществляется вызов процедуры проверки операции 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

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

Тип биллингового номера, в пользу которого производится оплата: номер мобильного телефона, номер договора на оказание услуг связи и т.д. В настоящий момент для активации доступны следующие типы биллингов:

  • YBIL (Yota billing);
  • MTSBelBlN (MTS Belarussia BillNumber);
  • MTSBelPhN (MTS Belarussia PhoneNumber);
  • MTTPhN (MTT Phone Number);
  • MTTTel (MTT Telecommunication);
  • MTTInt (MTT Internet).

Строковый (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>

***Формат 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)

Таблица 4.1.1.6 – Данные клиента

Поле

Описание

Тип

Cookie

Значение уникального идентификатора пользователя в платежном сервисе внешней системы, который соответствует указанному domainId (см.табл.4.1.1.1)

Строковый (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)

Таблица 4.1.1.7 – 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)

Таблица 4.1.1.8 – Переменные окружения сервера

Поле

Описание

Тип

RemoteAddress

IP-адрес клиента.

Строковый (16 символов)

ServerProtocol

Переменная окружения Server_Protocol.

Строковый (16 символов)

HostName

Имя хоста клиента.

Строковый (70 символов)

В случае превышения указанной длины полей параметра процедура закончится неуспешно (код результата работы вызванной процедуры будет отличен от нуля). Исключение составляют только HTTP заголовки. В случае превышения длины HTTP заголовков они будут принудительно укорочены до указанной длины, после чего процедура продолжит работу.

4.1.2. Выходные параметры

Результатом работы процедуры всегда является ответ в виде объекта типа getAFSResult, содержащий данные о проверке платежа в случае успешного выполнения процедуры (код результата ее работы RetCode равен нулю) или не содержащий данные о проверке платежа в случае неуспешного выполнения процедуры (код результата ее работы RetCode не равен нулю).

Таблица 4.1.2.1 – Выходные параметры процедуры check

Параметр

Описание

Тип

FraudStatus

Код фрод-статуса проверяемой операции (см.табл.3.1).

Числовой (15)

ReasonDescription

Описание причины выставления фрод-статуса проверяемой операции (см. табл.3.2).

Строковый (100 символов)

ReasonId

Код причины выставления фрод-статуса (см. табл.3.2).

Числовой (15)

RetCode

Результат выполнения процедуры.

Целочисленный (10)

Description

Произвольный комментарий к результату выполнения процедуры.

Строковый (2000 символов)

Таблица 4.1.2.2 – Коды результатов выполнения процедуры check

Код

Описание

0

Операция прошла успешно, ошибок нет.

2

Ошибка авторизации внешней системы.

3

Указан неправильный идентификатор мерчанта.

6

Указан неправильный идентификатор типа платежа.

7

Указан неправильный идентификатор приложения/сервиса внешней системы или же данное приложение/сервис в СПМ не соответствует указанной внешней системе.

8

Превышено выделенное время обработки платежа. При этом обработка платежа в СПМ будет продолжена, но запрос от внешней системы будет прерван и внешней системе будет отослан только данный код ошибки.

1

Другая ошибка при выполнении операции.

4.2. Одновременная проверка нескольких платежных операций

Наименование процедуры одновременной проверки нескольких платежных операций - checkArray.

4.2.1. Входные параметры

Таблица 4.2.1.1 – Входные параметры процедуры checkArray

Параметр

Описание

Тип

Params

Массив структур данных, каждый элемент которого представляет собой структуру CheckPaymentParams (подробнее см. п.4.1.1.)

Массив структур данных

waitResults

Параметр указывает, стоит ли дожидаться окончания проверки всех платежей, либо метод вернет ответ (пустой) сразу после создания задач по обработке платежей. Переданные данные по платежам обрабатываются в параллельных потоках, что уменьшает общее время обработки.

Логический (true, false)

4.2.2. Выходные параметры

Результатом работы процедуры является ответ в виде массива объектов типа getAFSResult. Ответ содержит данные о проверке платежей (коды RetCode), если задано ожидание проверки всех платежей. Ответ не содержит данные о проверке платежей (коды RetCode равны нулю), если не задано ожидание проверки всех платежей. Подробнее см.п.4.1.1.

4.3. Процедура передачи данных по 3DS транзакциям

Наименование процедуры передачи данных по 3DS транзакциям - set3DSecData. Вызов этой процедуры следует осуществлять после вызова процедуры checkPayment для данного платежа.

4.3.1. Входные параметры

Все параметры данной процедуры являются обязательными.

Таблица 4.3.1.1 – Входные параметры процедуры set3DSecData

Параметр

Описание

Тип

outPaymentId

Идентификатор платежной операции во внешней системе.

Числовой (15)

outSystemId

Идентификатор внешней системы.

Числовой (15)

authResult

Результат авторизации по 3DSecure (Y - успешно, N - неуспешно, A - Attempt, U –неизвестно). 

Строковый (1 символ)

authRequired

Результат проверки вовлеченности карты (1 – вовлечена, 0 – не вовлечена, -1 – неизвестно, null – все остальное).

Числовой (1)

4.3.2. Выходные параметры

Результатом работы процедуры является текущий фрод-статус платежа, который можно использовать для принятия решения о дальнейших действиях над платежом.

Таблица 4.3.2.1 – Выходные параметры процедуры set3DSecData

Параметр

Описание

Тип

FraudStatus

Код фрод-статуса проверяемой операции (см.табл.3.1).

Числовой (15)

ReasonDescription

Описание причины выставления фрод-статуса проверяемой операции (см. табл.3.2).

Строковый (100 символов)

ReasonId

Код причины выставления фрод-статуса (см. табл.3.2).

Числовой (15)

RetCode

Результат выполнения процедуры.

Целочисленный (10)

Description

Произвольный комментарий к результату выполнения процедуры.

Строковый (2000 символов)

Таблица 4.3.2.2 – Коды результатов выполнения процедуры set3DSecData

Код

Описание

0

Операция прошла успешно, ошибок нет.

2

Ошибка авторизации внешней системы.

4

Указан несуществующий идентификатор платежа.

1

Другая ошибка при выполнении операции.

4.4. Процедура получения фрод-статуса операции

Наименование процедуры получения фрод-статуса платежной операции - getFraudStatus. Вызов этой процедуры следует осуществлять после вызова процедуры checkPayment для данного платежа.

4.4.1. Входные параметры

Все параметры данной процедуры являются обязательными.

Таблица 4.4.1.1 – Входные параметры процедуры getFraudStatus

Параметр

Описание

Тип

outPaymentId

Идентификатор платежной операции во внешней системе.

Числовой (15)

outSystemId

Идентификатор внешней системы.

Числовой (15)

4.4.2. Выходные параметры

Результатом работы процедуры всегда является ответ в виде объекта типа getAFSResult, содержащий данные о проверке платежа в случае успешного выполнения процедуры (код результата ее работы RetCode равен нулю) или не содержащий данные о проверке платежа в случае неуспешного выполнения процедуры (код результата ее работы RetCode не равен нулю).

Таблица 4.4.2.1 – Выходные параметры процедуры getFraudStatus

Параметр

Описание

Тип

FraudStatus

Код фрод-статуса проверяемой операции (см.табл.3.1).

Числовой (15)

ReasonDescription

Описание причины выставления фрод-статуса проверяемой операции (см. табл.3.2).

Строковый (100 символов)

ReasonId

Код причины выставления фрод-статуса (см. табл.3.2).

Числовой (15)

RetCode

Результат выполнения процедуры.

Целочисленный (10)

Description

Произвольный комментарий к результату выполнения процедуры.

Строковый (2000 символов)

PaymentParameters

Список возвращаемых параметров платежа

Список из структур:

name — название параметра (строка, регистр не важен);

booleanValue — заполняется, если значение параметра имеет логический тип (true, false);

doubleValue — заполняется, если значение параметра имеет числовой тип;

stringValue — заполняется, если значение параметра имеет строковый тип;

intValue — заполняется, если значение параметра имеет целочисленный тип;

dateValue — заполняется, если значение параметра имеет тип дата.

Таблица 4.4.2.2 – Список возвращаемых параметров платежа PaymentParameters

Параметр

Описание

Тип

date

Дата платежа, если она была передана от внешней системы. Иначе дата получения данных по платежу в СПМ.

Дата

calculateAmount

Пересчитанная сумма платежа в основной валюте СПМ.

Числовой

outAmount

Переданная от внешней системы сумма платежа.

Числовой

outCurrencyCode

Код валюты, в которой была передана сумма платежа.

Строковый

email

Email плательщика.

Строковый

phone

Телефон плательщика.

Строковый

mobilePhone

Телефон плательщика.

Строковый

cardNumberMask

Номер банковской карты плательщика (первые 6 и последние 4 цифры).

Строковый

cardType

Тип банковской карты, определенный в СПМ по номеру карты.

Строковый

cardSubType

Подтип банковской карты, определенный в СПМ по номеру карты.

Строковый

cardholder

Держатель карты.

Строковый

cardBankCountry

Страна банка эмитента, определенная по номеру карты.

Строковый

cardBank

Название банка эмитента, определенное по номеру карты.

Строковый

expiredate

Дата окончания действия банковской карты.

Дата

acquirer

Уникальное название эквайера в переделах внешней системы.

Строковый

cookie

Значение уникального идентификатора плательщика, переданное внешней системой.

Строковый

ip

IP-адрес покупателя.

Строковый

ipCountry

Страна, определенная по IP-адресу покупателя.

Строковый

billNumber

Номер счета из внешней системы.

Строковый

orderNumber

Номер заказа из внешней системы.

Строковый

outStatus

Статус операции в соответствии со справочником СПМ (см.табл. 3.1).

Числовой

outStatusName

Название статуса операции.

Строковый

fraudStatus

Код из справочника фрод‑статусов (см.табл.4.2 на стр.4).

Числовой

reasonId

Код из справочника причин выставления фрод‑статусов (см.табл.3.2).

Числовой

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

Имя хоста покупателя.

Строковый

Таблица 4.4.2.3 – Коды результатов выполнения процедуры getFraudStatus

Код

Описание

0

Операция прошла успешно, ошибок нет.

2

Ошибка авторизации внешней системы.

4

Указан несуществующий идентификатор платежа.

1

Другая ошибка при выполнении операции.

4.5. Процедура изменения статуса операции

Наименование процедуры изменения статуса платежной операции - setStatus.

4.5.1. Входные параметры

Единственным входным параметром, который передается внешней системой в СПМ для изменения статуса платежной операции, является параметр params, который представляет собой структуру данных с именем SetPaymentStatusParams.

Таблица 4.5.1.1 – Поля SetPaymentStatusParams

Поле

Описание

Тип

outPaymentId

Идентификатор платежной операции во внешней системе.

Числовой (15)

outSystemId

Идентификатор внешней системы.

Числовой (15)

outStatus

Статус операции в соответствии со справочником СПМ (см. табл.3.3).

Числовой (15)

timeOut

Время ожидания ответа от сервера СПМ в мс. Если не указано, то используется значение по умолчанию (10 с). Если указано значение, меньшее или равное 0, то проверка на предельное время ожидания не используется.

Числовой (15), необязательный параметр

approvalCode

Код выполнения операции в процессинговом центре. Каждый процессинговый центр использует собственные коды.

Строковый (12)

psDate

Дата обработки платежной операции в процессинговом центре. Время передается в UTC (GMT-0) или же с указанием часового пояса.

Дата и время

responseCode

Код результата платежа от процессингового центра.

Строковый (70)

responseComment

Расшифровка кода результата платежа от процессингового центра.

Строковый (128)

externalTransactionID

  • Retrieval Reference Number (формируется процессинговым центром по собственному алгоритму) для процессинговых центров, передающих RRN (в настоящий момент это BPC, BPCBel, RAIF, SviazBank, MBank, AmexPOA и семейство MULT)

или

  • другой возможный номер транзакции

Строковый (50)

meanNumber

Передается номер кошелька, если он не был доступен для передачи при вызове процедуры Check.

Строковый (70)

meanTypeGroup

Группа по типу платежного средства: 1 – карта (значение по умолчанию), 2 – электронный кошелек.

Целочисленный (1)

meanType

Тип электронного кошелька (обязательный параметр для кошельков), используемые типы электронных кошельков представлены в дополнительной таблице «Типы электронных кошельков» .

Строковый (3 символа)

reasonId

Причина выставления статуса операции.

Целочисленный (15)

reasonComment

Комментарий к причине выставления статуса.

Строковый (400 символов)

Выделенные жирным шрифтом поля являются обязательными.

Причины выставления статуса актуальны для тех операций, которые неуспешно закончились до проведения авторизации.

Таблица 4.5.1.2 – Причины выставления статуса операции

Наименование

Код

Расшифровка

Превышение времени ожидания ввода данных

1

Пользователь не закончил ввод персональных данных, выбор платежного средства, ввод данных платежного средства за отведенное на платеж время.

Отказ от оплаты

2

В процессе проведения оплаты плательщик явно нажал на кнопку отмены и отказался продолжать оплату.

Превышены лимиты

3

Один из установленных лимитов мерчанта не позволяет провести этот платеж.

Операция заблокирована черным списком

4

Черный список по IP плательщика или по платежному средству мерчанта не позволяет провести платеж.

Операция заблокирована фильтром.

5

Один из активных белых или остальных черных списков мерчанта не позволяет провести платеж или карта не участвует в промоакции.

Превышение времени ожидания 3DS

6

Плательщик не завершил 3DS авторизацию (на стороне ACS) за отведенное на это время.

3DS результат N

7

Плательщик не прошел 3DS авторизацию.

3DS результат U

8

В ходе проведения 3DS авторизации возникла ошибка.

Ошибка настроек

9

Ошибки, связанные с невозможностью провести платеж в связи с настройками мерчанта или системы (нет подходящего процессинга, не можем провести такую валюту, ошибки OneClick, и т.д.).

Техническая ошибка

10

На стороне внешней системы произошла ошибка (общие, системные и прочие технические ошибки процессе подготовки к проведению оплаты).

4.5.2. Выходные параметры

Результатом работы процедуры всегда является ответ, содержащий код результата ее работы и закодированное описание результата в случае успешного выполнения процедуры (код результата RetCode равен нулю) или не содержащий данные о проверке платежа в случае неуспешного выполнения процедуры (код результата ее работы RetCode не равен нулю).

Таблица 4.5.2.1 – Выходные параметры процедуры setStatus

Параметр

Описание

Тип

RetCode

Результат выполнения процедуры.

Целочисленный (10)

Description

Произвольный комментарий к результату выполнения процедуры.

Строковый (2000 символов)

Таблица 4.5.2.2 – Коды результатов выполнения процедуры setStatus

Код

Описание

0

Операция прошла успешно, ошибок нет.

2

Ошибка авторизации внешней системы.

4

Указан несуществующий идентификатор платежа.

5

Указан некорректный код статуса операции

8

Превышено выделенное время обработки платежа. При этом обработка статуса платежа в СПМ будет продолжена, но запрос от внешней системы будет прерван и внешней системе будет отослан только данный код ошибки.

1

Другая ошибка при выполнении операции.

4.6. Процедура передачи данных по мерчанту

Наименование процедуры передачи данных по мерчанту - setMerchantData.

4.6.1. Входные параметры

Все параметры данной процедуры, кроме параметра Email, являются обязательными.

Таблица 4.6.1.1 – Входные параметры процедуры setMerchantData

Параметр

Описание

Тип

outSystemId

Идентификатор внешней системы.

Числовой (15)

outMerchantId

Идентификатор мерчанта во внешней системе.

Числовой (15)

merchantName

Наименование мерчанта.

Строковый (128 символов)

merchantEmail

E-mail адрес мерчанта

Строковый (64 символа), необязательный параметр

isOnMonitoring

Подлежат ли мониторингу платежи по данному мерчанту

Логический (true, false)

categoryId

Идентификатор категории мерчанта из справочника категорий

Числовой (15)

mcc

Идентификатор категории мерчанта (MCC - Merchant Category Code)

Строковый (4) – четырех-значный цифровой код

Результатом процедуры является обновление всех указанных параметров для мерчанта с данным идентификатором. Если в базе СПМ не найден мерчант с данным идентификатором из внешней системы, то в базе будет создана новая запись.

Таблица 4.6.1.2 – Категории мерчантов

Код

Название

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

Работа/рекрутинг/фриланс

4.6.2. Выходные параметры

Результатом работы процедуры всегда является ответ, содержащий код результата ее работы и закодированное описание результата в случае успешного выполнения процедуры (код результата RetCode равен нулю) или не содержащий данные о проверке платежа в случае неуспешного выполнения процедуры (код результата ее работы RetCode не равен нулю).