Описание базового функционала

1. Описание базового функционала

• 1.1 Назначение документа
• 1.2 Список сокращений

2. Общие положения
3. Базовый сценарий оплаты заказа

• 3.1. Регистрация
• 3.2. Переход пользователя на страницу авторизации

4. Получение статуса оплаты заказа

• 4.1. Получение статуса по номеру заказа. PULL метод.
• 4.2. Получение результатов оплаты за период. PULL метод.
• 4.3. Оповещение об изменении статуса оплаты. PUSH метод.

5. Дополнительные сценарии

• 5.1 Отказ от заказа, отмена регистрации
• 5.2 Подтверждение оплаты
• 5.3 Аннулирование оплаты
• 5.4 Возврат платежа/части заказа
• 5.5 Корзина товаров и услуг.
• 5.6 Регулярные платежи (подписка)
• 5.6.1 Отмена подписки
• 5.7 Повторные платежи
• 5.7.1 Последующие платежи

6. Дополнительный функционал

• 6.1 Кастомизация платежной страницы
• 6.2 Определение устройства для приема платежа
• 6.3 Ограничение доступных к оплате карт.
• 6.4 Платежная страница на стороне предприятия
• 6.4.1 Оплата несколькими картами
• 6.5 Получение электронного чека с результатами авторизации

7. Справочники

• 7.1 Результаты выполнения запроса
• 7.2 Результаты авторизации платежа
• 7.3 Статусы заказа
• 7.4 Типы платежных сессий
• 7.5 Языки пользовательского интерфейса
• 7.6 Типы товаров и услуг
• 7.7 Статусы 3DS аутентификации

Описание базового функционала

1.1 Назначение документа

Документ содержит техническое описание процесса оплаты заказов интернет–магазина посредством использования сервисов платежного шлюза.

Документ предназначен для технических специалистов Заказчика, которые отвечают за разработку сервиса оплаты банковскими картами в интернет–магазине Заказчика с использованием процессинговой системы MyPayments.

1.2 Список сокращений

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

Таблица 1. Список сокращений

2. Общие положения

При взаимодействии интернет-магазина (далее ИМ) и платёжного шлюза (далее ПШ) используются RPC SOAP WEB–сервисы (далее сервис). В качестве транспортного протокола используется протокол HTTPS.

Для вызовов всех методов сервиса необходима BASIC HTTP аутентификация ИМ. Данные для доступа (login, pass) предоставляются Заказчику в рамках настройки подключения ИМ к ПШ. Если не указано иное, то в ответ на успешное выполнение метода сервиса возвращается стандартный RPC SOAP конверт без полезной нагрузки. Если при вызове метода сервиса происходит исключительная ситуация, в результате которой невозможна обработка запроса, то в ответ на запрос возвращается SOAP Fault, а в поле faultstring – содержится код ошибки выполнения запроса (см. справочник результатов выполнения запроса, п. 7.1).

3. Базовый сценарий оплаты заказа

Общая схема процесса оплаты заказа состоит из следующих шагов:

1. Регистрация заказа: Заказчик в ИМ формирует заказ, ИМ определяет его стоимость и направляет запрос на регистрацию заказа в ПШ.

2. Переход пользователя на страницу авторизации: из полученных в ответ на регистрацию данных от ПШ, ИМ формирует адрес для перевода Заказчика на ПС

3. Оплата заказа: Заказчик на ПС вводит данные карты, ПШ производит проверку внесенных данных карты и подлинности владельца карты по технологии 3D Secure, выполняется авторизация платежа.

4. Возврат пользователя на страницу магазина: ПШ отображает Заказчику результат авторизации операции и переводит браузер Заказчика на адрес указанный в параметрах запроса регистрации.

5. Получение результатов оплаты: ИМ запрашивает результаты оплаты у ПШ и в случае успеха выполняет оформление заказа.

