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

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

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

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

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

• 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 Получение статуса по номеру заказа После успешной регистрации заказа, ИМ в любой момент может уточнить статус оплаты заказа.

Метод: 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).

##4.2 Получение результатов оплаты за период Методы 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)

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

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

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

Методы: cancel Сервис: order

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

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

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

Методы: confirm Сервис: order

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

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

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

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

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

Методы: reject Сервис: order

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

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

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

##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 Корзина товаров и услуг.

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

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

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

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

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

   Пример:

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

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

Пример:

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

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

Требования: необходимо наличие сертификата 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.3.1 Оплата несколькими картами Данный функционал позволяет передать данные нескольких карт в том случае, если клиент сомневается в достаточности средств на счете. Для реализации этого функционала ИМ необходимо добавить в базовый запрос параметр cards в необходимом количестве.

##6.4 Получение электронного чека с результатами авторизации Если ИМ при регистрации заказа вносит 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 аутентификации

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