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

Важно! Все исправления/обновления данной документации вносятся в Историю изменений

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

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

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

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 являются обязательными, остальные – используются в расширенных сценариях оплаты, а так же в целях автоматизированного фрод–мониторинга, задач отчётности и аналитики.

Сервис: order

Метод: register

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

• 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 – идентификатор заказчика в ИМ

Ответ сервиса состоит из:

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

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 Получение статуса по номеру заказа

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

Сервис: status

Метод: get_by_order

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

• 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).

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

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

Сервис: status

Методы: get_by_payment_period | get_by_order_period

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

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

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

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

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

Опционально ПШ имеет возможность оповещать ИМ посредством вызова SOAP сервиса на стороне предприятия. Адрес сервиса оповещения передается в заявке на подключение ИМ. При изменении статуса заказа на оплату конечного статуса ПШ вызывает метод notify сервиса ИМ. Структура запроса полностью совпадает с ответом метода get_by_order сервиса status.

Метод: notify

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

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

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

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

Сервис: order

Метод: cancel

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

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

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

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

Сервис: order

Метод: confirm

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

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

Если ИМ не может принять оплату, то ИМ должен вызвать метод reject сервиса order для аннулирования платежа п. 5.3.

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

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

Сервис: order

Метод: reject

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

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

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

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

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

Сервис: order

Метод: refund

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

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

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

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

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

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

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

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

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

• id – номер элемента заказа (например порядковый номер)
• amount – стоимость данного элемента заказа
  • amount – сумма к оплате
  • currency – валюта

Данный блок параметров заполняется

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

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

Требования:

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

Пример:

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

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

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

Сервис: order

Метод: cancel

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

• 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.

   Пример:

      <name>ChoosenCardType</name>
      <value>VI</value>

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

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

Пример:

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

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

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

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

Сервис: order

Метод: register

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

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

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

• device - информация об устройстве, состоящая из:
  • agent – device description
  • ip – IP-адрес
  • uid – device identifier

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

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

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

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

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

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

Сервис: ticket

Метод: get_checks

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

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

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

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

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

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

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

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

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

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

История изменений