6. Выполнение платежа: система ПШ, на основании выполненных авторизаций формирует файл финансовых транзакций, банк-экваер в установленные сроки выполняет перечисление денежных средств предприятию.

3.1 Регистрация

Для оплаты заказа, ИМ направляет запрос на регистрацию в ПШ. Параметры NUMBER и COST являются обязательными, остальные – используются в расширенных сценариях оплаты, а так же в целях автоматизированного фрод–мониторинга, задач отчетности и аналитики.

Метод: register

Сервис: order

Параметры запроса:

• order – идентификатор заказа, состоящий из: * shop_id – идентификатор магазина в ПШ * number – уникальный идентификатор заказа в ИМ
• cost – полная стоимость заказа к оплате, состоящая из: * amount – стоимость * currency – латинский код валюты (RUB, EUR, USD)
• description – описание заказа (в согласованном формате), состоящее из: * shopref – внутренний параметр ИМ, который возвращается в одноименном параметре ответа на запросы * descr – XML c описанием заказа * timelimit – время, до которого данный заказ разрешено оплачивать * customer – информация о Заказчике
• postdata – параметры настройки авторизационной страницы * ReturnURLOk – адрес возврата, на который будет перенаправлен браузер пользователя в случае успешной оплаты * ReturnURLFault – адрес возврата, на который будет перенаправлен браузер пользователя в случае несостоявшейся оплаты * ReturnURLReceipt – адрес возврата, на который будет перенаправлен браузер пользователя для случая отображения результатов оплаты на стороне предприятия.

Структура информации о заказчике, параметр customer, состоит из:

• phone – телефон
• email – адрес электронной почты
• name – ФИО
• id – идентификатор заказчика в ИМ

Пример:

Базовый пример:

<soap-env:Envelope
    xmlns:xs="http://www.w3.org/2001/XMLSchema"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:soap-env="http://schemas.xmlsoap.org/soap/envelope/">
    <soap-env:Body>
        <register>
            <order>
                <shop_id>123</shop_id>
                <number>12345</number>
            </order>
            <cost>
                <currency>RUB</currency>
                <amount>1350</amount>
            </cost>
            <customer>
                <phone>+79859998877</phone>
                <name>PETROV IVAN</name>
                <email>vasya@mail.ru</email>
            </customer>
            <description>
                <timelimit>2015-04-21T23:23:23</timelimit>
            </description>
            <postdata>
                <PostEntry>
                    <name>Language</name>
                    <value>ru</value>
                </PostEntry>
                <PostEntry>
                    <name>ReturnURLOk</name>
                    <value>http://abc.ru</value>
                </PostEntry>
                <PostEntry>
                    <name>ReturnURLFault</name>
                    <value>http://abc.ru</value>
                </PostEntry>
            </postdata>
        </register>
    </soap-env:Body>
</soap-env:Envelope>

Структура ответа сервиса зависит от конфигурации ИМ и сценария оплаты заказа. Ответ содержит данные адреса для отправки платежных реквизитов только если это требуется - т.е. сценарии с получением ссылки на платежную страницу (для переадресации браузера плательщика для ввода им данных) или ссылки для передачи данных (если используется межхостовой протокол передачи карточных данных от ИМ в ПШ). При использовании сценария, когда ИМ лишь инициирует регистрацию заказа в системе ПШ, а платеж инициируется 3ей стороной - ответ возвращается пустой.

Ответ сервиса может состоять из:

• redirect_url – адрес, на который необходимо перенаправить браузер Заказчика
• session – идентификатор сессии
• paycode – код для оплаты в системах приёма платежей (Евросеть, Связной)

Пример при успешной обработки запроса:

<soap-env:Envelope xmlns:soap-env=«http://schemas.xmlsoap.org/soap/envelope/«>
    <soap-env:Body>
        <registerResponse xmlns=«http://www.sirena-travel.ru»>
            <retval/>
        </registerResponse>
    </soap-env:Body>
</soap-env:Envelope>

Пример ответа с ошибкой:

<soap-env:Envelope xmlns:soap-env=«http://schemas.xmlsoap.org/soap/envelope/«>
    <soap-env:Body>
        <soap-env:Fault>
            <faultcode>registerFault</faultcode>
            <faultstring>ALREADY_PROCESSED</faultstring>
            <detail />
        </soap-env:Fault>
    </soap-env:Body>
</soap-env:Envelope>

Описание деталей ошибок содержится в справочниках.

3.2 Переход пользователя на страницу авторизации

В случае успешного ответа на запрос регистрации заказа и при сценарии, когда требуется перенаправит Плательщика на защищенную страницу для ввода карточных данных, ИМ перенаправляет браузер Плательщика на страницу ПШ методом HTTP GET с параметрами redirect_url (адрес) + session (идентификатор сессии), который был получен в ответ на запрос register (см. п. 3.1).

3.3 Оплата заказа

Пользователь осуществляет ввод данных банковской карты на платёжной странице ИМ, после чего выполняются процедуры аутентификации и авторизации, согласно установленной технологии.

3.4 Возврат пользователя на страницу ИМ

В случае успешной авторизации (блокировки) необходимой суммы на счете Заказчика, его браузер перенаправляется по URL, переданному в параметре ReturnURLOk (см. п. 3.1). В случае отказа в авторизации браузер Заказчика перенаправляется по URL, переданному в параметре ReturnURLFault (см. п. 3.1).

#4. Получение статуса оплаты заказа

4.1 Получение статуса по номеру заказа. PULL метод.

После успешной регистрации заказа, ИМ в любой момент может уточнить статус оплаты заказа.

Метод: get_by_order

Сервис: status

Параметры запроса:

• order
  • shop_id – идентификатор магазина в ПШ
  • number – уникальный номер заказа в ИМ

Параметры ответа:

• attempts – список платежных сессий Заказчика
• devices – список устройств Заказчика, с которых осуществлялась оплата
• customer – информация о Заказчике
• order – идентификатор заказа
• status – финальный статус заказа
• shopref – данные магазина, которые возвращаются без изменения
• items – список элементов заказа
• payments – список авторизованных платежей
• clearing – распределение платежей по системам расчета и элементам заказа
• documents – список платежных документов, которые были использованы для оплаты заказа

Структура информации о платежных сессиях, параметр attempts, состоит из:

• secure – статус 3дс аутентификации
• docid – идентификатор платежного документа в системе ПШ
• date – дата и время оплаты
• devid – идентификатор устройства заказчика в системе ПШ
• id – уникальный идентификатор Заказчика в системе ПШ.
• holder – держатель платёжного документа
• error – информация об ошибке авторизации платёжа (см. п. 7.2) и (см. п. 7.3), состоит из:
  • code – код ошибки результата авторизации
  • category – код категории ошибки
  • id – код ошибки

Структура информации о устройствах, параметр devices, состоит:

• id – уникальный идентификатор устройства Заказчика (присваивается сервисами ПШ)
• ip – IP-адрес
• agent – информация о клиентском приложении (User Agent)
• uid – уникальный идентификатор клиентского приложении

Структура информации о пользователе, параметр customer, состоит из:

• phone – телефон
• email – адрес электронной почты
• name – ФИО
• id – идентификатор Заказчика в ИМ

Структура информации о заказе, параметр number, состоит из:

• shop_id – идентификатор магазина в ПШ
• number – уникальный идентификатор заказа в ИМ

Структура информации о распределении платежей по элементам заказа и системам расчета, параметр clearing, состоит из:

• pref – ссылка на авторизованный платеж
• iref – ссылка на элемент заказа
• amount – сумма по элементу
• ctype – тип расчетов (см. п. 7.9))

Структура информации о сумме к оплате, параметр amount, состоит из:

• amount – стоимость
• currency – латинский код валюты (RUB, EUR, USD)

Структура информации о списке авторизованных платежей, параметр payments, состоит из:

• id – идентификатор платёжа в системе ПШ, используется во вторичных операциях (подтверждения и возврата).
• aref – ссылка на попытку оплаты
• ptype – тип платежа
• date – дата оплаты
• amount – авторизованная сумма
• authorg – код организации выполневшего авторизацию платежа
• authcode – код подтверждения оплаты
• salepoint – код точки оплаты

Структура информации о списке элементов в заказе, параметр items, состоит из:

• id – идентификатор элемента заказа
• descr – XML c описанием заказа
• amount – стоимость

Структура информации о списке платёжных документов, использованных для оплаты, параметр documents, состоит из:

• id – уникальный идентификатор карты Заказчика в системе ПШ
• token – идентификатор привязанной карты
• code – код платежной системы (VI, CA, JC, DC, AX)
• number – маскированный номер платёжного документа
• exp_date – срок действия карты
• desc – дополнительная информация о платежном документе:
  • country – 2х–значный код страны банка–эмитента карты
  • product – код карточного продукта
  • bank – название банка–эмитента карты

Информация о статусе оплаты возвращается только в случае успешного выполнения запроса.

Информация о форме оплаты возвращается только в случае успешной оплаты заказа. Если происходит ошибка при выполнении запроса, то метод возвращает faultcode – код ошибки выполнения запроса (см. справочник результатов выполнения запроса, п. 7.1).

Пример запроса:

<SOAP-ENV:Envelope
    xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:xs="http://www.w3.org/2001/XMLSchema"
    xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance"
    xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/08/addressing">
    <SOAP-ENV:Body>
        <get_by_order
            xmlns="http://www.sirena-travel.ru">
            <order>
                <shop_id>123</shop_id>
                <number>12345</number>
            </order>
        </get_by_order>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

4.2 Получение результатов оплаты за период. PULL метод.

Методы get_by_order_period/get_by_payment_period сервиса status используются для получения статусов заказов, за период создания/оплаты заказа соответственно.

Методы: get_by_payment_period  get_by_order_period

Сервис: status

Параметры запроса:

• shop_id – идентификатор магазина в ПШ;
• start – время начала периода создания/оплаты (относительно UTC);
• stop – время окончания периода создания/оплаты (относительно UTC).

Величина периода не должна превышать 2 часов.

Параметры ответа: Список заказов, каждый из которых представляет собой ответ из (п. 4.1)

Пример запроса:

<SOAP-ENV:Envelope
    xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:xs="http://www.w3.org/2001/XMLSchema"
    xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance"
    xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/08/addressing">
    <SOAP-ENV:Body>
        <get_by_payment_period
            xmlns="http://www.sirena-travel.ru">
            <shop_id>123</shop_id>
            <start>2020-02-09T04:04:29.2269069Z</start>
            <stop>2020-02-11T06:04:29.2269069Z</stop>
        </get_by_payment_period>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

4.3 Оповещение об изменении статуса оплаты. PUSH метод.

Опционально ПШ имеет возможность оповещать ИМ посредством вызова SOAP сервиса на стороне предприятия.

Для использования данного функционала необходимо:

1. реализовать сервис на стороне ИМ, который будет готов принимать сообщения от ПШ. Структура сообщения описана WSDL-файлом, который необходимо запросить у службы тех. поддержки.
2. сообщить адрес сервиса, для внесения его в конфигурацию точки продажи на стороне ПШ. Если доступ к сервису закрыт, необходимо сообщить не только URL, но и данные для авторизации на сервисе (логин/пароль).

При изменении статуса заказа, сервисы ПШ направляют метод notify сервиса notify. Информация, содержащаяся в методе notify, аналогична информации, которая может быть получена от сервиса status.

Пример запроса:

<SOAP-ENV:Envelope
    xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:xs="http://www.w3.org/2001/XMLSchema"
    xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance"
    xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/08/addressing">
    <SOAP-ENV:Body>
        <notify
            xmlns="http://www.sirena-travel.ru">
            <order>
                <shop_id>123</shop_id>
                <number>12345</number>
            </order>
            <status>acknowledged</status>
            <error>
                <category>system</category>
                <code>ok</code>
            </error>
            <payments>
                <Payment>
                    <id>001231231231</id>
                    <type>card</type>
                    <date>2020-02-06T21:33:13</date>
                    <amount>
                        <currency>RUB</currency>
                        <amount>100.00</amount>
                    </amount>
                    <doc>
                        <holder>pupkin vasilii</holder>
                        <code>MC</code>
                        <number>510000*0008</number>
                        <token/>
                    </doc>
                    <authcode>112014</authcode>
                    <authorg>bank_code</authorg>
                    <clearing>card</clearing>
                    <salepoint></salepoint>
                </Payment>
            </payments>
        </notify>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Ответ на данный запрос не требуется.

5. Дополнительные сценарии

Функционал, описанный в п. 3 и п. 4, является базовым вариантом настройки функционала оплаты картами. В этом случае, клиенты ИМ получают возможность оплаты товаров/услуг на сайте, а ИМ – возможность принять средства и получить информацию об совершенной авторизации.

5.1 Отказ от заказа, отмена регистрации

Метод cancel используется в случае если ИМ до истечении переданного времени на оплату хочет прекратить процесс оплаты заказа в ПШ. Рекомендуется также использовать этот метод во избежание двойной оплаты, если Заказчик изменил свой выбор способа оплаты.

Методы: cancel

Сервис: order

Условия вызова: статус заказа registered

Параметры запроса:

• order – идентификатор заказа состоящий из:
  • shop_id – идентификатор магазина в ПШ
  • number – уникальный идентификатор заказа в ИМ

Пример запроса:

<SOAP-ENV:Envelope
    xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:xs="http://www.w3.org/2001/XMLSchema"
    xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance"
    xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/08/addressing">
    <SOAP-ENV:Body>
        <cancel>
            <order>
                <shop_id>123</shop_id>
                <number>12345</number>
            </order>
        </cancel>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Ответ содержит информацию о состоянии заказа после исполнения запроса и детали ошибки, если она имела место.

5.2 Подтверждение оплаты

В случае если характер деятельности ИМ предусматривает ситуации, когда при успешной оплате, товар или услуга не может быть оказана, ИМ может использовать сценарий 2х стадийной оплаты. При данном сценарии от ИМ ожидаются:

1. регистрация заказа + инициаци платежа;

2. отправка подтверждения о необходимости списать денежные средства;

Важно: система ИМ обязана следить за состоянием заказов во избежание автоматического расхолдирования средств. Рекомендуемый срок, в рамках которого должено совершиться либо отказ от сделки/заказа либо подтверждение ее - 3 дня.

Важно: если ИМ принимает решение об отказе от сделки/заказа, необходимо направить запрос отмены заказа ** reject** (см п. 5.3)..

Методы: confirm

Сервис: order

Условия вызова: статус заказа not_acknowledged

Параметры запроса:

• order – идентификатор заказа состоящий из:
  • shop_id – идентификатор магазина в ПШ
  • number – уникальный идентификатор заказа в ИМ
• cost – полная стоимость заказа к оплате, состоящая из:
  • amount – стоимость
  • currency – код валюты (RUB, EUR, USD)
• txn_id – уникальный идентификатор операции в системе ИМ

Функционал подтверждения оплаты также доступен в БО ПС – Блок «Параметры заказа», кнопка «Подтверждение платежа».

5.3 Аннулирование оплаты

Метод аннулирования заказа используется в 2х сценариях:

• при использовании сценария с 2х стадийной оплатой ;
• в редких случаях при возникновении сбойных ситуаций, когда платеж принят, однако или услуга не может быть оказана или возникла проблема с оформлением документов, сервисы ПШ переводят заказ в статус not_acknowledged и ожидают действий от точки продажи. Это могут быть действия по API - вызов методов confirm или reject , или в Бэк Офисе ПШ.

Tip: ряд правил обработки сбойных ситуаций может быть заведен в конфигурацию ИМ на стороне ПШ. За деталями обратитесь в службу тех. поддержки.

Методы: reject

Сервис: order

Условия вызова: статус заказа not_acknowledged

Параметры запроса:

• order – идентификатор заказа состоящий из:
  • shop_id – идентификатор магазина в ПШ
  • number – уникальный идентификатор заказа в ИМ

Пример запроса:

<SOAP-ENV:Envelope
    xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:xs="http://www.w3.org/2001/XMLSchema"
    xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance"
    xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/08/addressing">
    <SOAP-ENV:Body>
        <reject>
            <order>
                <shop_id>123</shop_id>
                <number>12345</number>
            </order>
        </reject>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Ответ содержит информацию о состоянии заказа после исполнения запроса и детали ошибки, если она имела место.

Функционал отмены заказа также доступен в БО ПС – Блок «Параметры заказа», кнопка «Откат заказа».

5.4 Возврат платежа/части заказа

Чтобы выполнить возврат платежа ИМ должен вызвать метод refund сервиса order.

Методы: refund

Сервис: order

Параметры запроса:

• order – идентификатор заказа состоящий из:
  • shop_id – идентификатор магазина в ПШ
  • number – уникальный идентификатор заказа в ИМ
• payment_id – идентификатор первоначального платежа (может отсутствовать в случае одной транзакции оплаты)
• cost – полная стоимость заказа к оплате, состоящая из:
  • amount – стоимость
  • currency – код валюты (RUB, EUR, USD)
• txn_id – уникальный (в рамках заказа) идентификатор операции возврата в системе ИМ (для защиты от двойных возвратов)

В случае если выполняется возврат только части заказа, то в запросе возврата рекомендуем указывать параметр items – список возвращаемый элементов заказа, состоящих из:

• item – элемент заказа
  • descr – XML c описанием заказа
  • amount – стоимость данного элемента заказа
    • amount – стоимость
    • currency – код валюты (RUB, EUR, USD)
  • id – идентификатор части заказа в системе ПШ

Сумма элементов amount из items должна быть равна сумме возврата заказа.

Функционал возврата полной (или части) стоимости заказа также доступен в БО ПС – Блок «Управление платежами», кнопка «Возврат платежа».

5.5 Корзина товаров и услуг.

Передача информации о корзине товаров и услуг используется в 2х случаях:

1. для передачи дополнительной информации о составе заказа и сохранении ее в системе ПШ. Эти данные используются для получения расширенной отчетности и отображения в Бэк Офисе;

2. для инициации процесса формирования документов, подтверждающих оплату совершенной сделки и возможность ИМ предоставить Покупателю выбранную им услугу или товар. Для работы данного функционала необходима интеграция между системой ПШ и системой провайдера товаров/услуг. Описание данного функционала находится в отдельных документах и предоставляется под запрос.

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

Для реализации данного кейса ИМ необходимо настроить передачу параметров items блока description.

5.6 Регулярные платежи (подписка)

Регулярные платежи – это платежи без участия пользователя, которые совершаются по установленному расписанию, в течении установленного периода времени подписки. Для того, чтобы использовать данный функционал ИМ при регистрации первого платежа необходимо передавать в блоке postdata параметр Recurring, с названием заведенного в ПШ профиля подписки.

Требования:

1. Для создания профиля подписки, ИМ должен заполнить заявку, которая предоставляется службой тех. поддержи по запросу.
2. У ИМ должен быть договор с банком-эквайером, предусматривающий выполнение регулярных платежей.

Пример:

  <name>Recurring</name>
  <value>default</value>

5.6.1 Отмена подписки

Для отмены регулярных платежей до срока истечения подписки необходимо вызвать метод cancel сервиса order.

Методы: cancel

Сервис: order

Параметры запроса:

• order – идентификатор заказа, состоящий из:
  • shop_id – идентификатор магазина в ПШ
  • number – уникальный идентификатор заказа в ИМ

5.7 Повторные платежи

Повторные платежи – это платежи, которые выполняются по “привязанной” (на стороне ПШ) к аутентифицированному ИМ-ом Заказчику карте. Для начала работы с данным функционалом ИМ выполняет установочный платеж, в рамках которого на стороне ПШ регистрируется переданный ИМ идентификатор Заказчика и формируется связь с введенной Заказчиком картой. В результатах оплаты установочного платежа возвращается в том числе заполненное поле token необходимое для последующих платежей.

Требования:

1. ИМ должен вести базу Заказчиков и должным образом обеспечивать аутентификацию Заказчика.
   
2. У ИМ должен быть договор с банком-эквайером на эквайринг платежей такого типа.

5.7.1 Последующие платежи

Для выполнения второго и последующих оплат ИМ регистрирует заказ с параметром Showcase в блоке postdata cо значением token. По возвращенной ссылке из клиентского устройства необходимо отправить запрос согласно установленному протоколу.

Пример:

  <name>Recurring</name>
  <value>default</value>

6. Дополнительный функционал

6.1 Кастомизация платежной страницы

По-умолчанию, к идентификатору ИМ в ПШ привязывается стандартный вариант ПС. При желании ИМ может кастомизировать ПС в стилистике сайте – для этого специалисту, отвечающему за интеграцию с ПШ, необходимо запросить у службы тех. поддержки макеты платежных страниц.

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

   Требования: кастомизированные ПС размещаются в системе ПШ. После завершения работ по дизайну страниц, их необходимо выслать на адрес службы тех. поддержки для рассмотрения и выгрузки в систему.

   Для отображения выбранной ПС, ИМ необходимо передавать параметр Showcase, содержащийся в блоке postdata (сервис order метод register), с идентификатором той или иной ПС.

   Пример:

      <name>Showcase</name>
      <value>pp_white</value>

   Также, данный параметр используется в случае если, ИМ использует разные типы открываемых платежных страниц – полный перечень содержится в п. 7.7 – Типы платежных сессий.

2. Отображения ПС на иностранном языке. Список языков находится в п. 7.5 – Языки пользовательского интерфейса.

   Требования: если ИМ выбирает иностранный язык, для которого в ПШ нет перевода, специалист ИМ должен запросить у службы тех. поддержки файл локализации для самостоятельного перевода.

   Для отображения ПС в выбранном языке, ИМ необходимо передавать параметр Language, содержащийся в блоке postdata (сервис order метод register), с идентификатором языка.

   Пример:

      <name>Language</name>
      <value>en</value>

3. Отображения текстовое описание заказа на странице ввода реквизитов банковской карты.

   Для отображения комментария, ИМ должен настроить передачу параметра Comment, содержащийся в блоке postdata (сервис order метод register).

   Пример:

      <name>Comment</name>
      <value>ваш текст</value>

4. Выбор карты по умолчанию.

   Для отображения предварительного выбранной Заказчиком карты платежной системы, ИМ должен настроить передачу в блоке postdata параметра ChoosenCardType.

   Пример: xml <name>ChoosenCardType</name> <value>VI</value>

6.2 Определение устройства для приема платежа

 При использовании технологии приема оплаты на POS-терминале (а не с платежной WEB-странице), системе ПШ требуется информация об устройстве, на котором необходимо произвести платеж - код поставщика POS оборудования и серийный номер устройства. Выбор устройства может осуществлять как сам ПШ (на основании специфичных настроек), так и самой точкой продажи.

 При необходимости выбора конкретного устройства для каждого Заказа на оплату информация об устройстве передается в запросе на регистрацию заказа (к примеру, метод **register**) в блоке параметров **postdata**, параметры **POSVendor** - код поставщика POS-терминала, **POSSerialNumber** - серийный номер устройства.
 
 Пример:
 

<PostEntry>
    <name>POSVendor</name>
    <value>AQSI</value>
</PostEntry>
<PostEntry>
    <name>POSSerialNumber</name>
    <value>1002277478015719</value>
</PostEntry>

6.3 Ограничение доступных к оплате карт.

Для ограничение возможности использования платежных карт, с целью противодействия мошенничеству или для проведения маркетинговых акций, предприятие может отправить заявку на создание профиля карт. При регистрации заказа к оплате которого должны применятся ограничения по приему карты ИМ должен передавать в блоке postdata параметр AllowedCards, с кодом созданного профиля.

Пример:

   <name>AllowedCards</name>
   <value>Business</value>

6.4 Платежная страница на стороне предприятия

ИМ может направить запрос в ПШ, содержащий в себе одновременно данные и для регистрации заказа в системе и для авторизации средств на карте клиента. Такой вариант взаимодействия, как правило, используется в том случае, если ИМ реализует форму для ввода данных на своей стороне.

Требования: необходимо наличие сертификата PCI DSS у ИМ, который предоставляется .

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

cards (сервис order метод register) состоящий из:

• card – информация о платежном документе
  • number – маскированный номер платёжного документа
  • cvv – cvv/cvv2/cvc2 код
  • exp – срок действия карты
    • month – месяц
    • year – год
  • holder – держатель платёжного документа
  • amount – сумма к списанию
    • amount – стоимость
    • currency – латинский код валюты (RUB, EUR, USD)

В дополнение к этому блоку данных рекомендуется передавать информацию об устройстве, с которого была совершена оплата. Для этого ИМ необходимо передавать параметр device, который содержится в блоке description, (сервис order метод register) состоящий из:

• agent – device description
• ip – IP-адрес
• uid – device identifier

Важно! При таком варианте взаимодействия с ПШ, параметры ReturnURLOk/ReturnURLFault не используются, вместо этого в случае прохождения процедуры аутентификации по технологии 3DSecure, браузер клиента перенаправляется по адресу указанному в параметре ReceiptURL, блока postdata.

6.4.1 Оплата несколькими картами

Данный функционал позволяет передать данные нескольких карт в том случае, если клиент сомневается в достаточности средств на счете. Для реализации этого функционала ИМ необходимо добавить в базовый запрос параметр cards в необходимом количестве.

6.5 Получение электронного чека с результатами авторизации

Если ИМ при регистрации заказа вносит email адрес плательщика, то по факту оплаты к нему на указанный адрес поступает уведомление (от ПШ) о совершенной авторизации. Данное уведомление носит информативный характер, но вместе с тем содержит основную информацию о совершенной сделке (краткая информация о ИМ, тип операции, id платежа в системе процессинга, дату, код и сумму авторизации). По-умолчанию, данные уведомления отправляются по факту успешной/неуспешной авторизации, а также ее отмены.

Если у ИМ возникает потребность в получении данных чеков (собственный или плательщика), ИМ может использовать метод get_checks сервиса ticket для их получения.

Параметры запроса:

• order – идентификатор заказа, состоящий из:
  • number – уникальный идентификатор заказа в ИМ
  • shop_id – идентификатор магазина в ПШ

7. Справочники

7.1 Результаты выполнения запроса

7.2 Результаты авторизации платежа

7.3 Статусы заказа

7.4 Типы платежных сессий

7.5 Языки пользовательского интерфейса

7.6 Типы товаров и услуг

7.7 Статусы 3DS аутентификации