Manual SBRF
User Manual:
Open the PDF directly: View PDF 
.
Page Count: 167 [warning: Documents this large are best viewed by clicking the View PDF Link!]
Инструкция по подключению интернет-магазина к
платежному шлюзу
1. О документе
2. Терминология
3. Введение
4. Подключение
5. Взаимодействие
5.1. Схема работы с использованием 3d secure
5.2. Off-line взаимодействие между Магазином и Платежным шлюзом
5.2.1. Авторизация в случае двухстадийных платежей
5.2.2. Отмена операции (Reversal)
5.2.3. Возврат средств (Refund)
5.3. Реализация схем на стороне магазина
6. Алгоритм действий для подключения к платёжному шлюзу
7. Интерфейс на WebService-ах
7.1. Запросы, используемые при одностадийной оплате
7.1.1. Запрос регистрации заказа
7.1.2. Запрос отмены оплаты заказа
7.1.3. Запрос возврата средств оплаты заказа
7.1.4. Расширенный запрос состояния заказа
7.1.5. Запрос проверки вовлечённости карты в 3DS
7.1.6. Запрос добавления дополнительных параметров к заказу
7.2. Запросы, используемые при двухстадийной оплате
7.2.1. Запрос регистрации заказа с предавторизацией
7.2.2. Запрос завершения оплаты заказа
7.2.3. Запрос отмены оплаты заказа
7.2.4. Запрос возврата средств оплаты заказа
7.2.5. Расширенный запрос состояния заказа
7.2.6. Запрос проверки вовлечённости карты в 3DS
7.2.7. Запрос добавления дополнительных параметров к заказу
8. Интерфейс REST
8.1. Особенности тестирования REST-запросов в интернет-браузере
8.2. Запросы, используемые при одностадийной оплате
8.2.1. Запрос регистрации заказа
8.2.2. Запрос отмены оплаты заказа
8.2.3. Запрос возврата средств оплаты заказа
8.2.4. Расширенный запрос состояния заказа
8.2.5. Запрос проверки вовлечённости карты в 3DS
8.3. Запросы, используемые при двухстадийной оплате
8.3.1. Запрос регистрации заказа c предавторизацией
8.3.2. Запрoс завершения oплаты заказа
8.3.3. Запрос отмены оплаты заказа
8.3.4. Запрос возврата средств оплаты заказа
8.3.5. Расширенный запрос состояния заказа
8.3.6. Запрос проверки вовлечённости карты в 3DS
9. Callback-уведомления
9.1. Общие сведения
9.1.1. Типы операций, на которые могут быть получены уведомления
9.1.2. Типы уведомлений
9.1.3. Требования к SSL-сертификатам сайта магазина
9.2. Формат URL callback-уведомлений
9.3. Алгоритм обработки callback-уведомлений
9.4. Примеры кода
9.4.1. Пример для Java (симметричная криптография)
9.4.2. Пример для Java (асимметричная криптография)
9.4.3. Пример для PHP (симметричная криптография)
10. Оформление платёжного интерфейса
11. Требования Сбербанка к электронным витринам
12. Координаты подключения
13. Тестовые карты
14. Приложение 1. Описание функционала связок
14.1. Общее описание
14.2. Отображение на платёжной странице. Форма выбора связки
14.3. Создание запросов по связкам
14.3.1. Описание запросов, интерфейс на WebService-ах
14.3.1.1. Запрос проведения платежа по связкам
14.3.1.2. Запрос деактивации связки
14.3.1.3. Запрос активации связки
14.3.1.4. Запрос изменения срока действия связки
14.3.1.4. Запрос изменения срока действия связки
14.3.1.5. Запрос списка связок по идентификатору клиента
14.3.1.6. Запрос списка связок определённой банковской карты
14.3.2. Описание запросов, интерфейс REST
14.3.2.1. Запрос проведения платежа по связкам
14.3.2.2. Запрос деактивации связки
14.3.2.3. Запрос активации связки
14.3.2.4. Запрос изменения срока действия связки
14.3.2.5. Запрос списка связок по идентификатору клиента
14.3.2.6. Запрос списка связок определённой банковской карты
15. Приложение 2. Коды ответа - расшифровка actionCode (ответ процессинга)
16. Приложение 3. Оплата из мобильного приложения с использованием Apple Pay
16.1. Общие сведения
16.1.1. Действия продавца, необходимые для подключения к Apple Pay
16.1.1.1. Действия в личном кабинете платёжного шлюза
16.1.1.2. Создание Merchant ID
16.1.1.3. Создание сертификата для Merchant ID
16.1.2. Схема взаимодействия при оплате из мобильного приложения
16.1.3. Apple Pay - ссылки на справочную информацию
16.2. Запрос на оплату Apple Pay
16.2.1. Интерфейс REST
16.2.2. Интерфейс WebService-ах
16.3. Тестирование интеграции с Apple Pay
16.3.1. Подготовка к работе
16.3.2. Создание тестовой учётной записи
16.3.3. Добавление номера тестовой банковской карты
17. Приложение 4. Оплата через Android Pay
17.1. Общие сведения
17.2. Запрос на оплату Android Pay
17.2.1. Интерфейс REST
17.2.2. Интерфейс WebService-ах
18. Приложение 5. Оплата через Samsung Pay
18.1. Общие сведения
18.1.1. Схема взаимодействия при оплате из мобильного приложения
18.1.2. Схема взаимодействия при оплате с веб-страницы (платёжная форма на стороне платёжного шлюза)
18.1.3. Схема взаимодействия при оплате с веб-страницы (платёжная форма на стороне продавца)
18.2. Запрос на оплату Samsung Pay
18.2.1. Интерфейс REST
18.2.2. Интерфейс WebService
18.3. Запрос на оплату Samsung Pay Web
19. Приложение 7. Интернет-кредитование
19.1. Общее описание
19.2. Схема взаимодействий при использовании интернет-кредитования
19.3. Принципы работы с товарной корзиной
19.3.1. Требования к регистрации заказов с передачей товарной корзины
19.3.2. Требования к завершению заказов с товарной корзиной (для двухстадийных платежей)
19.3.3. Требования к возвратам средств за заказы с товарной корзиной
19.4. Запросы на регистрацию заказа с передачей товарной корзины
19.4.1. Интерфейс WS
19.4.1.1. Одностадийная оплата
19.4.1.2. Двухстадийная оплата
19.4.2. Интерфейс REST
19.4.2.1. Одностадийная оплата
19.4.2.2. Двухстадийная оплата
20. Приложение 8. Оплата через Google Pay
20.1. Введение
20.2. Схемы взаимодействия
20.2.1. Оплата в мобильном приложении
20.2.2. Оплата на платёжной странице, которая расположена на стороне интернет-магазина
20.2.3. Оплата на платёжной странице, которая расположена на стороне платёжного шлюза
20.3. Запросы на оплату
20.3.1. Запрос на оплату Google Pay, интерфейс WS
20.3.2. Запрос на оплату Google Pay, интерфейс REST
1. О документе
Настоящий документ описывает принципы подключения и программные интерфейсы платёжного шлюза.
2. Терминология
3-D Secure – технология МПС Visa, позволяющая дополнительно авторизовать пользователя средствами банка-эмитента.
ACS – Access Control Server, элемент инфраструктуры 3-D Secure, обеспечивающий валидацию плательщика на стороне
банка-эмитента.
Merchant Plugin Interface (MPI) – технологический компонент 3-D Secure и SecureCode, который может быть размещен на стороне
ПС или на стороне магазина
SecureCode – технология МПС MasterCard, позволяющая дополнительно авторизовать пользователя средствами
банка-эмитента. Технологически равносильна 3-D Secure. В тексте ниже при упоминании 3-D Secure будем иметь ввиду и
SecureCode.
Банковская Карта – карта международных платежных систем VISA и MasterCard.
Банк-эквайер – банк, который реализует и эксплуатирует платёжный шлюз.
Банк-эмитент – банк, выпустивший банковскую карту клиента.
Возврат средств (Refund) – частичный или полный возврат денежных средств на карту покупателя в случае его отказа от
получения товара(услуги) или его возврата. Операция возврата денежных средств выполняется после списания денежных
средств со счета покупателя.
Двухстадийный платеж – операция по оплате товаров/услуг, совершенная через Интернет с использованием банковских карт,
требующая дополнительного подтверждения. Двухстадийный механизм работы позволяет разделить процесс проверки
платежеспособности банковской карты (авторизация) и снятие денег (финансовое подтверждение). На первой стадии
двустадийного платежа происходит проверка платежеспособности банковской карты и блокирование средств на счету клиента.
Заказ – элементарная сущность системы, описывает заказ в некотором интернет-магазине или его аналоге. У любого заказа
есть сумма.
Магазин (мерчант) – торгово-сервисное предприятие (ТСП), продающее товары или оказывающее услуги через интернет-сайт.
МПС – Международная платежная система (например, Visa или MasterCard)
Одностадийный платеж -- операция по оплате товаров/услуг, совершенная через Интернет с использованием банковских карт,
которая не требует дополнительного подтверждения.
Отмена операции оплаты (Reversal) – снятие блокировки с денежных средств на карте покупателя. Данная функция доступна
ограниченное время, точные сроки необходимо уточнять в банке.
Платёжная форма – HTML-страница, которая используется клиентом для ввода реквизитов платежа.
Платёжные реквизиты – реквизиты, используемые пользователем для оплаты заказа. Обычно, это номер карты, expiration date,
CVC.
Платёжный шлюз Банка-эквайера (ПШ) – автоматическая система, предоставляющая принимать, а Клиентумагазину
отправлять платежи через Интернет с использованием банковских карт.
Плательщик – физическое лицо совершающее платеж по своей карте за услуги мерчанта в интернет магазине мерчанта.
Связка – соответствие между Плательщиком и платежными реквизитами карты (номер карты, срок действия карты).
3. Введение
Интернет-эквайринг – это современный способ продажи услуг или товаров через публичную сеть Интернет, посредством банковских
карт.
В связи с особенностями осуществления покупок в сети Интернет существует необходимость в обеспечении безопасного
взаимодействия сторон, участвующих при осуществлении операции продажи товаров/услуг – клиента, магазина и банка-эквайера.
Магазин, планирующий осуществлять продажу услуг или товаров в сети Интернет посредством банковских карт должен выполнять
процедуры по обеспечению безопасности проведения платежей:
Взаимодействие с клиентом в момент передачи ключевых данных (персональные данные, данные о реквизитах платёжных карт)
должно осуществляться с применением криптографических средств (SSL/TLS).
Информация о совершаемом платеже (сумма, валюта, описание заказа), а также результат проведения платежа должны быть
надежно защищены от вмешательства злоумышленников.
В момент совершения платежа должны применяться процедуры проверки принадлежности карты клиенту.
Для выполнения данных требований банк-эквайер использует специализированную технологию по обеспечению безопасности платежей
в сети Интернет, разработанную Международными Платёжными Системами Visa International и MasterCard – З-D Secure (Verified by Visa
и MasterCard SecureCode).
В качестве технологической платформы используется платежный шлюз, позволяющий магазину выполнить необходимые процедуры
безопасности без существенной перестройки Сайта Интернет-магазина и существующих бизнес-процессов.
4. Подключение
В результате подключения магазин получает:
1.
2.
В результате подключения магазин получает:
Логин – имя магазина в рамках платёжного шлюза. Оно используется только для произведения операций посредством API.
Пароль – пароль магазина в рамках платёжного шлюза. Используется только для произведения операций посредством API
5. Взаимодействие
5.1. Схема работы с использованием 3d secure
1.
2.
3.
4.
5.
6.
7.
8.
9.
Описание:
Клиент взаимодействует с магазином для создания заказа в магазине.
После подтверждения заказа клиентом, система магазина регистрирует заказ в платежном шлюзе. Для регистрации
используются такие параметры как сумма списания, валюта списание, номер заказа в системе магазина, а также URL возврата
клиента.
На запрос регистрации платежный шлюз возвращает уникальный идентификатор заказа в платежной системе и URL, на который
надо перенаправить пользователя для получения платежной формы.
Система магазина передает браузеру клиента redirect на URL, полученный на шаге 3.
Браузер клиента открывает URL.
В качестве страницы по указанному URL браузер клиента получает платежную форму.
Пользователь заполняет полученную форму и отправляет данные на сервер платежного шлюза.
Система проверяет вовлеченности карты в 3DSecure (SecureCode).
Шлюз отправляет браузеру клиента redirect на страницу ACS банка эмитента (этот шаг является необходимым для реализации
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
Шлюз отправляет браузеру клиента redirect на страницу ACS банка эмитента (этот шаг является необходимым для реализации
3DS).
Браузер клиента запрашивает у ACS форму авторизации пользователя (у каждого эмитента это делается по-своему).
ACS отправляет в браузер клиента эту форму, клиент ее видит.
Клиент заполняет форму и отправляет ее в ACS.
ACS обрабатывает заполненную форму и (в не зависимости от результата) передает браузеру redirect на URL страницы
платежного шлюза. Вместе с этим URL передаются зашифрованные параметры результата авторизации.
Браузер клиента запрашивает страницу платежного шлюза, передавая зашифрованные параметры результата авторизации.
Платежный шлюз производит оплату (списание).
После проведения оплаты, платежный шлюз передает браузеру клиента URL возврата (указанный ранее при регистрации заказа
магазином).
Браузер клиента запрашивает страницу с результатами оплаты у магазина.
(необязательно) Система магазина запрашивает платежный шлюз о статусе оплаты заказа (по внутреннему номеру в платежной
системе).
(необязательно) платежный шлюз возвращает статус оплаты.
Система магазина передает в браузер клиента страницу с результатами оплаты.
В этой схеме шаги 18 и 19 не являются обязательными, магазин может не использовать их в работе.
Если по истечении отведенных на оплату 20 минут клиент не вернулся с платежного шлюза на страницу результатов оплаты магазина
(на URL возврата клиента), то оплата считается неудачной.
Изменение статуса оплаты заказа может быть выполнено по запросу магазина вручную сотрудниками Банка после проверки состояния
транзакции в банковских системах. В этом случае после подтверждения изменения статуса заказа магазин может выполнить повторный
запрос о статусе оплаты заказа (шаги 18-19).
По завершении п.20 заканчивается взаимодействие между магазином и платежным шлюзом в on-line режиме. Дальнейшие операции по
завершению платежа (в случае двухстадийных платежей), отмене платежа и возврату денежных средств проводятся в off-line режиме.
Жизненный цикл заказа приводится в документе .Работа с заказом
5.2. Off-line взаимодействие между Магазином и Платежным шлюзом
5.2.1. Авторизация в случае двухстадийных платежей
1.
2.
3.
4.
5.
1.
2.
3.
4.
5.
Описание:
Система магазина отправляет запрос на завершение платежа (Deposit).
Платежный шлюз выполняет завершение платежа.
Платежный шлюз возвращает результат операции (в ответе на запрос завершения не указывается, прошел ли запрос;
указывается только, что запрос был обработан платежным шлюзом без системных ошибок).
Система магазина запрашивает платежный шлюз о статусе заказа (по внутреннему номеру в платежной системе).
Платежный шлюз возвращает статус заказа.
5.2.2. Отмена операции (Reversal)
Описание:
Если платеж одностадийный и статус заказа Deposited (либо платеж двухстадийный и статус заказа Approved), магазин
отправляет в платежный шлюз запрос на отмену транзакции.
Платежный шлюз выполняет отмену операции.
Платежный шлюз возвращает результат операции.
Система магазина запрашивает платежный шлюз о статусе заказа.
Платежный шлюз возвращает статус заказа.
Примечание. Операция отмены платежа (Revers) может быть проведена до момента завершения платежа (в случае одностадийных
платежей , Aиз состояния Deposited - только в тот же календарный день авторизации до 0:00 для двухстадийных платежей из состояния
pproved, срок оговаривается в договоре на Интернет-эквайринг с Банком).
Операцию отмены платежа (Revers) запрещается проводить после 00:00 дня, следующего за днем оплаты заказа.
Кроме того, данную операцию можно сделать только один раз. Если она закончится ошибкой, то повторная операция отмены платежа не
пройдет.
5.2.3. Возврат средств (Refund)
1.
2.
3.
4.
5.
1.
2.
Описание:
Если статус заказа Deposited, магазин отправляет в платежный шлюз запрос на возврат денежных средств.
Платежный шлюз выполняет операцию возврата.
Платежный шлюз возвращает результат операции.
Система магазина запрашивает платежный шлюз о статусе заказа.
Платежный шлюз возвращает статус заказа.
Примечание. Возврат средств (Refund) по заказу возможен более одного раза, до тех пор, пока не будет возвращена вся сумма заказа
полностью.
5.3. Реализация схем на стороне магазина
Взаимодействия магазина и платежного шлюза синхронны, т.е. вызывающая сторона должна дождаться получения ответа или таймаута
для продолжения работы, а также однонаправлены - всегда система магазина обращается к платежному шлюзу и никогда не наоборот.
Для реализации указанного взаимодействия платежный шлюз поддерживает API из 2х запросов:
Зарегистрировать заказ
Получить информацию по состоянию заказа
Система предоставляет 2 реализации API:
Реализация на WebService-ах (SOAP)
Реализация на REST
Примечание: С момента регистрации заказа у покупателя есть 20 минут для его оплаты. При попытке его оплаты по истечении этого
срока будет выдаваться страница с ошибками.
6. Алгоритм действий для подключения к платёжному шлюзу
1.
2.
3.
4.
5.
6.
7.
8.
Получение логинов и паролей на тестовый сервер.
Тестирование работоспособности платёжной страницы:
с использованием интерфейса REST \ интерфейса на web-сервисах;
с использованием формы для регистрации заказа;
с использованием личного кабинета и консоли.
По готовности интеграции и страницы свяжитесь с службой сопровождения (rbssupport@bpc.ru), чтобы вашу платёжную
страницу проверили. Если проверка прошла успешно, сотрудники сопровождения перенесут вашу платёжную страницу на
боевой сервер.
Получение логинов и паролей на боевой сервер.
Переключение вашего магазина на использование промышленной системы.
Произведение тестовой оплаты настоящей картой (рекомендуется провести оплату по 3DS-карте, а также выполнить
SSL-платёж).
Выполнить отмену и возврат платежа через личный кабинет платежа.
Подписание акта о готовности интернет-магазина.
7. Интерфейс на WebService-ах
Описание (WSDL) сервиса находится на тестовом сервере, который доступен без ограничений. Адреса см. "Координаты подключения"
ниже.
Для авторизации обращения магазина к системе платежного шлюза, в любом запросе со стороны магазина должны быть приведены
имя и пароль магазина, которые представитель магазина ввел при регистрации магазина в системе. Значения имени и пароля
передаются в формате, описанном в рамках спецификации WS-Security, тип авторизации userName token. Заголовок при такой
авторизации будет выглядеть примерно так:
<wsse:Security
xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecu
rity-secext-1.0.xsd"
xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-%20wsse
curity-utility-1.0.xsd">
<wsse:UsernameToken wsu:Id="UsernameToken-87">
<wsse:Username>aa</wsse:Username>
<wsse:Password
Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-tok
en-profile-1.0#PasswordText">123456</wsse:Password>
</wsse:UsernameToken>
</wsse:Security>
В зависимости от выбранной схемы системы оплаты (одностадийная или двухстадийная) синтаксис запросов различается. Ниже
описаны запросы для каждой из них.
Если код ошибки , запрос был обработан платежным шлюзом без системных ошибок (при этом не показываетerrorCode=0 errorCode
статус заказа).
Для получения статуса заказа следует использовать запрос .getOrderStatusExtended
7.1. Запросы, используемые при одностадийной оплате
7.1.1. Запрос регистрации заказа
Для регистрации заказа в платёжном шлюзе используется метод . Описание метода представлено в WSDL сервиса.registerOrder
Параметры запроса:
Название Тип Обязательно Описание
merchantOrderNumber ANS..32 да Номер (идентификатор) заказа в системе магазина, уникален для каждого магазина в пределах
системы. Если номер заказа генерируется на стороне платёжного шлюза, этот параметр
передавать необязательно.
description ANS..512 нет Описание заказа в свободной форме. В процессинг банка для включения в финансовую
отчётность продавца передаются только первые 24 символа этого поля.
amount N..20 да Сумма платежа в минимальных единицах валюты
currency N3 нет Код валюты платежа ISO 4217. Единственное допустимое значение - 643.
language A2 нет Язык в кодировке ISO 639-1. Если не указан, будет использован язык, указанный в настройках
магазина как язык по умолчанию (default language).
pageView ANS..20 нет По значению данного параметра определяется, какие страницы платёжного интерфейса должны
загружаться для клиента. Возможные значения:
DESKTOP – для загрузки страниц, верстка которых предназначена для отображения на
экранах ПК (в архиве страниц платёжного интерфейса будет осуществляться поиск страниц с
названиями и );payment_<locale>.html ocale>.htmlerrors_<l
MOBILE – для загрузки страниц, верстка которых предназначена для отображения на экранах
мобильных устройств (в архиве страниц платёжного интерфейса будет осуществляться
поиск страниц с названиями и mobile_payment_<locale>.html ocalemobile_errors_<l
);>.html
Если магазин создал страницы платёжного интерфейса, добавив в название файлов страниц
произвольные префиксы, передайте значение нужного префикса в параметре дляpageView
загрузки соответствующей страницы. Например, при передаче значения в архивеiphone
страниц платёжного интерфейса будет осуществляться поиск страниц с названиями iphone
и ._payment_<locale>.html iphone_error_<locale>.html
Где:
locale – я . Например, для русского или длязык страницы в кодировке ISO 639-1 ru en
английского.
Если параметр отсутствует, либо не соответствует формату, то по умолчанию считается pageVie
.w=DESKTOP
sessionTimeoutSecs N...9 нет Продолжительность жизни заказа в секундах.
В случае если параметр не задан, будет использовано значение, указанное в настройках
мерчанта или время по умолчанию (1200 секунд = 20 минут).
Если в запросе присутствует параметр expirationDate, то значение параметра sessionTimeo
utSecs не учитывается.
bindingId AN..255 no Идентификатор связки, созданной ранее. Может использоваться, только если у магазина есть
разрешение на работу со связками. Если этот параметр передаётся в данном запросе, то это
означает:
1. Данный заказ может быть оплачен только с помощью связки;
2. Плательщик будет перенаправлен на платёжную страницу, где требуется только ввод CVC.
expirationDate ANS нет Дата и время окончания жизни заказа. Формат: .yyyy-MM-dd'T'HH:mm:ss
Если этот параметр не передаётся в запросе, то для определения времени окончания жизни
заказа используется .sessionTimeoutSecs
returnUrl AN..512 да Адрес, на который требуется перенаправить пользователя в случае успешной оплаты. Адрес
должен быть указан полностью, включая используемый протокол (например, вместо https://test.ru t
). В противном случае пользователь будет перенаправлен по адресу следующего вида: est.ru http:/
./<адрес_платёжного_шлюза>/<адрес_продавца>
failUrl AN..512 нет Адрес, на который требуется перенаправить пользователя в случае неуспешной оплаты. Адрес
должен быть указан полностью, включая используемый протокол (например, вместо https://test.ru t
). В противном случае пользователь будет перенаправлен по адресу следующего вида: est.ru http:/
./<адрес_платёжного_шлюза>/<адрес_продавца>
params нет Тэг с атрибутами для передачи дополнительных параметров мерчанта.
Поля дополнительной информации для последующего хранения. Для передачи N параметров, в
запросе должно находиться N тэгов , где атрибут содержит название, а атрибут params name valu
содержит значение:e
Название Тип Обязательно Описание
name AN..20 да Название дополнительного параметра
value AN..1024 да Значение дополнительного параметра
Данные поля могут быть переданы в процессинг банка для последующего отображения в
реестрах.*
Включение данного функционала возможно по согласованию с банком в период интеграции.
Если для продавца настроена отправка покупателю, адрес электронной почтыуведомлений
покупателя должен передаваться в этом тэге в параметре с именем .email
clientId ANS..255 нет Номер (идентификатор) клиента в системе магазина. Используется для реализации функционала
связок. Может присутствовать, если магазину разрешено создание связок.
merchantLogin AN..255 нет Чтобы зарегистрировать заказ от имени дочернего мерчанта, укажите его логин в этом параметре.
features ANS..255 нет Контейнер для параметра , в котором можно указать следующие значения.feature
AUTO_PAYMENT - Если запрос на регистрацию заказа инициирует проведение автоплатежей.
FORCE_TDS - Принудительное проведение платежа с использованием 3-D Secure. Если карта не
поддерживает 3-D Secure, транзакция не пройдёт.
FORCE_SSL - Принудительное проведение платежа через SSL (без использования 3-D Secure).
FORCE_FULL_TDS - После проведения аутентификации с помощью 3-D Secure статус PaRes
должен быть только , что гарантирует успешную аутентификацию пользователя. В противномY
случае транзакция не пройдёт.
Ниже представлен пример использования.
<features>
<feature>AUTO_PAYMENT</feature>
</features>
* По умолчанию в процессинг банка передаются поля:
merchantOrderNumber – номер заказа в системе магазина;
description – описание заказа (не более 24 символов, запрещены к использованию %, +, конец строки \r и
перенос строки \n).
Если в заказе передать дополнительный параметр с именем , то именно его значение будет передано вmerchantOrderId
процессинг в качестве номера заказа (вместо значения поля ).orderNumber
Параметры ответа:
Название Тип Обязательно Описание
orderId ANS36 нет Номер заказа в платежной системе. Уникален в пределах системы. Отсутствует, если регистрация заказа на
удалась по причине ошибки, детализированной в .errorCode
formUrl AN..512 нет URL платежной формы, на который надо перенаправить браузер клиента. Не возвращается, если
регистрация заказа не удалась по причине ошибки, детализированной в .errorCode
errorCode N3 нет Код ошибки.
Указание этого параметра при платежах по связке необходимо - в противном случае
платёж будет неуспешен.
errorMessage AN..512 нет Описание ошибки на языке, переданном в параметре в запросе.language
Коды ошибок (поле ):errorCode
Значение Описание
0Обработка запроса прошла без системных ошибок
1 Неверный номер заказа
1 Заказ с таким номером уже обработан
3 Неизвестная валюта
4 Отсутствует сумма
4 Номер заказа не может быть пуст
4 URL возврата не может быть пуст
5 Неверно указано значение одного из параметров
5 Неверная сумма
5 Доступ запрещён
5 Пользователь должен сменить свой пароль
7 Системная ошибка
13 Мерчант не имеет привилегии выполнять проверочные платежи
14 Features указаны некорректно
Пример запроса:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:mer="http://engine.paymentgate.ru/webservices/merchant">
<soapenv:Header/>
<soapenv:Body>
<mer:registerOrder>
<order merchantOrderNumber="78ds901234567890" description=" "
amount="15000" currency=" " language=" " pageView="MOBILE"
sessionTimeoutSecs=" " bindingId=" " expirationDate="2014-09-08T14:14:14">
<returnUrl>https://server/applicaton_context/finish.html</returnUrl>
<params name="param1" value="valueParam1"/>
<params name="param2" value="valueParam2"/>
<clientId>666</clientId>
<merchantLogin> </merchantLogin>
<features>
<feature>AUTO_PAYMENT</feature>
</features>
</order>
</mer:registerOrder>
</soapenv:Body>
</soapenv:Envelope>
Пример ответа:
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<ns1:registerOrderResponse
xmlns:ns1="http://engine.paymentgate.ru/webservices/merchant">
<return orderId="05fcbc62-7ee6-4f1a-b3d5-6ca41a982283"
errorCode="0" errorMessage="">
<formUrl>
https://server/application_context/mobile_payment_ru.html?mdOrder=05fcbc62
-7ee6-4f1a-b3d5-6ca41a982283 </formUrl>
</return>
</ns1:registerOrderResponse>
</soap:Body>
</soap:Envelope>
7.1.2. Запрос отмены оплаты заказа
Для запроса отмены заказа используется запрос . Функция отмены доступна в течение ограниченного времени послеreverseOrder
оплаты, точные сроки необходимо уточнять в Банке.
Операция отмены оплаты может быть совершена только один раз. Если она закончится ошибкой, то повторная операция отмены
платежа не пройдет.
Данная функция доступна магазинам по согласованию с Банком. Для выполнения операции отмены пользователь должен обладать
соответствующими правами.
Параметры запроса:
Название Тип Обязательно Описание
orderId ANS36 да Номер заказа в платежной системе. Уникален в пределах системы.
language A2 нет Язык в кодировке ISO 639-1. Если не указан, считается, что язык – русский. Сообщение ошибке будет
возвращено именно на этом языке.
Параметры ответа:
Название Тип Обязательно Описание
errorCode N3 нет Код ошибки.
errorMessage AN..512 нет Описание ошибки на языке, переданном в параметре Language в запросе.
Коды ошибок (поле errorCode):
Значение Описание
0Обработка запроса прошла без системных ошибок
5 Доступ запрещён
5 Пользователь должен изменить свой пароль
5 [orderId] не задан
6 Неверный номер заказа
7 Недопустимая операция для текущего состояния заказа
7 Системная ошибка
Пример запроса:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:mer="http://engine.paymentgate.ru/webservices/merchant">
<soapenv:Header/>
<soapenv:Body>
<mer:reverseOrder>
<order language="ru"
orderId="f88a2bbf-2021-4ccc-8783-8a13068a89f9">
<!-- Zero or more repetitions: -->
<params name="param1" value="paramValue1"/>
</order>
</mer:reverseOrder>
</soapenv:Body>
</soapenv:Envelope>
Пример ответа:
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<ns1:reverseOrderResponse
xmlns:ns1="http://engine.paymentgate.ru/webservices/merchant">
<return errorCode="7" errorMessage=" "/>
</ns1:reverseOrderResponse>
</soap:Body>
</soap:Envelope>
7.1.3. Запрос возврата средств оплаты заказа
Для возврата средств используется запрос .refundOrder
По этому запросу средства по указанному заказу будут возвращены плательщику. Запрос закончится ошибкой в случае, если средства
по этому заказу не были списаны. Система позволяет возвращать средства более одного раза, но в общей сложности не более
первоначальной суммы списания.
Для выполнения операции возврата необходимо наличие соответствующих права в системе.
Параметры запроса:
Параметры запроса:
Название Тип Обязательно Описание
orderId ANS36 да Номер заказа в платежной системе. Уникален в пределах системы.
refundAmount N..5 да Сумма возврата в валюте заказа. Может быть меньше или равна остатку в заказе.
language A2 нет Язык в кодировке ISO 639-1. Если не указан, считается, что язык – русский. Сообщение ошибке будет
возвращено именно на этом языке.
Параметры ответа:
Название Тип Обязательно Описание
errorCode N3 нет Код ошибки.
errorMessage AN..512 нет Описание ошибки на языке, переданном в параметре Language в запросе.
Коды ошибок (поле errorCode):
Значение Описание
0Обработка запроса прошла без системных ошибок
5 Доступ запрещён
5 Пользователь должен изменить свой пароль
5 [orderId] не задан
5 Неверная сумма
6 Неверный номер заказа
7 Платёж должен быть в корректном состоянии
7 Сумма возврата превышает сумму списания
7 Системная ошибка
Пример запроса:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:mer="http://engine.paymentgate.ru/webservices/merchant">
<soapenv:Header/>
<soapenv:Body>
<mer:refundOrder>
<order language="ru"
orderId="4302d369-a5e8-4432-a5e5-42acfab52c86" refundAmount="20000">
<!-- Zero or more repetitions: -->
<params name=" " value=" "/>
</order>
</mer:refundOrder>
</soapenv:Body>
</soapenv:Envelope>
Пример ответа:
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<ns1:refundOrderResponse
xmlns:ns1="http://engine.paymentgate.ru/webservices/merchant">
<return errorCode="7" errorMessage=" "/>
</ns1:refundOrderResponse>
</soap:Body>
</soap:Envelope>
7.1.4. Расширенный запрос состояния заказа
Для запроса состояния зарегистрированного заказа используется запрос . getOrderStatusExtended
Параметры запроса:
Название Тип Обязательно Описание
orderId ANS36 да* Номер заказа в платёжной системе. Уникален в пределах системы
language A2 нет Язык в кодировке ISO 639-1. Если не указан, считается, что язык – русский. Сообщение ошибке
будет возвращено именно на этом языке.
merchantOrderNumber ANS..32 да* Номер (идентификатор) заказа в системе магазина.
* В запросе необходимо передать или параметр , или . Если в запросе передаются оба параметра,orderId merchantOrderNumber
приоритет выше.orderId
Существует несколько наборов параметров ответа. Какие именно наборы параметров будут возвращены, завит от версии getOrderSta
, указанной в настройках продавца.tusExtended
Название Тип Обязательно Описание Версия
getOrderStatusExtended
orderNumber AN..32 да Номер (идентификатор) заказа в системе магазина. Все версии.
orderStatus N2 нет По значению этого параметра определяется состояние заказа в
платёжной системе. Список возможных значений приведён в списке
ниже. Отсутствует, если заказ не был найден.
0 - Заказ зарегистрирован, но не оплачен;
1 - Предавторизованная сумма захолдирована (для двухстадийных
платежей);
2 - Проведена полная авторизация суммы заказа;
3 - Авторизация отменена;
4 - По транзакции была проведена операция возврата;
5 - Инициирована авторизация через ACS банка-эмитента;
6 - Авторизация отклонена.
Все версии.
actionCode N3 да Код ответа. Все версии.
actionCodeDescription AN..512 да Расшифровка кода ответа на языке, переданном в параметре Language
в запросе.
Все версии.
errorCode N3 нет Код ошибки. Возможны следующие варианты.
0 - Обработка запроса прошла без системных ошибок;
1 - Ожидается [orderId] или [orderNumber];
5 - Доступ запрещён;
5 - Пользователь должен сменить свой пароль;
6 - Заказ не найден;
7 - Системная ошибка.
Все версии.
errorMessage AN..512 нет Описание ошибки на языке, переданном в параметре Language в
запросе.
Все версии.
amount N..20 да Сумма платежа в копейках (или центах) Все версии.
currency N3 нет Код валюты платежа ISO 4217. Единственное допустимое значение -
643.
Все версии.
date ANS да Дата и время регистрации заказа, выраженные в количестве
миллисекунд, прошедших с 1 января 1970 года.
Все версии.
orderDescription AN..512 нет Описание заказа, переданное при его регистрации Все версии.
ip AN..20 да IP-адрес покупателя. Все версии.
Элемент – присутствует в ответе, если в заказе содержатся дополнительные параметры продавца. Каждый дополнительныйmerchantOrderParams
параметр заказа представлен в отдельном элементе .merchantOrderParams
name AN..20 нет Название дополнительного параметра Все версии.
value AN..1024 нет Значение дополнительного параметра Все версии.
Элемент – в элементе лежит структура, состоящая из списка элемента и следующих параметеров:cardAuthInfo secureAuthInfo
maskedPan N..19 нет Маскированный номер карты, которая использовалась для оплаты.
Указан только после оплаты заказа.
Все версии.
expiration N6 нет Срок истечения действия карты в формате YYYYMM. Указан только
после оплаты заказа.
Все версии.
cardholderName A..64 нет Имя держателя карты. Указан только после оплаты заказа. Все версии.
approvalCode AN6 нет Код авторизации платежа. Поле фиксированной длины (6 символов),
может содержать цифры и латинские буквы. Указан только после
оплаты заказа.
Все версии.
chargeback A..5 нет Были ли средства принудительно возвращены покупателю банком.
Возможны следующие значения.
true (истина);
false (ложь).
06 и выше.
paymentSystem N..10 да Наименование платёжной системы. Доступны следующие варианты.
VISA;
MASTERCARD;
AMEX;
JCB;
CUP;
MIR.
08 и выше.
product AN..255 да Дополнительные сведения о корпоративных картах. Эти сведения
заполняются службой технической поддержки в консоли управления.
Если такие сведения отсутствуют, возвращается пустое значение.
08 и выше.
paymentWay AS..14 да Способ совершения платежа (платёж в с вводом карточных данных,
оплата по связке и т. п.).
09 и выше.
Элемент (элемент состоит из элемента и элемента , являющимся списком параметров и ):secureAuthInfo eci threeDSInfo cavv xid
eci N..4 нет Электронный коммерческий индикатор. Указан только после оплаты
заказа и в случае соответствующего разрешения.
Все версии.
cavv ANS..200 нет Значение проверки аутенфикации владельца карты. Указан только
после оплаты заказа и в случае соответствующего разрешения.
Все версии.
xid ANS..80 нет Электронный коммерческий идентификатор транзакции. Указан только
после оплаты заказа и в случае соответствующего разрешения.
Все версии.
Элемент состоит из параметров:bindingInfo
clientId ANS..255 нет Номер (идентификатор) клиента в системе магазина, переданный при
регистрации заказа. Присутствует только если магазину разрешено
создание связок.
Все версии.
bindingId AN..255 нет Идентификатор связки созданной при оплате заказа или
использованной для оплаты. Присутствует только если магазину
разрешено создание связок.
Все версии.
authDateTime ANS нет Дата/время авторизации. 02 и выше.
authRefNum AN..24 нет Учётный номер авторизации платежа, который присваивается при
регистрации платежа.
02 и выше.
terminalId AN..10 нет Id терминала. 02 и выше.
Элемент состоит из параметров:paymentAmountInfo
approvedAmount N..20 нет Сумма, захолдированная на карте (используется только при
двухстадийных платежах).
03 и выше.
depositedAmount N..20 нет Сумма, подтверждённая для списания с карты. 03 и выше.
refundedAmount N..20 нет Сумма возврата. 03 и выше.
paymentState A..10 нет Состояние заказа. 03 и выше.
feeAmount N..20 нет Сумма комиссии. 11 и выше.
Элемент состоит из параметров:bankInfo
bankName AN..200 нет Наименование банка-эмитента. 03 и выше.
bankCountryCode AN..4 нет Код страны банка-эмитента. 03 и выше.
bankCountryName AN..160 нет Наименование страны банка-эмитента на языке, переданном в
параметре language в запросе, или на языке пользователя, вызвавшего
метод, если язык в запросе не указан.
03 и выше.
Элемент payerData состоит из параметров:
email ANS * нет Email-адрес плательщика. 13 и выше.
Пример запроса:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:mer="http://engine.paymentgate.ru/webservices/merchant">
<soapenv:Header/>
<soapenv:Body>
<mer:getOrderStatusExtended>
<order orderId="942e8534-ac73-4e3c-96c6-f6cc448018f7"
language="en">
<!--Optional:-->
<merchantOrderNumber> </merchantOrderNumber>
</order>
</mer:getOrderStatusExtended>
</soapenv:Body>
</soapenv:Envelope>
Пример ответа:
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<ns1:getOrderStatusExtendedResponse
xmlns:ns1="http://engine.paymentgate.ru/webservices/merchant">
<return orderNumber="0s7a84sPe49Hdsddd0134567a0" orderStatus="2"
actionCode="0" actionCodeDescription="Request processed successfully"
amount="33000" currency="643" date="2013-11-13T16:51:02.785+04:00"
orderDescription=" " errorCode="0" errorMessage="Success">
<attributes name="mdOrder"
value="942e8534-ac73-4e3c-96c6-f6cc448018f7"/>
<cardAuthInfo maskedPan="411111**1111" expiration="201512"
cardholderName="Ivan" approvalCode="123456"/>
<authDateTime>2013-11-13T16:51:02.898+04:00</authDateTime>
<terminalId>111113</terminalId>
<authRefNum>111111111111</authRefNum>
<paymentAmountInfo paymentState="DEPOSITED"
approvedAmount="33000" depositedAmount="33000" refundedAmount="0"/>
<bankInfo bankName="TEST CARD" bankCountryCode="RU"
bankCountryName="Russian Federation"/>
</return>
</ns1:getOrderStatusExtendedResponse>
</soap:Body>
</soap:Envelope>
7.1.5. Запрос проверки вовлечённости карты в 3DS
Для проверки вовлечённости карты в 3DS используется запрос . verifyEnrollment
Параметры запроса:
Название Тип Обязательно Описание
pan N12...19 да Номер карты
Параметры ответа:
Название Тип Обязательно Описание
errorCode N3 нет Код ошибки.
errorMessage AN..512 нет Описание ошибки.
isEnrolled A1 нет Признак вовлечённости карты в 3DS. Возможные значения: Y, N, U.
emitterName AN..160 нет Наименование банка-эмитента.
emitterCountryCode AN..4 нет Код страны банка-эмитента.
Коды ошибок (поле ErrorCode):
Значение Описание
0 Обработка запроса прошла без системных ошибок
1 Не указан номер карты
1 Номер карты должен быть числом, содержащим от 13 до 19 цифр
5 Доступ запрещён
5 Пользователь должен сменить свой пароль
6 По заданному номеру карты информация не найдена
7 Произошла системная ошибка
Пример запроса:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:mer="http://engine.paymentgate.ru/webservices/merchant">
<soapenv:Header/>
<soapenv:Body>
<mer:verifyEnrollment>
<pan>4111111111111111</pan>
</mer:verifyEnrollment>
</soapenv:Body>
</soapenv:Envelope>
Пример ответа:
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<ns1:verifyEnrollmentResponse
xmlns:ns1="http://engine.paymentgate.ru/webservices/merchant">
<return isEnrolled="Y" emitterName="TEST CARD"
emitterCountryCode="RU" errorCode="0"/>
</ns1:verifyEnrollmentResponse>
</soap:Body>
</soap:Envelope>
7.1.6. Запрос добавления дополнительных параметров к заказу
Для добавления к заказу новых дополнительных параметров используется метод .addParams
Если в заказе уже существует дополнительный параметр, то при добавлении параметра с тем же именем в заказе сохранится
последнее переданное значение.
Параметры запроса:
Название Тип Обязательно Описание
orderId ANS36 да Номер заказа в платежной системе. Уникален в пределах системы.
Блок дополнительных параметров - params:
name AN..20 да Название дополнительного параметра
value AN..1024 да Значение дополнительного параметра
Параметры ответа
Название Тип Обязательно Описание
errorCode N3 да Код ошибки.
errorMessage AN..512 нет Описание ошибки. Отсутствует при успешном выполнении запроса.
Коды ошибок (поле ErrorCode):
Значение Описание
0Обработка запроса прошла без системных ошибок
5Доступ запрещён
5Пользователь должен сменить свой пароль
6 Не указан orderId
6 Не верный формат номера заказа
7 Произошла системная ошибка
Пример запроса:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:mer="http://engine.paymentgate.ru/webservices/merchant">
<soapenv:Header/>
<soapenv:Body>
<mer:addParams>
<request orderId="02988563-0cc4-4109-84ed-15781f0d718e">
<!--Zero or more repetitions:-->
<params name="Param1" value="Param1"/>
<params name="Param2" value="Param2"/>
</request>
</mer:addParams>
</soapenv:Body>
</soapenv:Envelope>
Пример ответа:
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<ns1:addParamsResponse
xmlns:ns1="http://engine.paymentgate.ru/webservices/merchant">
<return errorCode="0"/>
</ns1:addParamsResponse>
</soap:Body>
</soap:Envelope>
7.2. Запросы, используемые при двухстадийной оплате
7.2.1. Запрос регистрации заказа с предавторизацией
Для предавторизации заказа в платёжном шлюзе используется метод .registerOrderPreAuth
Для предавторизации заказа в платёжном шлюзе используется метод .registerOrderPreAuth
Параметры запроса:
Название Тип Обязательно Описание
merchantOrderNumber ANS..32 да Номер (идентификатор) заказа в системе магазина, уникален для каждого магазина в пределах
системы. Если номер заказа генерируется на стороне платёжного шлюза, этот параметр
передавать необязательно.
description ANS..512 нет Описание заказа в свободной форме. В процессинг банка для включения в финансовую
отчётность продавца передаются только первые 24 символа этого поля.
amount N..20 да Сумма платежа в копейках (или центах)
currency N3 нет Код валюты платежа ISO 4217. Единственное допустимое значение - 643.
language A2 нет Язык в кодировке ISO 639-1. Если не указан, будет использован язык, указанный в настройках
магазина как язык по умолчанию.
pageView ANS..20 нет По значению данного параметра определяется, какие страницы платёжного интерфейса должны
загружаться для клиента. Возможные значения:
DESKTOP – для загрузки страниц, верстка которых предназначена для отображения на
экранах ПК (в архиве страниц платёжного интерфейса будет осуществляться поиск страниц с
названиями и );payment_<locale>.html ocale>.htmlerrors_<l
MOBILE – для загрузки страниц, верстка которых предназначена для отображения на экранах
мобильных устройств (в архиве страниц платёжного интерфейса будет осуществляться
поиск страниц с названиями и mobile_payment_<locale>.html ocalemobile_errors_<l
);>.html
Если магазин создал страницы платёжного интерфейса, добавив в название файлов страниц
произвольные префиксы, передайте значение нужного префикса в параметре дляpageView
загрузки соответствующей страницы. Например, при передаче значения в архивеiphone
страниц платёжного интерфейса будет осуществляться поиск страниц с названиями iphone
и ._payment_<locale>.html iphone_error_<locale>.html
Где:
locale – я . Например, для русского или длязык страницы в кодировке ISO 639-1 ru en
английского.
Если параметр отсутствует, либо не соответствует формату, то по умолчанию считается pageVie
.w=DESKTOP
sessionTimeoutSecs N...9 нет Продолжительность жизни заказа в секундах.
В случае если параметр не задан, будет использовано значение, указанное в настройках
мерчанта или время по умолчанию (1200 секунд = 20 минут).
Если в запросе присутствует параметр expirationDate, то значение параметра sessionTimeo
utSecs не учитывается.
bindingId AN..255 no Идентификатор связки, созданной ранее. Может использоваться, только если у магазина есть
разрешение на работу со связками. Если этот параметр передаётся в данном запросе, то это
означает:
1. Данный заказ может быть оплачен только с помощью связки;
2. Плательщик будет перенаправлен на платёжную страницу, где требуется только ввод
CVC.
expirationDate ANS нет Дата и время окончания жизни заказа. Формат: .yyyy-MM-dd'T'HH:mm:ss
Если этот параметр не передаётся в запросе, то для определения времени окончания жизни
заказа используется .sessionTimeoutSecs
returnUrl AN..512 да Адрес, на который требуется перенаправить пользователя в случае успешной оплаты. Адрес
должен быть указан полностью, включая используемый протокол (например, вместо https://test.ru t
). В противном случае пользователь будет перенаправлен по адресу следующего вида: est.ru http:/
./<адрес_платёжного_шлюза>/<адрес_продавца>
failUrl AN..512 нет Адрес, на который перенаправить пользователя в случае неуспешной оплаты. Адрестребуется
должен быть указан полностью, включая используемый протокол (например, вместо https://test.ru t
). В противном случае пользователь будет перенаправлен по адресу следующего вида: est.ru http:/
./<адрес_платёжного_шлюза>/<адрес_продавца>
params нет Тэг с атрибутами для передачи дополнительных параметров мерчанта.
Поля дополнительной информации для последующего хранения. Для передачи N параметров, в
запросе должно находиться N тэгов , где атрибут содержит название, а атрибут params name valu
содержит значение:e
Название Тип Обязательно Описание
name AN..20 да Название дополнительного параметра
value AN..1024 да Значение дополнительного параметра
Данные поля могут быть переданы в процессинг банка для последующего отображения в
реестрах.*
Включение данного функционала возможно по согласованию с банком в период интеграции.
Если для продавца настроена отправка покупателю, адрес электронной почтыуведомлений
покупателя должен передаваться в этом тэге в параметре с именем .email
clientId ANS..255 нет Номер (идентификатор) клиента в системе магазина. Используется для реализации функционала
связок. Может присутствовать, если магазину разрешено создание связок.
merchantLogin AN..255 нет Чтобы зарегистрировать заказ от имени дочернего мерчанта, укажите его логин в этом параметре.
features ANS..255 нет Контейнер для параметра , в котором можно указать следующие значения.feature
AUTO_PAYMENT - Если запрос на регистрацию заказа инициирует проведение автоплатежей.
FORCE_TDS - Принудительное проведение платежа с использованием 3-D Secure. Если карта не
поддерживает 3-D Secure, транзакция не пройдёт.
FORCE_SSL - Принудительное проведение платежа через SSL (без использования 3-D Secure).
FORCE_FULL_TDS - После проведения аутентификации с помощью 3-D Secure статус PaRes
должен быть только , что гарантирует успешную аутентификацию пользователя. В противномY
случае транзакция не пройдёт.
Ниже представлен пример использования.
<features>
<feature>AUTO_PAYMENT</feature>
</features>
* По умолчанию в процессинг банка передаются поля:
merchantOrderNumber – номер заказа в системе магазина;
description – описание заказа (не более 24 символов, запрещены к использованию %, +, конец строки \r и
перенос строки \n).
Если в заказе передать дополнительный параметр с именем , то именно его значение будет передано вmerchantOrderId
процессинг в качестве номера заказа (вместо значения поля ).orderNumber
Параметры ответа:
Название Тип Обязательно Описание
Указание этого параметра при платежах по связке необходимо - в противном случае
платёж будет неуспешен.
orderId ANS36 нет Номер заказа в платежной системе. Уникален в пределах системы. Отсутствует, если регистрация заказа на
удалась по причине ошибки, детализированной в .errorCode
formUrl AN..512 нет URL платежной формы, на который надо перенаправить браузер клиента. Не возвращается, если
регистрация заказа не удалась по причине ошибки, детализированной в .errorCode
errorCode N3 нет Код ошибки.
errorMessage AN..512 нет Описание ошибки на языке, переданном в параметре в запросе. language
Коды ошибок (поле ):errorCode
Значение Описание
0Обработка запроса прошла без системных ошибок
1 Неверный номер заказа
1 Заказ с таким номером уже обработан
3 Неизвестная валюта
4 Отсутствует сумма
4 Номер заказа не может быть пуст
4 URL возврата не может быть пуст
5 Платежи с предавторизацией не разрешены
5 Неверно указано значение одного из параметров
5 Доступ запрещён
5 Пользователь должен сменить свой пароль
7 Системная ошибка
13 Мерчант не имеет привилегии выполнять проверочные платежи
14 Features указаны некорректно
Пример запроса:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:mer="http://engine.paymentgate.ru/webservices/merchant">
<soapenv:Header/>
<soapenv:Body>
<mer:registerOrderPreAuth>
<order merchantOrderNumber="asuaakdfadsfasdfasdd5" description="
" amount="10000" currency=" " language="ru" pageView="DESKTOP"
sessionTimeoutSecs=" " bindingId=" " expirationDate="2014-09-08T14:14:14">
<returnUrl>https://server/applicaton_context/finish.html</returnUrl>
<params name="param1" value="paramValue1"/>
<params name="param2" value="paramValue2"/>
<clientId>7777</clientId>
<merchantLogin> </merchantLogin>
<features>
<feature>AUTO_PAYMENT</feature>
</features>
</order>
</mer:registerOrderPreAuth>
</soapenv:Body>
</soapenv:Envelope>
Пример ответа:
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<ns1:registerOrderPreAuthResponse
xmlns:ns1="http://engine.paymentgate.ru/webservices/merchant">
<return orderId="5e5dc6bd-dee3-4c96-849a-09f3f575f4b6"
errorCode="0" errorMessage="">
<formUrl>
https://server/merchants/rbs/payment_ru.html?mdOrder=5e5dc6bd-dee3-4c96-84
9a-09f3f575f4b6 </formUrl>
</return>
</ns1:registerOrderPreAuthResponse>
</soap:Body>
</soap:Envelope>
7.2.2. Запрос завершения оплаты заказа
Для запроса списания ранее предавторизованного заказа используется запрос . Данную операцию можно осуществлять,depositOrder
если есть соответствующие права всистеме.
Параметры запроса:
Название Тип Обязательно Описание
orderId ANS36 да Номер заказа в платежной системе. Уникален в пределах системы.
depositAmount N..5 да Сумма списания в валюте заказа. Может быть меньше или равна сумме преавторизации. Не может быть
меньше 1 рубля.
language A2 нет Язык в кодировке ISO 639-1. Если не указан, считается, что язык – русский. Сообщение ошибке будет
возвращено именно на этом языке.
Параметры ответа:
Название Тип Обязательно Описание
errorCode N3 нет Код ошибки.
errorMessage AN..512 нет Описание ошибки на языке, переданном в параметре Language в запросе.
Коды ошибок (поле errorCode):
Значение Описание
0Обработка запроса прошла без системных ошибок
5 Сумма депозита превышает захолдированную сумму
5 Сумма депозита должна быть больше нуля или не менее одного рубля
5 Доступ запрещён
5 Пользователь должен сменить свой пароль
6 Неверный номер заказа
6 [orderId] не задан
7 Платёж должен быть в корректном состоянии
7 Системная ошибка
Пример запроса:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:mer="http://engine.paymentgate.ru/webservices/merchant">
<soapenv:Header/>
<soapenv:Body>
<mer:depositOrder>
<order language="ru"
orderId="4302d369-a5e8-4432-a5e5-42acfab52c86" depositAmount="30000">
<!-- Zero or more repetitions: -->
<params name="param1" value="paramValue1"/>
</order>
</mer:depositOrder>
</soapenv:Body>
</soapenv:Envelope>
Пример ответа:
Если не указать параметр "amount", завершение произойдёт на всю пред авторизованную сумму.
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<ns1:depositOrderResponse
xmlns:ns1="http://engine.paymentgate.ru/webservices/merchant">
<return errorCode="6" errorMessage=" "/>
</ns1:depositOrderResponse>
</soap:Body>
</soap:Envelope>
7.2.3. Запрос отмены оплаты заказа
Для запроса отмены заказа используется запрос . Функция отмены доступна в течение ограниченного времени послеreverseOrder
оплаты, точные сроки необходимо уточнять в Банке.
Операция отмены оплаты может быть совершена только один раз. Если она закончится ошибкой, то повторная операция отмены
платежа не пройдет.
Данная функция доступна магазинам по согласованию с Банком. Для выполнения операции отмены пользователь должен обладать
соответствующими правами.
Параметры запроса:
Название Тип Обязательно Описание
orderId ANS36 да Номер заказа в платежной системе. Уникален в пределах системы.
language A2 нет Язык в кодировке ISO 639-1. Если не указан, считается, что язык – русский. Сообщение ошибке будет
возвращено именно на этом языке.
Параметры ответа:
Название Тип Обязательно Описание
errorCode N3 нет Код ошибки.
errorMessage AN..512 нет Описание ошибки на языке, переданном в параметре Language в запросе.
Коды ошибок (поле errorCode):
Значение Описание
0Обработка запроса прошла без системных ошибок
5 Доступ запрещён
5 Пользователь должен изменить свой пароль
5 [orderId] не задан
6 Неверный номер заказа
7 Недопустимая операция для текущего состояния заказа
7 Системная ошибка
Пример запроса:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:mer="http://engine.paymentgate.ru/webservices/merchant">
<soapenv:Header/>
<soapenv:Body>
<mer:reverseOrder>
<order language="ru"
orderId="f88a2bbf-2021-4ccc-8783-8a13068a89f9">
<!-- Zero or more repetitions: -->
<params name="param1" value="paramValue1"/>
</order>
</mer:reverseOrder>
</soapenv:Body>
</soapenv:Envelope>
Пример ответа:
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<ns1:reverseOrderResponse
xmlns:ns1="http://engine.paymentgate.ru/webservices/merchant">
<return errorCode="7" errorMessage=" "/>
</ns1:reverseOrderResponse>
</soap:Body>
</soap:Envelope>
7.2.4. Запрос возврата средств оплаты заказа
Для возврата средств используется запрос .refundOrder
По этому запросу средства по указанному заказу будут возвращены плательщику. Запрос закончится ошибкой в случае, если средства
по этому заказу не были списаны. Система позволяет возвращать средства более одного раза, но в общей сложности не более
первоначальной суммы списания.
Для выполнения операции возврата необходимо наличие соответствующих права в системе.
Параметры запроса:
Название Тип Обязательно Описание
orderId ANS36 да Номер заказа в платежной системе. Уникален в пределах системы.
refundAmount N..5 да Сумма возврата в валюте заказа. Может быть меньше или равна остатку в заказе.
language A2 нет Язык в кодировке ISO 639-1. Если не указан, считается, что язык – русский. Сообщение ошибке будет
возвращено именно на этом языке.
Параметры ответа:
Название Тип Обязательно Описание
errorCode N3 нет Код ошибки.
errorMessage AN..512 нет Описание ошибки на языке, переданном в параметре Language в запросе.
Коды ошибок (поле errorCode):
Значение Описание
0Обработка запроса прошла без системных ошибок
5 Доступ запрещён
5 Пользователь должен изменить свой пароль
5 [orderId] не задан
5 Неверная сумма
6 Неверный номер заказа
7 Платёж должен быть в корректном состоянии
7 Сумма возврата превышает сумму списания
7 Системная ошибка
Пример запроса:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:mer="http://engine.paymentgate.ru/webservices/merchant">
<soapenv:Header/>
<soapenv:Body>
<mer:refundOrder>
<order language="ru"
orderId="4302d369-a5e8-4432-a5e5-42acfab52c86" refundAmount="20000">
<!-- Zero or more repetitions: -->
<params name=" " value=" "/>
</order>
</mer:refundOrder>
</soapenv:Body>
</soapenv:Envelope>
Пример ответа:
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<ns1:refundOrderResponse
xmlns:ns1="http://engine.paymentgate.ru/webservices/merchant">
<return errorCode="7" errorMessage=" "/>
</ns1:refundOrderResponse>
</soap:Body>
</soap:Envelope>
7.2.5. Расширенный запрос состояния заказа
Для запроса состояния зарегистрированного заказа используется запрос . getOrderStatusExtended
Параметры запроса:
Название Тип Обязательно Описание
orderId ANS36 да* Номер заказа в платёжной системе. Уникален в пределах системы
language A2 нет Язык в кодировке ISO 639-1. Если не указан, считается, что язык – русский. Сообщение ошибке
будет возвращено именно на этом языке.
merchantOrderNumber ANS..32 да* Номер (идентификатор) заказа в системе магазина.
* В запросе необходимо передать или параметр , или . Если в запросе передаются оба параметра,orderId merchantOrderNumber
приоритет выше.orderId
Существует несколько наборов параметров ответа. Какие именно наборы параметров будут возвращены, завит от версии getOrderSta
, указанной в настройках продавца.tusExtended
Название Тип Обязательно Описание Версия
getOrderStatusExtended
orderNumber AN..32 да Номер (идентификатор) заказа в системе магазина. Все версии.
orderStatus N2 нет По значению этого параметра определяется состояние заказа в
платёжной системе. Список возможных значений приведён в списке
ниже. Отсутствует, если заказ не был найден.
0 - Заказ зарегистрирован, но не оплачен;
1 - Предавторизованная сумма захолдирована (для двухстадийных
платежей);
2 - Проведена полная авторизация суммы заказа;
3 - Авторизация отменена;
4 - По транзакции была проведена операция возврата;
5 - Инициирована авторизация через ACS банка-эмитента;
6 - Авторизация отклонена.
Все версии.
actionCode N3 да Код ответа. Все версии.
actionCodeDescription AN..512 да Расшифровка кода ответа на языке, переданном в параметре Language
в запросе.
Все версии.
errorCode N3 нет Код ошибки. Возможны следующие варианты.
0 - Обработка запроса прошла без системных ошибок;
1 - Ожидается [orderId] или [orderNumber];
5 - Доступ запрещён;
5 - Пользователь должен сменить свой пароль;
6 - Заказ не найден;
7 - Системная ошибка.
Все версии.
errorMessage AN..512 нет Описание ошибки на языке, переданном в параметре Language в
запросе.
Все версии.
amount N..20 да Сумма платежа в копейках (или центах) Все версии.
currency N3 нет Код валюты платежа ISO 4217. Единственное допустимое значение -
643.
Все версии.
date ANS да Дата и время регистрации заказа, выраженные в количестве
миллисекунд, прошедших с 1 января 1970 года.
Все версии.
orderDescription AN..512 нет Описание заказа, переданное при его регистрации Все версии.
ip AN..20 да IP-адрес покупателя. Все версии.
Элемент – присутствует в ответе, если в заказе содержатся дополнительные параметры продавца. Каждый дополнительныйmerchantOrderParams
параметр заказа представлен в отдельном элементе .merchantOrderParams
name AN..20 нет Название дополнительного параметра Все версии.
value AN..1024 нет Значение дополнительного параметра Все версии.
Элемент – в элементе лежит структура, состоящая из списка элемента и следующих параметеров:cardAuthInfo secureAuthInfo
maskedPan N..19 нет Маскированный номер карты, которая использовалась для оплаты.
Указан только после оплаты заказа.
Все версии.
expiration N6 нет Срок истечения действия карты в формате YYYYMM. Указан только
после оплаты заказа.
Все версии.
cardholderName A..64 нет Имя держателя карты. Указан только после оплаты заказа. Все версии.
approvalCode AN6 нет Код авторизации платежа. Поле фиксированной длины (6 символов),
может содержать цифры и латинские буквы. Указан только после
оплаты заказа.
Все версии.
chargeback A..5 нет Были ли средства принудительно возвращены покупателю банком.
Возможны следующие значения.
true (истина);
false (ложь).
06 и выше.
paymentSystem N..10 да Наименование платёжной системы. Доступны следующие варианты.
VISA;
MASTERCARD;
AMEX;
JCB;
CUP;
MIR.
08 и выше.
product AN..255 да Дополнительные сведения о корпоративных картах. Эти сведения
заполняются службой технической поддержки в консоли управления.
Если такие сведения отсутствуют, возвращается пустое значение.
08 и выше.
paymentWay AS..14 да Способ совершения платежа (платёж в с вводом карточных данных,
оплата по связке и т. п.).
09 и выше.
Элемент (элемент состоит из элемента и элемента , являющимся списком параметров и ):secureAuthInfo eci threeDSInfo cavv xid
eci N..4 нет Электронный коммерческий индикатор. Указан только после оплаты
заказа и в случае соответствующего разрешения.
Все версии.
cavv ANS..200 нет Значение проверки аутенфикации владельца карты. Указан только
после оплаты заказа и в случае соответствующего разрешения.
Все версии.
xid ANS..80 нет Электронный коммерческий идентификатор транзакции. Указан только
после оплаты заказа и в случае соответствующего разрешения.
Все версии.
Элемент состоит из параметров:bindingInfo
clientId ANS..255 нет Номер (идентификатор) клиента в системе магазина, переданный при
регистрации заказа. Присутствует только если магазину разрешено
создание связок.
Все версии.
bindingId AN..255 нет Идентификатор связки созданной при оплате заказа или
использованной для оплаты. Присутствует только если магазину
разрешено создание связок.
Все версии.
authDateTime ANS нет Дата/время авторизации. 02 и выше.
authRefNum AN..24 нет Учётный номер авторизации платежа, который присваивается при
регистрации платежа.
02 и выше.
terminalId AN..10 нет Id терминала. 02 и выше.
Элемент состоит из параметров:paymentAmountInfo
approvedAmount N..20 нет Сумма, захолдированная на карте (используется только при
двухстадийных платежах).
03 и выше.
depositedAmount N..20 нет Сумма, подтверждённая для списания с карты. 03 и выше.
refundedAmount N..20 нет Сумма возврата. 03 и выше.
paymentState A..10 нет Состояние заказа. 03 и выше.
feeAmount N..20 нет Сумма комиссии. 11 и выше.
Элемент состоит из параметров:bankInfo
bankName AN..200 нет Наименование банка-эмитента. 03 и выше.
bankCountryCode AN..4 нет Код страны банка-эмитента. 03 и выше.
bankCountryName AN..160 нет Наименование страны банка-эмитента на языке, переданном в
параметре language в запросе, или на языке пользователя, вызвавшего
метод, если язык в запросе не указан.
03 и выше.
Элемент payerData состоит из параметров:
email ANS * нет Email-адрес плательщика. 13 и выше.
Пример запроса:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:mer="http://engine.paymentgate.ru/webservices/merchant">
<soapenv:Header/>
<soapenv:Body>
<mer:getOrderStatusExtended>
<order orderId="942e8534-ac73-4e3c-96c6-f6cc448018f7"
language="en">
<!--Optional:-->
<merchantOrderNumber> </merchantOrderNumber>
</order>
</mer:getOrderStatusExtended>
</soapenv:Body>
</soapenv:Envelope>
Пример ответа:
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<ns1:getOrderStatusExtendedResponse
xmlns:ns1="http://engine.paymentgate.ru/webservices/merchant">
<return orderNumber="0s7a84sPe49Hdsddd0134567a0" orderStatus="2"
actionCode="0" actionCodeDescription="Request processed successfully"
amount="33000" currency="643" date="2013-11-13T16:51:02.785+04:00"
orderDescription=" " errorCode="0" errorMessage="Success">
<attributes name="mdOrder"
value="942e8534-ac73-4e3c-96c6-f6cc448018f7"/>
<cardAuthInfo maskedPan="411111**1111" expiration="201512"
cardholderName="Ivan" approvalCode="123456"/>
<authDateTime>2013-11-13T16:51:02.898+04:00</authDateTime>
<terminalId>111113</terminalId>
<authRefNum>111111111111</authRefNum>
<paymentAmountInfo paymentState="DEPOSITED"
approvedAmount="33000" depositedAmount="33000" refundedAmount="0"/>
<bankInfo bankName="TEST CARD" bankCountryCode="RU"
bankCountryName="Russian Federation"/>
</return>
</ns1:getOrderStatusExtendedResponse>
</soap:Body>
</soap:Envelope>
7.2.6. Запрос проверки вовлечённости карты в 3DS
Для проверки вовлечённости карты в 3DS используется запрос . verifyEnrollment
Параметры запроса:
Название Тип Обязательно Описание
pan N12...19 да Номер карты
Параметры ответа:
Название Тип Обязательно Описание
errorCode N3 нет Код ошибки.
errorMessage AN..512 нет Описание ошибки.
isEnrolled A1 нет Признак вовлечённости карты в 3DS. Возможные значения: Y, N, U.
emitterName AN..160 нет Наименование банка-эмитента.
emitterCountryCode AN..4 нет Код страны банка-эмитента.
Коды ошибок (поле ):errorCode
Значение Описание
0 Обработка запроса прошла без системных ошибок
1 Не указан номер карты
1Номер карты должен быть числом, содержащим от 13 до 19 цифр
5 Доступ запрещён
5Пользователь должен сменить свой пароль
6 По заданному номеру карты информация не найдена.
7 Произошла системная ошибка
Пример запроса:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:mer="http://engine.paymentgate.ru/webservices/merchant">
<soapenv:Header/>
<soapenv:Body>
<mer:verifyEnrollment>
<pan>4111111111111111</pan>
</mer:verifyEnrollment>
</soapenv:Body>
</soapenv:Envelope>
Пример ответа:
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<ns1:verifyEnrollmentResponse
xmlns:ns1="http://engine.paymentgate.ru/webservices/merchant">
<return isEnrolled="Y" emitterName="TEST CARD"
emitterCountryCode="RU" errorCode="0"/>
</ns1:verifyEnrollmentResponse>
</soap:Body>
</soap:Envelope>
7.2.7. Запрос добавления дополнительных параметров к заказу
Для добавления к заказу новых дополнительных параметров используется метод .addParams
Если в заказе уже существует дополнительный параметр, то при добавлении параметра с тем же именем в заказе сохранится
последнее переданное значение.
Параметры запроса:
Название Тип Обязательно Описание
orderId ANS36 да Номер заказа в платежной системе. Уникален в пределах системы.
Блок дополнительных параметров - params:
name AN..20 да Название дополнительного параметра
value AN..1024 да Значение дополнительного параметра
Параметры ответа
Название Тип Обязательно Описание
errorCode N3 да Код ошибки.
errorMessage AN..512 нет Описание ошибки. Отсутствует при успешном выполнении запроса.
Коды ошибок (поле ErrorCode):
Значение Описание
0Обработка запроса прошла без системных ошибок
5Доступ запрещён
5Пользователь должен сменить свой пароль
6 Не указан orderId
6 Не верный формат номера заказа
7 Произошла системная ошибка
Пример запроса:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:mer="http://engine.paymentgate.ru/webservices/merchant">
<soapenv:Header/>
<soapenv:Body>
<mer:addParams>
<request orderId="02988563-0cc4-4109-84ed-15781f0d718e">
<!--Zero or more repetitions:-->
<params name="Param1" value="Param1"/>
<params name="Param2" value="Param2"/>
</request>
</mer:addParams>
</soapenv:Body>
</soapenv:Envelope>
Пример ответа:
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<ns1:addParamsResponse
xmlns:ns1="http://engine.paymentgate.ru/webservices/merchant">
<return errorCode="0"/>
</ns1:addParamsResponse>
</soap:Body>
</soap:Envelope>
8. Интерфейс REST
Каждый запрос представляет собой HTTP-обращения на определённые URL-адреса (см. раздел ). ОбращенияКоординаты подключения
могут быть реализованы методами GET и POST, при этом значения должны быть совместимы с URL (т.е. URL encoded).
Результат обработки запроса возвращается в виде JSON объекта. Например:
{"errorCode":"12","errorMessage":"Empty amount"}
Для авторизации обращения магазина к системе платежного шлюза, в любом запросе со стороны магазина должны быть приведены
имя и пароль магазина, которые представитель магазина ввел при регистрации магазина в системе. Значения имени и пароля
передаются в следующих параметрах:
Название Тип Обязательность Описание
userName AN..30 да Логин магазина, полученный при подключении
password AN..30 да Пароль магазина, полученный при подключении
Для регистрации заказа (обычной регистрации и регистрации с предавторизацией) также можно использовать открытый токен -
В зависимости от выбранной схемы оплаты (одностадийная или двухстадийная) используется различный набор запросов. Ниже
описаны запросы для каждой из схем.
Все текстовые поля должны иметь кодировку Юникод (UTF-8).
Спец-символы в REST запросе должны быть экранированы в соответствии с URL-кодом. Таблица символов представлена здесь: http://w
. Например, пароль должен передаваться в виде .eb-developer.name/urlcode/ "qwe?rt%y" "qwe%0Frt%25y"
Если код ошибки , запрос был обработан Платежным шлюзом без системных ошибок. При этом не показываетerrorCode=0 errorCode
статус заказа. Для получения статуса заказа следует использовать запрос .getOrderStatusExtended
8.1. Особенности тестирования REST-запросов в интернет-браузере
Если одновременно с тестированием REST-запросов в том же интернет-браузере осуществлять работу с административной консолью,
то после выполнения любого REST-запроса при переходе на вкладку браузера с ЛК любое действие в консоли становится причиной
ошибки. Чтобы восстановить корректную работу административной консоли:
В некоторых случаях достаточно выполнить и заново пройти аутентификацию; выход из ЛК
Иногда необходимо очистить cookie-файлы или дождаться завершения сессии.
Подобной ситуации можно избежать одним из следующих способов:
Используйте для REST-запросов режим инкогнито, а работу в административной консоли проводите в окне браузера в обычном
режиме;
Для тестирования REST-запросов и работы в ЛК используйте разные интернет-браузеры.
8.2. Запросы, используемые при одностадийной оплате
8.2.1. Запрос регистрации заказа
Для регистрации заказа используется запрос (см. раздел "Координаты подключения").register.do
Параметры запроса:
Название Тип Обязательно Описание
userName AN..30 нет (нужно
указать либо
пару логин и
пароль, либо
токен)
Логин магазина, полученный при подключении. Если вместо аутентификации по логину и паролю
используется открытый токен (параметр token), параметр передавать не нужно.userName
password AN..30 нет (нужно
указать либо
пару логин и
пароль, либо
токен)
Пароль магазина, полученный при подключении. Если для аутентификации при регистрации вместо
логина и пароля используется открытый токен (параметр token), параметр передавать неpassword
нужно.
token AN..30 нет (нужно
указать либо
пару логин и
пароль, либо
токен)
Открытый ключ, который можно использовать для регистрации заказа. Если для аутентификации
при регистрации заказа используются логин и пароль, параметр передавать не нужно.token
Для регистрации заказа (обычной регистрации и регистрации с предавторизацией) также можно использовать открытый токен -
его значение можно получить у технической поддержки. Открытый токен передаётся в следующем параметре.
Название Тип Обязательность Описание
token AN..30 да, если не используется имя
пользователя и пароль
Значение, которое можно использовать вместо логина и пароля при
регистрации заказа.
Внимание! При использовании открытого токена логин и пароль не должны передаваться.
orderNumber AN..32 да Номер (идентификатор) заказа в системе магазина, уникален для каждого магазина в пределах
системы. Если номер заказа генерируется на стороне платёжного шлюза, этот параметр передавать
необязательно.
amount N..20 да Сумма платежа в копейках (или центах)
currency N3 нет Код валюты платежа ISO 4217. Единственное допустимое значение - 643.
returnUrl AN..512 да Адрес, на который требуется перенаправить пользователя в случае успешной оплаты. Адрес
должен быть указан полностью, включая используемый протокол (например, вместо https://test.ru tes
). В противном случае пользователь будет перенаправлен по адресу следующего вида: t.ru http://<ад
.рес_платёжного_шлюза>/<адрес_продавца>
failUrl AN..512 нет Адрес, на который требуется перенаправить пользователя в случае неуспешной оплаты. Адрес
должен быть указан полностью, включая используемый протокол (например, вместо https://test.ru tes
). В противном случае пользователь будет перенаправлен по адресу следующего вида: t.ru http://<ад
.рес_платёжного_шлюза>/<адрес_продавца>
description ANS..512 нет Описание заказа в свободной форме. В процессинг банка для включения в финансовую отчётность
продавца передаются только первые 24 символа этого поля.
language A2 нет Язык в кодировке ISO 639-1. Если не указан, будет использован язык, указанный в настройках
магазина как язык по умолчанию (default language)
pageView ANS..20 нет По значению данного параметра определяется, какие страницы платёжного интерфейса должны
загружаться для клиента. Возможные значения:
DESKTOP – для загрузки страниц, верстка которых предназначена для отображения на экранах
ПК (в архиве страниц платёжного интерфейса будет осуществляться поиск страниц с
названиями и );payment_<locale>.html ocale>.htmlerrors_<l
MOBILE – для загрузки страниц, верстка которых предназначена для отображения на экранах
мобильных устройств (в архиве страниц платёжного интерфейса будет осуществляться поиск
страниц с названиями и mobile_payment_<locale>.html ocale>.htmlmobile_errors_<l
);
Если магазин создал страницы платёжного интерфейса, добавив в название файлов страниц
произвольные префиксы, передайте значение нужного префикса в параметре дляpageView
загрузки соответствующей страницы. Например, при передаче значения в архивеiphone
страниц платёжного интерфейса будет осуществляться поиск страниц с названиями iphone_p
и .ayment_<locale>.html iphone_error_<locale>.html
Где:
locale – я . Например, для русского или длязык страницы в кодировке ISO 639-1 ru en
английского.
Если параметр отсутствует, либо не соответствует формату, то по умолчанию считается pageView=
.DESKTOP
clientId ANS..255 нет Номер (идентификатор) клиента в системе магазина. Используется для реализации функционала
связок. Может присутствовать, если магазину разрешено создание связок.
merchantLogin AN..255 нет Чтобы зарегистрировать заказ от имени дочернего мерчанта, укажите его логин в этом параметре.
jsonParams AN..1024 нет Блок для передачи дополнительных параметров мерчанта. Поля дополнительной информации для
последующего хранения, передаются в виде:
{"<name1>":"<value1>",...,"<nameN>":"<valueN>"},
Данные поля могут быть переданы в процессинг банка для последующего отображения в реестрах.*
Включение данного функционала возможно по согласованию с банком в период интеграции.
Если для продавца настроена отправка покупателю, адрес электронной почтыуведомлений
покупателя должен передаваться в этом блоке в параметре с именем .email
sessionTimeoutSecs N...9 нет Продолжительность жизни заказа в секундах.
В случае если параметр не задан, будет использовано значение, указанное в настройках мерчанта
или время по умолчанию (1200 секунд = 20 минут).
Если в запросе присутствует параметр expirationDate, то значение параметра sessionTimeout
Secs не учитывается.
Указание этого параметра при платежах по связке необходимо - в противном случае
платёж будет неуспешен.
expirationDate ANS нет Дата и время окончания жизни заказа. Формат: .yyyy-MM-ddTHH:mm:ss
Если этот параметр не передаётся в запросе, то для определения времени окончания жизни заказа
используется .sessionTimeoutSecs
bindingId AN..255 нет Идентификатор связки, созданной ранее. Может использоваться, только если у магазина есть
разрешение на работу со связками. Если этот параметр передаётся в данном запросе, то это
означает:
1. Данный заказ может быть оплачен только с помощью связки;
2. Плательщик будет перенаправлен на платёжную страницу, где требуется только ввод CVC.
features ANS..255 нет Возможно использование следующих значений.
AUTO_PAYMENT - Платёж проводится без проверки подлинности владельца карты (без CVC и
3D-Secure). Чтобы проводить подобные платежи и продавца должны быть соответствующие
разрешения.
FORCE_TDS - Принудительное проведение платежа с использованием 3-D Secure. Если карта не
поддерживает 3-D Secure, транзакция не пройдёт.
FORCE_SSL - Принудительное проведение платежа через SSL (без использования 3-D Secure).
FORCE_FULL_TDS - После проведения аутентификации с помощью 3-D Secure статус PaRes должен
быть только , что гарантирует успешную аутентификацию пользователя. В противном случаеY
транзакция не пройдёт.
* По умолчанию в процессинг банка передаются поля:
orderNumber – номер заказа в системе магазина;
description – описание заказа (не более 24 символов, запрещены к использованию %, +, конец строки \r и
перенос строки \n).
Если в заказе передать дополнительный параметр с именем , то именно его значение будет передано вmerchantOrderId
процессинг в качестве номера заказа (вместо значения поля ).orderNumber
Параметры ответа:
Название Тип Обязательно Описание
orderId ANS36 Нет Номер заказа в платежной системе. Уникален в пределах системы. Отсутствует если регистрация заказа на
удалась по причине ошибки, детализированной в ErrorCode.
formUrl AN..512 Нет URL платежной формы, на который надо перенаправить броузер клиента. Не возвращается если
регистрация заказа не удалась по причине ошибки, детализированной в ErrorCode.
errorCode N3 Нет Код ошибки.
errorMessage AN..512 нет Описание ошибки на языке, переданном в параметре Language в запросе.
Коды ошибок (поле errorCode):
Классификация ошибок:
Значение Описание
0 Обработка запроса прошла без системных ошибок
1 Заказ с таким номером уже зарегистрирован в системе
3 Неизвестная (запрещенная) валюта
4 Отсутствует обязательный параметр запроса
5 Ошибка значение параметра запроса
7 Системная ошибка
Расшифровка:
Значение Описание
0 Обработка запроса прошла без системных ошибок
1 Заказ с таким номером уже обработан
1 Заказ с таким номером был зарегистрирован, но не был оплачен
1 Неверный номер заказа
3 Неизвестная валюта
4 Номер заказа не может быть пуст
4 Имя мерчанта не может быть пустым
4 Отсутствует сумма
4 URL возврата не может быть пуст
4 Пароль не может быть пуст
5 Неверное значение одного из параметров
5 Доступ запрещён
5 Пользователь должен сменить свой пароль
5 Доступ запрещён
5 [jsonParams] неверен
7 Системная ошибка
13 Мерчант не имеет привилегии выполнять проверочные платежи
14 Features указаны некорректно
Пример запроса GET:
?amount=100&orderNumber=87654321&password=password&returnhttps://3dsec.sberbank.ru/payment/rest/register.do
Url= finish.html&userName=userName&jsonParams={"orderNumber":1234567890}&phttps://3dsec.sberbank.ru/payment/
ageView=DESKTOP&expirationDate=2014-09-08T14:14:14&merchantLogin=merch_child&features=AUTO_PAYMENT
Пример запроса POST:
amount=100¤cy=643&language=ru&orderNumber=87654321&returnUrl= finishhttps://3dsec.sberbank.ru/payment/
.html&jsonParams={"orderNumber":1234567890}&pageView=DESKTOP&expirationDate=2014-09-08T14:14:14&merchantLog
in=merch_child&features=AUTO_PAYMENT
Пример ответа:
{"orderId":"70906e55-7114-41d6-8332-4609dc6590f4","formUrl":" merchants/tehttps://3dsec.sberbank.ru/payment/
"}st/payment_ru.html?mdOrder=70906e55-7114-41d6-8332-4609dc6590f4
8.2.2. Запрос отмены оплаты заказа
Для запроса отмены оплаты заказа используется запрос . Функция отмены доступна в течение ограниченного времениreverse.do
после оплаты, точные сроки необходимо уточнять в Банке.
Операция отмены оплаты может быть совершена только один раз. Если она закончится ошибкой, то повторная операция отмены
платежа не пройдет.
Данная функция доступна магазинам по согласованию с Банком. Для выполнения операции отмены пользователь должен обладать
соответствующими правами.
Параметры запроса:
Название Тип Обязательность Описание
userName AN..30 да Логин магазина, полученный при подключении
password AN..30 да Пароль магазина, полученный при подключении
orderId ANS36 да Номер заказа в платежной системе. Уникален в пределах системы.
language A2 нет Язык в кодировке ISO 639-1. Описание ошибки возвращается на этом языке. Если параметр отсутствует,
используется язык по умолчанию, указанный в настройках мерчанта.
Параметры ответа:
Название Тип Обязательность Описание
errorCode N3 Нет Код ошибки.
errorMessage AN..512 Нет Описание ошибки на языке.
Коды ошибок (поле ErrorCode):
Классификация:
Значение Описание
0 Обработка запроса прошла без системных ошибок
5 Ошибка значение параметра запроса
6 Незарегистрированный OrderId
7 Системная ошибка
Расшифровка:
Значение Описание
0 Обработка запроса прошла без системных ошибок
5 Доступ запрещён
5 Пользователь должен сменить свой пароль
5 [orderId] не задан
6 Неверный номер заказа
7 Операция невозможна для текущего состояния платежа
7 Реверсал невозможен. Причина: неверные внутренние значения, проверьте суммы холда, депозита
7 Ошибка системы
Пример запроса GET:
https://server/applicaton_context/rest/reverse.do?language=ru&orderId=9231
a838-ac68-4a3e-bddb-d9781433d852&password=password&userName=userName
Пример запроса POST:
language=ru&orderId=9231a838-ac68-4a3e-bddb-d9781433d852
Пример ответа:
{"errorCode":"0","errorMessage":""}
8.2.3. Запрос возврата средств оплаты заказа
Для возврата средств используется запрос .refund.do
По этому запросу средства по указанному заказу будут возвращены плательщику. Запрос закончится ошибкой в случае, если средства
по этому заказу не были списаны. Система позволяет возвращать средства более одного раза, но в общей сложности не более
первоначальной суммы списания.
Для выполнения операции возврата необходимо наличие соответствующих права в системе.
Параметры запроса:
Название Тип Обязательно Описание
userName AN..30 да Логин магазина, полученный при подключении
password AN..30 да Пароль магазина, полученный при подключении
orderId ANS36 да Номер заказа в платежной системе. Уникален в пределах системы.
amount N..20 да Сумма платежа в копейках (или центах)
Параметры ответа:
Название Тип Обязательно Описание
errorCode N3 Нет Код ошибки.
errorMessage AN..512 Нет Описание ошибки на языке.
Коды ошибок (поле ErrorCode):
Классификация:
Значение Описание
0 Обработка запроса прошла без системных ошибок
5 Ошибка значение параметра запроса
6 Незарегистрированный OrderId
7 Системная ошибка
Расшифровка:
Значение Описание
0 Обработка запроса прошла без системных ошибок
5 Доступ запрещён
5 Пользователь должен сменить свой пароль
5 [orderId] не задан
6 Неверный номер заказа
7 Платёж должен быть в корректном состоянии
7 Неверная сумма депозита (менее одного рубля)
7 Ошибка системы
Пример запроса GET:
https://server/application_context/rest/refund.do?amount=500¤cy=643&
language=ru&orderId=5e97e3fd-1d20-4b4b-a542-f5995f5e8208&password=password
&userName=userName
Пример запроса POST:
amount=500¤cy=643&language=ru&orderId=5e97e3fd-1d20-4b4b-a542-f5995f
5e8208
Пример ответа:
{"errorCode":0}
8.2.4. Расширенный запрос состояния заказа
Для запроса состояния зарегистрированного заказа используется запрос .getOrderStatusExtended.do
Параметры запроса:
Название Тип Обязательность Описание
userName AN..30 да Логин магазина, полученный при подключении
password AN..30 да Пароль магазина, полученный при подключении
orderId ANS36 да* Номер заказа в платежной системе. Уникален в пределах системы.
orderNumber AN..32 да* Номер (идентификатор) заказа в системе магазина.
language A2 нет Язык в кодировке ISO 639-1. Если не указан, считается, что язык – русский. Сообщение ошибке будет
возвращено именно на этом языке.
* В запросе должен присутствовать либо , либо . Если в запросе присутствуют оба параметра, то приоритетнымorderId orderNumber
считается .orderId
Существует несколько наборов параметров ответа. Какие именно наборы параметров будут возвращены, завит от версии getOrderSta
, указанной в настройках продавца.tusExtended
Название Тип Обязательно Описание Версия
getOrderStatusExtended
orderNumber AN..32 да Номер (идентификатор) заказа в системе магазина. Все версии.
orderStatus N2 нет По значению этого параметра определяется состояние заказа в
платёжной системе. Список возможных значений приведён в списке
ниже. Отсутствует, если заказ не был найден.
0 - Заказ зарегистрирован, но не оплачен;
1 - Предавторизованная сумма захолдирована (для двухстадийных
платежей);
2 - Проведена полная авторизация суммы заказа;
3 - Авторизация отменена;
4 - По транзакции была проведена операция возврата;
5 - Инициирована авторизация через ACS банка-эмитента;
6 - Авторизация отклонена.
Все версии.
actionCode N3 да Код ответа. Все версии.
actionCodeDescription AN..512 да Расшифровка кода ответа на языке, переданном в параметре Language
в запросе.
Все версии.
errorCode N3 нет Код ошибки. Возможны следующие варианты.
0 - Обработка запроса прошла без системных ошибок;
1 - Ожидается [orderId] или [orderNumber];
5 - Доступ запрещён;
5 - Пользователь должен сменить свой пароль;
6 - Заказ не найден;
7 - Системная ошибка.
Все версии.
errorMessage AN..512 нет Описание ошибки на языке, переданном в параметре Language в
запросе.
Все версии.
amount N..20 да Сумма платежа в копейках (или центах) Все версии.
currency N3 нет Код валюты платежа ISO 4217. Единственное допустимое значение -
643.
Все версии.
date ANS да Дата и время регистрации заказа, выраженные в количестве
миллисекунд, прошедших с 1 января 1970 года.
Все версии.
orderDescription AN..512 нет Описание заказа, переданное при его регистрации Все версии.
ip AN..20 да IP-адрес покупателя. Все версии.
Элемент – присутствует в ответе, если в заказе содержатся дополнительные параметры продавца. Каждый дополнительныйmerchantOrderParams
параметр заказа представлен в отдельном элементе .merchantOrderParams
name AN..20 нет Название дополнительного параметра Все версии.
value AN..1024 нет Значение дополнительного параметра Все версии.
Элемент – в элементе лежит структура, состоящая из списка элемента и следующих параметеров:cardAuthInfo secureAuthInfo
maskedPan N..19 нет Маскированный номер карты, которая использовалась для оплаты.
Указан только после оплаты заказа.
Все версии.
expiration N6 нет Срок истечения действия карты в формате YYYYMM. Указан только
после оплаты заказа.
Все версии.
cardholderName A..64 нет Имя держателя карты. Указан только после оплаты заказа. Все версии.
approvalCode AN6 нет Код авторизации платежа. Поле фиксированной длины (6 символов),
может содержать цифры и латинские буквы. Указан только после
оплаты заказа.
Все версии.
chargeback A..5 нет Были ли средства принудительно возвращены покупателю банком.
Возможны следующие значения.
true (истина);
false (ложь).
06 и выше.
paymentSystem N..10 да Наименование платёжной системы. Доступны следующие варианты.
VISA;
MASTERCARD;
AMEX;
JCB;
CUP;
MIR.
08 и выше.
product AN..255 да Дополнительные сведения о корпоративных картах. Эти сведения
заполняются службой технической поддержки в консоли управления.
Если такие сведения отсутствуют, возвращается пустое значение.
08 и выше.
paymentWay AS..14 да Способ совершения платежа (платёж в с вводом карточных данных,
оплата по связке и т. п.).
09 и выше.
Элемент (элемент состоит из элемента и элемента , являющимся списком параметров и ):secureAuthInfo eci threeDSInfo cavv xid
eci N..4 нет Электронный коммерческий индикатор. Указан только после оплаты
заказа и в случае соответствующего разрешения.
Все версии.
cavv ANS..200 нет Значение проверки аутенфикации владельца карты. Указан только
после оплаты заказа и в случае соответствующего разрешения.
Все версии.
xid ANS..80 нет Электронный коммерческий идентификатор транзакции. Указан только
после оплаты заказа и в случае соответствующего разрешения.
Все версии.
Элемент состоит из параметров:bindingInfo
clientId ANS..255 нет Номер (идентификатор) клиента в системе магазина, переданный при
регистрации заказа. Присутствует только если магазину разрешено
создание связок.
Все версии.
bindingId AN..255 нет Идентификатор связки созданной при оплате заказа или
использованной для оплаты. Присутствует только если магазину
разрешено создание связок.
Все версии.
authDateTime ANS нет Дата/время авторизации. 02 и выше.
authRefNum AN..24 нет Учётный номер авторизации платежа, который присваивается при
регистрации платежа.
02 и выше.
terminalId AN..10 нет Id терминала. 02 и выше.
Элемент состоит из параметров:paymentAmountInfo
approvedAmount N..20 нет Сумма, захолдированная на карте (используется только при
двухстадийных платежах).
03 и выше.
depositedAmount N..20 нет Сумма, подтверждённая для списания с карты. 03 и выше.
refundedAmount N..20 нет Сумма возврата. 03 и выше.
paymentState A..10 нет Состояние заказа. 03 и выше.
feeAmount N..20 нет Сумма комиссии. 11 и выше.
Элемент состоит из параметров:bankInfo
bankName AN..200 нет Наименование банка-эмитента. 03 и выше.
bankCountryCode AN..4 нет Код страны банка-эмитента. 03 и выше.
bankCountryName AN..160 нет Наименование страны банка-эмитента на языке, переданном в
параметре language в запросе, или на языке пользователя, вызвавшего
метод, если язык в запросе не указан.
03 и выше.
Элемент состоит из параметров:payerData
email ANS..* нет Email адрес плательщика. 13 и выше.
Пример запроса GET:
https://server/application_context/rest/getOrderStatusExtended.do?userName
=userName&password=password&orderId=b9054496-c65a-4975-9418-1051d101f1b9&l
anguage=ru&merchantOrderNumber=0784sse49d0s134567890
Пример запроса POST:
orderId=b9054496-c65a-4975-9418-1051d101f1b9&language=ru&merchantOrderNumb
er=0784sse49d0s134567890
Пример ответа:
{"errorCode":"0","errorMessage":"","orderNumber":"0784sse49d0s134567890","
orderStatus":6,"actionCode":-2007,"actionCodeDescription":"
","amount":33000,"currency":"643","date":1383819429914,"orderDescription":"
","merchantOrderParams":[{"name":"email","value":"yap"}],"attributes":[{"n
ame":"mdOrder","value":"b9054496-c65a-4975-9418-1051d101f1b9"}],"cardAuthI
nfo":{"expiration":"201912","cardholderName":"Ivan","secureAuthInfo":{"eci
":6,"threeDSInfo":{"xid":"MDAwMDAwMDEzODM4MTk0MzAzMjM="}},"pan":"411111**1
111"},"terminalId":"333333"}
8.2.5. Запрос проверки вовлечённости карты в 3DS
Для проверки вовлечённости карты в 3DS используется запрос .verifyEnrollment
Параметры запроса:
Название Тип Обязательно Описание
userName AN..30 да Логин пользователя (API)
password AN..30 да Пароль пользователя (API)
pan N12...19 да Номер карты
Параметры ответа:
Название Тип Обязательно Описание
errorCode N3 нет Код ошибки.
errorMessage AN..512 нет Описание ошибки.
enrolled A1 нет Признак вовлечённости карты в 3DS. Возможные значения: Y, N, U.
emitterName AN..160 нет Наименование банка-эмитента.
emitterCountryCode AN..4 нет Код страны банка-эмитента.
Коды ошибок (поле ):errorCode
Значение Описание
0 Обработка запроса прошла без системных ошибок
1 Не указан номер карты
1 Номер карты должен быть числом, содержащим от 13 до 19 цифр
5 Пользователь должен изменить свой пароль.
5 Доступ запрещён
6 По заданному номеру карты информация не найдена.
7 Произошла системная ошибка.
Пример запроса GET:
https://server/application_context/rest/verifyEnrollment.do?userName=userN
ame&password=password&pan=4111111111111111
Пример запроса POST:
pan=4111111111111111
Пример ответа:
{"errorCode":"0","errorMessage":"","emitterName":"TEST
CARD","emitterCountryCode":"RU","enrolled":"Y"}
8.3. Запросы, используемые при двухстадийной оплате
8.3.1. Запрос регистрации заказа c предавторизацией
Для запроса регистрации заказа с предавторизацией используется метод (см. раздел "КоординатыregisterPreAuth.do
подключения").
Параметры запроса:
Название Тип Обязательно Описание
userName AN..30 нет (нужно
указать либо
пару логин и
пароль, либо
токен)
Логин магазина, полученный при подключении. Если вместо аутентификации по логину и паролю
используется открытый токен (параметр token), параметр передавать не нужно.userName
password AN..30 нет (нужно
указать либо
пару логин и
пароль, либо
токен)
Пароль магазина, полученный при подключении. Если для аутентификации при регистрации вместо
логина и пароля используется открытый токен (параметр token), параметр передавать неpassword
нужно.
token AN..30 нет (нужно
указать либо
пару логин и
пароль, либо
токен)
Открытый ключ, который можно использовать для регистрации заказа. Если для аутентификации
при регистрации заказа используются логин и пароль, параметр передавать не нужно.token
orderNumber AN..32 да Номер (идентификатор) заказа в системе магазина, уникален для каждого магазина в пределах
системы. Если номер заказа генерируется на стороне платёжного шлюза, этот параметр передавать
необязательно.
amount N..20 да Сумма платежа в копейках (или центах)
currency N3 нет Код валюты платежа ISO 4217. Единственное допустимое значение - 643.
returnUrl AN..512 да Адрес, на который требуется перенаправить пользователя в случае успешной оплаты. Адрес
должен быть указан полностью, включая используемый протокол (например, вместо https://test.ru tes
). В противном случае пользователь будет перенаправлен по адресу следующего вида: t.ru http://<ад
.рес_платёжного_шлюза>/<адрес_продавца>
failUrl AN..512 нет Адрес, на который требуется перенаправить пользователя в случае неуспешной оплаты. Адрес
должен быть указан полностью, включая используемый протокол (например, вместо https://test.ru tes
). В противном случае пользователь будет перенаправлен по адресу следующего вида: t.ru http://<ад
.рес_платёжного_шлюза>/<адрес_продавца>
description ANS..512 нет Описание заказа в свободной форме. В процессинг банка для включения в финансовую отчётность
продавца передаются только первые 24 символа этого поля.
language A2 нет Язык в кодировке ISO 639-1. Если не указан, будет использован язык, указанный в настройках
магазина как язык по умолчанию (default language)
pageView ANS..20 нет По значению данного параметра определяется, какие страницы платёжного интерфейса должны
загружаться для клиента. Возможные значения:
DESKTOP – для загрузки страниц, верстка которых предназначена для отображения на экранах
ПК (в архиве страниц платёжного интерфейса будет осуществляться поиск страниц с
названиями и );payment_<locale>.html ocale>.htmlerrors_<l
MOBILE – для загрузки страниц, верстка которых предназначена для отображения на экранах
мобильных устройств (в архиве страниц платёжного интерфейса будет осуществляться поиск
страниц с названиями и mobile_payment_<locale>.html ocale>.htmlmobile_errors_<l
);
Если магазин создал страницы платёжного интерфейса, добавив в название файлов страниц
произвольные префиксы, передайте значение нужного префикса в параметре дляpageView
загрузки соответствующей страницы. Например, при передаче значения в архивеiphone
страниц платёжного интерфейса будет осуществляться поиск страниц с названиями iphone_p
и .ayment_<locale>.html iphone_error_<locale>.html
Где:
locale – я . Например, для русского или длязык страницы в кодировке ISO 639-1 ru en
английского.
Если параметр отсутствует, либо не соответствует формату, то по умолчанию считается pageView=
.DESKTOP
clientId ANS..255 нет Номер (идентификатор) клиента в системе магазина. Используется для реализации функционала
связок. Может присутствовать, если магазину разрешено создание связок.
merchantLogin AN..255 нет Чтобы зарегистрировать заказ от имени дочернего мерчанта, укажите его логин в этом параметре.
jsonParams AN..1024 нет Блок для передачи дополнительных параметров мерчанта. Поля дополнительной информации для
последующего хранения, передаются в виде:
{"<name1>":"<value1>",...,"<nameN>":"<valueN>"},
Данные поля могут быть переданы в процессинг банка для последующего отображения в реестрах.*
Включение данного функционала возможно по согласованию с банком в период интеграции.
Если для продавца настроена отправка покупателю, адрес электронной почтыуведомлений
покупателя должен передаваться в этом блоке в параметре с именем .email
sessionTimeoutSecs N...9 нет .Продолжительность жизни заказа в секундах
В случае если параметр не задан, будет использовано значение, указанное в настройках мерчанта
или время по умолчанию (1200 секунд = 20 минут).
Если в запросе присутствует параметр expirationDate, то значение параметра sessionTimeout
Secs не учитывается.
expirationDate ANS нет Дата и время окончания жизни заказа. Формат: .yyyy-MM-ddTHH:mm:ss
Если этот параметр не передаётся в запросе, то для определения времени окончания жизни заказа
.используется sessionTimeoutSecs
Указание этого параметра при платежах по связке необходимо - в противном случае
платёж будет неуспешен.
bindingId AN..255 no Идентификатор связки, созданной ранее. Может использоваться, только если у магазина есть
разрешение на работу со связками. Если этот параметр передаётся в данном запросе, то это
означает:
1. Данный заказ может быть оплачен только с помощью связки;
2. Плательщик будет перенаправлен на платёжную страницу, где требуется только ввод CVC.
features ANS..255 нет Возможно использование следующих значений.
AUTO_PAYMENT - Платёж проводится без проверки подлинности владельца карты (без CVC и
3D-Secure). Чтобы проводить подобные платежи и продавца должны быть соответствующие
разрешения.
FORCE_TDS - Принудительное проведение платежа с использованием 3-D Secure. Если карта не
поддерживает 3-D Secure, транзакция не пройдёт.
FORCE_SSL - Принудительное проведение платежа через SSL (без использования 3-D Secure).
FORCE_FULL_TDS - После проведения аутентификации с помощью 3-D Secure статус PaRes должен
быть только , что гарантирует успешную аутентификацию пользователя. В противном случаеY
транзакция не пройдёт.
* По умолчанию в процессинг банка передаются поля:
orderNumber – номер заказа в системе магазина;
description – описание заказа (не более 24 символов, запрещены к использованию %, +, конец строки \r и
перенос строки \n).
Если в заказе передать дополнительный параметр с именем , то именно его значение будет передано вmerchantOrderId
процессинг в качестве номера заказа (вместо значения поля ).orderNumber
Параметры ответа:
Название Тип Обязательно Описание
orderId ANS36 Нет Номер заказа в платежной системе. Уникален в пределах системы. Отсутствует если регистрация заказа на
удалась по причине ошибки, детализированной в .errorCode
formUrl AN..512 Нет URL платежной формы, на который надо перенаправить броузер клиента. Не возвращается если
регистрация заказа не удалась по причине ошибки, детализированной в .errorCode
errorCode N3 Нет Код ошибки.
errorMessage AN..512 нет Описание ошибки на языке, переданном в параметре в запросе.language
Коды ошибок (поле errorCode):
Классификация ошибок:
Значение Описание
0 Обработка запроса прошла без системных ошибок
1 Заказ с таким номером уже зарегистрирован в системе
3 Неизвестная (запрещенная) валюта
4 Отсутствует обязательный параметр запроса
5 Ошибка значение параметра запроса
7 Системная ошибка
Расшифровка:
Значение Описание
0 Обработка запроса прошла без системных ошибок
1 Заказ с таким номером уже обработан
1 Заказ с таким номером был зарегистрирован, но не был оплачен
1 Неверный номер заказа
3 Неизвестная валюта
4 Номер заказа не может быть пуст
4 Имя мерчанта не может быть пустым
4 Отсутствует сумма
4 URL возврата не может быть пуст
4 Пароль не может быть пуст
5 Неверная сумма
5 Неправильный параметр 'Язык'
5 Логин продавца неверен
5 Доступ запрещён
5 Пользователь должен сменить свой пароль
5 Доступ запрещён
5 [jsonParams] неверен
7 Системная ошибка
13 Мерчант не имеет привилегии выполнять проверочные платежи
14 Features указаны некорректно
Пример запроса GET:
https://3dsec.sberbank.ru/payment/rest/registerPreAuth.do?amount=100¤currency=643&language=ru&orderNumber=87654321&password=password&returnUrl=
finish.html&userName=userName&pageView=MOBILE&expirationDate=2014-09-08T14:14:14&merchantLogin=merch_child&fhttps://3dsec.sberbank.ru/payment/
eatures=AUTO_PAYMENT
Пример запроса POST:
amount=100¤cy=643&language=ru&orderNumber=87654321&returnUrl= finish.hhttps://3dsec.sberbank.ru/payment/
tml&pageView=MOBILE&expirationDate=2014-09-08T14:14:14&merchantLogin=merch_child&features=AUTO_PAYMENT
Пример ответа:
{"orderId":"61351fbd-ac25-484f-b930-4d0ce4101ab7","formUrl":"https://3dsec.sberbank.ru/payment/mobile_pay
"}ment_ru.html?mdOrder=61351fbd-ac25-484f-b930-4d0ce4101ab7
8.3.2. Запрoс завершения oплаты заказа
Для запроса завершения ранее пред авторизованного заказа используется запрос .deposit.do
Данную операцию можно осуществлять, если есть соответствующие права в системе.
Параметры запроса:
Название Тип Обязательно Описание
userName AN..30 да Логин магазина, полученный при подключении
password AN..30 да Пароль магазина, полученный при подключении
orderId ANS36 да Номер заказа в платежной системе. Уникален в пределах системы.
amount N..20 да Сумма платежа в копейках (или центах).
Внимание!!! Если в этом параметре указать ноль, завершение произойдет на всю предавторизованную сумму.
Параметры ответа:
Параметры ответа:
Название Тип Обязательно Описание
errorCode N3 Нет Код ошибки.
errorMessage AN..512 Нет Описание ошибки на языке.
Коды ошибок (поле ErrorCode):
Классификация:
Значение Описание
0 Обработка запроса прошла без системных ошибок
5 Ошибка значение параметра запроса
6 Незарегистрированный OrderId
7 Системная ошибка
Расшифровка:
Значение Описание
5 Доступ запрещён
5 Пользователь должен сменить свой пароль
5 Неверная сумма
5 Сумма депозита должна быть равной нулю или не менее одного рубля
6 Неверный номер заказа
7 Платёж должен быть в корректном состоянии
7 Ошибка системы
Пример запроса GET:
https://server/application_context/rest/deposit.do?amount=100¤cy=643
&language=ru&orderId=e5b59d3d-746b-4828-9da4-06f126e01b68&password=passwor
d&userName=userName
Пример ответа:
{"errorCode":0}
8.3.3. Запрос отмены оплаты заказа
Для запроса отмены оплаты заказа используется запрос . Функция отмены доступна в течение ограниченного времениreverse.do
после оплаты, точные сроки необходимо уточнять в Банке.
Операция отмены оплаты может быть совершена только один раз. Если она закончится ошибкой, то повторная операция отмены
платежа не пройдет.
Данная функция доступна магазинам по согласованию с Банком. Для выполнения операции отмены пользователь должен обладать
соответствующими правами.
Параметры запроса:
Название Тип Обязательность Описание
userName AN..30 да Логин магазина, полученный при подключении
password AN..30 да Пароль магазина, полученный при подключении
orderId ANS36 да Номер заказа в платежной системе. Уникален в пределах системы.
language A2 нет Язык в кодировке ISO 639-1. Описание ошибки возвращается на этом языке. Если параметр отсутствует,
используется язык по умолчанию, указанный в настройках мерчанта.
Параметры ответа:
Название Тип Обязательность Описание
errorCode N3 Нет Код ошибки.
errorMessage AN..512 Нет Описание ошибки на языке.
Коды ошибок (поле ErrorCode):
Классификация:
Значение Описание
0 Обработка запроса прошла без системных ошибок
5 Ошибка значение параметра запроса
6 Незарегистрированный OrderId
7 Системная ошибка
Расшифровка:
Значение Описание
0 Обработка запроса прошла без системных ошибок
5 Доступ запрещён
5 Пользователь должен сменить свой пароль
5 [orderId] не задан
6 Неверный номер заказа
7 Операция невозможна для текущего состояния платежа
7 Реверсал невозможен. Причина: неверные внутренние значения, проверьте суммы холда, депозита
7 Ошибка системы
Пример запроса GET:
https://server/applicaton_context/rest/reverse.do?language=ru&orderId=9231
a838-ac68-4a3e-bddb-d9781433d852&password=password&userName=userName
Пример запроса POST:
language=ru&orderId=9231a838-ac68-4a3e-bddb-d9781433d852
Пример ответа:
{"errorCode":"0","errorMessage":""}
8.3.4. Запрос возврата средств оплаты заказа
Для возврата средств используется запрос .refund.do
По этому запросу средства по указанному заказу будут возвращены плательщику. Запрос закончится ошибкой в случае, если средства
по этому заказу не были списаны. Система позволяет возвращать средства более одного раза, но в общей сложности не более
первоначальной суммы списания.
Для выполнения операции возврата необходимо наличие соответствующих права в системе.
Параметры запроса:
Название Тип Обязательно Описание
userName AN..30 да Логин магазина, полученный при подключении
password AN..30 да Пароль магазина, полученный при подключении
orderId ANS36 да Номер заказа в платежной системе. Уникален в пределах системы.
amount N..20 да Сумма платежа в копейках (или центах)
Параметры ответа:
Название Тип Обязательно Описание
errorCode N3 Нет Код ошибки.
errorMessage AN..512 Нет Описание ошибки на языке.
Коды ошибок (поле ErrorCode):
Классификация:
Значение Описание
0 Обработка запроса прошла без системных ошибок
5 Ошибка значение параметра запроса
6 Незарегистрированный OrderId
7 Системная ошибка
Расшифровка:
Значение Описание
0 Обработка запроса прошла без системных ошибок
5 Доступ запрещён
5 Пользователь должен сменить свой пароль
5 [orderId] не задан
6 Неверный номер заказа
7 Платёж должен быть в корректном состоянии
7 Неверная сумма депозита (менее одного рубля)
7 Ошибка системы
Пример запроса GET:
https://server/application_context/rest/refund.do?amount=500¤cy=643&
language=ru&orderId=5e97e3fd-1d20-4b4b-a542-f5995f5e8208&password=password
&userName=userName
Пример запроса POST:
amount=500¤cy=643&language=ru&orderId=5e97e3fd-1d20-4b4b-a542-f5995f
5e8208
Пример ответа:
{"errorCode":0}
8.3.5. Расширенный запрос состояния заказа
Для запроса состояния зарегистрированного заказа используется запрос .getOrderStatusExtended.do
Параметры запроса:
Название Тип Обязательность Описание
userName AN..30 да Логин магазина, полученный при подключении
password AN..30 да Пароль магазина, полученный при подключении
orderId ANS36 да* Номер заказа в платежной системе. Уникален в пределах системы.
orderNumber AN..32 да* Номер (идентификатор) заказа в системе магазина.
language A2 нет Язык в кодировке ISO 639-1. Если не указан, считается, что язык – русский. Сообщение ошибке будет
возвращено именно на этом языке.
* В запросе должен присутствовать либо , либо . Если в запросе присутствуют оба параметра, то приоритетнымorderId orderNumber
считается .orderId
Существует несколько наборов параметров ответа. Какие именно наборы параметров будут возвращены, завит от версии getOrderSta
, указанной в настройках продавца.tusExtended
Название Тип Обязательно Описание Версия
getOrderStatusExtended
orderNumber AN..32 да Номер (идентификатор) заказа в системе магазина. Все версии.
orderStatus N2 нет По значению этого параметра определяется состояние заказа в
платёжной системе. Список возможных значений приведён в списке
ниже. Отсутствует, если заказ не был найден.
0 - Заказ зарегистрирован, но не оплачен;
1 - Предавторизованная сумма захолдирована (для двухстадийных
платежей);
2 - Проведена полная авторизация суммы заказа;
3 - Авторизация отменена;
4 - По транзакции была проведена операция возврата;
5 - Инициирована авторизация через ACS банка-эмитента;
6 - Авторизация отклонена.
Все версии.
actionCode N3 да Код ответа. Все версии.
actionCodeDescription AN..512 да Расшифровка кода ответа на языке, переданном в параметре Language
в запросе.
Все версии.
errorCode N3 нет Код ошибки. Возможны следующие варианты.
0 - Обработка запроса прошла без системных ошибок;
1 - Ожидается [orderId] или [orderNumber];
5 - Доступ запрещён;
5 - Пользователь должен сменить свой пароль;
6 - Заказ не найден;
7 - Системная ошибка.
Все версии.
errorMessage AN..512 нет Описание ошибки на языке, переданном в параметре Language в
запросе.
Все версии.
amount N..20 да Сумма платежа в копейках (или центах) Все версии.
currency N3 нет Код валюты платежа ISO 4217. Единственное допустимое значение -
643.
Все версии.
date ANS да Дата и время регистрации заказа, выраженные в количестве
миллисекунд, прошедших с 1 января 1970 года.
Все версии.
orderDescription AN..512 нет Описание заказа, переданное при его регистрации Все версии.
ip AN..20 да IP-адрес покупателя. Все версии.
Элемент – присутствует в ответе, если в заказе содержатся дополнительные параметры продавца. Каждый дополнительныйmerchantOrderParams
параметр заказа представлен в отдельном элементе .merchantOrderParams
name AN..20 нет Название дополнительного параметра Все версии.
value AN..1024 нет Значение дополнительного параметра Все версии.
Элемент – в элементе лежит структура, состоящая из списка элемента и следующих параметеров:cardAuthInfo secureAuthInfo
maskedPan N..19 нет Маскированный номер карты, которая использовалась для оплаты.
Указан только после оплаты заказа.
Все версии.
expiration N6 нет Срок истечения действия карты в формате YYYYMM. Указан только
после оплаты заказа.
Все версии.
cardholderName A..64 нет Имя держателя карты. Указан только после оплаты заказа. Все версии.
approvalCode AN6 нет Код авторизации платежа. Поле фиксированной длины (6 символов),
может содержать цифры и латинские буквы. Указан только после
оплаты заказа.
Все версии.
chargeback A..5 нет Были ли средства принудительно возвращены покупателю банком.
Возможны следующие значения.
true (истина);
false (ложь).
06 и выше.
paymentSystem N..10 да Наименование платёжной системы. Доступны следующие варианты.
VISA;
MASTERCARD;
AMEX;
JCB;
CUP;
MIR.
08 и выше.
product AN..255 да Дополнительные сведения о корпоративных картах. Эти сведения
заполняются службой технической поддержки в консоли управления.
Если такие сведения отсутствуют, возвращается пустое значение.
08 и выше.
paymentWay AS..14 да Способ совершения платежа (платёж в с вводом карточных данных,
оплата по связке и т. п.).
09 и выше.
Элемент (элемент состоит из элемента и элемента , являющимся списком параметров и ):secureAuthInfo eci threeDSInfo cavv xid
eci N..4 нет Электронный коммерческий индикатор. Указан только после оплаты
заказа и в случае соответствующего разрешения.
Все версии.
cavv ANS..200 нет Значение проверки аутенфикации владельца карты. Указан только
после оплаты заказа и в случае соответствующего разрешения.
Все версии.
xid ANS..80 нет Электронный коммерческий идентификатор транзакции. Указан только
после оплаты заказа и в случае соответствующего разрешения.
Все версии.
Элемент состоит из параметров:bindingInfo
clientId ANS..255 нет Номер (идентификатор) клиента в системе магазина, переданный при
регистрации заказа. Присутствует только если магазину разрешено
создание связок.
Все версии.
bindingId AN..255 нет Идентификатор связки созданной при оплате заказа или
использованной для оплаты. Присутствует только если магазину
разрешено создание связок.
Все версии.
authDateTime ANS нет Дата/время авторизации. 02 и выше.
authRefNum AN..24 нет Учётный номер авторизации платежа, который присваивается при
регистрации платежа.
02 и выше.
terminalId AN..10 нет Id терминала. 02 и выше.
Элемент состоит из параметров:paymentAmountInfo
approvedAmount N..20 нет Сумма, захолдированная на карте (используется только при
двухстадийных платежах).
03 и выше.
depositedAmount N..20 нет Сумма, подтверждённая для списания с карты. 03 и выше.
refundedAmount N..20 нет Сумма возврата. 03 и выше.
paymentState A..10 нет Состояние заказа. 03 и выше.
feeAmount N..20 нет Сумма комиссии. 11 и выше.
Элемент состоит из параметров:bankInfo
bankName AN..200 нет Наименование банка-эмитента. 03 и выше.
bankCountryCode AN..4 нет Код страны банка-эмитента. 03 и выше.
bankCountryName AN..160 нет Наименование страны банка-эмитента на языке, переданном в
параметре language в запросе, или на языке пользователя, вызвавшего
метод, если язык в запросе не указан.
03 и выше.
Элемент состоит из параметров:payerData
email ANS..* нет Email адрес плательщика. 13 и выше.
Пример запроса GET:
https://server/application_context/rest/getOrderStatusExtended.do?userName
=userName&password=password&orderId=b9054496-c65a-4975-9418-1051d101f1b9&l
anguage=ru&merchantOrderNumber=0784sse49d0s134567890
Пример запроса POST:
orderId=b9054496-c65a-4975-9418-1051d101f1b9&language=ru&merchantOrderNumb
er=0784sse49d0s134567890
Пример ответа:
{"errorCode":"0","errorMessage":"","orderNumber":"0784sse49d0s134567890","
orderStatus":6,"actionCode":-2007,"actionCodeDescription":"
","amount":33000,"currency":"643","date":1383819429914,"orderDescription":"
","merchantOrderParams":[{"name":"email","value":"yap"}],"attributes":[{"n
ame":"mdOrder","value":"b9054496-c65a-4975-9418-1051d101f1b9"}],"cardAuthI
nfo":{"expiration":"201912","cardholderName":"Ivan","secureAuthInfo":{"eci
":6,"threeDSInfo":{"xid":"MDAwMDAwMDEzODM4MTk0MzAzMjM="}},"pan":"411111**1
111"},"terminalId":"333333"}
8.3.6. Запрос проверки вовлечённости карты в 3DS
Для проверки вовлечённости карты в 3DS используется запрос .verifyEnrollment
Параметры запроса:
Название Тип Обязательно Описание
userName AN..30 да Логин пользователя (API)
password AN..30 да Пароль пользователя (API)
pan N12...19 да Номер карты
Параметры ответа:
Название Тип Обязательно Описание
errorCode N3 нет Код ошибки.
errorMessage AN..512 нет Описание ошибки.
enrolled A1 нет Признак вовлечённости карты в 3DS. Возможные значения: Y, N, U.
emitterName AN..160 нет Наименование банка-эмитента.
emitterCountryCode AN..4 нет Код страны банка-эмитента.
Коды ошибок (поле ):errorCode
Значение Описание
0 Обработка запроса прошла без системных ошибок
1 Не указан номер карты
1 Номер карты должен быть числом, содержащим от 13 до 19 цифр
5 Пользователь должен изменить свой пароль.
5 Доступ запрещён
6 По заданному номеру карты информация не найдена.
7 Произошла системная ошибка.
Пример запроса GET:
https://server/application_context/rest/verifyEnrollment.do?userName=userN
ame&password=password&pan=4111111111111111
Пример запроса POST:
pan=4111111111111111
Пример ответа:
{"errorCode":"0","errorMessage":"","emitterName":"TEST CARD",
"emitterCountryCode":"RU","enrolled":"Y"}
9. Callback-уведомления
9.1. Общие сведения
9.1.1. Типы операций, на которые могут быть получены уведомления
Продавец может получать от платёжного шлюза callback-уведомления (уведомления обратного вызова) об операциях с заказами,
указанных в таблице ниже.
Операция Система оплаты
Удержание (холдирование) средств. Только двухстадийная система оплаты.
Списание средств. Одностадийная и двухстадийная системы оплаты.
Отмена перевода средств.
Возврат средств.
9.1.2. Типы уведомлений
Уведомления могут быть двух типов (см. таблицу ниже).
Тип
уведомления
Описание
Уведомления
без
контрольной
суммы
Такие уведомления содержат только сведения о заказе - потенциально продавец рискует принять уведомление,
отправленное злоумышленником, за подлинное.
Уведомления
с
контрольной
суммой
Такие уведомления, помимо сведений о заказе, содержат аутентификационный код. Аутентификационный код
представляет собой контрольную сумму сведений о заказе. Эта контрольная сумма позволяет убедиться, что
callback-уведомление действительно было отправлено платёжным шлюзом.
Существует два способа реализации callback-уведомлений с контрольной суммой:
с помощью симметричной криптографии - для формирования контрольной суммы на стороне шлюза и для её
проверки на стороне продавца используется один и тот же (симметричный) криптографический ключ;
с помощью асимметричной криптографии - для формирования контрольной суммы на стороне платёжного шлюза
используется закрытый ключ, известный только шлюзу, а для подтверждения контрольной суммы используется
связанный с закрытым ключом открытый ключ, который известен продавцам и может распространяться свободно.
9.1.3. Требования к SSL-сертификатам сайта магазина
Если для доступа к магазину, который работает с callback-уведомлениями, используется HTTPS-соединение, сертификат сайта, на
котором расположен этот магазин, должен соответствовать следующим требованиям (см. таблицу ниже).
Требование Описание
Длина и тип ключа
сертификата.
Ключ RSA не менее 2048 байт.
Алгоритм подписи. Не ниже SHA-256.
Для большей безопасности рекомендуется использовать способ, в котором контрольная сумма
формируется с помощью асимметричной криптографии.
Чтобы включить возможность получения уведомлений с контрольной суммой и получить закрытый ключ,
обратитесь в службу технической поддержки.
Поддерживаемые центры
сертификации.
Ниже представлены примеры организаций, осуществляющих регистрацию сертификатов:
Thawte Consulting cc – ;https://www.thawte.com/
VeriSign – ;https://www.verisign.com/
DigiCert Inc – ;https://www.digicert.com/
COMODO CA Limited – ;https://www.comodo.com/
GeoTrust Inc. – ;https://www.geotrust.com/
GlobalSign – ;https://www.globalsign.com/
Trustis Limited – ;http://www.trustis.com/
UniTrust – .http://www.unitrust.co.uk/
Также существует возможность оформления сертификатов через поставщиков в России:
RU-CENTER – ;http://ssl.ru/
REG.RU – ;https://www.reg.ru/ssl-certificate/
MySSL – .https://myssl.ru/
9.2. Формат URL callback-уведомлений
Уведомление без контрольной суммы
{merchant-url}?mdOrder={mdOrder}&orderNumber={orderNumber}&
operation={operation}&status={status}
Уведомление с контрольной суммой
{merchant-url}?mdOrder={mdOrder}&orderNumber={orderNumber}&
checksum={checksum}&operation={operation}&status={status}
Передаваемые параметры представлены в таблице ниже.
Имя параметра Описание
mdOrder Уникальный номер заказа в платёжной системе.
orderNumber Уникальный номер (идентификатор) заказа в системе магазина.
checksum Аутентификационный код, или контрольная сумма, полученная из набора параметров.
operation Тип операции, о которой пришло уведомление:
approved - операция удержания (холдирования) суммы;
deposited - операция завершения;
reversed - операция отмены;
refunded - операция возврата;
declinedByTimeout - истекло время, отпущенное на оплату заказа.
status Индикатор успешности операции, указанной в параметре :operation
1 - операция прошла успешно;
0 - операция завершилась ошибкой.
Пример URL уведомления без контрольной суммы
Не допускается использование самоподписанных сертификатов. Сертификат должен быть
подписан доверенным центром сертификации (см. выше).
В таблице приведены базовые параметры. В личном кабинете также существует возможность указать ряд дополнительных
параметров, которые будут передаваться в уведомлениях. Подробнее см. инструкцию администратора по работе с консолью.
1.
2.
https://myshop.ru/callback/?mdOrder=
1234567890-098776-234-522&orderNumbe
r=0987&operation=deposited&status=0
Пример URL уведомления с контрольной суммой
https://myshop.ru/callback/?mdOrder=1234567890-098776-234-522&
orderNumber=0987&checksum=DBBE9E54D42072D8CAF32C7F660DEB82086A
25C14FD813888E231A99E1220AB3&operation=deposited&status=0
9.3. Алгоритм обработки callback-уведомлений
В таблице ниже представлен алгоритм обработки callback-уведомлений в зависимости от типа таких уведомлений.
Уведомление
без
контрольной
суммы
Платёжный шлюз отправляет на сервер продавца HTTP-запрос следующего вида.GET
https://myshop.ru/callback/?mdOrder=
1234567890-098776-234-522&orderNumbe
r=0987&operation=deposited&status=0
Сервер отправляет в платёжный шлюз HTTP-код .200 OK
1.
2.
3.
4.
a.
b.
5.
6.
7.
Уведомление с
контрольной
суммой
Платёжный шлюз отправляет на сервер продавца HTTP-запрос следующего вида (см. ниже), при этом:GET
при использовании симметричной криптографии контрольная сумма формируется с помощью ключа,
общего для платёжного шлюза и продавца;
при использовании асимметричной криптографии контрольная сумма формируется с помощью закрытого
ключа, известного только платёжному шлюзу.
http://site.ru/path?amount=123456&
orderNumber=10747&checksum=DBBE9E5
4D42072D8CAF32C7F660DEB82086A25C14
FD813888E231A99E1220AB3&mdOrder=3f
f6962a-7dcc-4283-ab50-a6d7dd3386fe
&operation=deposited&status=1
На стороне продавца из строки параметров уведомления удаляется параметр , а значение этогоchecksum
параметра (контрольная сумма) сохраняется для проверки подлинности уведомления.
Из оставшихся параметров и их значений генерируется строка следующего вида.
_1;_1;
_2;_2;...;
_N;_N;
Пример сгенерированной строки параметров представлен ниже.
amount;123456;mdOrder;3ff6962a-7dcc-42
83-ab50-a6d7dd3386fe;operation;deposit
ed;orderNumber;10747;status;1;
На стороне продавца высчитывается контрольная сумма, способ вычисления зависит от способа её
формирования:
при использовании симметричной криптографии - с помощью алгоритма HMAC-SHA256 и общего с
платёжным шлюзом закрытого ключа;
при использовании асимметричной криптографии - с помощью алгоритма хеширования, который зависит
от способа создания ключевой пары, и открытого ключа, который связан с закрытым ключом, находящимся
на стороне платёжного шлюза.
В получившейся строке контрольной суммы все буквы нижнего регистра заменяются на буквы верхнего
регистра.
Происходит сравнение полученного значения с контрольной суммой, извлечённой ранее из параметра checks
.um
Если контрольные суммы совпадают, сервер отправляет в платёжный шлюз HTTP-код .200 OK
Порядок параметров в уведомлении может быть произвольным.
При этом пары должны быть отсортированы в прямом алфавитном порядке по имени_;_
параметров.
Если контрольные суммы совпадают, это уведомление подлинно и было отправлено платёжным шлюзом.
В противном случае вероятно, что злоумышленник пытается выдать своё уведомление за уведомление
платёжного шлюза.
Если в платёжный шлюз возвращается ответ, отличный от HTTP-кода , отправка уведомления считается неуспешной.200 OK
В этом случае платёжный шлюз повторяет отправку уведомления с интервалами минут (где A - порядковый номер10*A
попытки уведомления, т. е., например, после второй попытки интервал составит 20 минут, после третьей 30 и т. п.) - до тех пор,
пока не будет достигнуто одно из следующих условий:
9.4. Примеры кода
9.4.1. Пример для Java (симметричная криптография)
import org.apache.commons.codec.binary.Hex;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;
import java.security.InvalidKeyException;
import java.security.NoSuchAlgorithmException;
public class Example {
public static String generateHMacSHA256(final String key, final String
data) throws InvalidKeyException, NoSuchAlgorithmException {
final Mac hMacSHA256 = Mac.getInstance("HmacSHA256");
byte[] hmacKeyBytes = key.getBytes(StandardCharsets.UTF_8);
final SecretKeySpec secretKey = new SecretKeySpec(hmacKeyBytes,
"HmacSHA256");
hMacSHA256.init(secretKey);
byte[] dataBytes = data.getBytes(StandardCharsets.UTF_8);
byte[] res = hMacSHA256.doFinal(dataBytes);
return new String(Hex.encodeHex(res));
}
public static void main(String[] args) throws NoSuchAlgorithmException,
InvalidKeyException {
String secretToken = "123";
String message =
"amount;1500;mdOrder;ed6f3abf-cea0-427e-afdf-0ba43ead124f;operation;deposi
ted;orderNumber;89312;status;1;";
String signature = Expample.generateHMacSHA256(secretToken,
message).toUpperCase();
System.out.println(signature);
}
9.4.2. Пример для Java (асимметричная криптография)
платёжный шлюз получает HTTP-код в ответ на callback-уведомление200 OK
или
происходит шесть неуспешных попыток информирования подряд.
По достижении одного из указанных выше условий попытки отправки callback-уведомлений об операции прекращаются.
package ru.bpc.test;
import org.apache.commons.codec.binary.Base64;
import org.apache.commons.codec.binary.Hex;
import java.io.ByteArrayInputStream;
import java.io.InputStream;
import java.security.Signature;
import java.security.cert.CertificateFactory;
import java.security.cert.X509Certificate;
import java.util.Comparator;
import java.util.Map;
import java.util.stream.Collector;
import java.util.stream.Collectors;
import java.util.stream.Stream;
public class App99 {
public static void main(String[] args) throws Exception {
String callbackParamsString = "amount=35000099, sign_alias=SHA-256
with RSA,
checksum=163BD9FAE437B5DCDAAC4EB5ECEE5E533DAC7BD2C8947B0719F7A8BD17C101EBD
BEACDB295C10BF041E903AF3FF1E6101FF7DB9BD024C6272912D86382090D5A7614E174DC0
34EBBB541435C80869CEED1F1E1710B71D6EE7F52AE354505A83A1E279FBA02572DC4661C1
D75ABF5A7130B70306CAFA69DABC2F6200A698198F8,
mdOrder=12b59da8-f68f-7c8d-12b5-9da8000826ea, operation=deposited,
status=1";
Map<String, String> callbackParamsMap =
Stream.of(callbackParamsString.split(","))
.map(String::trim)
.map(s -> s.split("="))
.collect(Collectors.toMap(s -> s[0].trim(), s ->
s[1].trim()));
String checksum = callbackParamsMap.get("checksum");
callbackParamsMap.remove("checksum");
callbackParamsMap.remove("sign_alias");
String signString = callbackParamsMap.entrySet().stream()
.sorted(Map.Entry.comparingByKey(Comparator.naturalOrder()))
.collect(Collector.of(
StringBuilder::new,
(accumulator, element) -> accumulator
.append(element.getKey()).append(";")
.append(element.getValue()).append(";"),
StringBuilder::append,
StringBuilder::toString
));
String cert =
"MIICcTCCAdqgAwIBAgIGAWAnZt3aMA0GCSqGSIb3DQEBCwUAMHwxIDAeBgkqhkiG9w0BCQEWE
Wt6\n" +
"bnRlc3RAeWFuZGV4LnJ1MQswCQYDVQQGEwJSVTESMBAGA1UECBMJVGF0YXJzdGFuMQ4wDAYDV
QQH\n" +
"EwVLYXphbjEMMAoGA1UEChMDUkJTMQswCQYDVQQLEwJRQTEMMAoGA1UEAxMDUkJTMB4XDTE3M
TIw\n" +
"NTE2MDEyMFoXDTE4MTIwNTE2MDExOVowfDEgMB4GCSqGSIb3DQEJARYRa3pudGVzdEB5YW5kZ
Xgu\n" +
"cnUxCzAJBgNVBAYTAlJVMRIwEAYDVQQIEwlUYXRhcnN0YW4xDjAMBgNVBAcTBUthemFuMQwwC
gYD\n" +
"VQQKEwNSQlMxCzAJBgNVBAsTAlFBMQwwCgYDVQQDEwNSQlMwgZ8wDQYJKoZIhvcNAQEBBQADg
Y0A\n" +
"MIGJAoGBAJNgxgtWRFe8zhF6FE1C8s1t/dnnC8qzNN+uuUOQ3hBx1CHKQTEtZFTiCbNLMNkgW
tJ/\n" +
"CRBBiFXQbyza0/Ks7FRgSD52qFYUV05zRjLLoEyzG6LAfihJwTEPddNxBNvCxqdBeVdDThG81
zC0\n" +
"DiAhMeSwvcPCtejaDDSEYcQBLLhDAgMBAAEwDQYJKoZIhvcNAQELBQADgYEAfRP54xwuGLW/C
g08\n" +
"ar6YqhdFNGq5TgXMBvQGQfRvL7W6oH67PcvzgvzN8XCL56dcpB7S8ek6NGYfPQ4K2zhgxhxpF
EDH\n" +
"PcgU4vswnhhWbGVMoVgmTA0hEkwq86CA5ZXJkJm6f3E/J6lYoPQaKatKF24706T6iH2htG4Bk
jre\n" +
"gUA=";
byte[] b = Base64.decodeBase64(cert);
CertificateFactory certFactory =
CertificateFactory.getInstance("X.509");
InputStream in = new ByteArrayInputStream(b);
X509Certificate x509Cert =
(X509Certificate)certFactory.generateCertificate(in);
Signature sig = Signature.getInstance("SHA512withRSA");
sig.initVerify(x509Cert.getPublicKey());
sig.update(signString.getBytes());
boolean verifies =
sig.verify(Hex.decodeHex(checksum.toLowerCase().toCharArray()));
System.out.println("signature verifies: " + verifies);
1.
2.
3.
4.
5.
6.
}
}
9.4.3. Пример для PHP (симметричная криптография)
<?php
$data =
'amount;123456;mdOrder;3ff6962a-7dcc-4283-ab50-a6d7dd3386fe;operation;depo
sited;orderNumber;10747;status;1;';
$key = 'yourSecretToken';
$hmac = hash_hmac ( 'sha256' , $data , $key);
echo "[$hmac]\n";
?>
Пропишите строку в переменную .data
В переменную пропишите закрытый ключ.key
Функция ( , , ) вычисляет контрольную сумму от переданной строки, с помощью закрытогоhash_hmac 'sha256' $data $key
ключа по алгоритму SHA-256.
Сохраните результат работы функции в переменной .hmac
Выведите результат работы функции функцией .echo
Сравните это значение с тем, что передано в callback-уведомлении.
10. Оформление платёжного интерфейса
В настоящее время доступна минимальная кастомизация платёжной страницы, можно изменить только следующие элементы:
логотип;
подвал.
Требования к этим элементам представлены в инструкции по работе с личным кабинетом.
11. Требования Сбербанка к электронным витринам
1. ТРЕБОВАНИЯ БАНКА К ЭЛЕКТРОННЫМ ВИТРИНАМ
1.1. Все внутренние ссылки Cайта Интернет-магазина должны быть рабочими и адекватно обрабатываемыми.
1.2. Интернет-магазин не должен предоставлять услуги «развлечений для взрослых» («Adult Entertainment»), «игры на деньги», а
также другие виды услуг и товаров, запрещенные правилами международных систем и законодательством РФ.
1.3. На электронной витрине не должно быть ссылок или баннеров подозрительных сайтов (например, сайтов для взрослых и т.п.),
а также ссылок баннерных сетей, в которых могут всплыть баннеры подозрительного содержания.
1.4. Сайт Интернет-магазина не должен располагаться на бесплатных серверах, предоставляющихся для бесплатного хостинга
(например, )narod.ru
1.5. Наличие на электронной витрине актуальной справочной информации об Интернет-магазине или о Предприятии.
Обязательным условием является наличие на электронной витрине страны, адреса места нахождения, адреса для корреспонденции
(адрес не может быть до востребования), а также контактных телефонов, по которым покупатель может связаться со службой
поддержки Интернет-магазина.
1.6. Перечень товаров/услуг, предоставляемый на электронной витрине Интернет-магазина, должен соответствовать роду
деятельности Предприятия, сообщенному в Банк.
1.7. Полнота описания потребительских характеристик продаваемых товаров (работ, услуг). (Проверяется для того, чтобы
недостаток описания товара, работы, услуги не мог стать причиной для возврата платежа). В том числе, в обязательном порядке на
сайте должны быть указаны цены на товары, работы, услуги в рублях РФ.
1.8. Реквизиты карты не должны приниматься на электронной витрине Интернет-магазина. Для оплаты товаров/услуг с
использованием карты покупатель должен обязательно переадресовываться на сайт Провайдера услуг.
1.9. Наличие на электронной витрине описания процедур заказа товаров (работ, услуг) и их оплаты с использованием карт. Также
обязательным условием является наличие на электронной витрине формы оплаты товара/услуг с использованием карт и
переадресация покупателя на сайт Провайдера услуг.
Под формой оплаты товара (работы, услуги) с использованием банковских карт понимается форма, в которой покупатель указывает
такие реквизиты как фамилия, имя, отчество, адрес доставки, контактная информация и т.п.
1.10. Наличие на электронной витрине Интернет-магазина информации по доставке товара/получении услуги, такой как сроки,
способы, а также любой другой информации, необходимой для получения ясного представления о доставке товара/получении услуги
после оплаты с использованием карты.
1.11. Наличие на электронной витрине Интернет-магазина описания процедур возврата денежных средств, предоставления
взаимозаменяемых товаров, обмена товаров и т.п. при отказе от товара/услуги. В случае, если такие процедуры не предусмотрены, то
Интернет-магазин обязан информировать об этом на своей электронной витрине.
1.12. Наличие на электронной витрине Интернет-магазин информации о защите данных банковской карты, указываемых Держателем
карты.
1.13. Наличие на электронной витрине Интернет-магазина информации о действиях Держателя карты в сбойной ситуации
1.14. Предприятие обязано предусмотреть осуществление контроля получения заказов покупателями.
1.15. Предприятие обязано предусмотреть методы ограничения и контроля рисков мошеннических операций. Обязательным
условием является применение при этом возможностей Провайдера услуг по борьбе с мошенничеством.
1.16. Все страницы, которые связаны с работой электронной витрины или требованиями Банка, должны находиться под единым
доменным именем.
1.17. Наличие предупреждения о том, что посещение сайта, приобретение и доставка конкретного товара/услуги могут быть
незаконными на территории страны, где находится Держатель карты.
1.18. Наличие предупреждения о том, что Держатель карты несет ответственность за невыполнение законов своей страны при
посещении данного сайта и попытке приобрести товары/услуги, если таковые запрещены законодательством на территории страны, где
он находится.
1.19. Наличие на электронной витрине описания экспортных ограничений по доставке товаров/услуг, если таковые существуют.
1.20. Наличие предупреждения о том, что таможенная очистка товара в стране покупателя является ответственностью покупателя.
2. РЕКОМЕНДАЦИИ БАНКА ДЛЯ ЭЛЕКТРОННЫХ ВИТРИН
2.1. Не рекомендуется предоставлять услуги знакомств через сеть Интернет (брачные агентства). Каждая такая заявка
рассматривается особым образом, а решение по ней может быть вынесено на основании требований, не представленных в данном
документе.
2.2. Рекомендуется полное соответствие юридического лица, на которое зарегистрировано доменное имя Интенет-магазина и
юридического лица, указанного в заявке. Юридическое лицо, на которое зарегистрировано доменное имя, устанавливается с помощью
соответствующих баз данных в сети Интернет (БД РосНИИРоса ( ), , ).http://www.ripn.net:8080/nic/ http://www.ripe.net/ http://www.whois.net/
2.3. Рекомендуется, чтобы домен электронной витрины Интернет-магазина был доменом второго уровня.
Пример: www.site.ru
12. Координаты подключения
Для доступа к системе, необходимо иметь открытый исходящий доступ по следующим адресам:
Боевая среда: IP 62.76.205.3;
Тестовая среда: IP 62.76.205.110;
Порт 443.
Сервер должен поддерживать протокол TLS 1.2.
При регистрации мерчанта, представителю предоставляется логин и пароль, который можно использовать в личном кабинете, а также
нужно использовать в протоколах.
Описание тестового сервиса (WSDL) находится по адресу https://3dsec.sberbank.ru/payment/ .webservices/merchant-ws?wsdl
URL для доступа к методам REST:
Название метода URL
Регистрация заказа https://3dsec.sberbank.ru/payment/rest/register.do
Регистрация заказа с предавторизацией https://3dsec.sberbank.ru/payment/rest/registerPreAuth.do
Запрос завершения оплаты заказа https://3dsec.sberbank.ru/payment/rest/deposit.do
Запрос отмены оплаты заказа https://3dsec.sberbank.ru/payment/rest/reverse.do
Запрос возврата средств оплаты заказа https://3dsec.sberbank.ru/payment/rest/refund.do
Получение статуса заказа https://3dsec.sberbank.ru/payment/rest/getOrderStatusExtended.do
Запрос проверки вовлеченности карты в 3DS https://3dsec.sberbank.ru/payment/rest/verifyEnrollment.do
Запрос проведения оплаты по связкам https://3dsec.sberbank.ru/payment/rest/paymentOrderBinding.do
Запрос деактивации связки https://3dsec.sberbank.ru/payment/rest/unBindCard.do
Запрос активации связки https://3dsec.sberbank.ru/payment/rest/bindCard.do
Запрос изменения срока действия связки https://3dsec.sberbank.ru/payment/rest/extendBinding.do
Запрос списка всех связок клиента https://3dsec.sberbank.ru/payment/rest/getBindings.do
Запрос списка связок определённой банковской карты https://3dsec.sberbank.ru/payment/rest/getBindingsByCardOrId.do
Запрос оплаты через Apple Pay https://3dsec.sberbank.ru/payment/applepay/payment.do
Запрос оплаты через Samsung Pay https://3dsec.sberbank.ru/payment/samsung/payment.do
Запрос оплаты через Samsung Pay Web https://3dsec.sberbank.ru/payment/samsungWeb/payment.do
Запрос оплаты через Google Pay https://3dsec.sberbank.ru/payment/google/payment.do
13. Тестовые карты
В качестве Cardholder name указывать от 2 слов в английской раскладке. / Use two or more words in Roman letters as the name of the
cardholder.
Для всех карт, вовлеченных в 3d Secure ( ) пароль на ACS: 12345678. / For cards involeved into 3d Secure (veres=y, pares=y или a veres=y,
) ACS password is 12345678.pares=y or a
Тестовая карта МИР
pan: 2200 0000 0000 0053
exp date: 2019/12
cvv2: 123
3dsecure: veres=Y, pares=Y
"Заглушка" в самом шлюзе /
"Stub" in the payment gate:
pan: 4111 1111 1111 1111
exp date: 2019/12
cvv2: 123
3dsecure: veres=y, pares=y
pan: 6011 0000 0000 0004
exp date: 2019/12
cvv2: 123
3dsecure: veres=Y pares=A
pan: 5555 5555 5555 5599
exp date: 2019/12
cvv2: 123
3dsecure: veres=n
pan: 6390 0200 0000 000003
exp date: 2019/12
cvv2: 123(необязательный параметр)
3dsecure: veres=y, pares=a
Карты, возвращающие ошибки /
Cards returning errors:
pan: 5555 5555 5555 5557
exp date: 2019/12
cvv2: 123
3dsecure: veres=y, pares=u
Declined. PaRes status is U (-2011)
pan: 4000 0000 0000 0002
exp date: 2019/12
cvv2: 123
3dsecure: veres=u
Declined. VeRes status is U (-2016)
pan: 4444 3333 2222 1111
exp date: 2019/12
cvv2: 123
3dsecure: veres=y, pares=u
Declined. PaRes status is U (-2011)
pan: 5555 5555 4444 4442
exp date: 2019/12
cvv2: 123
3dsecure: veres=u
Declined. VeRes status is U (-2016)
pan: 4444 4444 4444 4422
exp date: 2019/12
cvv2: 123
Invalid message format (913)
pan: 4444 4444 1111 1111
exp date: 2019/12
cvv2: 123
Network refused transaction (5)
pan: 4444 4444 4444 6666
exp date: 2019/12
cvv2: 123
BLOCKED_BY_LIMIT (-20010)
pan: 4444 4444 4444 4455
exp date: 2019/12
cvv2: 123
Card limitations exceeded (902)
pan: 4444 4444 9999 9999
exp date: 2019/12
cvv2: 123
TDSEC_COMM_ERROR (151017)
pan: 4444 4444 4444 3333
exp date: 2019/12
cvv2: 123
Limit exceeded (123)
pan: 4408 8962 5320 5448
exp date: 2019/12
cvv2: 123
Not enough money (116)
pan: 4012 8888 8888 1881
exp date: 2019/12
cvv2: 123
RESPONSE_TIMEOUT(151019)
pan: 4563 9601 2200 1999
exp date: 2019/12
cvv2: 123
CANNOT_SEND_REQUEST(151018)
Карты с баллами /"СПАСИБО"
Loyalty "SPASIBO" cards:
pan: 4276 0100 1329 6064
exp date: 2019/12
cvv2: 555
3dsecure: veres=n
SPASIBO AMOUNT = true
pan: 4276 0100 1386 6254
exp date: 2019/12
cvv2: 272
3dsecure: veres=n
SPASIBO AMOUNT = disabled
pan: 4276 0100 1966 3648
exp date: 2019/12
cvv2: 774
3dsecure: veres=n
Activity, FRAUD = true
14. Приложение 1. Описание функционала связок
14.1. Общее описание
Данный функционал используется для привязки номера карты к id покупателя в системе магазина (например, к логину). Существует 2
способа использования связок: и .#отображение на платежной странице #создание запроса оплаты по связкам
В первом варианте, если после авторизации на сайте магазина и успешной оплаты заказа по карте, пользователь повторно на данном
сайте оформит заказ под тем же id, то при перенаправлении на платежную страницу ему будет предложено автозаполнение всех
данных по карте, исключая CVC/ CVV.
Во втором варианте (создание запроса оплаты) при оплате заказа картой, для которой существует связка, передаётся только id связки -
карточные данные не указываются.
В любом случае помимо данной карты у покупателя остается возможность использовать для оплаты другую карту.
14.2. Отображение на платёжной странице. Форма выбора связки
Если для мерчанта предполагается использование функционала связок, платежная страница содержать форму выбора связкиможет
для оплаты заказа.
Оформление формы должно удовлетворять следующим условиям:
Форма должна иметь идентификатор id="formBinding".
Форма должна быть скрыта по-умолчанию при помощи CSS свойства "display: none;".
Форма должна содержать выпадающий список выбора связки с именем name="bindingId".
Форма должна содержать выпадающий список выбора связки с именем name="bindingId".
Выпадающий список должен содержать один вариант выбора: <option value="" selected="selected">другая</option>, при выборе
которого пользователь осуществляет обычную оплату по карте, без использования функционала связок.
Форма должна содержать поле ввода СVC/CVV с именем name="cvc".
Форма должна содержать кнопку "Оплатить": <input value="Оплатить" type="button" id="buttonBindingPayment"> с
идентификатором id="buttonBindingPayment".
Поле ввода CVC/CVV и кнопка "Оплатить" должны быть обрамлены элементами с классом class="rbs_hidden". При выборе
варианта оплаты без использования функционала связок, эти элементы будут скрыты путем установки свойства CSS "display:
none;".
Пример формы:
<form action="" id="formBinding" style="display: none;">
<table cellpadding="10">
<tbody>
<tr valign="TOP">
<td valign="top" width="50%" align="right">
<span>Выберите карту:</span>
</td>
<td valign="top">
<select name="bindingId">
<option value="" selected="selected">другая</option>
</select>
</td>
</tr>
<tr class="rbs_hidden">
<td align="right">
<span>Введите CVC2/CVV2/CID код :</span><br>(находится на обратной стороне карты)
</td>
<td>
<input name="cvc" maxlength="4" type="password" autocomplete="off" />
</td>
</tr>
<tr class="rbs_hidden">
<td> </td>
<td valign="top" >
<input value="Оплатить" type="button" id="buttonBindingPayment">
</td>
</tr>
</tbody>
</table>
</form>
14.3. Создание запросов по связкам
14.3.1. Описание запросов, интерфейс на WebService-ах
14.3.1.1. Запрос проведения платежа по связкам
Для проведения платежа по связкам используется запрос .paymentOrderBinding
Параметры запроса:
Название Тип Обязательно Описание
mdOrder ANS36 да Номер заказа в платежной системе. Уникален в пределах системы.
bindingId ANS36 да Идентификатор связки созданной при оплате заказа или использованной для оплаты. Присутствует только
если магазину разрешено создание связок.
params нет Дополнительный тэг с атрибутами для передачи дополнительных параметров мерчанта.*
language A2 нет Язык в кодировке ISO 639-1. Если не указан, будет использован язык, указанный в настройках магазина как
язык по умолчанию (default language)
ip NS..15 да ip адрес плательщика
cvc N4 нет Код CVC.
Этот параметр обязателен, если для мерчанта не выбрано разрешение "Может проводить оплату без
подтверждения CVC".
email ANS..* нет Email адрес плательщика
* Поля дополнительной информации для последующего хранения. Данные поля могут быть переданы в процессинг банка
для последующего отображения в реестрах.**
Включение данного функционала возможно по согласованию с банком в период интеграции. Для передачи N параметров, в
запросе должно находиться N тэгов Params, где атрибут name содержит название, а атрибут value содержит значение:
Название Тип Обязательно Описание
name AN..20 да Название дополнительного параметра
value AN..1024 да Значение дополнительного параметра
** По умолчанию в процессинг банка передаются поля номер заказа orderNumber и его описание description (не более 24
символов, запрещены к использованию %, +, конец строки \r и перенос строки \n)
Параметры ответа:
Название Тип Обязательно Описание
redirect ANS..* нет При успешном ответе. В случае SSL-платежа – URL, на который производится переадресация после
платежа. В случае 3DS-платежа – URL для возврата с ACS.
info ANS..* нет При успешном ответе. Результат попытки оплаты. Возможные значения представлены ниже:
Ваш платёж обработан, происходит переадресация...
Операция отклонена. Проверьте введенные данные, достаточность средств на карте и повторите
операцию. Происходит переадресация...
Извините, платеж не может быть совершен. Происходит переадресация...
Операция отклонена. Обратитесь в магазин. Происходит переадресация...
Операция отклонена. Обратитесь в банк, выпустивший карту. Происходит переадресация...
Операция невозможна. Аутентификация держателя карты завершена неуспешно. Происходит
переадресация...
Нет связи с банком. Повторите позже. Происходит переадресация...
Истек срок ожидания ввода данных. Происходит переадресация...
Не получен ответ от банка. Повторите позже. Происходит переадресация...
errorCode N1 да Код завершения.
errorMessage ANS..* нет При ответе с ошибкой. Сообщение об ошибке.
acsUrl ANS..* нет При успешном ответе в случае 3DS-платежа. URL перехода на ACS
paReq ANS..* нет При успешном ответе в случае 3DS-платежа. Payment Authentication Request.
Коды ошибок (поле ):errorCode
Значение Описание
0Обработка запроса прошла без системных ошибок
1 Необходимо указать CVC2/CVV2 код, поскольку у мерчанта нет разрешения на проведение платежа без CVC
1 Неверный формат CVC
1 [mdOrder] не задан
1 [bindingId] не задан
1 Адрес электронной почты не удовлетворяет шаблону
1 Неверный язык
2 Заказ не найден
2 Связка не найдена
5 Доступ запрещен
5 Пользователь должен изменить свой пароль
5 Исчерпаны попытки оплаты или закончилось время сессии
7 Системная ошибка
Пример запроса:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:mer="http://engine.paymentgate.ru/webservices/merchant">
<soapenv:Header/>
<soapenv:Body>
<mer:paymentOrderBinding>
<order mdOrder="9213bc5f-5d5b-43d6-a408-b6b93cdde992"
bindingId="ca91a4ab-b6d4-495d-b606-8fb0114e679e" language="ru"
ip="127.0.0.1" cvc="123" email=" ">
<!-Zero or more repetitions:->
<params name=" " value=" "/>
</order>
</mer:paymentOrderBinding>
</soapenv:Body>
</soapenv:Envelope>
Пример ответа:
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<ns1:paymentOrderBindingResponse
xmlns:ns1="http://engine.paymentgate.ru/webservices/merchant">
<return errorCode="0" info=" , ..."
redirect="http://example.ru?orderId=9213bc5f-5d5b-43d6-a408-b6b93cdde992"/
"/>
</ns1:paymentOrderBindingResponse>
</soap:Body>
</soap:Envelope>
14.3.1.2. Запрос деактивации связки
Для того, чтобы сделать существующую связку неактивной, используется запрос .unBindCard
Параметры запроса:
Название Тип Обязательно Описание
bindingId ANS36 да Идентификатор связки созданной при оплате заказа или использованной для оплаты. Присутствует только
если магазину разрешено создание связок
Параметры ответа:
Название Тип Обязательно Описание
errorCode N1 да Код завершения
errorMessage ANS..* (при ошибке) Сообщение об ошибке
Коды ошибок (поле ):errorCode
Значение Описание
0Обработка запроса прошла без системных ошибок
2 Неверное состояние связки (при попытке деактивировать неактивную связку)
2 Связка не найдена
5 Доступ запрещен
5 Пользователь должен сменить свой пароль
7 Системная ошибка
Пример запроса:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:mer="http://engine.paymentgate.ru/webservices/merchant">
<soapenv:Header/>
<soapenv:Body>
<mer:unBindCard>
<bindingId>fd3afc57-c6d0-4e08-aaef-1b7cfeb093dc</bindingId>
</mer:unBindCard>
</soapenv:Body>
</soapenv:Envelope>
Пример ответа:
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<ns1:unBindCardResponse
xmlns:ns1="http://engine.paymentgate.ru/webservices/merchant">
<return errorCode="0" errorMessage=""/>
</ns1:unBindCardResponse>
</soap:Body>
</soap:Envelope>
14.3.1.3. Запрос активации связки
Для активации деактивированной ранее связки используется запрос .bindCard
Параметры запроса:
Название Тип Обязательно Описание
bindingId ANS36 да Идентификатор связки созданной при оплате заказа или использованной для оплаты. Присутствует только
если магазину разрешено создание связок
Параметры ответа:
Название Тип Обязательно Описание
errorCode N1 да Код завершения
errorMessage ANS..* (при ошибке) Сообщение об ошибке
Коды ошибок (поле ):errorCode
Значение Описание
0Обработка запроса прошла без системных ошибок
2 Неверное состояние связки (при попытке деактивировать неактивную связку)
2 Связка не найдена
5 Доступ запрещен
5 Пользователь должен сменить свой пароль
7 Системная ошибка
Пример запроса:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:mer="http://engine.paymentgate.ru/webservices/merchant">
<soapenv:Header/>
<soapenv:Body>
<mer:bindCard>
<bindingId>fd3afc57-c6d0-4e08-aaef-1b7cfeb093dc</bindingId>
</mer:bindCard>
</soapenv:Body>
</soapenv:Envelope>
Пример ответа:
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<ns1:bindCardResponse
xmlns:ns1="http://engine.paymentgate.ru/webservices/merchant">
<return errorCode="5" errorMessage=" "/>
</ns1:bindCardResponse>
</soap:Body>
</soap:Envelope>
14.3.1.4. Запрос изменения срока действия связки
Для изменения срока действия связки используйтся метод .extendBinding
Параметры запроса:
Название Тип Обязательно Описание
bindingId ANS36 да Идентификатор связки созданной при оплате заказа или использованной для оплаты. Присутствует только
если магазину разрешено создание связок.
newExpiry N6 да Новая дата (год и месяц) окончания срока действия в формате YYYYMM
language А2 нет Язык в кодировке ISO 639-1. Если не указан, будет использован язык, указанный в настройках магазина как
язык по умолчанию (default language)
Параметры ответа:
Название Тип Обязательно Описание
errorCode N1 да Код завершения
errorMessage ANS..* (при ошибке) Сообщение об ошибке
Коды ошибок (поле ):errorCode
Значение Описание
0 Обработка запроса прошла без системных ошибок
1 Не указан или неверно указан один или несколько обязательных параметров
2 Связка не найдена
5 Доступ запрещён
5 Пользователь должен сменить свой пароль
7 Системная ошибка
Пример запроса:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:mer="http://engine.paymentgate.ru/webservices/merchant">
<soapenv:Header/>
<soapenv:Body>
<mer:extendBinding>
<request language=" "
bindingId="1eabfb8e-b90e-4dc8-bef6-14bd392b1cec" newExpiry="201807"/>
</mer:extendBinding>
</soapenv:Body>
</soapenv:Envelope>
Пример ответа:
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<ns1:extendBindingResponse
xmlns:ns1="http://engine.paymentgate.ru/webservices/merchant">
<return errorCode="0" errorMessage=""/>
</ns1:extendBindingResponse>
</soap:Body>
</soap:Envelope>
14.3.1.5. Запрос списка связок по идентификатору клиента
Для получения списка связок по идентификатору клиента используется запрос .getBindings
Параметры запроса:
Название Тип Обязательно Описание
clientId ANS..255 да Номер (идентификатор) клиента в системе магазина, переданный при регистрации заказа. Присутствует
только если магазину разрешено создание связок.
Параметры ответа:
Название Тип Обязательно Описание
errorCode N1 да Код завершения
errorMessage ANS..* (при ошибке) Сообщение об ошибке
Элемент binding (состоит из bindingId,
maskedPan и expiryDate):
bindingId AN..255 нет Идентификатор связки созданной при оплате заказа или использованной для
оплаты. Присутствует только если магазину разрешено создание связок.
maskedPan N..19 нет Маскированный номер карты, которая использовалась для оплаты. Указан только
после оплаты заказа.
expiryDate N6 нет Срок истечения действия карты в формате YYYYMM. Указан только после оплаты
заказа.
Коды ошибок (поле ):errorCode
Коды ошибок (поле ):errorCode
Значение Описание
0Обработка запроса прошла без системных ошибок
1 [clientId] не задан
2 Информация не найдена
5 Доступ запрещен
5 Пользователь должен сменить свой пароль
7 Системная ошибка
Пример запроса:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:mer="http://engine.paymentgate.ru/webservices/merchant">
<soapenv:Header/>
<soapenv:Body>
<mer:getBindings>
<request clientId="client"/>
</mer:getBindings>
</soapenv:Body>
</soapenv:Envelope>
Пример ответа:
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<ns1:getBindingsResponse
xmlns:ns1="http://engine.paymentgate.ru/webservices/merchant">
<return errorCode="0" errorMessage="">
<bindings>
<binding bindingId="fd3afc57-c6d0-4e08-aaef-1b7cfeb093dc"
maskedPan="4000 00** **** **02" expiryDate="201512"/>
</bindings>
</return>
</ns1:getBindingsResponse>
</soap:Body>
</soap:Envelope>
14.3.1.6. Запрос списка связок определённой банковской карты
При наличии соответствующих разрешений магазин может запросить список всех связок, относящихся к определённой банковской
карте. Сделать это можно по номеру карты или по известному идентификатору связки.
Для получения списка связок банковской карты используется метод .getBindingsByCardOrId.do
В ответе возвращаются все связки, доступные мерчанту в соответствии с его настройками.
В ответе возвращаются все связки, доступные мерчанту в соответствии с его настройками.
Параметры запроса:
Название Тип Обязательно Описание
pan N..19 нет Номер карты. Обязательно, если не указан .bindingId
Поиск по полному номеру карты доступен магазинам только при наличии соответствующего разрешения.
bindingId AN..255 нет Идентификатор связки. Обязательно, если не указан .pan
Если в запросе передаётся , то значение игнорируется.pan bindingId
showExpired boolean нет Параметр определяет необходимость отображать связки с истёкшим сроком действия карты. Возможные
значения: , . По умолчанию параметр принимает значение .true false false
language A2 нет Язык в кодировке ISO 639-1. Если не указан, считается, используется язык, указанный в настройках
пользователя. Сообщение ошибке будет возвращено именно на этом языке.
Параметры ответа:
Название Тип Обязательно Описание
errorCode N1 да Код завершения.
errorMessage ANS..* да Описание кода завершения.
Элемент bindings (может состоять из нескольких элементов
binding)
Элемент binding (состоит из bindingId, maskedPan, expiryDate и
clientId):
bindingId AN..255 нет Идентификатор связки.
maskedPan N..19 нет Маскированный номер карты, которая использовалась
для оплаты.
expiryDate N6 нет Срок истечения действия карты в формате .YYYYMM
clientId ANS..255 нет Номер (идентификатор) клиента в системе мерчанта.
Коды ошибок (поле ):errorCode
Значение Описание
0 Обработка запроса прошла без системных ошибок.
1 Не указан ни номер карты, ни идентификатор связки.
2 Информация не найдена.
5 Доступ запрещен.
5 Пользователь должен сменить свой пароль.
7 Системная ошибка.
Пример запроса:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:mer="http://engine.paymentgate.ru/webservices/merchant">
<soapenv:Header/>
<soapenv:Body>
<mer:getBindingsByCardOrId>
<request pan="4111111111111111" bindingId=" " showExpired="true"
language="ru"/>
</mer:getBindingsByCardOrId>
</soapenv:Body>
</soapenv:Envelope>
Параметры ответа:
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<ns1:getBindingsByCardOrIdResponse
xmlns:ns1="http://engine.paymentgate.ru/webservices/merchant">
<return errorCode="0" errorMessage="">
<bindings>
<binding bindingId="9f43e86d-9744-42a5-8646-c4bb7cf8799a"
maskedPan="411111**1111" expiryDate="201912" clientId="12345"/>
<binding bindingId="51c0750b-1a23-424b-8989-5e8f669124b4"
maskedPan="411111**1111" expiryDate="201512" clientId="123456"/>
<binding bindingId="6a8c0738-cc88-4200-acf6-afc264d66cb0"
maskedPan="411111**1111" expiryDate="201912" clientId="666"/>
<binding bindingId="97a70989-c1fb-49f7-8a42-27c19dc160dw"
maskedPan="411111**1111" expiryDate="201512" clientId="666"/>
</bindings>
</return>
</ns1:getBindingsByCardOrIdResponse>
</soap:Body>
</soap:Envelope>
14.3.2. Описание запросов, интерфейс REST
14.3.2.1. Запрос проведения платежа по связкам
Для проведения платежа по связкам используется запрос .paymentOrderBinding.do
Параметры запроса:
Название Тип Обязательно Описание
userName AN..30 да Логин магазина, полученный при подключении.
password AN..30 да Пароль магазина, полученный при подключении.
mdOrder ANS36 да Номер заказа в платежной системе. Уникален в пределах системы.
bindingId AN..255 да Идентификатор связки созданной при оплате заказа или использованной для оплаты. Присутствует только
если магазину разрешено создание связок.
language A2 нет Язык в кодировке ISO 639-1. Если не указан, будет использован язык, указанный в настройках магазина как
язык по умолчанию.
ip NS..15 да ip-адрес плательщика.
cvc N..3 нет CVC код.
Этот параметр обязателен, если для мерчанта не выбрано разрешение "Может проводить оплату без
подтверждения CVC".
email ANS..* нет Адрес электронной почты плательщика.
Параметры ответа:
Название Тип Обязательно Описание
redirect ANS..* нет При успешном ответе в случае SSL-платежа. URL, на который производится переадресация после платежа.
info ANS..* нет При успешном ответе. Результат попытки оплаты. Возможные значения представлены ниже:
Ваш платёж обработан, происходит переадресация...
Операция отклонена. Проверьте введенные данные, достаточность средств на карте и повторите
операцию. Происходит переадресация...
Извините, платеж не может быть совершен. Происходит переадресация...
Операция отклонена. Обратитесь в магазин. Происходит переадресация...
Операция отклонена. Обратитесь в банк, выпустивший карту. Происходит переадресация...
Операция невозможна. Аутентификация держателя карты завершена неуспешно. Происходит
переадресация...
Нет связи с банком. Повторите позже. Происходит переадресация...
Истек срок ожидания ввода данных. Происходит переадресация...
Не получен ответ от банка. Повторите позже. Происходит переадресация...
errorCode N1 да Код ошибки.
errorMessage AN..* нет При ответе с ошибкой. Сообщение об ошибке.
error AN..* нет При ответе с ошибкой. Сообщение об ошибке.
acsUrl ANS..* нет При успешном ответе в случае 3DS-платежа. URL для перехода на ACS.
paReq ANS..* нет При успешном ответе в случае 3DS-платежа. Payment Authentication Request.
termUrl ANS..* нет При успешном ответе в случае 3DS-платежа. URL для возврата с ACS.
Коды ошибок (поле success):
Значение Описание
0 Обработка запроса прошла без системных ошибок
1 Необходимо указать CVC2/CVV2, поскольку у мерчатна нет разрешения на проведение оплаты без CVC
1 Неверный формат CVC
1 Неверный язык
2 Связка не найдена
2 Заказ с таким номером не найден
5 Доступ запрещен
5 Пользователь, осуществляющий вызов сервиса, должен изменить свой пароль
7 Системная ошибка
Пример запроса POST:
mdOrder=eb49300c-95b7-4dcd-9739-eee6c61f2ac4&bindingId=308042e8-2b28-484a-
811e-f786c9776c3b&cvc=123
Пример успешного ответа при SSL-платеже:
{"redirect":"http://ya.ru?orderId=eb49300c-95b7-4dcd-9739-eee6c61f2ac4","i
nfo":" , ...","errorCode":0}
Пример успешного ответа при 3DS-платеже:
{"info":" ,
...","acsUrl":"https://test.paymentgate.ru/acs/auth/start.do","paReq":"eJx
VUdtugkAQ/RXCOy7LRdQMa2ixKU28pGrfyTICqSzKpcW/765AbR8mOWcyOWfmDCy74qx9YVXn\
npfB1OjF1DQUvk1ykvn48vBgzfcngkFWI4R55WyGDNdZ1nKKWJ74+TVz05tPE8NyZbThOfDJmF
jcN\ni55Mz+MJzu25zmAXvOOVwWDEpM/EAjJSqVjxLBYNg5hfn6INcyxvappABgoFVlHIPCA9A
BEXyPb4\nhWKVp1mzyQUCuTeBl61oqhubOjaQkUBbnVnWNJcFId5sPuFlAUT1gDy8d61CtdTo8
oStw+C7r5W5\nCVNZx9v6ENmyfCBqApK4QWaZ1KXUcjVqLVx7Ycu77n2IC2XOqDqjh3BRDsGj/
5eDDLeS2Y+bjwyw\nu5QC5YRU/sVAHts+v6rceCODyfbb7m3bfmzD22dnlycaFHF+DGl0y6hK8
z6kFHMZity7l1QEiJIh\nw6PI8GOJ/v3+BweMtyE=","termUrl":"https://test.payment
gate.ru:443/testpayment/rest/finish3ds.do","errorCode":0}
Пример ответа с ошибкой:
{"error":"Access denied","errorCode":5,"errorMessage":"Access denied"}
14.3.2.2. Запрос деактивации связки
Для того, чтобы сделать существующую связку неактивной, используется запрос (см. раздел "КоординатыunBindCard.do
подключения").
Параметры запроса:
Название Тип Обязательно Описание
userName AN..30 да Логин магазина, полученный при подключении.
password AN..30 да Пароль магазина, полученный при подключении.
bindingId AN..255 да Идентификатор связки созданной при оплате заказа или использованной для оплаты. Присутствует только
если магазину разрешено создание связок.
Параметры ответа:
Название Тип Обязательно Описание
errorCode N3 нет Код ошибки.
errorMessage AN..512 нет Описание ошибки.
Коды ошибок (поле ):errorCode
Значение Описание
0 Обработка запроса прошла без системных ошибок
2 Неверное состояние связки (при попытке деактивировать неактивную связку
2 Связка не найдена
5 Доступ запрещён
5 Пользователь должен сменить свой пароль
7 Системная ошибка
Пример запроса GET:
https://server/application_context/rest/unBindCard.do?userName=userName&pa
ssword=password&bindingId=fd3afc57-c6d0-4e08-aaef-1b7cfeb093dc
Пример запроса POST:
bindingId=fd3afc57-c6d0-4e08-aaef-1b7cfeb093dc
Пример ответа:
{"errorCode":"2","errorMessage":"Binging isn't active"}
14.3.2.3. Запрос активации связки
Для активации деактивированной ранее связки используется запрос (см. раздел "Координаты подключения").bindCard.do
Параметры запроса:
Название Тип Обязательно Описание
userName AN..30 да Логин магазина, полученный при подключении.
password AN..30 да Пароль магазина, полученный при подключении.
bindingId AN..255 да Идентификатор связки созданной при оплате заказа или использованной для оплаты. Присутствует только
если магазину разрешено создание связок.
Параметры ответа:
Название Тип Обязательно Описание
errorCode N3 нет Код ошибки.
errorMessage AN..512 нет Описание ошибки.
Коды ошибок (поле ):errorCode
Значение Описание
0 Обработка запроса прошла без системных ошибок
2 Неверное состояние связки (при попытке активировать активную связку)
2 Связка не найдена
5 Доступ запрещён
5 Пользователь должен сменить свой пароль
7 Системная ошибка
Пример запроса GET:
https://server/application_context/rest/bindCard.do?userName=userName&pass
word=password&bindingId=fd3afc57-c6d0-4e08-aaef-1b7cfeb093dc
Пример запроса POST:
bindingId=fd3afc57-c6d0-4e08-aaef-1b7cfeb093dc
Пример ответа:
{"errorCode":"2","errorMessage":"Binding is active"}
14.3.2.4. Запрос изменения срока действия связки
Для изменения срока действия связки используется запрос (см. раздел "Координаты подключения").extendBinding.do
Параметры запроса:
Название Тип Обязательно Описание
userName AN..30 да Логин магазина, полученный при подключении.
password AN..30 да Пароль магазина, полученный при подключении.
bindingId ANS36 да Идентификатор связки созданной при оплате заказа или использованной для оплаты. Присутствует только
если магазину разрешено создание связок.
newExpiry N6 да Новая дата (год и месяц) окончания срока действия в формате YYYYMM
language A2 нет Язык в кодировке ISO 639-1. Если не указан, будет использован язык, указанный в настройках магазина как
язык по умолчанию (default language)
Параметры ответа:
Название Тип Обязательно Описание
errorCode N1 да Код завершения
errorMessage ANS..* (при ошибке) Сообщение об ошибке
Коды ошибок (поле ):errorCode
Значение Описание
0 Обработка запроса прошла без системных ошибок
1 Не указан или неверно указан один или несколько обязательных параметров
2 Связка не найдена
5 Доступ запрещён
5 Пользователь должен сменить свой пароль
7 Системная ошибка
Пример запроса GET:
https://server/application_context/rest/extendBinding.do?userName=userName
&password=password&bindingId=1eabfb8e-b90e-4dc8-bef6-14bd392b1cec&newExpir
y=201612&language=ru
Пример запроса POST:
bindingId=1eabfb8e-b90e-4dc8-bef6-14bd392b1cec&newExpiry=201612&language=ru
Пример ответа:
{"errorCode":"0","errorMessage":""}
14.3.2.5. Запрос списка связок по идентификатору клиента
Для получения списка связок по идентификатору клиента используется запрос (см. раздел "КоординатыgetBindings.do
подключения").
Параметры запроса:
Название Тип Обязательно Описание
clientId ANS..255 да Номер (идентификатор) клиента в системе магазина, переданный при регистрации заказа. Присутствует
только если магазину разрешено создание связок.
Параметры ответа:
Название Тип Обязательно Описание
errorCode N1 да Код завершения
errorMessage ANS..* (при ошибке) Сообщение об ошибке
Элемент binding (состоит из bindingId,
maskedPan и expiryDate):
bindingId AN..255 нет Идентификатор связки созданной при оплате заказа или использованной для
оплаты. Присутствует только если магазину разрешено создание связок.
maskedPan N..19 нет Маскированный номер карты, которая использовалась для оплаты. Указан только
после оплаты заказа.
expiryDate N6 нет Срок истечения действия карты в формате YYYYMM. Указан только после оплаты
заказа.
Коды ошибок (поле ):errorCode
Значение Описание
0 Обработка запроса прошла без системных ошибок
1 [clientId] не задан
2 Информация не найдена
5 Доступ запрещен
5 Пользователь должен сменить свой пароль
7 Системная ошибка
Пример запроса GET:
https://server/application_context/rest/getBindings.do?userName=userName&p
assword=password&clientId=client
Пример запроса POST:
clientId=client
Пример ответа:
{"bindings":[{"bindingId":"fd3afc57-c6d0-4e08-aaef-1b7cfeb093dc","maskedPa
n":"4000 00** ****
**02","expiryDate":"201512"}],"errorCode":"0","errorMessage":""}
14.3.2.6. Запрос списка связок определённой банковской карты
При наличии соответствующих разрешений магазин может запросить список всех связок, относящихся к определённой банковской
карте. Сделать это можно по номеру карты или по известному идентификатору связки.
Для получения списка связок банковской карты используется метод .getBindingsByCardOrId.do
В ответе возвращаются все связки, доступные мерчанту в соответствии с его настройками.
Параметры запроса:
Название Тип Обязательно Описание
userName AN..30 да Логин магазина, полученный при подключении
password AN..30 да Пароль магазина, полученный при подключении
pan N..19 нет Номер карты. Обязательно, если не указан .bindingId
Поиск по полному номеру карты доступен магазинам только при наличии соответствующего разрешения.
bindingId AN..255 нет Идентификатор связки. Обязательно, если не указан .pan
Если в запросе передаётся , то значение игнорируется.pan bindingId
showExpired boolean нет Параметр определяет необходимость отображать связки с истёкшим сроком действия карты. Возможные
значения: , . По умолчанию параметр принимает значение .true false false
Параметры ответа:
Название Тип Обязательно Описание
errorCode N1 да Код завершения.
errorMessage ANS..* да Описание кода завершения.
Элемент bindings (содержит блоки, состоящие из параметров bindingId,
):maskedPan, expiryDate и clientId
bindingId AN..255 нет Идентификатор связки.
maskedPan N..19 нет Маскированный номер карты, которая
использовалась для оплаты.
expiryDate N6 нет Срок истечения действия карты в
формате .YYYYMM
clientId ANS..255 нет Номер (идентификатор) клиента в
системе мерчанта.
Коды ошибок (поле ):errorCode
Значение Описание
0 Обработка запроса прошла без системных ошибок.
1 Не указан ни номер карты, ни идентификатор связки.
2 Информация не найдена.
5 Доступ запрещен.
5 Пользователь должен сменить свой пароль.
7 Системная ошибка.
Пример запроса:
https:/server/application_context/rest/getBindingsByCardOrId.do?userName=l
ogin&password=password&pan=4111111111111111
Параметры ответа:
{"errorCode":"0","errorMessage":"","bindings":[{"bindingId":"0b8edeb2-8380
-4092-bf7e-1e1a78f2b15e","maskedPan":"411111**1111","expiryDate":"201912",
"clientId":"12"},{"bindingId":"6a8c0738-cc88-4200-acf6-afc264d66cb0","mask
edPan":"411111**1111","expiryDate":"201912","clientId":"666"},{"bindingId"
:"97a70989-c1fb-49f7-8a42-27c19dc160dw","maskedPan":"411111**1111","expiry
Date":"201512","clientId":"666"}]}
15. Приложение 2. Коды ответа - расшифровка actionCode (ответ
процессинга)
Код ответа – это цифровое обозначение результата, к которому привело обращение к системе со стороны пользователя. В системе
определены следующие коды:
Action code - digital code of a result received after a client addressed to the system. The following codes exist in the system:
Action
code
error_id error_message Описание / Description Сообщение на платёжной странице / Message on the
payment page
-20010 -20010 BLOCKED_BY_LIMIT Транзакция отклонена по причине того, что размер
платежа превысил установленные лимиты
Банком-эмитентом /
Transaction is rejected since the amount exceeds limits
specified by the Issuing bank
Операция отклонена. Обратитесь в банк, выпустивший
карту. / Payment declined. Please, contact with your bank.
-9000 -9000 Started Состояние начала транзакции / State of transaction
start
Операция отклонена. Обратитесь в магазин. / Payment
declined. Please, contact with merchant.
-2102 -2102 Блокировка по имени
пассажира
Блокировка по имени пассажира / Regect by a
passanger name
Операция отклонена. Обратитесь в магазин. / Payment
declined. Please, contact with merchant.
-2101 -2101 Блокировка по e-mail Блокировка по e-mail / Reject by email Операция отклонена. Обратитесь в магазин. / Payment
declined. Please, contact with merchant.
-2020 -2020 Получен неверный ECI Получен неверный ECI. Код выставляется в том
случае, если пришедший в PaRes ECI не
соответствует допустимому значению для данной
МПС. Правило работает только для Mastercard
(01,02) и Visa (05,06), где значения в скобках -
допустимые для МПС. /
Invalid ECI. This code means that ECI received in PaRes
is not valid for the IPS. The rule applies only to
Mastercard (available values - 01,02) and Visa (available
values - 05,06)
Операция отклонена. Обратитесь в банк, выпустивший
карту. / Payment declined. Please, contact with your bank.
-2019 -2019 Decline by iReq in PARes PARes от эмитента содержит iReq, вследствие чего
платеж был отклонен /
PARes from the issuing bank contains iReq, which
caused the payment rejection
Операция отклонена. Обратитесь в банк, выпустивший
карту. / Payment declined. Please, contact with your bank.
-2018 -2018 Declined. DS connection timeout Directory server Visa или MasterCard либо недоступен,
либо в ответ на запрос вовлеченности карты (VeReq)
пришла ошибка связи. Это ошибка взаимодействия
платежного шлюза и серверов МПС по причине
технических неполадок на стороне последних. /
There is no access to Directory server Visa or MaterCard
or a connection error occured after card involvement
request (VeReq). This is an error of interacion between
payment gate and IPS servers due to technical problems
on the side of IPS servers.
Операция отклонена. Обратитесь в банк, выпустивший
карту. / Payment declined. Please, contact with your bank.
-2017 -2017 Отклонено. Статус PARes-а не
"Y"
Отклонено. Статус PARes-а не "Y"/ Rejected. PARes
status is not "Y"
Операция отклонена. Обратитесь в магазин. / Payment
declined. Please, contact with merchant.
-2016 -2016 Declined. VeRes status is
unknown
Банк-эмитент не смог определить, является ли карта
3dsecure. / Issuing bank could not determine if the card
is 3dsecure.
Операция отклонена. Обратитесь в банк, выпустивший
карту. / Payment declined. Please, contact with your bank.
-2015 -2015 Decline by iReq in VERes VERes от DS содержит iReq, вследствие чего платеж
был отклонен. / VERes from DS contains iReq, which
caused the payment rejection.
Операция отклонена. Обратитесь в банк, выпустивший
карту. / Payment declined. Please, contact with your bank.
-2013 -2013 Исчерпаны попытки оплаты Исчерпаны попытки оплаты. / All payment attempts
were used.
Операция отклонена. Проверьте введенные данные,
достаточность средств на карте и повторите операцию. /
Operation declined. Please check the data and available
balance of the card.
-2011 -2011 Declined. PaRes status is
unknown
Банк-эмитент не смог провести авторизацию
3dsecure-карты / Issuing bank was not able to perform
3dsecure card authorization.
Операция отклонена. Обратитесь в банк, выпустивший
карту. / Payment declined. Please, contact with your bank.
-2010 -2010 Несовпадение XID Несовпадение XID. / Mismatching of XID. Операция отклонена. Обратитесь в магазин. / Payment
declined. Please, contact with merchant.
-2007 2007 Decline. Payment time limit Истек срок, отведенный на ввод данных карты с
момента регистрации платежа (таймаут по
умолчанию - 20 минут; продолжительность сессии
может быть указана при регистрации заказа; если у
мерчанта установлена привилегия "Нестандартная
продолжительность сессии", то берётся период,
). / указнанный в настройках мерчанта
The period allotted for card details entering has expired
(by default timeout is 20 minutes; session duration may
be specified while order registering; if the merchant has
"Alternative session timeout" permission, then timeout
duration is specified in merchant settings).
Истек срок ожидания ввода данных. / Payment declined.
Please, contact with merchant.
-2006 2006 Decline. 3DSec decline Означает, что эмитент отклонил аутентификацию
(3DS авторизация не пройдена) / Means that issuing
bank rejected authentication (3DS authorization has not
been performed).
Операция невозможна. Аутентификация держателя карты
завершена неуспешно. / Payment declined. Please, contact
with your bank.
-2005 2005 Decline. 3DSec sign error Означает, что мы не смогли проверить подпись
эмитента, то есть PARes был читаемый, но подписан
неверно. / Means that RBS could not check issuing
bank sign, i.e. PARes was readable, but the sign was
wrong.
Операция отклонена. Обратитесь в банк, выпустивший
карту. / Payment declined. Please, contact with your bank.
-2003 -2003 Блокировка по порту Блокировка по порту. / Blocking by port. Операция отклонена. Обратитесь в магазин. / Payment
declined. Please, contact with merchant.
-2002 2002 Decline. Payment over limit Транзакция отклонена по причине того, что размер
платежа превысил установленные лимиты.
Примечание: имеется в виду либо лимиты
Банка-эквайера на дневной оборот Магазина, либо
лимиты Магазина на оборот по одной карте, либо
лимит Магазина по одной операции.
/
Transaction was rejected because payment amount
exceeded established limits. Note: it could be limit of day
withdrawal established by Bank-acquirer, or limit of
transaction by one card established by a merchant, or
limit for one transaction established by a merchant.
Операция отклонена. Обратитесь в магазин. / Payment
declined. Please, contact with merchant.
-2001 2001 Decline. IP blacklisted Транзакция отклонена по причине того, что IP-адрес
Клиента внесен в черный список. / Transaction is
rejected since Client's IP-address is in the black list.
Операция отклонена. Обратитесь в магазин. / Payment
declined. Please, contact with merchant.
-2000 2000 Decline. PAN blacklisted Транзакция отклонена по причине того, что карта
внесена в черный список. / Transaction is rejected
since card number in in the black list.
Операция отклонена. Обратитесь в магазин. / Payment
declined. Please, contact with merchant.
-100 -100 no_payments_yet Не было попыток оплаты. / There were not payment
attempts.
-
0 0 Approved. Платеж успешно прошел. / Payment has been
performed successfully.
-
1 1 Declined. Honor with id Для успешного завершения транзакции требуется
подтверждение личности. В случае
интернет-транзакции (соот-но и в нашем)
невозможно, поэтому считается как declined. / Proof of
identity is necessary for successful completion of the
transaction. In case of internet transaction (our case) it is
impossible, so transaction is considered as declined.
Операция отклонена. Обратитесь в банк, выпустивший
карту. / Payment declined. Please, contact with your bank.
5 5 Decline. Unable to process Отказ сети проводить транзакцию. / Refuse of network
to process transaction.
Операция отклонена. Обратитесь в банк, выпустивший
карту. / Payment declined. Please, contact with your bank.
15 15 DECLINED_BY_BADINSTIT МПС не смогла определить эмитента карты. / IPS
cannot identify the issuing bank.
Ошибка проведения платежа. Попробуйте позднее. Если
данная ошибка возникла повторно, обратитесь в Ваш банк
для разъяснения причин. Телефон банка должен быть
указан на обратной стороне карты. / Payment error. Try again
If this error occures repeatedly, please contact your banklater.
for more details. You can find bank telephone number on the
back side of your bank card.
53 53 DECLINED_BY_INVALID_ACCT Карты не существует в системах процессинга. / The
card does not exist in processing systems.
Операция отклонена. Обратитесь в магазин. / Payment
declined. Please, contact with merchant.
57 57 неизвестно Недопустимый тип операции для данного вида карты. Операция отклонена. Обратитесь в магазин.
81 81 DECLINED_BY_PINPROC Отказ в проведении операции со стороны
банка-эмитента.
Операция отклонена. Обратитесь в банк, выпустивший
карту. / Payment declined. Please, contact your issuing bank.
100 100 Decline. Card declined Ограничение по карте (Банк эмитент запретил
интернет транзакции по картe). / Card limits (Issuing
bank forbade internet transactions by the card).
Операция отклонена. Обратитесь в банк, выпустивший
карту. / Payment declined. Please, contact your bank.
101 101 Decline. Expired card Истек срок действия карты. / Card is expired. Операция отклонена. Проверьте введенные данные,
достаточность средств на карте и повторите операцию. /
Operation declined. Please check the data and available
balance of the card.
103 103 Decline. Call issuer Нет связи с Банком-Эмитентом. Торговой точке
необходимо связаться с банком-эмитентом. / There is
no connection with the Issuing bank. Sales oulet need to
contact Issuing bank.
Операция отклонена. Обратитесь в банк, выпустивший
карту. / Payment declined. Please, contact with your bank.
104 104 Decline. Card declined Попытка выполнения операции по счету, на
использование которого наложены ограничения. /
This is an attempt to perform a transaction by an account
that has restrictions for use.
Операция отклонена. Обратитесь в банк, выпустивший
карту. / Payment declined. Please, contact with your bank.
106 106 Превышено допустимое число
попыток ввода ПИН. Вероятно
карта временно
заблокирована.
Превышено допустимое число попыток ввода ПИН.
Вероятно карта временно заблокирована. / The
maximum number of attempts to enter PIN is exceeded.
It is possible that the card is blocked temporary.
Операция отклонена. Обратитесь в магазин. / Payment
declined. Please, contact with merchant.
107 107 Decline. Call issuer Следует обратиться к Банку-Эмитенту. / Please,
contact Issuing bank.
Операция отклонена. Обратитесь в банк, выпустивший
карту. / Payment declined. Please, contact with your bank.
109 109 Decline. Invalidnj merchant Неверно указан идентификатор мерчанта/терминала
или АСС заблокирован на уровне процессинга.
/
Merchant/terminal identifier is incorrect or ACC is
blocked on the processing level.
Операция отклонена. Обратитесь в магазин. / Payment
declined. Please, contact with merchant.
110 110 Decline. Invalid amount Неверно указана сумма транзакции. / Transaction
amount is incorrect.
Операция отклонена. Обратитесь в магазин. / Payment
declined. Please, contact with merchant.
111 111 Decline. No card record Неверный номер карты. / Card number is incorrect. Операция отклонена. Обратитесь в банк, выпустивший
карту. / Payment declined. Please, contact with your bank.
116 116 Decline. Not enough money Сумма транзакции превышает доступный остаток
средств на выбранном счете. / Transaction amount
exceeds the available balance of the selected account.
Операция отклонена. Проверьте введенные данные,
достаточность средств на карте и повторите операцию. /
Operation declined. Please check the data and available
balance of the card.
117 117 INCORRECT PIN Неверно указан пин код (не для интернет транзакций)
/ Incorrect PIN (not for internet transactions).
Операция отклонена. Проверьте введенные данные,
достаточность средств на карте и повторите операцию. /
Operation declined. Please check the data and available
balance of the card.
118 118 Сервис не разрешен Сервис не разрешён (отказ от эмитента). / Service is
not allowed .(rejection came from the issuer)
Операция отклонена. Обратитесь в банк, выпустивший
карту. / Payment declined. Please, contact with your bank.
119 119 Decline.
SECURITY_VIOLATION из SV
Транзакция незаконна. / Illegal transaction. Операция отклонена. Обратитесь в банк, выпустивший
карту. / Payment declined. Please, contact with your bank.
120 120 Decline. Not allowed Отказ в проведении операции - транзакция не
разрешена эмитентом. Код ответа платежной сети -
57. Причины отказа необходимо уточнять у эмитента.
/
Refusal to perform the operation - the transaction is not
allowed by Issuing bank. Response code of the IPS - 57.
Reasons for rejection should be specified an the issuing
bank.
Операция отклонена. Обратитесь в банк, выпустивший
карту. / Payment declined. Please, contact with your bank.
121 121 Decline. Excds wdrwl limt Предпринята попытка выполнить транзакцию на
сумму, превышающую дневной лимит, заданный
банком-эмитентом. / This is an attempt to perform
transaction of amount exceeding the day limit
established by the issuing bank.
Операция отклонена. Обратитесь в банк, выпустивший
карту. / Payment declined. Please, contact with your bank.
123 123 Decline. Excds wdrwl ltmt Превышен лимит на число транзакций: клиент
выполнил максимально разрешенное число
транзакций в течение лимитного цикла и пытается
провести еще одну. / The client has performed the
maximum number of transactions during the limit cycle
and tries to perform another one.
Операция отклонена. Обратитесь в банк, выпустивший
карту. / Payment declined. Please, contact with your bank.
125 125 Decline. Card declined Неверный номер карты. Подобная ошибка может
означать ряд вещей: Попытка возврата на сумму,
больше холда, попытка возврата нулевой
суммы. Для AmEx - неверно указан срок действия
карты.
/
Card number is incorrect. This error may have several
meanings: Attempt to perform a refund of amount
exceeding the hold amount; Attempt to refund zero
amount; for AmEx - expiry date is specified incorrectly.
Операция отклонена. Проверьте введенные данные,
достаточность средств на карте и повторите операцию. /
Operation declined. Please check the data and available
balance of the card.
208 208 Decline. Card is lost Карта утеряна. / Card is lost. Операция отклонена. Обратитесь в магазин. / Payment
declined. Please, contact with merchant.
209 209 Decline. Card limitations
exceeded
Превышены ограничения по карте. / Card limitations
exceeded.
Операция отклонена. Обратитесь в магазин. / Payment
declined. Please, contact with merchant.
400 400 Реверсал обработан. Реверсал обработан. / Reversal is processed. -
902 902 Decline. Invalid trans Ограничение по карте (Владелец карты пытается
выполнить транзакцию, которая для него не
разрешена). / Card limitations (Cardholder tries to
perform a transaction that is forbidden for him).
Операция отклонена. Обратитесь в банк, выпустивший
карту. / Payment declined. Please, contact with your bank.
903 903 Decline. Re-enter trans. Предпринята попытка выполнить транзакцию на
сумму, превышающую лимит, заданный
банком-эмитентом. / Attempt to perform a transaction of
amount exceeding Issuing bank limit.
Операция отклонена. Обратитесь в банк, выпустивший
карту. / Payment declined. Please, contact with your bank.
904 904 Decline. Format error Ошибочный формат сообщения с точки зрения банка
эмитента. / The message format is incorrect in terms of
the issuing bank.
Операция отклонена. Обратитесь в банк, выпустивший
карту. / Payment declined. Please, contact with your bank.
907 907 Decline. Host not avail. Нет связи с Банком, выпустившим Вашу карту. Для
данного номера карты не разрешена авторизация в
режиме stand-in (этот режим означает, что эмитент
не может связаться с платежной сетью и поэтому
транзакция возможна либо в оффлайне с
последующей выгрузкой в бэк офис, либо она будет
отклонена).
/
There is no connection with the Issuing bank.
Authorization in stand-in mode is not allowed for this
card number (this mode means that the Issuing bank is
unable to connect to the IPS, and therefore the
transaction can be either offline with further unloading to
back office, or it can be declined).
Нет связи с банком. Повторите позже. / Can't connect with
your bank. Please, contact with your bank.
909 909 Decline. Call issuer Невозможно провести операцию (Ошибка
функционирования системы, имеющая общий
характер. Фиксируется платежной сетью или
банком-эмитентом). / Operation is impossible (General
error of the system functioning. May be detected by IPS
or the Issuing bank).
Операция отклонена. Обратитесь в банк, выпустивший
карту. / Payment declined. Please, contact with your bank.
910 910 Decline. Host not avail. Банк-эмитент недоступен. / Issuing bank is not
available.
Нет связи с банком. Повторите позже. / Can't connect with
your bank. Please, contact with your bank.
913 913 Decline. Invalid trans Неверный формат сообщения (Неправильный
формат транзакции с точки зрения сети). / The
message format is incorrect in terms of IPS.
Операция отклонена. Обратитесь в банк, выпустивший
карту. / Payment declined. Please, contact with your bank.
914 914 Decline. Orig trans not found Не найдена транзакция (когда посылается
завершение или reversal или refund). / Transaction is
not found (when sending a completion, reversal or refund
request).
Операция отклонена. Обратитесь в магазин. / Payment
declined. Please, contact with merchant.
999 999 Declined by fraud Отсутствует начало авторизации транзакции.
Отклонено по фроду или ошибка 3dsec. / The
beginning of the transaction authorization is missed.
Declined by fraud.
Операция отклонена. Обратитесь в магазин. / Payment
declined. Please, contact with merchant.
1001 1001 Decline. Data input timeout Пусто (Выставляется в момент регистрации
транзакции, т.е. когда еще по транзакции не было
введено данных карт). / Empty (is specified at the
moment of transaction authorization, when card details
are not entered yet).
Не получен ответ от банка. Повторите позже. / Processing
timeout. Please, try again later.
2002 2002 Неверная операция Неверная операция. / Incorrect operation. Операция отклонена. Обратитесь в магазин. / Payment
declined. Please, contact with merchant.
2003 2003 Decline. SSL restricted SSL (Не 3d-Secure/SecureCode) транзакции
запрещены Магазину. / SSL (not
3D-Secure/SecureCode) transactions are forbidden for
the Merchant.
Операция отклонена. Обратитесь в магазин. / Payment
declined. Please, contact with merchant.
2004 2004 SSL without CVC forbidden Оплата через SSL без ввода CVС2 запрещена. /
Payment through SSL without CVC2 is forbidden.
Операция отклонена. Обратитесь в магазин. / Payment
declined. Please, contact with merchant.
2005 2005 3DS rule failed Платеж не соотвествует условиям правила проверки
по 3ds. / Payment does not meet terms of the rule of 3ds
validation.
Операция отклонена. Обратитесь в магазин. / Payment
declined. Please, contact with merchant.
2006 2006 Однофазные платежи
запрещены
Однофазные платежи запрещены. / One-phase
payments are forbidden.
Операция отклонена. Обратитесь в магазин. / Payment
declined. Please, contact with merchant.
2007 2007 Заказ уже оплачен Заказ уже оплачен. / The order is payed. Операция отклонена. Обратитесь в магазин. / Payment
declined. Please, contact with merchant.
2008 2008 Транзакция ещё не завершена Транзакция ещё не завершена. / The transaction is not
completed.
Операция отклонена. Обратитесь в магазин. / Payment
declined. Please, contact with merchant.
2009 2009 Сумма возврата превышает
сумму оплаты
Сумма возврата превышает сумму оплаты. / Refund
amount exceeds deposited amount.
Операция отклонена. Обратитесь в магазин. / Payment
declined. Please, contact with merchant.
2014 2014 Ошибка выполнения
3DS-правила
Ошибка выполнения 3DS-правила / Error of 3DS rule
execution.
Операция отклонена. Обратитесь в магазин. / Payment
declined. Please, contact with merchant.
2015 2015 Terminal select rule error Ошибка выполнения правила выбора терминала
(правило некорректно). / Terminal select rule error (rule
is incorrect).
Операция отклонена. Обратитесь в магазин. / Payment
declined. Please, contact with merchant.
2016 2016 TDS_FORBIDDEN Мерчант не имеет разрешения на 3-D Secure,
необходимое для проведения платежа. / 3-D Secure
payment is necessary, but the merchant does not have
permission for 3-D Secure payment.
Операция отклонена. Обратитесь в магазин. / Payment
declined. Please, contact with merchant.
2023 2023 Достигнут лимит потоков Очередь на запросов на обработку в процессинг
превысила допустимый лимит.
Ошибка проведения платежа. Попробуйте позднее.
71015 1015 Decline. Input error Введены неправильные параметры карты. / Entered
card details are incorrect.
Операция отклонена. Проверьте введенные данные,
достаточность средств на карте и повторите операцию. /
Operation declined. Please check the data and available
balance of the card.
151018 018 Decline. Processing timeout Таймаут в процессинге. Не удалось отправить. /
Processing timeout. Sending is failed.
Не получен ответ от банка. Повторите позже. / Processing
timeout. Please, try again later.
151019 1019 Decline. Processing timeout Таймаут в процессинге. Удалось отправить, но не
получен ответ от банка. / Processing timeout. Sending
is success, response from the bank was not received.
Не получен ответ от банка. Повторите позже. / Processing
timeout. Please, try again later.
341014 1014 Decline. General Error Код отказа платёжного шлюза. / Payment gate general
error.
Операция отклонена. Обратитесь в магазин. / Payment
declined. Please, contact with merchant.
16. Приложение 3. Оплата из мобильного приложения с использованием
Apple Pay
16.1. Общие сведения
16.1.1. Действия продавца, необходимые для подключения к Apple Pay
Перед тем, как принимать платежи с помощью Applу Pay, выполните действия, представленные в секциях ниже. После выполнения
указанных действий вы можете приступать к доработке своего мобильного приложения для взаимодействия с Apple Pay (описание
При настройке варианта оплаты Apple Pay для веб-версий необходимо предоставить покупателю выбор способа оплаты:
банковская карта или оплата с помощью Apple Pay, добавив дополнительный вариант оплаты на информационной странице
интернет-магазина. Описанные ниже методы API функционируют как для мобильных версий, так и для веб-версий интеграции.
1.
2.
3.
4.
5.
6.
7.
1.
2.
3.
4.
5.
6.
7.
8.
указанных действий вы можете приступать к доработке своего мобильного приложения для взаимодействия с Apple Pay (описание
технических подробностей таких доработок не входит в задачи настоящего документа, подробнее см. документацию Apple Pay).
16.1.1.1. Действия в личном кабинете платёжного шлюза
В личном кабинете сформируйте ключевую пару и выгрузите запрос подписи сертификата открытого ключа. Эта процедура описана в
документе «Инструкция администратора по работе с консолью».
16.1.1.2. Создание Merchant ID
Чтобы создать свой Merchant ID (Идентификатор продаваца), выполните следующие действия.
В личном кабинете (Партнёрский центр) Apple перейдите в раздел (Сертификаты,Member Center Certificates, Identifiers & Profiles
идентификаторы и профили).
На отобразившейся странице в секции (Идентификаторы) слева выберите (Идентификаторы продавцов).Identifiers Merchant IDs
На отобразившейся странице щёлкните на значке ( (Добавить)) в правом верхнем углу.+ Add
В полях (Описание идентификатора продавца) и (Идентификатор) введите описание своегоMerchant ID Descritpion Identifier
идентификатора продавца Apple и сам идентификатор соответственно.
Нажмите (Продолжить).Continue
На отобразившейся странице проверьте введённые данные и нажмите (Зарегистрировать).Register
На отобразившейся странице нажмите (Готово).Done
16.1.1.3. Создание сертификата для Merchant ID
Чтобы создать сертификат для своего Merchant ID (Идентификатора продавца), выполните следующие действия.
В личном кабинете (Партнёрский центр) Apple перейдите в раздел (Сертификаты,Member Center Certificates, Identifiers & Profiles
идентификаторы и профили).
На отобразившейся странице в секции (Идентификаторы) слева выберите (Идентификаторы продавцов).Identifiers Merchant IDs
Выберите свой Merchant ID (Идентификатор продавца) из списка и нажмите (Редактировать).Edit
Нажмите (Создать сертификат), после чего нажмите (Продолжить).Create Certificate Continue
Нажмите (Выбрать файл), укажите путь к файлу запросу подписи сертификата, выгруженному из личного кабинетаChoose File
платёжного шлюза.
Нажмите (Сгенерировать).Generate
Нажмите (Загрузить), чтобы загрузить созданный сертификат на компьютер.Download
После загрузки сертификата нажмите (Готово).Done
16.1.2. Схема взаимодействия при оплате из мобильного приложения
При оплате с использованием Apple Pay взаимодействие происходит по следующей схеме.
Для завершения этой процедуры у вас должна быть учётная запись Apple Developer (Разработчик Apple).
Идентификатор следует начать со слова , например, .merchant merchant.ru.test.sale
Процедура создания файла запроса подписи сертификата представлена в документе «Инструкция администратора по
работе с консолью».
1.
2.
3.
4.
5.
6.
7.
8.
9.
Описание схемы приведено ниже.
Пользователь в мобильном приложении выбирает вариант оплаты с помощью Apple Pay.
Сведения о платеже направляются на обработку в систему Apple Pay.
Для обработки данных о платеже в системе Apple Pay создаётся объект , который содержит свойство PKPaymentToken Object
(здесь и далее см. ).paymentData документацию Apple Pay
Apply Pay направляет продавцу (мобильному приложению) ответ.
Продавец извлекает из полученного объекта свойство и кодирует его содержимое вPKPaymentToken Object paymentData
Base64.
Продавец создаёт запрос на оплату, содержащий в том числе свойство , полученное из ответа системы Apple PaypaymentData
и закодированное в Base64, и отправляет его на обработку в платёжный шлюз (см. пункт «Запрос на оплату через Apple Pay» в
подразделах и для интерфейсов WS и REST соответственно). Интерфейс на Web-Service Интерфейс REST
Платёжная система обрабатывает запрос.
Платёжная система возвращает ответ с результатом.
Мобильное приложение отображает пользователю результат оплаты.
16.1.3. Apple Pay - ссылки на справочную информацию
В таблице ниже представлены ссылки на справочную информацию об Apple Pay.
Ссылка
https://www.apple.com/apple-pay/
https://developer.apple.com/apple-pay/
https://developer.apple.com/support/apple-pay-sandbox/
https://developer.apple.com/apple-pay/Getting-Started-with-Apple-Pay.pdf
https://developer.apple.com/apple-pay/Apple-Pay-Identity-Guidelines.pdf
https://developer.apple.com/library/ios/ApplePay_Guide/
https://developer.apple.com/app-store/review/guidelines/#apple-pay
https://developer.apple.com/library/ios/documentation/UserExperience/Reference/PassKit_Framework/index.html#//apple_ref/doc/uid/TP40012158
https://developer.apple.com/library/ios/documentation/PassKit/Reference/PaymentTokenJSON/PaymentTokenJSON.html#//apple_ref/doc/uid/TP40014929
https://devforums.apple.com/community/ios/connected/applepay/
16.2. Запрос на оплату Apple Pay
16.2.1. Интерфейс REST
Запрос на оплату с помощью Apple Pay в платёжный шлюз
Для регистрации заказа используется запрос (см. раздел ).payment.do Координаты подключения
Пример запроса POST
{"merchant":"merchant_name","orderNumber":"applepay123456794","description
":"descritpion_text",
"paymentToken":"eyJ2ZXJzaW9uIjoiRUNfdjEiLCJkYXRhIjoiNTFhUTNGOXl0Q1YwYTdpQS
9mMUh0RGc1TnBvSVZtc2RFa1FvTlpoOW95ZVA3eGgvVDk4dXJkenJDN0dOQ3o4c1FodXpXOVZN
WUhGU25DTytTWXo0eDYrTnZwZjdCUzhOcnlUWk1Keldtcml0VUZJVytwVjNvNWY4M0F3OU55c1
BCMlAxZGZicS9hZDVzV1RwZTMwTnV2UDltRGhaUStET1M3RzB6MDZSNHRXY0R0VFErT0U5YlI1
OHFQRUdnTTRiSmRmUklZb25oQlJrdWY2cGw4aU9PQ0VvS01QN2lRck84Z2IrVGNnSjVZSDdDL3
J3enBDUVZjMGQxNWJuME9wbE1SOGwxMDcrMDR4ZVVWT3BUMGI3cHRmYnA3VmVaeHVXaHhSTTlH
YlF5QmVkVlJHQ2toN3kyREtZY3BRdjJqM1h2L0NjNzRKaVBZM09DTFVEMEIvS0UwUFo1TnJvUE
JFUmZ2a1B4WUFzV1ZmM1E3UUtTcTk4Z3p5UXlrWEpwTmFwcEt6cENDMkNKU09XdzVkenNPWjAi
LCAic2lnbmF0dXJlIjoiTUlBR0NTcUdTSWIzRFFFSEFxQ0FNSUFDQVFFeER6QU5CZ2xnaGtnQl
pRTUVBZ0VGQURDQUJna3Foa2lHOXcwQkJ3RUFBS0NBTUlJRDVqQ0NBNHVnQXdJQkFnSUlhR0Qy
bWRuTXB3OHdDZ1lJS29aSXpqMEVBd0l3ZWpFdU1Dd0dBMVVFQXd3bFFYQndiR1VnUVhCd2JHbG
pZWFJwYjI0Z1NXNTBaV2R5WVhScGIyNGdRMEVnTFNCSE16RW1NQ1FHQTFVRUN3d2RRWEJ3YkdV
Z1EyVnlkR2xtYVdOaGRHbHZiaUJCZFhSb2IzSnBkSGt4RXpBUkJnTlZCQW9NQ2tGd2NHeGxJRW
x1WXk0eEN6QUpCZ05WQkFZVEFsVlRNQjRYRFRFMk1EWXdNekU0TVRZME1Gb1hEVEl4TURZd01q
RTRNVFkwTUZvd1lqRW9NQ1lHQTFVRUF3d2ZaV05qTFhOdGNDMWljbTlyWlhJdGMybG5ibDlWUX
pRdFUwRk9SRUpQV0RFVU1CSUdBMVVFQ3d3TGFVOVRJRk41YzNSbGJYTXhFekFSQmdOVkJBb01D
a0Z3Y0d4bElFbHVZeTR4Q3pBSkJnTlZCQVlUQWxWVE1Ga3dFd1lIS29aSXpqMENBUVlJS29aSX
pqMERBUWNEUWdBRWdqRDlxOE9jOTE0Z0xGRFptMFVTNWpmaXFRSGRiTFBnc2MxTFVtZVkrTTlP
dmVnYUphakNIa3d6M2M2T0twYkM5cStoa3dORnhPaDZSQ2JPbFJzU2xhT0NBaEV3Z2dJTk1FVU
dDQ3NHQVFVRkJ3RUJCRGt3TnpBMUJnZ3JCZ0VGQlFjd0FZWXBhSFIwY0RvdkwyOWpjM0F1WVhC
d2JHVXVZMjl0TDI5amMzQXdOQzFoY0hCc1pXRnBZMkV6TURJd0hRWURWUjBPQkJZRUZBSWtNQX
VhN3UxR01aZWtwbG9wbmtKeGdoeEZNQXdHQTFVZEV3RUIvd1FDTUFBd0h3WURWUjBqQkJnd0Zv
QVVJL0pKeEUrVDVPOG41c1QyS0d3L29ydjlMa3N3Z2dFZEJnTlZIU0FFZ2dFVU1JSUJFRENDQV
F3R0NTcUdTSWIzWTJRRkFUQ0IvakNCd3dZSUt3WUJCUVVIQWdJd2diWU1nYk5TWld4cFlXNWpa
U0J2YmlCMGFHbHpJR05sY25ScFptbGpZWFJsSUdKNUlHRnVlU0J3WVhKMGVTQmhjM04xYldWek
lHRmpZMlZ3ZEdGdVkyVWdiMllnZEdobElIUm9aVzRnWVhCd2JHbGpZV0pzWlNCemRHRnVaR0Z5
WkNCMFpYSnRjeUJoYm1RZ1kyOXVaR2wwYVc5dWN5QnZaaUIxYzJVc0lHTmxjblJwWm1sallYUm
xJSEJ2YkdsamVTQmhibVFnWTJWeWRHbG1hV05oZEdsdmJpQndjbUZqZEdsalpTQnpkR0YwWlcx
bGJuUnpMakEyQmdnckJnRUZCUWNDQVJZcWFIUjBjRG92TDNkM2R5NWhjSEJzWlM1amIyMHZZMl
Z5ZEdsbWFXTmhkR1ZoZFhSb2IzSnBkSGt2TURRR0ExVWRId1F0TUNzd0thQW5vQ1dHSTJoMGRI
QTZMeTlqY213dVlYQndiR1V1WTI5dEwyRndjR3hsWVdsallUTXVZM0pzTUE0R0ExVWREd0VCL3
dRRUF3SUhnREFQQmdrcWhraUc5Mk5rQmgwRUFnVUFNQW9HQ0NxR1NNNDlCQU1DQTBrQU1FWUNJ
UURhSEdPdWkrWDJUNDRSNkdWcE43bTJuRWNyNlQ2c01qT2haNU51U28xZWd3SWhBTDFhKy9ocD
g4REtKMHN2M2VUM0Z4V2NzNzF4bWJMS0QvUUozbVdhZ3JKTk1JSUM3akNDQW5XZ0F3SUJBZ0lJ
U1cwdnZ6cVkycGN3Q2dZSUtvWkl6ajBFQXdJd1p6RWJNQmtHQTFVRUF3d1NRWEJ3YkdVZ1VtOX
ZkQ0JEUVNBdElFY3pNU1l3SkFZRFZRUUxEQjFCY0hCc1pTQkRaWEowYVdacFkyRjBhVzl1SUVG
MWRHaHZjbWwwZVRFVE1CRUdBMVVFQ2d3S1FYQndiR1VnU1c1akxqRUxNQWtHQTFVRUJoTUNWVk
13SGhjTk1UUXdOVEEyTWpNME5qTXdXaGNOTWprd05UQTJNak0wTmpNd1dqQjZNUzR3TEFZRFZR
UUREQ1ZCY0hCc1pTQkJjSEJzYVdOaGRHbHZiaUJKYm5SbFozSmhkR2x2YmlCRFFTQXRJRWN6TV
NZd0pBWURWUVFMREIxQmNIQnNaU0JEWlhKMGFXWnBZMkYwYVc5dUlFRjFkR2h2Y21sMGVURVRN
QkVHQTFVRUNnd0tRWEJ3YkdVZ1NXNWpMakVMTUFrR0ExVUVCaE1DVlZNd1dUQVRCZ2NxaGtqT1
Для операций отмены, возврата и завершения платежа следует использовать стандартные запросы к платёжному шлюзу.
BRSUJCZ2dxaGtqT1BRTUJCd05DQUFUd0Z4R0VHZGRraGRVYVhpV0JCM2JvZ0tMdjNudXVUZUNO
L0V1VDRUTlcxV1piTmE0aTBKZDJEU0pPZTdvSS9YWVh6b2pMZHJ0bWNMN0k2Q21FLzFSRm80SD
NNSUgwTUVZR0NDc0dBUVVGQndFQkJEb3dPREEyQmdnckJnRUZCUWN3QVlZcWFIUjBjRG92TDI5
amMzQXVZWEJ3YkdVdVkyOXRMMjlqYzNBd05DMWhjSEJzWlhKdmIzUmpZV2N6TUIwR0ExVWREZ1
FXQkJRajhrbkVUNVBrN3lmbXhQWW9iRCtpdS8wdVN6QVBCZ05WSFJNQkFmOEVCVEFEQVFIL01C
OEdBMVVkSXdRWU1CYUFGTHV3M3FGWU00aWFwSXFaM3I2OTY2L2F5eVNyTURjR0ExVWRId1F3TU
M0d0xLQXFvQ2lHSm1oMGRIQTZMeTlqY213dVlYQndiR1V1WTI5dEwyRndjR3hsY205dmRHTmha
ek11WTNKc01BNEdBMVVkRHdFQi93UUVBd0lCQmpBUUJnb3Foa2lHOTJOa0JnSU9CQUlGQURBS0
JnZ3Foa2pPUFFRREFnTm5BREJrQWpBNnozS0RVUmFac1liN05jTld5bUsvOUJmdDJROTFUYUtP
dnZHY2dWNUN0NG40bVBlYldaK1kxVUVOajUzcHd2NENNREl0MVVRaHNLTUZkMnhkOHpnN2tHZj
lGM3dzSVcyV1Q4WnlhWUlTYjFUNGVuMGJtY3ViQ1lraFlRYVpEd21TSFFBQU1ZSUJYekNDQVZz
Q0FRRXdnWVl3ZWpFdU1Dd0dBMVVFQXd3bFFYQndiR1VnUVhCd2JHbGpZWFJwYjI0Z1NXNTBaV2
R5WVhScGIyNGdRMEVnTFNCSE16RW1NQ1FHQTFVRUN3d2RRWEJ3YkdVZ1EyVnlkR2xtYVdOaGRH
bHZiaUJCZFhSb2IzSnBkSGt4RXpBUkJnTlZCQW9NQ2tGd2NHeGxJRWx1WXk0eEN6QUpCZ05WQk
FZVEFsVlRBZ2hvWVBhWjJjeW5EekFOQmdsZ2hrZ0JaUU1FQWdFRkFLQnBNQmdHQ1NxR1NJYjNE
UUVKQXpFTEJna3Foa2lHOXcwQkJ3RXdIQVlKS29aSWh2Y05BUWtGTVE4WERURTJNVEV3TVRBNU
5UY3dObG93THdZSktvWklodmNOQVFrRU1TSUVJQWpSdk9nWkxDa0w5ZmNCZjdOSm5RY3hsd2lt
L09ieHkrcEltZ1M0TGRUYU1Bb0dDQ3FHU000OUJBTUNCRWN3UlFJZ1BKaHlkTXE5UDdTaHJFT2
RxVk5KUk84QnN1MC93SXNCS0Y1cnlFR0JPSDRDSVFEeWo4Wml3VVV5alRJUFRUZDBKTTlaMExI
dGZTQVhOWVN2T0t4eGN3MTlod0FBQUFBQUFBPT0iLCJoZWFkZXIiOnsiZXBoZW1lcmFsUHVibG
ljS2V5IjoiTUZrd0V3WUhLb1pJemowQ0FRWUlLb1pJemowREFRY0RRZ0FFNUdmb2t2U2Z3WnV3
aXYwSGxKVE1MS0dlMS96dWtjejczSFlvVjh5cjNGNWdmZmthVmNQTmptNjFhdFNOZm9UZUxiSn
Q1aHBLWkJuSWlwZlVXSXZxMmc9PSIsInB1YmxpY0tleUhhc2giOiJLMG9KcmJiYURVUDh6YitS
1.
2.
3.
UEZhTmxVUTdTU2I3T1FEWERVeU9vM0JXdDJzPSIsInRyYW5zYWN0aW9uSWQiOiIyYTNkZjhjND
g0Y2JmMDg1OTgyN2Y0ZDBkZjhkYjY4YjYyNjBlNTIxYWUwZmI4YjI1NDRmNzNiM2RlMDVlYjE5
In19","language":"ru","additionalParameters":{},"preAuth":"true"}
Описание параметров запроса приведено в таблице ниже.
Параметр Тип
данных
Обязательный
параметр
Описание
merchant AN..30 Да Имя входа продавца в системе платёжного шлюза.
orderNumber AN..32 Да Уникальный номер заказа на стороне продавца.
description ANS..512 Нет Описание заказа в свободной форме. В процессинг банка для включения в финансовую
отчётность продавца передаются только первые 24 символа этого поля.
language A2 Нет Язык в кодировке ISO 639-1. Если не указан, будет использован язык, указанный в
настройках магазина как язык по умолчанию.
additionalParameters AN..1024 Нет Дополнительные параметры заказа, которые сохраняются для просмотра из личного
кабинета продавца. Дополнительные параметры следует указывать в следующем формате.
"_": "_"
Каждую новую пару имени и значения параметра следует отделять запятой.
preAuth A..5 Нет Параметр, определяющий необходимость предварительной авторизации (блокирования
средств на счету клиента до их списания). Доступны следующие значения:
true (истина) - параметр включён, оплата происходит с предавторизацией (происходит
блокирование средств клиента до списания);
false (ложь) - параметр выключен (списание происходит сразу).
Если параметр не указан в запросе, списание происходит сразу.
paymentToken AN..8192 Да Параметр должен содержать закодированное в Base64 значение свойства paymentToken p
, полученного из объекта от системы Apple PayaymentData PKPaymentToken Object
(подробнее см. ). Таким образом, чтобы сделать запрос на оплату вдокументацию Apple Pay
платёжный шлюз, продавец должен:
получить от системы Apple Pay объект , содержащийPKPaymentToken Object
свойство ;paymentData
извлечь значение свойства и закодировать его в Base64;paymentData
включить закодированное значение свойства в качестве значенияpaymentData
парамера в запросе на оплату, который продавец направит вpaymentToken
платёжный шлюз.
Примеры и описание ответа
Успешная оплата
Если у продавца настроена фискализация, при указании в качестве
дополнительных параметров (адрес электронной почты покупателя) и/или email
(номер сотового телефона покупателя) эти параметры в первую очередьphone
используются для отправки фискального чека.
{
"success": true,
"data": {
"orderId": "b926351f-a634-49cf-9484-ccb0a3b8cfad"
},
"orderStatus": {
"errorCode": "0",
"orderNumber": "229",
"orderStatus": 1,
"actionCode": 0,
"actionCodeDescription": "",
"amount": 960000,
"currency": "643",
"date": 1478682458102,
"ip": "81.18.144.51",
"merchantOrderParams": [
{
"name": "param2",
"value": "param2"
},
{
"name": "param1",
"value": "param1"
}
],
"attributes": [
{
"name": "mdOrder",
"value": "b926351f-a634-49cf-9484-ccb0a3b8cfad"
}
],
"cardAuthInfo": {
"expiration": "201907",
"cardholderName": "CARD HOLDER",
"approvalCode": "123456",
"pan": "520424**0010"
},
"authDateTime": 1478682459082,
"terminalId": "12345678",
"authRefNum": "111111111111",
"paymentAmountInfo": {
"paymentState": "APPROVED",
"approvedAmount": 960000,
"depositedAmount": 0,
"refundedAmount": 0
},
"bankInfo": {
"bankCountryName": "<>"
}
}
}
Неуспешная оплата
Неуспешная оплата
{
"error": {
"code": 1,
"description": "Processing Error",
"message": " "
},
"success": false
}
Описание параметров ответа приведено в таблице ниже.
Параметр Вложенный параметр Тип
данных
Обязательный
параметр
Описание
success Не актуально A..5 Да Указывает на успешность проведения платежа. Доступны
следующие значения:
true (истина) - платёж прошёл успешно;
false (ложь) - платёж не прошёл.
data
(возвращается, только если платёж
прошёл успешно)
orderId ANS36 Да Уникальный для продавца номер заказа в платёжной системе.
error
(возвращается, только если платёж не
прошёл)
code N3 Да Код ошибки. Возможны следующие коды ошибок (см. таблицу
ниже).
Код
ошибки
Сообщение
4 Некорректное значение параметра
[paymentToken.signature], проверка не пройдена
10 Некорректное значение параметра [merchant]
Некорректное значение параметра [orderNumber]
Некорректное значение параметра [paymentToken]
Некорректное значение параметра
[paymentToken.version]
Некорректное значение параметра
[paymentToken.header]
Некорректное значение параметра
[paymentToken.signature]
Некорректное значение параметра
[paymentToken.header.transactionId]
Некорректное значение параметра
[paymentToken.header.wrappedKey]
Некорректное значение параметра
[paymentToken.header.publicKeyHash]
Авторизация неуспешна
description ANS..512 Да Подробное техническое объяснение ошибки - содержимое этого
параметра не предназначено для отображения пользователю.
message AN..512 Да Понятное описание ошибки - предназначено для отображения
пользователю.
orderStatus
(содержит параметры состояния заказа и
возвращается, только если платёж шлюз
признал все параметры запроса верными)
errorCode N3 Нет Код ошибки. Список возможных кодов ошибок представлен в
описании .запроса состояния заказа
orderNumber AN..32 Да Номер (идентификатор) заказа в системе магазина, уникален для
каждого магазина в пределах системы.
orderStatus N..2 Нет По значению этого параметра определяется состояние заказа в
платёжной системе:
0- платёж прошёл без ошибок;
7 - произошла внутренняя ошибка системы, платёж не
прошёл.
actionCode N..5 Да Коды ответа - цифровое обозначение результата, к которому
привело обращение к системе со стороны пользователя. Коды,
принятые в системе, представлены в приложении Коды ответа -
.расшифровка actionCode
actionCodeDescription AN..512 Да Расшифровка кода ответа на языке, переданном в параметре
запроса .language
amount N..20 Да Сумма платежа в минимальных единицах валюты (например, в
копейках или центах).
currency N3 Нет Код валюты платежа ISO 4217. Единственное допустимое
значение - 643.
date ANS Да Дата регистрации заказа в формате UNIX-времени
(POSIX-времени).
ip AN..20 Да IP-адрес покупателя.
merchantOrderParams AN..1024 Нет Параметр, содержащий атрибуты, в которых передаются
дополнительные параметры продавца:
name - название дополнительного параметра;
value - значение дополнительного параметра.
attributes AN..1024 Да Атрибуты заказа в платёжной системе (номер заказа):
name - название атрибута, всегда принимает значение mdO
;rder
value - номер заказа в платёжной системе (уникален в
.пределах системы)
cardAuthInfo См.
описание
Нет Данные о платёжной карте покупателя:
expiration (ANS) - год и месяц истечения срока действия
платёжной карты;
cardholderName (A..64) - имя держателя карты, если
доступно;
approvalCode (AN6) - к , можетод авторизации платежа
содержать цифры и латинские буквы;
pan (N..19) - маскированный DPAN: номер, привязанный к
мобильному устройству покупателя и выполняющий
функции номера платёжной карты в системе Apple Pay.
authDateTime ANS Нет Дата и время авторизации в формате UNIX-времени
.(POSIX-времени)
terminalId AN..10 Нет Идентификатор терминала в процессинге, через который
осуществлялась оплата.
authRefNum AN..24 Нет Учётный номер авторизации, который присваивается при
регистрации платежа.
paymentAmountInfo См.
описание
Нет Параметр, содержащий вложенные параметры с информацией о
суммах подтверждения, списания, возврата:
paymentState (A..10) - состояние платежа;
approvedAmount (N..20) - сумма, подтверждённая к
списанию;
depositedAmount (N..20) - сумма списания с карты;
refundedAmount (N..20) - сумма возврата.
bankInfo См.
описание
Нет Содержит вложенный параметр (AN..160) - bankCountryName ес
ли доступно, в параметре передаётся наименование страны
банка-эмитента на языке, переданном в параметре вlanguage
запросе, или на языке пользователя, вызвавшего метод, если
язык в запросе не указан.
16.2.2. Интерфейс WebService-ах
Для оплаты через Apple Pay используется запрос .applePay
Пример запроса представлен ниже.
Для операций отмены, возврата и завершения платежа следует использовать стандартные запросы к платёжному шлюзу.
1.
2.
3.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:mer="http://engine.paymentgate.ru/webservices/merchant">
<soapenv:Header/>
<soapenv:Body>
<mer:applePay>
<arg0>
<merchant>OurBestMerchantLogin</merchant>
<orderNumber>UAF-203974-DE</orderNumber>
<description>Test description</description>
<paymentToken>ew0KICB7DQoJICAidmVyc2lvbiI6ICJSU0FfdjEiLA0KCSAgInNpZ25hdHVy
ZSI6ICJabUZyWlNCemFXZHVZWFIxY21VPSIsDQoJICAiaGVhZGVyIjogew0KCQkiZXBoZW1lcm
FsUHVibGljS2V5IjogIk1Ga3dFd1lIS29aSXpqMENBUVlJS29aSXpqMERBUWNEUWdBRW14Q2hD
cGpLemY5YVh6MjZXVDZaVE4yekUzaUdYUWpjWlJZWUFkUUlURFgyUmtBTmJ0N2s5cmFoRjFoem
pqbWVWVHhjZ0NvZkg4MXprMkdOVFozZHRnPT0iICAgICAgIA0KCQkid3JhcHBlZEtleSI6ICJY
ejI2V1Q2WlROMnpFM2lHWFFqYz0iDQoJCSJwdWJsaWNLZXlIYXNoIjogIk9yV2dqUkdrcUVXam
RrUmRVclhmaUxHRDBoZS96cEV1NTEyRkpXckdZRm89IiwNCgkJInRyYW5zYWN0aW9uSWQiOiAi
YXBwbGUtMTIzNDU2Nzg5MEFCQ0RFRiINCgkgIH0sDQoJICAiZGF0YSI6ICIxZFhFMTNrdnpUVl
A2bldFTjhEMnBoclBsZlFjR3I4VzN5ajJTSFlZai9QeWNIV1RqbnBWN3ovRXI3OGJyaT09Ig0K
ICB9DQp9</paymentToken>
<language>RU</language>
<additionalParameters>
<entry>
<key>firstParamName</key>
<value>firstParamValue</value>
</entry>
</additionalParameters>
<preAuth>true</preAuth>
<ip>127.0.0.1</ip>
</arg0>
</mer:applePay>
</soapenv:Body>
</soapenv:Envelope>
Описание запроса представлено в таблице ниже.
Параметр Тип
данных
Обязательность Описание
merchant AN..30 Нет Имя входа продавца в системе платёжного шлюза.
orderNumber AN..32 Нет Уникальный номер заказа на стороне продавца.
description ANS..512 Нет Описание заказа в свободной форме. В процессинг банка для включения в финансовую
отчётность продавца передаются только первые 24 символа этого поля.
paymentToken AN..8192 Нет Параметр должен содержать закодированное в Base64 значение свойства paymentToken
, полученного из объекта от системы Apple PaypaymentData PKPaymentToken Object
(подробнее см. ). Таким образом, чтобы сделать запрос на оплатудокументацию Apple Pay
в платёжный шлюз, продавец должен:
получить от системы Apple Pay объект , содержащийPKPaymentToken Object
свойство ;paymentData
извлечь значение свойства и закодировать его в Base64;paymentData
включить закодированное значение свойства в качестве значенияpaymentData
парамера в запросе на оплату, который продавец направит вpaymentToken
платёжный шлюз.
language A2 Нет Язык в кодировке ISO 639-1. Если не указан, будет использован язык, указанный в
настройках магазина как язык по умолчанию.
additionalParameters AN..1024 Нет Дополнительные параметры заказа, которые сохраняются для просмотра из личного
кабинета продавца. Для каждого дополнительного параметра следует использовать
следующие вложенный параметр , в который, в свою очередь, входят следующиеentry
вложенные параметры:
key - имя параметра;
value - значение параметра.
Ниже представлен пример части кода запроса с несколькими вложенными параметрами.
<entry>
<key>parameter_1</key>
<value>value_1</value>
</entry>
<entry>
<key>parameter_2</key>
<value>value_2</value>
</entry>
preAuth A..5 Да Параметр, определяющий необходимость предварительной авторизации (блокирования
средств на счету клиента до их списания). Доступны следующие значения:
true (истина) - параметр включён, оплата происходит с предавторизацией
(происходит блокирование средств клиента до списания);
false (ложь) - параметр выключен (списание происходит сразу).
Если параметр не указан в запросе, списание происходит сразу.
ip AN..20 Нет IP-адрес плательщика.
Ниже представлен пример ответа после успешной оплаты.
Если у продавца настроена фискализация, при указании в качестве
дополнительных параметров (адрес электронной почты покупателя)email
и/или (номер сотового телефона покупателя) эти параметры в первуюphone
очередь используются для отправки фискального чека.
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<ns1:applePayResponse
xmlns:ns1="http://engine.paymentgate.ru/webservices/merchant">
<return>
<success>true</success>
<data>
<orderId>4574f3e8-0d9a-418e-adcc-4b63aadee95b</orderId>
</data>
<orderStatus orderNumber="1478528500391" orderStatus="2"
actionCode="0" actionCodeDescription="" amount="960000" currency="643"
date="2016-11-07T17:24:13.573+03:00" ip="81.18.144.51" errorCode="0">
<attributes name="mdOrder"
value="4574f3e8-0d9a-418e-adcc-4b63aadee95b"/>
<cardAuthInfo maskedPan="520424**0010" expiration="201907"
cardholderName="CARD HOLDER" approvalCode="123456"/>
<authDateTime>2016-11-07T17:24:13.890+03:00</authDateTime>
<terminalId>12345678</terminalId>
<authRefNum>111111111111</authRefNum>
<paymentAmountInfo paymentState="DEPOSITED"
approvedAmount="960000" depositedAmount="960000" refundedAmount="0"/>
<bankInfo bankCountryName="<>"/>
</orderStatus>
</return>
</ns1:applePayResponse>
</soap:Body>
</soap:Envelope>
Ниже представлен пример ответа после неуспешной оплаты.
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<ns1:applePayResponse
xmlns:ns1="http://engine.paymentgate.ru/webservices/merchant">
<return>
<success>false</success>
<error>
<code>10</code>
<description> </description>
</error>
<orderStatus errorCode="0"/>
</return>
</ns1:applePayResponse>
</soap:Body>
</soap:Envelope>
Описание параметров ответа представлено в таблице ниже.
Параметр Вложенный параметр Обязательный
параметр
Описание
success Не актуально A..5 Да Указывает на успешность проведения платежа. Доступны
следующие значения:
true (истина) - платёж прошёл успешно;
false (ложь) - платёж не прошёл.
data
(возвращается, только если платёж
прошёл успешно)
orderId ANS36 Да Уникальный для продавца номер заказа в платёжной системе.
error
(возвращается, только если платёж не
прошёл)
code N..2 Да Код ошибки. Коды ошибок, которые могут быть возвращены в
результате неуспешной оплаты, представлены в таблице ниже.
Код
ошибки
Сообщение
4 Некорректное значение параметра
[paymentToken.signature], проверка не пройдена
10 Некорректное значение параметра [merchant]
Некорректное значение параметра [orderNumber]
Некорректное значение параметра [paymentToken]
Некорректное значение параметра
[paymentToken.version]
Некорректное значение параметра
[paymentToken.header]
Некорректное значение параметра
[paymentToken.signature]
Некорректное значение параметра
[paymentToken.header.transactionId]
Некорректное значение параметра
[paymentToken.header.wrappedKey]
Некорректное значение параметра
[paymentToken.header.publicKeyHash]
Авторизация неуспешна
description ANS..512 Да Подробное техническое объяснение ошибки - содержимое этого
параметра не предназначено для отображения пользователю.
orderStatus
(содержит параметры состояния заказа и
возвращается, только если платёж шлюз
признал все параметры запроса верными)
errorCode N3 Нет Код ошибки. Список возможных кодов ошибок представлен в опис
.ании запроса состояния заказа
orderNumber AN..32 Да Номер (идентификатор) заказа в системе магазина, уникален для
каждого магазина в пределах системы.
orderStatus N..2 Нет По значению этого параметра определяется состояние заказа в
платёжной системе:
0- платёж прошёл без ошибок;
7 - произошла внутренняя ошибка системы, платёж не
прошёл.
actionCode N..5 Да Коды ответа - цифровое обозначение результата, к которому
привело обращение к системе со стороны пользователя. Коды,
принятые в системе, представлены в приложении Коды ответа -
.расшифровка actionCode
actionCodeDescription AN..512 Да Расшифровка кода ответа на языке, переданном в параметре la
в запросе.nguage
amount N..20 Да Сумма платежа в минимальных единицах валюты (например, в
копейках или центах).
currency N3 Нет Код валюты платежа ISO 4217. Единственное допустимое
значение - 643.
date ANS Да Дата регистрации заказа в формате UNIX-времени
(POSIX-времени).
ip AN..20 Да IP-адрес покупателя.
merchantOrderParams AN..1024 Нет Параметр, содержащий атрибуты, в которых передаются
дополнительные параметры продавца:
name - название дополнительного параметра;
value - значение дополнительного параметра.
1.
2.
3.
4.
5.
6.
attributes AN..1024 Да Атрибуты заказа в платёжной системе (номер заказа):
name - название атрибута, всегда принимает значение mdO
;rder
value - номер заказа в платёжной системе (уникален в
.пределах системы)
cardAuthInfo См.
описание
Нет Данные о платёжной карте покупателя:
expiration (ANS) - год и месяц истечения срока действия
платёжной карты;
cardholderName (A..64) - имя держателя карты, если
доступно;
approvalCode (AN6) - к , можетод авторизации платежа
содержать цифры и латинские буквы;
pan (N..19) - маскированный DPAN: номер, привязанный к
мобильному устройству покупателя и выполняющий
функции номера платёжной карты в системе Apple Pay.
authDateTime ANS Нет Дата и время авторизации в формате UNIX-времени
(POSIX-времени).
terminalId AN..10 Нет Идентификатор терминала в процессинге, через который
осуществлялась оплата.
authRefNum AN..24 Нет Учётный номер авторизации, который присваивается при
регистрации платежа.
paymentAmountInfo См.
описание
Нет Параметр, содержащий вложенные параметры с информацией о
суммах подтверждения, списания, возврата:
paymentState (A..10) - состояние платежа;
approvedAmount (N..20) - сумма, подтверждённая к
списанию;
depositedAmount (N..20) - сумма списания с карты;
refundedAmount (N..20) - сумма возврата.
bankInfo См.
описание
Нет Содержит вложенный параметр (AN..160) - bankCountryName ес
ли доступно, в параметре передаётся наименование страны
банка-эмитента на языке, переданном в параметре вlanguage
запросе, или на языке пользователя, вызвавшего метод, если
язык в запросе не указан.
16.3. Тестирование интеграции с Apple Pay
После регистрации идентификатора продавца Apple Pay (MerchantID) и создания для него сертификата на тестовом платёжном шлюзе
вы можете приступать к тестированию тестовой среде Apple Pay.
16.3.1. Подготовка к работе
Чтобы проверить работу Apple Pay в тестовой среде, вам понадобится:
iPhone 6 или более поздняя модель, iPad mini 3 или более поздняя модель, iPad Air 2, iPad Pro или Apple Watch;
тестовая учётная запись в iTunes Connect.
16.3.2. Создание тестовой учётной записи
Чтобы создать тестовую учётную запись, выполните следующие действия.
Выполните вход на сайте .iTunes Connect
На домашней странице щёлкните на (Пользователи и роли).Users and Roles
Щёлкните (Тестировщики).Sandbox Testers
Нажмите «+», чтобы создать тестовую учётную запись.
Введите необходимые сведения о тестовой учётной записи, после чего нажмите (Сохранить).Save
Выполните выход из своего Apple ID на всех тестовых устройствах, после чего выполните вход, используя тестовую учётную
запись.
Ниже приведён краткий перечень действий, которые позволят вам протестировать Apple Pay. Более подробное описание
приведено в (на английском языке).разделе технической поддержки сайта Apple
Подробнее о создании тестовой учётной записи см. (на английском языке).документацию Apple
1.
2.
3.
16.3.3. Добавление номера тестовой банковской карты
Чтобы добавить номер тестовой банковской карты, выполните следующие действия.
Выполните выход из iCloud, затем выполните вход на своём тестовом устройстве, используя тестовую учётную запись.
Откройте приложение (Кошелёк) и выберите (Добавить кредитную или дебетовую карту).Wallet Add Credit or Debit Card
Завершите процедуру добавления карты, используя тестовые учётные данные и следующий тестовый номер банковской карты.
FPAN 5204 2477 5000 1471
(Тестовый номер, имитирующий номер банковской карты.)
Expiration Date 11/2022
(Месяц и год истечения срока действия карты.)
CVC 111
(Код проверки подлинности карты.)
После добавления карты вы можете начать тестирование.
17. Приложение 4. Оплата через Android Pay
17.1. Общие сведения
Перед тем как получать платежи через Android Pay продавец должен в личном кабинете платёжного шлюза сформировать ключевую
пару. Также, для подключения к Android Pay необходимо заполнить форму по ссылке .https://developers.google.com/android-pay
Подробнее о создании тестовой учётной записи см. (на английском языке).документацию Apple
Если вы по ошибке используете тестовую учётную запись на тестовом устройстве для входа в рабочую среду (такую как
iTunes) вместо входа в тестовую среду, эта тестовая учётная запись станет недействительной и не сможет быть использована
вновь. В этом случае создайте новую тестовую учётную запись с новым адресом электронной почты.
Платежи через Android Pay больше не поддерживаются - см. раздел о платежах через Google Pay.
1.
2.
3.
4.
5.
6.
7.
8.
9.
Плательщик выбирает способ оплаты Android Pay.
Приложение запрашивает Android Pay зашифрованные карточные данные.
Android Pay шифрует данные, используя публичный ключ.
Android Pay возвращает продавцу зашифрованные данные о платеже.
Приложение отправляет в платёжный шлюз запрос на оплату Android Pay, указывая полученный от Android Pay токен.
Платёжный шлюз расшифровывает полученный токен.
Платёжный шлюз производит оплату.
Платёжный шлюз возвращает результат оплаты в приложение.
Приложение отображает результат покупки плательщику.
1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
Плательщик выбирает способ оплаты Android Pay.
Приложение запрашивает Android Pay информацию о маскированных карточных данных.
Android Pay возвращает в приложение маскированные карточные данные.
Приложение отображает плательщику маскированные данные карты, добавленной в Android Pay.
Плательщик подтверждает оплату с помощью добавленной в Android Pay карты.
Приложение запрашивает Android Pay зашифрованные карточные данные.
Android Pay шифрует данные, используя открытый ключ.
Android Pay возвращает продавцу зашифрованные данные о платеже.
Приложение отправляет в платёжный шлюз запрос на оплату Android Pay, указывая полученный от Android токен.
Платёжный шлюз расшифровывает полученный токен и производит оплату.
Платёжный шлюз возвращает результат оплаты в приложение.
Приложение отображает результат покупки плательщику.
17.2. Запрос на оплату Android Pay
17.2.1. Интерфейс REST
Запрос на оплату с помощью Android Pay в платёжный шлюз
Для регистрации заказа используется запрос (см. ).payment.do Координаты подключения
Ниже представлен пример запроса на оплату.
{
"merchant": "OurBestMerchantLogin",
"orderNumber": "UAF-203974-DE",
"language": "RU",
"preAuth": true,
"description" : "Test description",
"additionalParameters":
{
"firstParamName": "firstParamValue",
"secondParamName": "secondParamValue"
},
"paymentToken":
"eyJtZXJjaGFudCI6ICJrdXBpdmlwIiwib3JkZXJOdW1iZXIiOiAyMDUxOTIzMzkxLCJwYXltZ
W50VG9rZW4iOiAie1wiZXBoZW1lcmFsUHVibGljS2V5XCI6XCJrZXlcIixcImVuY3J5cHRlZE1
lc3NhZ2VcIjpcIm1lc3NhZ2VcIixcInRhZ1wiOlwidGFnXCJ9In0=",
"ip" : "127.0.0.1",
"amount" : "230000",
"currencyCode" : 643
}
Описание параметров представлено в таблице ниже.
Параметр Обязательно Описание
merchant Да Имя входа продавца в системе платёжного шлюза.
orderNumber Да Уникальный номер заказа на стороне продавца.
description Нет Описание заказа.
language Нет Язык в кодировке ISO 639-1. Если не указан, будет использован язык, указанный в
настройках магазина как язык по умолчанию.
Для операций отмены, возврата и завершения платежа следует использовать стандартные запросы к платёжному шлюзу.
Для корректной обработки запроса необходимо добавить заголовок с определением типа содержимого - Content-Type:
.application/json
additionalParameters Нет Дополнительные параметры заказа, которые сохраняются для просмотра из личного
кабинета продавца. Дополнительные параметры следует указывать в следующем
формате.
"_": "_"
Каждую новую пару имени и значения параметра следует отделять запятой.
preAuth Нет Параметр, определяющий необходимость предварительной авторизации (блокирования
средств на счету клиента до их списания). Доступны следующие значения:
true (истина) - параметр включён, оплата происходит с предавторизацией
(происходит блокирование средств клиента до списания);
false (ложь) - параметр выключен (списание происходит сразу).
Если параметр не указан в запросе, списание происходит сразу.
clientId Нет Номер клиента, для которого следует создать связку для проведения регулярных
платежей. Следует указывать, только если проводится технический платёж для
последующих регулярных платежей.
paymentToken Да Токен, полученный от Android Pay и закодированный в Base64.
ip Да IP-адрес плательщика.
amount Да Сумма платежа в минимальный единицах валюты (например, в копейках).
currencyCode Нет Цифровой код валюты платежа ISO 4217. Если не указан, считается равным 643
(российский рубль).
Примеры и описание ответа
Успешная оплата
{
"success":true,
"data": {
"orderId": "12312312123"
}
Неуспешная оплата
Если у продавца настроена фискализация, при указании в качестве
дополнительных параметров (адрес электронной почты покупателя)email
и/или (номер сотового телефона покупателя) эти параметры в первуюphone
очередь используются для отправки фискального чека.
{
"error": {
"code": 1,
"description":
"Processing Error",
"message":
" "
},
"success": false
}
Описание параметров ответа приведены в таблице ниже.
Параметр Вложенный
параметр
Обязательный
параметр
Описание
success Не актуально Да Указывает на успешность проведения платежа. Доступны следующие значения:
true (истина) - платёж прошёл успешно;
false (ложь) - платёж не прошёл.
data
(возвращается, только если
платёж прошёл успешно)
orderId Да Уникальный для продавца номер заказа в платёжной системе.
error
(возвращается, только если
платёж не прошёл)
code Да Код ошибки.
description Да Подробное техническое объяснение ошибки - содержимое этого параметра не
предназначено для отображения пользователю.
message Да Понятное описание ошибки - предназначено для отображения пользователю.
Описание возможных кодов ошибок представлено в таблице ниже.
Код ошибки Сообщение об ошибке
0 Обработка запроса прошла без системных ошибок
1 Недостаточно средств на карте
5 Доступ запрещён
Пользователь должен сменить свой пароль
7 Системная ошибка
10 Некорректное значение параметра [paymentToken]
Некорректное значение параметра [orderNumber]
Некорректное значение параметра [merchant]
Некорректное значение параметра [ip]
Расшифровка переданных данных неуспешна
17.2.2. Интерфейс WebService-ах
Для оплаты через Android Pay используется запрос .androidPay
Ниже представлен пример запроса на оплату.
Для операций отмены, возврата и завершения платежа следует использовать стандартные запросы к платёжному шлюзу.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:mer="http://engine.paymentgate.ru/webservices/merchant">
<soapenv:Header/>
<soapenv:Body>
<mer:androidPay>
<arg0>
<merchant>OurBestMerchantLogin</merchant>
<orderNumber>UAF-203974-DE</orderNumber>
<language>RU</language>
<preAuth>true</preAuth>
<paymentToken>eyJtZXJjaGFudCI6ICJrdXBpdmlwIiwib3JkZXJOdW1iZXIiOiAyMDUxOTIz
MzkxLCJwYXltZW50VG9rZW4iOiAie1wiZXBoZW1lcmFsUHVibGljS2V5XCI6XCJrZXlcIixcIm
VuY3J5cHRlZE1lc3NhZ2VcIjpcIm1lc3NhZ2VcIixcInRhZ1wiOlwidGFnXCJ9In0=</paymen
tToken>
<ip>127.0.0.1</ip>
<amount>230000</amount>
<currencyCode>643</currencyCode>
</arg0>
</mer:androidPay>
</soapenv:Body>
</soapenv:Envelope>
Параметр Обязательность Описание
merchant Нет Имя входа продавца в системе платёжного шлюза.
orderNumber Да Уникальный номер заказа на стороне продавца.
paymentToken Да Токен, полученный от Android Pay и закодированный в Base64.
ip Да IP-адрес плательщика.
amount Да Сумма платежа в минимальный единицах валюты (например, в копейках).
description Нет Описание заказа.
language Нет Язык в кодировке ISO 639-1. Если не указан, будет использован язык, указанный в
настройках магазина как язык по умолчанию.
additionalParameters Нет Дополнительные параметры заказа, которые сохраняются для просмотра из личного
кабинета продавца. Для каждого дополнительного параметра следует использовать
следующие вложенный параметр , в который, в свою очередь, входятentry
следующие вложенные параметры:
key - имя параметра;
value - значение параметра.
Ниже представлен пример части кода запроса с несколькими вложенными
параметрами.
<entry>
<key>parameter_1</key>
<value>value_1</value>
</entry>
<entry>
<key>parameter_2</key>
<value>value_2</value>
</entry>
preAuth Нет Параметр, определяющий необходимость предварительной авторизации
(блокирования средств на счету клиента до их списания). Доступны следующие
значения:
true (истина) - параметр включён, оплата происходит с предавторизацией
(происходит блокирование средств клиента до списания);
false (ложь) - параметр выключен (списание происходит сразу).
Если параметр не указан в запросе, списание происходит сразу.
clientId Нет Номер клиента, для которого следует создать связку для проведения регулярных
платежей. Следует указывать, только если проводится технический платёж для
последующих регулярных платежей.
currencyCode Нет Цифровой код валюты платежа ISO 4217. Если не указан, считается равным 643
(российский рубль).
Описание параметров ответа представлено в таблице ниже.
Параметр Вложенный
параметр
Обязательный
параметр
Описание
success Не актуально Да Указывает на успешность проведения платежа. Доступны следующие значения:
true (истина) - платёж прошёл успешно;
false (ложь) - платёж не прошёл.
data
(возвращается, только если
платёж прошёл успешно)
orderId Да Уникальный для продавца номер заказа в платёжной системе.
error
(возвращается, только если
платёж не прошёл)
code Да Код ошибки.
description Да Подробное техническое объяснение ошибки - содержимое этого параметра не
предназначено для отображения пользователю.
message Да Понятное описание ошибки - предназначено для отображения пользователю.
Ниже представлен пример ответа после успешной оплаты.
Если у продавца настроена фискализация, при указании в качестве
дополнительных параметров (адрес электронной почты покупателя)email
и/или (номер сотового телефона покупателя) эти параметры в первуюphone
очередь используются для отправки фискального чека.
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<ns1:androidPayResponse
xmlns:ns1="http://engine.paymentgate.ru/webservices/merchant">
<return>
<success>true</success>
<data>
<orderId>12312312123</orderId>
</data>
<orderStatus errorCode="0"/>
</return>
</ns1:androidPayResponse>
</soap:Body>
</soap:Envelope>
Пример ответа после неуспешной оплаты.
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<ns1:androidPayResponse
xmlns:ns1="http://engine.paymentgate.ru/webservices/merchant">
<return>
<success>false</success>
<error>
<code>10</code>
<description> [orderNumber]</description>
</error>
<orderStatus errorCode="0"/>
</return>
</ns1:androidPayResponse>
</soap:Body>
</soap:Envelope>
Возможные коды ошибок представлены в таблице ниже.
Код ошибки Сообщение об ошибке
0 Обработка запроса прошла без системных ошибок
1 Недостаточно средств на карте
5 Доступ запрещён
Пользователь должен сменить свой пароль
7 Системная ошибка
10 Некорректное значение параметра [paymentToken]
Некорректное значение параметра [orderNumber]
Некорректное значение параметра [merchant]
Некорректное значение параметра [ip]
1.
2.
3.
4.
5.
6.
7.
8.
Расшифровка переданных данных неуспешна
18. Приложение 5. Оплата через Samsung Pay
18.1. Общие сведения
Перед тем, как принимать платежи через Samsung Pay, продавец должен зарегистрироваться на партнёрском портале Samsung. После
этого в личном кабинете платёжного шлюза продавец должен сгенерировать ключевую пару, экспортировать запрос подписи
сертификата и загрузить его на партнёрском портале Samsung.
18.1.1. Схема взаимодействия при оплате из мобильного приложения
Ниже представлена схема взаимодействия при проведения платежа с использованием мобильного приложения.
Плательщик выбирает способ оплаты Samsung Pay.
Приложение отправляет сведения о платеже в Samsung.
Samsung проверяет приложение.
Samsung отправляет в приложение ответ содержащий, среди прочего, парамер с зашифрованными данными о3ds.data
платеже.
Продавец отправляет запрос на оплату в платёжный шлюз, при этом в параметр включает содержимое paymentToken 3ds.dat
, полученное от Samsung:a
Запрос samsungPay, интерфейс REST;
Запрос samsungPay, интерфейс WS.
Платёжный шлюз расшифровывает содержимое и производит оплату.paymentToken
Платёжный шлюз отправляет в приложение результатом оплаты.
Приложение отображает плательщику результат оплаты.
Эти действия необходимы для обеспечения возможности оплаты через мобильное приложение. Для оплаты через сайт эти
действия предпринимать не нужно.
1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
18.1.2. Схема взаимодействия при оплате с веб-страницы (платёжная форма на стороне платёжного
шлюза)
Пользователь на сайте формирует заказ и начинает процедуру оплаты.
Продавец отправляет в платёжный шлюз запрос на оплату:
запрос для одностадийных платежей и для двухстадийных платежей, интерфейс REST;register registerPreAuth
запрос для одностадийных платежей и для двухстадийных платежей,registerOrder registerOrderPreAuth
интерфейс WS.
Платёжный шлюз перенаправляет клиента на платёжную страницу.
Клиент выбирает оплату через Samsung Pay.
Платёжный шлюз обменивается данными с системой Samsung Pay.
Клиент перенаправляется на страницу Samsung Pay.
Пользователь идентифицирует себя, введя логин. Примечание: это происходит только в том случае, если устройство
.пользователя не связано с единой учётной записью Samsung
Приложение на мобильном устройстве пользователя запрашивает аутентификационные данные.
Клиент в своём устройстве проходит аутентификацию.
Платёжный шлюз обменивается с системой Samsung Pay платёжными данными.
Пользователь перенаправляется на страницу результата оплаты.
18.1.3. Схема взаимодействия при оплате с веб-страницы (платёжная форма на стороне продавца)
См. раздел .Координаты подключения
1.
2.
При оплате с сайта, когда платёжная страница находится на стороне продавца, схема взаимодействий выглядит следующим образом.
Клиент формирует заказ на сайте продавца.
Продавец отправляет в РБС запрос регистрации заказа.
Интерфейс WS:
одностадийные платежи: ;запрос регистрации заказа
двухстадийные платежи: .запрос регистрации заказа с предавторизацией
Интерфейс REST:
Для успешного использования платёжной страницы на стороне магазина на сайте магазина необходимо встроить специальный
JavaScript-сценарий, который позволит перенаправлять покупателей на страницу Samsung Pay, используя параметры из
ответа платёжного шлюза. Для передачи этих параметров в Samsung Pay необходимо использовать функцию connect из этого
сценария. Чтобы получить этот JavaScript-сценарий, обратитесь в техническую поддержку.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
Интерфейс REST:
одностадийные платежи: ;запрос регистрации заказа
двухстадийные платежи: .запрос регистрации заказа с предавторизацией
Платёжный шлюз регистрирует заказ, в ответе отправляет идентификатор созданного заказа.
Система магазина перенаправляет клиента свою платёжную страницу.
Браузер клиента открывает платёжную страницу продавца.
Клиент получает платёжную форму.
Клиент выбирает оплату посредством Samsung Pay (Web): (в настоящее время запросЗапрос на оплату Samsung Pay Web
доступен только через интерфейс REST).
Продавец отправляет в платёжный шлюз запрос оплаты через Samsung Pay.
Платёжный шлюз обменивается данными с Samsung Pay, чтобы получить данные для отправки ответа продавцу.
Платёжный шлюз отправляет ответ на запрос оплаты через Samsung Pay.
Платёжная форма перенаправляет Клиента на страницу Samsung Pay. При этом используется JavaScript-сценарий, в котором
вызывается функция , в которой нужно передать данные из ответа на запрос оплаты через Samsung Pay.connect
Клиенту отображается форма для ввода идентификатора.
Клиент вводит идентификатор и подтверждает необходимость связывания устройства.
Samsung Pay информирует Клиента о необходимости аутентифицироваться.
Samsung Pay отправляет оповещение на мобильное устройство клиента для выбора карты оплаты и подтверждения оплаты.
Клиент подтверждает оплату.
Samsung Pay обменивается данным с платёжным шлюзом.
Платёжный шлюз передаёт на платёжную форму результат оплаты.
Платёжная форма отображает результат оплаты клиенту.
18.2. Запрос на оплату Samsung Pay
18.2.1. Интерфейс REST
Для регистрации заказа в Samsung Pay используется запрос payment.do. . . .
Ниже представлен пример запроса на оплату через Samsung Pay.
Шаги 12-13 выполняются в случае, если не было связывания устройства и идентификатора.
Для операций отмены, возврата и завершения платежа следует использовать стандартные запросы к платёжному шлюзу.
Для корректной обработки запроса необходимо добавить заголовок с определением типа содержимого - Content-Type:
.application/json
{
"merchant": "OurBestMerchantLogin",
"orderNumber": "UAF-203974-DE",
"language": "RU",
"preAuth": true,
"description" : "Test description",
"additionalParameters":
{
"firstParamName": "firstParamValue",
"secondParamName": "secondParamValue"
},
"paymentToken":
"ew0KICB7DQoJICAidmVyc2lvbiI6ICJSU0FfdjEiLA0KCSAgInNpZ25hdHVyZSI6ICJabUZyW
lNCemFXZHVZWFIxY21VPSIsDQoJICAiaGVhZGVyIjogew0KCQkiZXBoZW1lcmFsUHVibGljS2V
5IjogIk1Ga3dFd1lIS29aSXpqMENBUVlJS29aSXpqMERBUWNEUWdBRW14Q2hDcGpLemY5YVh6M
jZXVDZaVE4yekUzaUdYUWpjWlJZWUFkUUlURFgyUmtBTmJ0N2s5cmFoRjFoempqbWVWVHhjZ0N
vZkg4MXprMkdOVFozZHRnPT0iICAgICAgIA0KCQkid3JhcHBlZEtleSI6ICJYejI2V1Q2WlROM
npFM2lHWFFqYz0iDQoJCSJwdWJsaWNLZXlIYXNoIjogIk9yV2dqUkdrcUVXamRrUmRVclhmaUx
HRDBoZS96cEV1NTEyRkpXckdZRm89IiwNCgkJInRyYW5zYWN0aW9uSWQiOiAiYXBwbGUtMTIzN
DU2Nzg5MEFCQ0RFRiINCgkgIH0sDQoJICAiZGF0YSI6ICIxZFhFMTNrdnpUVlA2bldFTjhEMnB
oclBsZlFjR3I4VzN5ajJTSFlZai9QeWNIV1RqbnBWN3ovRXI3OGJyaT09Ig0KICB9DQp9",
"ip" : "127.0.0.1"
}
Описание параметров приведено в таблице ниже.
Название Обязательно Описание
merchant Да Имя входа продавца в системе платёжного шюлза.
orderNumber Да Уникальный номер заказа на стороне продавца.
description Нет Описание заказа.
language Нет Язык в кодировке ISO 639-1. Если не указан, будет использован язык, указанный в
настройках магазина как язык по умолчанию.
additionalParameters Нет Дополнительные параметры заказа, которые сохраняются для просмотра из личного
кабинета продавца. Дополнительные параметры следует указывать в следующем
формате.
"_": "_"
Каждую новую пару имени и значения параметра следует отделять запятой.
Если у продавца настроена фискализация, при указании в качестве
дополнительных параметров (адрес электронной почты покупателя)email
и/или (номер сотового телефона покупателя) эти параметры в первуюphone
очередь используются для отправки фискального чека.
preAuth Нет Параметр, определяющий необходимость предварительной авторизации (блокирования
средств на счету клиента до их списания). Доступны следующие значения:
true (истина) - параметр включён, оплата происходит с предавторизацией
(происходит блокирование средств клиента до списания);
false (ложь) - параметр выключен (списание происходит сразу).
Если параметр не указан в запросе, списание происходит сразу.
clientId Нет Номер клиента, для которого следует создать связку для проведения регулярных
платежей. Следует указывать, только если проводится технический платёж для
последующих регулярных платежей.
paymentToken Да Содержимое параметра из ответа, полученного от Samsung Pay.3ds.data
ip Да IP-адрес плательщика.
currencyCode Нет Цифровой код валюты платежа ISO 4217. Если не указан, считается равным коду валюты
по умолчанию.
Примеры и описание ответа
Успешная оплата
{
"success":true,
"data": {
"orderId": "12312312123"
}
}
Неуспешная оплата
{
"error": {
"code": 1,
"description": "Processing Error",
"message": " "
},
"success": false
}
Описание параметров ответа представлено в таблице ниже.
Параметр Вложенный
параметр
Обязательно Описание
success Не актуально Да Указывает на успешность проведения платежа. Доступны следующие
значения:
true (истина) - платёж прошёл успешно;
false (ложь) - платёж не прошёл.
data
(возвращается, только если
платёж прошёл успешно)
orderId Да Уникальный для продавца номер заказа в платёжной системе.
error
(возвращается, только если
платёж не прошёл)
code Да Код ошибки.
description Да Подробное техническое объяснение ошибки - содержимое этого параметра не
предназначено для отображения пользователю.
message Да Понятное описание ошибки - предназначено для отображения пользователю.
Описание возможных кодов ошибок представлено в таблице ниже.
Код Описание
0 Обработка запроса прошла без системных ошибок
1 Недостаточно средств на карте
5 Доступ запрещён
Пользователь должен сменить свой пароль
7 Системная ошибка
10 Некорректное значение параметра [paymentToken]
Некорректное значение параметра [orderNumber]
Некорректное значение параметра [merchant]
Некорректное значение параметра [ip]
Некорректное значение параметра [paymentToken.header.alg]
Некорректное значение параметра [paymentToken.header.enc]
Некорректное значение параметра [paymentToken.header.typ]
Некорректное значение параметра [paymentToken.header.channelSecurityContext]
Некорректное значение параметра [paymentToken.header.kid]
Расшифровка переданных данных неуспешна
18.2.2. Интерфейс WebService
Для оплаты через Samsung Pay используется запрос . Этот запрос используется только при оплате из мобильногоsamsungPay
приложения.
, .
Ниже представлен пример запроса на оплату.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:mer="http://engine.paymentgate.ru/webservices/merchant">
<soapenv:Header/>
<soapenv:Body>
<mer:samsungPay>
<arg0>
<merchant>OurBestMerchantLogin</merchant>
<orderNumber>UAF-203974-DE</orderNumber>
<description>Test description</description>
<paymentToken>ew0KICB7DQoJICAidmVyc2lvbiI6ICJSU0FfdjEiLA0KCSAgInNpZ25hdHVy
ZSI6ICJabUZyWlNCemFXZHVZWFIxY21VPSIsDQoJICAiaGVhZGVyIjogew0KCQkiZXBoZW1lcm
FsUHVibGljS2V5IjogIk1Ga3dFd1lIS29aSXpqMENBUVlJS29aSXpqMERBUWNEUWdBRW14Q2hD
cGpLemY5YVh6MjZXVDZaVE4yekUzaUdYUWpjWlJZWUFkUUlURFgyUmtBTmJ0N2s5cmFoRjFoem
pqbWVWVHhjZ0NvZkg4MXprMkdOVFozZHRnPT0iICAgICAgIA0KCQkid3JhcHBlZEtleSI6ICJY
ejI2V1Q2WlROMnpFM2lHWFFqYz0iDQoJCSJwdWJsaWNLZXlIYXNoIjogIk9yV2dqUkdrcUVXam
RrUmRVclhmaUxHRDBoZS96cEV1NTEyRkpXckdZRm89IiwNCgkJInRyYW5zYWN0aW9uSWQiOiAi
YXBwbGUtMTIzNDU2Nzg5MEFCQ0RFRiINCgkgIH0sDQoJICAiZGF0YSI6ICIxZFhFMTNrdnpUVl
A2bldFTjhEMnBoclBsZlFjR3I4VzN5ajJTSFlZai9QeWNIV1RqbnBWN3ovRXI3OGJyaT09Ig0K
ICB9DQp9</paymentToken>
<language>RU</language>
<additionalParameters>
<entry>
<key>firstParamName</key>
<value>firstParamValue</value>
</entry>
</additionalParameters>
<preAuth>true</preAuth>
<ip>127.0.0.1</ip>
</arg0>
</mer:samsungPay>
</soapenv:Body>
</soapenv:Envelope>
Описание параметров запроса представлено в таблице ниже.
merchant Нет Имя входа продавца в системе платёжного шлюза.
orderNumber Да Уникальный номер заказа на стороне продавца.
paymentToken Да Содержимое параметра из ответа, полученного от Samsung Pay.3ds.data
ip Да IP-адрес плательщика.
amount Да Сумма платежа в минимальный единицах валюты (например, в копейках).
description Нет Описание заказа.
language Нет Язык в кодировке ISO 639-1. Если не указан, будет использован язык, указанный в настройках
магазина как язык по умолчанию.
additionalParameters Нет Дополнительные параметры заказа, которые сохраняются для просмотра из личного кабинета
продавца. Для каждого дополнительного параметра следует использовать следующие вложенный
параметр , в который, в свою очередь, входят следующие вложенные параметры:entry
key - имя параметра;
value - значение параметра.
Ниже представлен пример части кода запроса с несколькими вложенными параметрами.
<entry>
<key>parameter_1</key>
<value>value_1</value>
</entry>
<entry>
<key>parameter_2</key>
<value>value_2</value>
</entry>
preAuth Нет Параметр, определяющий необходимость предварительной авторизации (блокирования средств на
счету клиента до их списания). Доступны следующие значения:
true (истина) - параметр включён, оплата происходит с предавторизацией (происходит
блокирование средств клиента до списания);
false (ложь) - параметр выключен (списание происходит сразу).
Если параметр не указан в запросе, списание происходит сразу.
clientId Нет Номер клиента, для которого следует создать связку для проведения регулярных платежей.
Следует указывать, только если проводится технический платёж для последующих регулярных
платежей.
currencyCode Нет Цифровой код валюты платежа ISO 4217. Если не указан, считается равным коду валюты по
умолчанию.
Ниже представлен пример ответа после успешной оплаты.
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<ns1:samsungPayResponse
xmlns:ns1="http://engine.paymentgate.ru/webservices/merchant">
<return>
<success>true</success>
<data>
<orderId>12312312123</orderId>
</data>
<orderStatus errorCode="0"/>
</return>
</ns1:samsungPayResponse>
</soap:Body>
</soap:Envelope>
Ниже представлен пример ответа после неуспешной оплаты.
Если у продавца настроена фискализация, при указании в качестве дополнительных
параметров (адрес электронной почты покупателя) и/или (номер сотовогоemail phone
телефона покупателя) эти параметры в первую очередь используются для отправки
фискального чека.
Ниже представлен пример ответа после неуспешной оплаты.
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<ns1:samsungPayResponse
xmlns:ns1="http://engine.paymentgate.ru/webservices/merchant">
<return>
<success>false</success>
<error>
<code>1</code>
<description> </description>
</error>
<orderStatus errorCode="0"/>
</return>
</ns1:samsungPayResponse>
</soap:Body>
</soap:Envelope>
Описание параметров ответа представлено в таблице ниже.
Параметр Вложенный
параметр
Описание Обязательно
success Не актуально Да Указывает на успешность проведения платежа. Доступны следующие значения:
true (истина) - платёж прошёл успешно;
false (ложь) - платёж не прошёл.
data
(возвращается, только если платёж
прошёл успешно)
orderId Да Уникальный для продавца номер заказа в платёжной системе.
error
(возвращается, только если платёж
не прошёл)
code Да Код ошибки.
description Да Подробное техническое объяснение ошибки - содержимое этого параметра не
предназначено для отображения пользователю.
message Да Понятное описание ошибки - предназначено для отображения пользователю.
Описание возможных кодов ошибок представлено в таблице ниже.
Код Описание
0 Обработка запроса прошла без системных ошибок
1 Недостаточно средств на карте
5 Доступ запрещён
Пользователь должен сменить свой пароль
7 Системная ошибка
10 Некорректное значение параметра [paymentToken]
Некорректное значение параметра [orderNumber]
Некорректное значение параметра [merchant]
Некорректное значение параметра [ip]
Некорректное значение параметра [paymentToken.header.alg]
Некорректное значение параметра [paymentToken.header.enc]
Некорректное значение параметра [paymentToken.header.typ]
Некорректное значение параметра [paymentToken.header.channelSecurityContext]
Некорректное значение параметра [paymentToken.header.kid]
Расшифровка переданных данных неуспешна
18.3. Запрос на оплату Samsung Pay Web
Для регистрации заказа используется запрос (см. раздел «Координаты для подключения»). Этот запрос используется дляpayment.do
оплаты через сайт, когда платёжная форма находится на странице продавца.
Параметры запроса
Название Тип Обязательно Описание
mdOrder Да Номер заказа в платёжном шлюзе. Уникален в пределах платёжного шлюза.
onFailedPaymentBackUrl Да URL-адрес, на который будет перенаправлен покупатель в случае ошибки или превышения
срока ожидания.
Параметры ответа
Название Тип Обязательно Описание
successful N1 Да Признак успешности операции, возможны следующие значения:
1 (успешно);
0 (неуспешно).
transactionId ANS..36 Да Значение, которое необходимо передать в Samsung Pay, вызывав функцию .connect
href AN..512 Да Значение, которое необходимо передать в Samsung Pay, вызывав функцию .connect
mod AN..256 Да Значение, которое необходимо передать в Samsung Pay, вызывав функцию .connect
exp AN..256 Да Значение, которое необходимо передать в Samsung Pay, вызывав функцию .connect
keyId AN..256 Да Значение, которое необходимо передать в Samsung Pay, вызывав функцию .connect
serviceId AN..256 Да Значение, которое необходимо передать в Samsung Pay, вызывав функцию .connect
callbackUrl AN..512 Да Значение, которое необходимо передать в Samsung Pay, вызывав функцию .connect
cancelUrl AN..512 Да Значение, которое необходимо передать в Samsung Pay, вызывав функцию .connect
countryCode A2 Да Значение, которое необходимо передать в Samsung Pay, вызывав функцию .connect
resultType AS..30 Да Результат операции. Возможны следующие значения:
SUCCESSFUL - операция успешна;
WRONG_TRANSACTION_STATE - неверное состояние транзакции;
CONNECTION_ERROR - ошибка соединения.
19. Приложение 7. Интернет-кредитование
19.1. Общее описание
При оплате товара или услуги «Сбербанк» по согласованию с магазином может предоставить возможность покупателю получить кредит
или приобрести этот товар/услугу в рассрочку.
При этом.
В настоящее время этот запрос доступен только через интерфейс REST.
1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
При этом.
В запросе на регистрацию заказа в платёжном шлюзе в запросе необходимо передать корзину товаров, содержащую
определённые параметры (см. схему взаимодействия ниже).
После получения кредита для оплаты покупатель может выбрать любую карту - необязательно карту «Сбербанка».
После получения кредита потенциальный покупатель может отказаться от дальнейшей процедуры покупки.
Регистрация заказа и получение кредита возможно только в российских рублях.
19.2. Схема взаимодействий при использовании интернет-кредитования
Описание схемы:
Клиент сформировал заказ в на сайте продавца и выбрал функцию «Оплата в кредит».
Система продавца регистрирует заказ в платёжном шлюзе:
интерфейс WS:
запрос на регистрацию заказа (одностадийная оплата);
запрос на регистрацию заказа (двухстадийная оплата);
интерфейс REST:
запрос на регистрацию заказа (одностадийная оплата);
запрос на регистрацию заказа (двухстадийная оплата).
Платёжный шлюз передаёт продавцу результат регистрации заказа, включая уникальный идентификатор заказа и URL страницы
выбора типа кредитования, на который надо перенаправить браузер Клиента.
Продавец перенаправляет браузер клиента URL, полученный на предыдущем шаге.
Браузер клиента переходит по указанному URL.
Клиент получает специальную страницу выбора типа кредитования.
Клиент выбирает тип кредитования, указывая срок кредитования, и подтверждает выбор.
Платёжный шлюз регистрирует заявку.
Платёжный шлюз перенаправляет браузер клиента URL Сбербанк Онлайн.
Браузер клиента переходит на страницу аутентификации Сбербанк Онлайн.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
21.
Браузер клиента переходит на страницу аутентификации Сбербанк Онлайн.
В личном кабинете Сбербанк Онлайн проходит процедура выдачи кредита.
Клиент «Перейти к оплате», Сбербанк Онлайн перенаправляет браузер клиента на страницу сбора данныхнажимает кнопку
банковской карты.
Браузер клиента переходит на страницу ввода банных банковской карты.
Клиент получает страницу сбора данных банковской карты.
Клиент вводит данные банковской карты с которой будет проводиться списание, подтверждает оплату и отправляет данные в
платёжный шлюз.
Платёжный шлюз производит оплату.
После проведения оплаты платёжный шлюз перенаправляет клиента на страницу, переданную в запросе на оплату.
Браузер клиента запрашивает у продавца страницу с результатами оплаты;
Продавец запрашивает платёжный шлюз о статусе оплаты заказа (по внутреннему номеру в платёжной системе).
Платёжный шлюз возвращает статус оплаты заказа;
Продавец передайт в браузер клиента страницу с результатами оплаты.
19.3. Принципы работы с товарной корзиной
Платёжный шлюз позволяет принимать оплату с передачей со стороны магазина Корзины товаров, относящихся к одному Заказу.
Корзина предоставляет собой детализацию Заказа по товарным позициям, по которым производится оплата в рамках одного Заказа.
19.3.1. Требования к регистрации заказов с передачей товарной корзины
В запросах на регистрацию заказа (с предавторизацией или без) Корзина товаров передаётся в параметре <orderBundle>.
Сумма всех товарных позиций Корзины должна быть равна сумме Заказа.
По каждой товарной позиции производится проверка переданного значения <quantity>. В случае если значение слишком
большое или слишком маленькое, то запрос завершается ошибкой.
Все параметры Корзины валидируются на соответствие требуемому формату (длине).
В случае невыполнения хотя бы одного из указанных выше условий Заказ считается неправильно сформированным и платёжный шлюз
возвращает ошибку.
19.3.2. Требования к завершению заказов с товарной корзиной (для двухстадийных платежей)
При завершении заказов Корзина передаётся в элементе <depositItems>.
В случае завершения на полную предавторизованную сумму передача Корзины необязательна.
Сумма завершения в Корзине не должна превышать предавторизованную денежную сумму заказа.
При завершении заказа на сумму отличную от суммы предавторизации (кроме передачи значения «0») обязательно должна
передаваться Корзина товаров.
В Корзине запрещены для передачи новые товарные позиции, отсутствующие в оригинальном заказе. Происходит проверка
наличия указанного товара в Корзине запроса на завершение в изначальном заказе. Необходимо совпадение элементов
<positionId>, <name>, <itemCode>. Если хотя бы одно из значений не совпадает, считается, что данная товарная позиция
отсутствует в Корзине заказа на регистрацию.
Значение элемента <quantity> в Корзине запроса на завершение не должно превышать значение аналогичного параметра в
Корзине заказа на регистрацию.
Значение элемента <itemAmount> блока <items> не должно превышать значение аналогичного параметра в оригинальном
заказе.
По каждой товарной позиции производится проверка переданного значения <quantity>. В случае если значение слишком
большое или слишком маленькое, то запрос завершается ошибкой.
Все параметры Корзины валидируются на соответствие требуемому формату (длине).
В случае невыполнения хотя бы одного из указанных выше условий, запрос завершения заказа считается неправильно
сформированным и платёжный шлюз возвращает ошибку.
19.3.3. Требования к возвратам средств за заказы с товарной корзиной
Основное отличие в обмене запросами и ответами через API по сравнению с использованием стандартной схемы -
необходимость передачи корзины товаров. Отмена платежа и возврат средств производятся по стандартной схеме.
В запросе на возврат Корзина указывается в блоке <refundItems>.
В случае полного возврата Заказа, передача Корзины товаров необязательна.
При возврате заказа на сумму отличную от суммы списания (кроме передачи значения «0») обязательно должна передаваться
Корзина товаров.
В случае проведения нескольких возвратов по заказам с Корзиной, все они должны осуществляться только по алгоритму
возврата с Корзиной.
Сумма возврата в Корзине не должна превышать подтверждённую денежную сумму оригинального заказа.
В Корзине запрещены для передачи товарные позиции, отсутствующие в оригинальном заказе. Происходит проверка наличия
указанного товара в Корзине запроса на возврат в изначальном заказе. Необходимо совпадение элементов <positionId>,
<name>, <itemCode>. Если хотя бы одно из значений не совпадает, считается, что данная товарная позиция отсутствует в
оригинальном заказе.
Значение элемента <quantity> в Корзине запроса на завершение не должно превышать значение аналогичного параметра в
Корзине заказа на регистрацию.
Значение элемента <itemAmount> блока <items> не должно превышать значение аналогичного параметра в оригинальном
заказе.
Все параметры Корзины валидируются на соответствие требуемому формату (длине).
В случае невыполнения хотя бы одного из указанных выше условий, запрос возврата заказа считается неправильно сформированным и
платёжный шлюз должен вернуть ошибку.
19.4. Запросы на регистрацию заказа с передачей товарной корзины
19.4.1. Интерфейс WS
19.4.1.1. Одностадийная оплата
При регистрации заказа необходимо дополнительно передать состав товарной Корзины.
Параметры запроса:
Название Тип Обязательно Описание
merchantOrderNumber ANS..32 да Номер (идентификатор) заказа в системе магазина, уникален для каждого магазина в пределах
системы. Если номер заказа генерируется на стороне платёжного шлюза, этот параметр
передавать необязательно.
description ANS..512 нет Описание заказа в свободной форме. В процессинг банка для включения в финансовую
отчётность продавца передаются только первые 24 символа этого поля.
amount N..20 да Сумма платежа в копейках (или центах)
currency N3 нет Код валюты платежа ISO 4217. Единственное допустимое значение - 643.
language A2 нет Язык в кодировке ISO 639-1. Если не указан, будет использован язык, указанный в настройках
магазина как язык по умолчанию.
pageView ANS..20 нет По значению данного параметра определяется, какие страницы платёжного интерфейса должны
загружаться для клиента. Возможные значения:
DESKTOP – для загрузки страниц, верстка которых предназначена для отображения на
экранах ПК (в архиве страниц платёжного интерфейса будет осуществляться поиск страниц с
названиями и );payment_<locale>.html ocale>.htmlerrors_<l
MOBILE – для загрузки страниц, верстка которых предназначена для отображения на экранах
мобильных устройств (в архиве страниц платёжного интерфейса будет осуществляться
поиск страниц с названиями и mobile_payment_<locale>.html ocalemobile_errors_<l
);>.html
Если магазин создал страницы платёжного интерфейса, добавив в название файлов страниц
произвольные префиксы, передайте значение нужного префикса в параметре дляpageView
загрузки соответствующей страницы. Например, при передаче значения в архивеiphone
страниц платёжного интерфейса будет осуществляться поиск страниц с названиями iphone
и ._payment_<locale>.html iphone_error_<locale>.html
Где:
locale – я . Например, для русского или длязык страницы в кодировке ISO 639-1 ru en
английского.
Если параметр отсутствует, либо не соответствует формату, то по умолчанию считается pageVie
.w=DESKTOP
sessionTimeoutSecs N...9 нет Продолжительность жизни заказа в секундах.
В случае если параметр не задан, будет использовано значение, указанное в настройках
мерчанта или время по умолчанию (1200 секунд = 20 минут).
Если в запросе присутствует параметр expirationDate, то значение параметра sessionTimeo
. utSecs не учитывается
bindingId AN..255 no Идентификатор связки, созданной ранее. Может использоваться, только если у магазина есть
разрешение на работу со связками. Если этот параметр передаётся в данном запросе, то это
означает:
1. Данный заказ может быть оплачен только с помощью связки;
2. Плательщик будет перенаправлен на платёжную страницу, где требуется только ввод
CVC.
expirationDate ANS нет Дата и время окончания жизни заказа. Формат: .yyyy-MM-dd'T'HH:mm:ss
Если этот параметр не передаётся в запросе, то для определения времени окончания жизни
заказа используется .sessionTimeoutSecs
returnUrl AN..512 да Адрес, на который требуется перенаправить пользователя после успешной оплаты. Адрес должен
быть указан полностью, включая используемый протокол (например, вместо ).https://test.ru test.ru
В противном случае пользователь будет перенаправлен по адресу следующего вида: http://<адре
.с_платёжного_шлюза>/<адрес_продавца>
failUrl AN..512 нет Адрес, на который требуется перенаправить пользователя в случае неуспешной оплаты. Адрес
должен быть указан полностью, включая используемый протокол (например, вместо https://test.ru t
). В противном случае пользователь будет перенаправлен по адресу следующего вида: est.ru http:/
./<адрес_платёжного_шлюза>/<адрес_продавца>
params нет Тэг с атрибутами для передачи дополнительных параметров мерчанта.
Поля дополнительной информации для последующего хранения. Для передачи N параметров, в
запросе должно находиться N тэгов , где атрибут содержит название, а атрибут params name valu
содержит значение:e
Название Тип Обязательно Описание
name AN..20 да Название дополнительного параметра
value AN..1024 да Значение дополнительного параметра
Данные поля могут быть переданы в процессинг банка для последующего отображения в
реестрах.*
Включение данного функционала возможно по согласованию с банком в период интеграции.
Если для продавца настроена отправка покупателю, адрес электронной почтыуведомлений
покупателя должен передаваться в этом тэге в параметре с именем .email
clientId ANS..255 нет Номер (идентификатор) клиента в системе магазина. Используется для реализации функционала
связок. Может присутствовать, если магазину разрешено создание связок.
merchantLogin AN..255 нет Чтобы зарегистрировать заказ от имени дочернего мерчанта, укажите его логин в этом параметре.
oderBundle Корзина товаров заказа
* По умолчанию в процессинг банка передаются поля:
merchantOrderNumber – номер заказа в системе магазина;
description – описание заказа (не более 24 символов, запрещены к использованию %, +, конец строки \r и
перенос строки \n).
Если в заказе передать дополнительный параметр с именем , то именно его значение будет передано вmerchantOrderId
процессинг в качестве номера заказа (вместо значения поля ).orderNumber
Параметр :orderBundle
Название Тип Обязательно Описание
orderCreationDate ANS..21 нет Дата создания заказа
customerDetails нет Тэг с атрибутами данных о покупателе
cartItems да Тэг с атрибутами товарных позиции Корзины
installments Условно
Обязательно при предоставлении покупателю возможности
интернет-кредитования
Блок, в котором указаны параметры типа и срока
интернет-кредитования.
Параметры блока :installments
Название Тип Обязательно Описание
productType N..1 да Признак покупки в кредит. Возможны следующие значения:
CREDIT - кредит;
INSTALLMENT - рассрочка.
productId ANS..50 да Идентификатор товара, должен быть согласован с банком.
Параметры блока :customerDetails
Название Тип Обязательно Описание
email ANS..40 Нет Электронная почта покупателя
phone ANS.12 Нет Номер телефона покупателя
contact ANS..40 Нет Способ связи с покупателем
deliveryInfo Нет Тэг с атрибутами адреса для доставки
Параметры блока :deliveryInfo
Название Тип Обязательно Описание
deliveryType ANS..20 нет Тип доставки
country A..2 да Страна доставки (в соответствии с ISO 3166-1)
city ANS..40 да Город доставки
postAddress ANS..255 да Адрес для доставки
: обязательность параметров указана для использования в рамках блока. Если блок необязательный и отсутствует, то иПримечание
входящие в него параметры не должны передаваться.
Параметры блока :cartItems
Название Тип Обязательно Описание
items да Элемент массива с атрибутами товарной позиции в Корзине
Атрибуты элемента :items
Название Тип Обязательно Описание
positionId ANS..12 да Уникальный идентификатор товарной позиции внутри Корзины Заказа
name ANS..100 да Наименование или описание товарной позиции в свободной форме
itemDetails нет Дополнительный тэг с параметрами описания товарной позиции
quantity N..18 да Элемент описывающий общее количество товарных позиций одного positionId и их меру
измерения. Для указания дробных чисел используйте десятичную точку.
itemAmount N..18 Условно
Обязательно при
предоставлении
покупателю
возможности
интернет-кредитования
Сумма стоимости всех товарных позиций одного в минимальных единицах валюты. positionId
обязателен к передаче, только если не был передан параметр . ВitemAmount itemPrice
противном случае передача не требуется. Если же в запросе передаются обаitemAmount
параметра: и , то должен равняться itemPrice itemAmount itemAmount itemPrice *
, в противном случае запрос завершится с ошибкой.quantity
itemCurrency N..3 Условно
Обязательно при
предоставлении
покупателю
возможности
интернет-кредитования
Код валюты товарной позиции ISO 4217. Если не указан, считается равным валюте заказа.
itemCode ANS..100 да Номер (идентификатор) товарной позиции в системе магазина
discount нет Дополнительный тэг с атрибутами описания скидки для товарной позиции
agentInterest нет Дополнительный тэг с атрибутами описания агентской комиссии за продажу товара
Атрибуты элемента :quantity
Название Тип Обязательно Описание
measure ANS..20 да Мера измерения количества товарной позиции
Параметры тэга :itemDetails
Название Тип Обязательно Описание
itemDetailsParams ANS..255 Условно
Обязательно при предоставлении покупателю возможности
интернет-кредитования
Параметр описывающий дополнительную информацию
по товарной позиции
Атрибуты параметра :itemDetailsParams
Название Тип Обязательно Описание
name AN..255 Условно
Обязательно при наличии параметра itemDetailsParams
Наименование параметра описания детализации товарной позиции
При расчёте параметра результат округляетсяitemAmount = itemPrice*quantity
до второго знака после десятичного разделителя. Например, если результат
вычислений равен , то итоговый результат будет равен .100,255 100,26
Параметры блока :discount
Название Тип Обязательно Описание
discountType ANS..20 да Тип скидки на товарную позицию
discountValue N..20 Да Значение скидки на товарную позицию
Параметры блока :agentInterest
Название Тип Обязательно Описание
interestType ANS..20 да Тип агентской комиссии за продажу товара
interestValue N..20 Да Значение агентской комиссии за продажу товара
Параметры ответа:
Название Тип Обязательно Описание
orderId ANS36 нет Номер заказа в платежной системе. Уникален в пределах системы. Отсутствует, если регистрация заказа на
удалась по причине ошибки, детализированной в .errorCode
formUrl AN..512 нет URL платежной формы, на который надо перенаправить браузер клиента. Не возвращается, если
регистрация заказа не удалась по причине ошибки, детализированной в .errorCode
errorCode N3 да Код ошибки.
errorMessage AN..512 нет Описание ошибки на языке, переданном в параметре в запросе. language
Коды ошибок (поле ErrorCode):
Значение Описание
0 Обработка запроса прошла без системных ошибок
1 Неверный номер заказа
1 Заказ с таким номером уже обработан
3 Неизвестная валюта
4 Отсутствует сумма
4 Номер заказа не может быть пуст
4 URL возврата не может быть пуст
5 Неверно указано значение одного из параметров
5 Доступ запрещён
5 Пользователь должен сменить свой пароль
7 Системная ошибка
8 Отсутствует обязательный параметр Корзины с указанием наименования отсутствующего элемента
8 Валюта в Корзине не совпадает с валютой заказа
8 Сумма товарных позиций в Корзине не совпадает с общей суммой заказа
8 Слишком большое либо слишком маленькое значение quantity
Пример запроса:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:mer="http://engine.paymentgate.ru/webservices/merchant">
<soapenv:Header/>
<soapenv:Body>
<mer:registerOrderPreAuth>
<order merchantOrderNumber="23a89ioouygnuygjhv"
description="short" amount="24000" currency="643" language="ru" pageView="
" sessionTimeoutSecs="5400" bindingId=" ">
<returnUrl>https://server/applicaton_context/finish.html</returnUrl>
<!--Zero or more repetitions:-->
<params name=" " value=" "/>
<!--Optional:-->
<clientId>666</clientId>
<!--Optional:-->
<merchantLogin> </merchantLogin>
<orderBundle>
<!-- Optional: -->
<orderCreationDate>2013-07-12T13:51:00</orderCreationDate>
<!-- -->
<!-- Optional: -->
<customerDetails>
<!-- Optional: -->
<email>johnsmith@mail.ru</email>
<!-- Optional: -->
<phone>79851231234</phone>
<!-- Optional: -->
<contact>Mega Tester</contact>
<!-- Optional: -->
<deliveryInfo>
<!-- Optional: -->
<deliveryType>courier</deliveryType>
<country>RU</country>
<city>Moscow</city>
<postAddress> 50 .2</postAddress>
</deliveryInfo>
</customerDetails>
<!-- -->
<cartItems>
<!-- Zero or more repetitions: -->
<items positionId="1">
<name>Metzeler Enduro 3 Sahara</name>
<!-- Optional: -->
<itemDetails>
<!-- Zero or more repetitions: -->
<itemDetailsParams
name="brand">Metzeler</itemDetailsParams>
<itemDetailsParams
name="radius">17inch</itemDetailsParams>
</itemDetails>
<quantity measure="">1</quantity>
<itemAmount>8000</itemAmount>
<itemCurrency>643</itemCurrency>
<itemCode>T-M-14</itemCode>
<!-- Optional: -->
<discount>
<!-- Optional: -->
<discountType>percent</discountType>
<!-- Optional: -->
<discountValue>5</discountValue>
</discount>
<!-- Optional: -->
<agentInterest>
<!-- Optional: -->
<interestType>agentPercent</interestType>
<!-- Optional: -->
<interestValue>7</interestValue>
</agentInterest>
</items>
<items positionId="2">
<name>Universal Mirror Enduro</name>
<!-- Optional: -->
<itemDetails>
<!-- Zero or more repetitions: -->
<itemDetailsParams
name="brand">Noname</itemDetailsParams>
<itemDetailsParams
name="diameter">12mm</itemDetailsParams>
</itemDetails>
<quantity measure="">1</quantity>
<itemAmount>8000</itemAmount>
<itemCurrency>643</itemCurrency>
<itemCode>NM-15</itemCode>
<!-- Optional: -->
<discount>
<!-- Optional: -->
<discountType>percent</discountType>
<!-- Optional: -->
<discountValue>5</discountValue>
</discount>
<!-- Optional: -->
<agentInterest>
<!-- Optional: -->
<interestType>agentPercent</interestType>
<!-- Optional: -->
<interestValue>7</interestValue>
</agentInterest>
</items>
<items positionId="3">
<name>Warm Grips</name>
<!-- Optional: -->
<itemDetails>
<!-- Zero or more repetitions: -->
<itemDetailsParams
name="brand">Noname</itemDetailsParams>
</itemDetails>
<quantity measure="">1</quantity>
<itemAmount>8000</itemAmount>
<itemCurrency>643</itemCurrency>
<itemCode>G-16</itemCode>
<!-- Optional: -->
<discount>
<!-- Optional: -->
<discountType>percent</discountType>
<!-- Optional: -->
<discountValue>5</discountValue>
</discount>
<!-- Optional: -->
<agentInterest>
<!-- Optional: -->
<interestType>agentPercent</interestType>
<!-- Optional: -->
<interestValue>7</interestValue>
</agentInterest>
</items>
</cartItems>
</orderBundle>
</order>
</mer:registerOrderPreAuth>
</soapenv:Body>
</soapenv:Envelope>
Пример ответа:
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<ns1:registerOrderPreAuthResponse
xmlns:ns1="http://engine.paymentgate.ru/webservices/merchant">
<return orderId="8c76c56b-426c-435d-a24c-1c0927dd6fca"
errorCode="0" errorMessage="">
<formUrl>https://server/application_context/payment_ru.html?mdOrder=8c76c5
6b-426c-435d-a24c-1c0927dd6fca</formUrl>
</return>
</ns1:registerOrderPreAuthResponse>
</soap:Body>
</soap:Envelope>
19.4.1.2. Двухстадийная оплата
Для регистрации заказа в системе используется запрос . Состав товарной Корзины передаётся в параметре registerOrder <orderBun
.dle>
Параметры запроса:
Название Тип Обязательно Описание
merchantOrderNumber ANS..32 да Номер (идентификатор) заказа в системе магазина, уникален для каждого магазина в пределах
системы. Если номер заказа генерируется на стороне платёжного шлюза, этот параметр
передавать необязательно.
description ANS..512 нет Описание заказа в свободной форме. В процессинг банка для включения в финансовую
отчётность продавца передаются только первые 24 символа этого поля.
amount N..20 да Сумма платежа в минимальных единицах валюты
currency N3 нет Код валюты платежа ISO 4217. Единственное допустимое значение - 643.
A2 нет Язык в кодировке ISO 639-1. Если не указан, будет использован язык, указанный в настройках
магазина как язык по умолчанию (default language).
pageView ANS..20 нет По значению данного параметра определяется, какие страницы платёжного интерфейса должны
загружаться для клиента. Возможные значения:
DESKTOP – для загрузки страниц, верстка которых предназначена для отображения на
экранах ПК (в архиве страниц платёжного интерфейса будет осуществляться поиск страниц с
названиями и );payment_<locale>.html ocale>.htmlerrors_<l
MOBILE – для загрузки страниц, верстка которых предназначена для отображения на экранах
мобильных устройств (в архиве страниц платёжного интерфейса будет осуществляться
поиск страниц с названиями и mobile_payment_<locale>.html ocalemobile_errors_<l
);>.html
Если магазин создал страницы платёжного интерфейса, добавив в название файлов страниц
произвольные префиксы, передайте значение нужного префикса в параметре дляpageView
загрузки соответствующей страницы. Например, при передаче значения в архивеiphone
страниц платёжного интерфейса будет осуществляться поиск страниц с названиями iphone
и ._payment_<locale>.html iphone_error_<locale>.html
Где:
locale – я . Например, для русского или длязык страницы в кодировке ISO 639-1 ru en
английского.
Если параметр отсутствует, либо не соответствует формату, то по умолчанию считается pageVie
.w=DESKTOP
sessionTimeoutSecs N...9 нет Продолжительность жизни заказа в секундах.
В случае если параметр не задан, будет использовано значение, указанное в настройках
мерчанта или время по умолчанию (1200 секунд = 20 минут).
Если в запросе присутствует параметр expirationDate, то значение параметра sessionTimeo
. utSecs не учитывается
bindingId AN..255 no Идентификатор связки, созданной ранее. Может использоваться, только если у магазина есть
разрешение на работу со связками. Если этот параметр передаётся в данном запросе, то это
означает:
1. Данный заказ может быть оплачен только с помощью связки;
2. Плательщик будет перенаправлен на платёжную страницу, где требуется только ввод CVC.
expirationDate ANS нет Дата и время окончания жизни заказа. Формат: .yyyy-MM-dd'T'HH:mm:ss
Если этот параметр не передаётся в запросе, то для определения времени окончания жизни
заказа используется .sessionTimeoutSecs
returnUrl AN..512 да Адрес, на который требуется перенаправить пользователя в случае успешной оплаты. Адрес
должен быть указан полностью, включая используемый протокол (например, вместо https://test.ru t
). В противном случае пользователь будет перенаправлен по адресу следующего вида: est.ru http:/
./<адрес_платёжного_шлюза>/<адрес_продавца>
failUrl AN..512 нет Адрес, на который требуется перенаправить пользователя в случае неуспешной оплаты. Адрес
должен быть указан полностью, включая используемый протокол (например, вместо https://test.ru t
). В противном случае пользователь будет перенаправлен по адресу следующего вида: est.ru http:/
./<адрес_платёжного_шлюза>/<адрес_продавца>
params нет Тэг с атрибутами для передачи дополнительных параметров мерчанта.
Поля дополнительной информации для последующего хранения. Для передачи N параметров, в
запросе должно находиться N тэгов , где атрибут содержит название, а атрибут params name valu
содержит значение:e
Название Тип Обязательно Описание
name AN..20 да Название дополнительного параметра
value AN..1024 да Значение дополнительного параметра
Данные поля могут быть переданы в процессинг банка для последующего отображения в
реестрах.*
Включение данного функционала возможно по согласованию с банком в период интеграции.
Если для продавца настроена отправка покупателю, адрес электронной почтыуведомлений
покупателя должен передаваться в этом тэге в параметре с именем .email
clientId ANS..255 нет Номер (идентификатор) клиента в системе магазина. Используется для реализации функционала
связок. Может присутствовать, если магазину разрешено создание связок.
merchantLogin AN..255 нет Чтобы зарегистрировать заказ от имени дочернего мерчанта, укажите его логин в этом параметре.
orderBundle Тэг, содержащий Корзину товаров заказа. Описание его атрибутов представлено ниже.
* По умолчанию в процессинг банка передаются поля:
merchantOrderNumber – номер заказа в системе магазина;
merchantOrderNumber – номер заказа в системе магазина;
description – описание заказа (не более 24 символов, запрещены к использованию %, +, конец строки \r и
перенос строки \n).
Если в заказе передать дополнительный параметр с именем , то именно его значение будет передано вmerchantOrderId
процессинг в качестве номера заказа (вместо значения поля ).orderNumber
Параметр :orderBundle
Название Тип Обязательно Описание
orderCreationDate ANS..21 нет Дата создания заказа
customerDetails нет Тэг с атрибутами данных о покупателе. Описание его
атрибутов представлено ниже.
cartItems да Тэг с атрибутами товарных позиции Корзины. Описание его
атрибутов представлено ниже.
installments Условно
Обязательно при предоставлении покупателю
возможности интернет-кредитования
Блок, в котором указаны параметры типа и срока
интернет-кредитования.
Параметры блока installments:
Название Тип Обязательно Описание
productType N..1 да Признак покупки в кредит. Возможны следующие значения:
CREDIT - кредит;
INSTALLMENT - рассрочка.
productId ANS..50 да Идентификатор товара, должен быть согласован с банком.
Параметры блока :customerDetails
Название Тип Обязательно Описание
email ANS..40 Нет Электронная почта покупателя
phone ANS.12 Нет Номер телефона покупателя
contact ANS..40 Нет Способ связи с покупателем
deliveryInfo Нет Тэг с атрибутами адреса для доставки. Описание его атрибутов представлено ниже.
Параметры блока :deliveryInfo
Название Тип Обязательно Описание
deliveryType ANS..20 нет Тип доставки
country A..2 да Страна доставки (в соответствии с ISO 3166-1)
city ANS..40 да Город доставки
postAddress ANS..255 да Адрес для доставки
: обязательность параметров указана для использования в рамках блока. Если блок необязательный и отсутствует, то иПримечание
входящие в него параметры не должны передаваться.
Параметры блока :cartItems
Название Тип Обязательно Описание
items да Элемент массива с атрибутами товарной позиции в Корзине. Описание его атрибутов представлено ниже.
Атрибуты элемента :items
Название Тип Обязательно Описание
positionId ANS..12 да Уникальный идентификатор товарной позиции внутри Корзины Заказа
name ANS..100 да Наименование или описание товарной позиции в свободной форме
itemDetails нет Дополнительный тэг с параметрами описания товарной позиции. Описание его атрибутов
представлено ниже.
quantity N..18 да Элемент описывающий общее количество товарных позиций одного и их меруpositionId
измерения. Для указания дробных чисел используйте десятичную точку. Описание его атрибутов
представлено ниже.
itemAmount N..18 Условно
Обязательно при
предоставлении
покупателю
возможности
интернет-кредитования
Сумма стоимости всех товарных позиций одного в минимальных единицах валюты. positionId
обязателен к передаче, только если не был передан параметр . ВitemAmount itemPrice
противном случае передача не требуется. Если же в запросе передаются обаitemAmount
параметра: и , то должен равняться itemPrice itemAmount itemAmount itemPrice *
, в противном случае запрос завершится с ошибкой.quantity
itemCurrency N..3 Условно
Обязательно при
предоставлении
покупателю
возможности
интернет-кредитования
Код валюты товарной позиции ISO 4217. Если не указан, считается равным валюте заказа.
itemCode ANS..100 да Номер (идентификатор) товарной позиции в системе магазина. Параметр должен быть
уникальным в рамках запроса.
discount нет Дополнительный тэг с атрибутами описания скидки для товарной позиции. Описание его
атрибутов представлено ниже.
agentInterest нет Дополнительный тэг с атрибутами описания агентской комиссии за продажу товара. Описание его
атрибутов представлено ниже.
Атрибуты элемента :quantity
Название Тип Обязательно Описание
measure ANS..20 да Мера измерения количества товарной позиции
Параметры тэга :itemDetails
Название Тип Обязательно Описание
itemDetailsParams ANS..255 Условно
Обязательно при предоставлении покупателю
возможности интернет-кредитования
Параметр описывающий дополнительную информацию по товарной
позиции. Описание его атрибутов представлено ниже.
Атрибуты параметра :itemDetailsParams
При расчёте параметра результат округляетсяitemAmount = itemPrice*quantity
до второго знака после десятичного разделителя. Например, если результат
вычислений равен , то итоговый результат будет равен .100,255 100,26
Название Тип Обязательно Описание
name AN..255 Условно
Обязательно при наличии параметра itemDetailsParams
Наименование параметра описания детализации товарной позиции
Параметры блока :discount
Название Тип Обязательно Описание
discountType ANS..20 да Тип скидки на товарную позицию
discountValue N..20 Да Значение скидки на товарную позицию
Параметры блока :agentInterest
Название Тип Обязательно Описание
interestType ANS..20 да Тип агентской комиссии за продажу товара
interestValue N..20 Да Значение агентской комиссии за продажу товара
Параметры ответа:
Название Тип Обязательно Описание
orderId ANS36 нет Номер заказа в платежной системе. Уникален в пределах системы. Отсутствует, если регистрация заказа на
удалась по причине ошибки, детализированной в .errorCode
formUrl AN..512 нет URL платежной формы, на который надо перенаправить браузер клиента. Не возвращается, если
регистрация заказа не удалась по причине ошибки, детализированной в .errorCode
errorCode N3 да Код ошибки.
errorMessage AN..512 нет Описание ошибки на языке, переданном в параметре в запросе.language
Коды ошибок (поле ):errorCode
Значение Описание
0 Обработка запроса прошла без системных ошибок.
1 Неверный номер заказа.
1 Заказ с таким номером уже обработан.
3 Неизвестная валюта.
4 Отсутствует сумма.
4 Номер заказа не может быть пуст.
4 URL возврата не может быть пуст.
5 Неверно указано значение одного из параметров.
5 Доступ запрещён.
5 Пользователь должен сменить свой пароль.
7 Системная ошибка.
8 Отсутствует обязательный параметр Корзины с указанием наименования отсутствующего элемента.
8 Валюта в Корзине не совпадает с валютой заказа.
8 Сумма товарных позиций в Корзине не совпадает с общей суммой заказа.
8 Слишком большое или слишком маленькое значение параметра .quantity
Пример запроса:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:mer="http://engine.paymentgate.ru/webservices/merchant">
<soapenv:Header/>
<soapenv:Body>
<mer:registerOrder>
<order merchantOrderNumber="110a88qerf8kfqdarf" description=" "
amount="24000" currency=" " pageView=" " sessionTimeoutSecs="5400"
binding=" " expirationDate=" ">
<!--Optional:-->
<returnUrl>https://server/applicaton_context/finish.html</returnUrl>
<!--Zero or more repetitions:-->
<params name="param1" value="valueParam1"/>
<params name="param2" value="valueParam2"/>
<!--Optional:-->
<clientId>666</clientId>
<!--Optional:-->
<merchantLogin> </merchantLogin>
<!--Optional:-->
<orderBundle>
<!-- Optional: -->
<orderCreationDate>2013-07-12T13:51:00</orderCreationDate>
<!-- -->
<!-- Optional: -->
<customerDetails>
<!-- Optional: -->
<email>johnsmith@mail.ru</email>
<!-- Optional: -->
<phone>79851231234</phone>
<!-- Optional: -->
<contact>Mega Tester</contact>
<!-- Optional: -->
<deliveryInfo>
<!-- Optional: -->
<deliveryType>courier</deliveryType>
<country>RU</country>
<city>Moscow</city>
<postAddress> 50 .2</postAddress>
</deliveryInfo>
</customerDetails>
<!-- -->
<cartItems>
<!-- Zero or more repetitions: -->
<items positionId="1">
<name>Metzeler Enduro 3 Sahara</name>
<!-- Optional: -->
<itemDetails>
<!-- Zero or more repetitions: -->
<itemDetailsParams
name="brand">Metzeler</itemDetailsParams>
<itemDetailsParams
name="radius">17inch</itemDetailsParams>
</itemDetails>
<quantity measure="">1</quantity>
<itemAmount>8000</itemAmount>
<itemCurrency>643</itemCurrency>
<itemCode>T-M-14</itemCode>
<!-- Optional: -->
<discount>
<!-- Optional: -->
<discountType>percent</discountType>
<!-- Optional: -->
<discountValue>5</discountValue>
</discount>
<!-- Optional: -->
<agentInterest>
<!-- Optional: -->
<interestType>agentPercent</interestType>
<!-- Optional: -->
<interestValue>7</interestValue>
</agentInterest>
</items>
<items positionId="2">
<name>Universal Mirror Enduro</name>
<!-- Optional: -->
<itemDetails>
<!-- Zero or more repetitions: -->
<itemDetailsParams
name="brand">Noname</itemDetailsParams>
<itemDetailsParams
name="diameter">12mm</itemDetailsParams>
</itemDetails>
<quantity measure="">1</quantity>
<itemAmount>8000</itemAmount>
<itemCurrency>643</itemCurrency>
<itemCode>NM-15</itemCode>
<!-- Optional: -->
<discount>
<!-- Optional: -->
<discountType>percent</discountType>
<!-- Optional: -->
<discountValue>5</discountValue>
</discount>
<!-- Optional: -->
<agentInterest>
<!-- Optional: -->
<interestType>agentPercent</interestType>
<!-- Optional: -->
<interestValue>7</interestValue>
</agentInterest>
</items>
<items positionId="3">
<name>Warm Grips</name>
<!-- Optional: -->
<itemDetails>
<!-- Zero or more repetitions: -->
<itemDetailsParams
name="brand">Noname</itemDetailsParams>
</itemDetails>
<quantity measure="">1</quantity>
<itemAmount>8000</itemAmount>
<itemCurrency>643</itemCurrency>
<itemCode>G-16</itemCode>
<!-- Optional: -->
<discount>
<!-- Optional: -->
<discountType>percent</discountType>
<!-- Optional: -->
<discountValue>5</discountValue>
</discount>
<!-- Optional: -->
<agentInterest>
<!-- Optional: -->
<interestType>agentPercent</interestType>
<!-- Optional: -->
<interestValue>7</interestValue>
</agentInterest>
</items>
</cartItems>
</orderBundle>
</order>
</mer:registerOrder>
</soapenv:Body>
</soapenv:Envelope>
Пример ответа:
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<ns1:registerOrderResponse
xmlns:ns1="http://engine.paymentgate.ru/webservices/merchant">
<return orderId="531eaa8d-b32d-46dd-8e48-64b873886e70"
errorCode="0" errorMessage="Success">
<formUrl>https://server/application_context/payment_ru.html?mdOrder=531eaa
8d-b32d-46dd-8e48-64b873886e70</formUrl>
</return>
</ns1:registerOrderResponse>
</soap:Body>
</soap:Envelope>
19.4.2. Интерфейс REST
19.4.2.1. Одностадийная оплата
Для регистрации заказа в схеме приёма платежа на стороне платёжной системы используется запрос (см. раздел "register.do Коорди
"). наты подключения
Товарная Корзина передаётся в параметре .orderBundle
Параметры запроса:
Название Тип Обязательно Описание
userName AN..30 нет (нужно
указать либо
пару логин и
пароль, либо
токен)
Логин магазина, полученный при подключении. Если вместо аутентификации по логину и паролю
используется открытый токен (параметр token), параметр передавать не нужно.userName
password AN..30 нет (нужно
указать либо
пару логин и
пароль, либо
токен)
Пароль магазина, полученный при подключении. Если для аутентификации при регистрации вместо
логина и пароля используется открытый токен (параметр token), параметр передавать неpassword
нужно.
token AN..30 нет (нужно
указать либо
пару логин и
пароль, либо
токен)
Открытый ключ, который можно использовать для регистрации заказа. Если для аутентификации
при регистрации заказа используются логин и пароль, параметр передавать не нужно.token
orderNumber AN..32 да Номер (идентификатор) заказа в системе магазина
amount N..20 да Сумма платежа в минимальных единицах валюты. Должна совпадать с общей суммой по всем
товарным позициям в Корзине.
currency N3 нет Код валюты платежа ISO 4217. Единственное допустимое значение - 643.
returnUrl AN..512 да Адрес, на который требуется перенаправить пользователя в случае успешной оплаты. Адрес
должен быть указан полностью, включая используемый протокол (например, вместо https://test.ru tes
). В противном случае пользователь будет перенаправлен по адресу следующего вида: t.ru http://<ад
.рес_платёжного_шлюза>/<адрес_продавца>
failUrl AN..512 нет Адрес, на который требуется перенаправить пользователя в случае неуспешной оплаты. Адрес
должен быть указан полностью, включая используемый протокол (например, вместо https://test.ru tes
). В противном случае пользователь будет перенаправлен по адресу следующего вида: t.ru http://<ад
.рес_платёжного_шлюза>/<адрес_продавца>
description ANS..512 нет Описание заказа в свободной форме. В процессинг банка для включения в финансовую отчётность
продавца передаются только первые 24 символа этого поля.
language A2 нет Язык в кодировке ISO 639-1. Если не указан, будет использован язык, указанный в настройках
магазина как язык по умолчанию (default language)
pageView ANS..20 нет По значению данного параметра определяется, какие страницы платёжного интерфейса должны
загружаться для клиента. Возможные значения:
DESKTOP – для загрузки страниц, верстка которых предназначена для отображения на экранах
ПК (в архиве страниц платёжного интерфейса будет осуществляться поиск страниц с
названиями и );payment_<locale>.html ocale>.htmlerrors_<l
MOBILE – для загрузки страниц, верстка которых предназначена для отображения на экранах
мобильных устройств (в архиве страниц платёжного интерфейса будет осуществляться поиск
страниц с названиями и mobile_payment_<locale>.html ocale>.htmlmobile_errors_<l
);
Если магазин создал страницы платёжного интерфейса, добавив в название файлов страниц
произвольные префиксы, передайте значение нужного префикса в параметре дляpageView
загрузки соответствующей страницы. Например, при передаче значения в архивеiphone
страниц платёжного интерфейса будет осуществляться поиск страниц с названиями iphone_p
и .ayment_<locale>.html iphone_error_<locale>.html
Где:
locale – я . Например, для русского или длязык страницы в кодировке ISO 639-1 ru en
английского.
Если параметр отсутствует, либо не соответствует формату, то по умолчанию считается pageView=
.DESKTOP
clientId ANS..255 нет Номер (идентификатор) клиента в системе магазина. Используется для реализации функционала
связок. Может присутствовать, если магазину разрешено создание связок.
merchantLogin AN..255 нет Чтобы зарегистрировать заказ от имени дочернего мерчанта, укажите его логин в этом параметре.
jsonParams AN..1024 нет Блок для передачи дополнительных параметров мерчанта. Поля дополнительной информации для
последующего хранения, передаются в виде:
{"<name1>":"<value1>",...,"<nameN>":"<valueN>"},
Данные поля могут быть переданы в процессинг банка для последующего отображения в реестрах.*
Включение данного функционала возможно по согласованию с банком в период интеграции.
Если для продавца настроена отправка покупателю, адрес электронной почтыуведомлений
покупателя должен передаваться в этом блоке в параметре с именем .email
sessionTimeoutSecs N...9 нет Продолжительность жизни заказа в секундах.
В случае если параметр не задан, будет использовано значение, указанное в настройках мерчанта
или время по умолчанию (1200 секунд = 20 минут).
Если в запросе присутствует параметр expirationDate, то значение параметра sessionTimeout
Secs не учитывается.
expirationDate ANS нет Дата и время окончания жизни заказа. Формат: .yyyy-MM-ddTHH:mm:ss
Если этот параметр не передаётся в запросе, то для определения времени окончания жизни заказа
используется sessionTimeoutSecs.
bindingId AN..255 no Идентификатор связки, созданной ранее. Может использоваться, только если у магазина есть
разрешение на работу со связками. Если этот параметр передаётся в данном запросе, то это
означает:
1. Данный заказ может быть оплачен только с помощью связки;
2. Плательщик будет перенаправлен на платёжную страницу, где требуется только ввод CVC.
orderBundle Блок, содержащий Корзину товаров заказа. Описание его атрибутов представлено в таблице
"Параметр orderBundle" ниже.
* По умолчанию в процессинг банка передаются поля:
orderNumber – номер заказа в системе магазина;
description – описание заказа (не более 24 символов, запрещены к использованию %, +, конец строки \r и перенос
description – описание заказа (не более 24 символов, запрещены к использованию %, +, конец строки \r и перенос
строки \n).
Если в заказе передать дополнительный параметр с именем , то именно его значение будет передано вmerchantOrderId
процессинг в качестве номера заказа (вместо значения поля ).orderNumber
Параметр :orderBundle
Название Тип Обязательно Описание
orderCreationDate ANS..21 нет Дата создания заказа
customerDetails нет Блок с атрибутами данных о покупателе. Описание его
атрибутов представлено ниже.
cartItems да Блок с атрибутами товарных позиции орзины. Описание егоК
атрибутов представлено ниже.
installments Условно
Обязательно при предоставлении покупателю
возможности интернет-кредитования
Блок, в котором указаны параметры типа и срока
интернет-кредитования
Параметры блока installments
Название Тип Обязательно Описание
productType N..1 да Признак покупки в кредит. Возможны следующие значения:
CREDIT - кредит;
INSTALLMENT - рассрочка.
ProductID ANS..50 да Идентификатор товара, должен быть согласован с банком.
Параметры блока :customerDetails
Название Тип Обязательно Описание
email ANS..40 Нет Электронная почта покупателя
phone N.12 Нет Номер телефона покупателя
contact ANS..40 Нет Способ связи с покупателем
deliveryInfo Нет Блок с атрибутами адреса для доставки. Описание его атрибутов представлено ниже.
Параметры блока :deliveryInfo
Название Тип Обязательно Описание
deliveryType ANS..20 нет Тип доставки
country A..2 да Страна доставки
city ANS..40 да Город доставки
postAddress ANS..255 да Адрес для доставки
Примечание: обязательность параметров указана для использования в рамках блока. Если блок необязательный и отсутствует, то и
параметры в него входящие не должны передаваться.
Параметры блока :cartItems
Название Тип Обязательно Описание
items нет Элемент массива с атрибутами товарной позиции в орзине. Описание его атрибутов представлено ниже.К
Атрибуты элемента :items
Название Тип Обязательно Описание
positionId N..12 да Уникальный идентификатор товарной позиции внутри Корзины Заказа
name ANS..100 да Наименование или описание товарной позиции в свободной форме
itemDetails нет Дополнительный блок с параметрами описания товарной позиции. Описание его атрибутов
представлено ниже.
quantity да Элемент описывающий общее количество товарных позиций одного и их меруpositionId
измерения. Описание его атрибутов представлено ниже.
itemAmount N..18 Условно
Обязательно при
предоставлении
покупателю
возможности
интернет-кредитования
Сумма стоимости всех товарных позиций одного в минимальных единицах валюты. positionId
обязателен к передаче, только если не был передан параметр . ВitemAmount itemPrice
противном случае передача не требуется. Если же в запросе передаются обаitemAmount
параметра: и , то должен равняться itemPrice itemAmount itemAmount itemPrice *
, в противном случае запрос завершится с ошибкой.quantity
itemCurrency N3 Условно
Обязательно при
предоставлении
покупателю
возможности
интернет-кредитования
Код валюты товарной позиции ISO 4217. Если не указан, считается равным валюте заказа.
itemCode ANS..100 да Номер (идентификатор) товарной позиции в системе магазина. Параметр должен быть
уникальным в рамках запроса.
discount нет Дополнительный блок с атрибутами описания скидки для товарной позиции. Описание его
атрибутов представлено ниже.
agentInterest нет Дополнительный блок с атрибутами описания агентской комиссии за продажу товара. Описание
его атрибутов представлено ниже.
Атрибуты элемента :quantity
Название Тип Обязательно Описание
value N..18 да Количество товарных позиций данного .positionId Для указания дробных чисел используйте десятичную
точку.
measure ANS..20 да Мера измерения количества товарной позиции
Параметры блока :itemDetails
Название Тип Обязательно Описание
itemDetailsParams Условно
Обязательно при предоставлении покупателю
возможности интернет-кредитования
Параметр описывающий дополнительную информацию по товарной
позиции. Описание его атрибутов представлено ниже.
Атрибуты параметра :itemDetailsParams
Название Тип Обязательно Описание
value ANS..255 Условно
Обязательно при наличии параметра itemDetailsPara
ms
Дополнительная информация по товарной позиции
name ANS..255 Условно
Обязательно при наличии параметра itemDetailsPara
ms
Наименование параметра описания детализации товарной
позиции
Параметры блока :discount
Название Тип Обязательно Описание
discountType ANS..20 да Тип скидки на товарную позицию
discountValue N..20 Да Значение скидки на товарную позицию
Параметры блока :agentInterest
Название Тип Обязательно Описание
interestType ANS..20 да Тип агентской комиссии за продажу товара
При расчёте параметра результат округляетсяitemAmount = itemPrice*quantity
до второго знака после десятичного разделителя. Например, если результат
вычислений равен , то итоговый результат будет равен .100,255 100,26
interestValue N..20 Да Значение агентской комиссии за продажу товара
Параметры ответа:
Название Тип Обязательно Описание
orderId ANS36 нет Номер заказа в платежной системе. Уникален в пределах системы. Отсутствует, если регистрация заказа на
удалась по причине ошибки, детализированной в .errorCode
formUrl AN..512 нет URL платежной формы, на который надо перенаправить браузер клиента. Не возвращается если
регистрация заказа не удалась по причине ошибки, детализированной в .errorCode
errorCode N3 нет Код ошибки. Может отсутствовать, если результат не привел к ошибке.
errorMessage AN..512 нет Описание ошибки на языке, переданном в параметре в запросе.language
Коды ошибок (поле ):errorCode
Значение Описание
1 Заказ с таким номером уже обработан.
1 Неверный номер заказа.
3 Неизвестная валюта.
4 Номер заказа не может быть пуст.
4 Имя мерчанта не может быть пустым.
4 Отсутствует сумма.
4 URL возврата не может быть пуст.
4 Пароль не может быть пуст.
5 Неверно указано значение одного из параметров.
5 Доступ запрещён.
5 Пользователь отключён.
7 Системная ошибка.
8 Отсутствие обязательного параметра орзины.К
8 Валюта в Корзине не совпадает с валютой заказа.
8 Сумма товарных позиций в Корзине не совпадает с общей суммой заказа.
8 Неверный формат Корзины.
8 Слишком большое либо слишком маленькое значение quantity.
Пример запроса GET:
https://3dsec.sberbank.ru/sbercredit/register.do?amount=24000¤cy=643&language=ru&
orderNumber=04f04a87d6f45rg3r3d21&password=password&returnUrl=https://server/applicaton_context/finish.ht
ml&userName=userName&
jsonParams={"name1":"value1"}&sessionTimeoutSecs=5400&merchantLogin=merch_child&
orderBundle={ "orderCreationDate":1373622660000, "customerDetails":
{ "email":"1234567890123456789012345678901234567890", "phone": "79851231234", "contact": "Mega Tester",
"deliveryInfo":{ "deliveryType":"courier", "country":"RU", "city":"Moscow",
"postAddress":" 50 .2" }}, "cartItems": { "items": [ { "positionId": "1",
"name": "Metzeler Enduro 3 Sahara", "itemDetails": { "itemDetailsParams":
[{ "value": "Metzeler ", "name": "brand" }, { "value": "17inch", "name": "radius" }]},
"quantity": { "value": 0.71, "measure": "" }, "itemAmount": 8000, "itemCurrency": "643",
"itemCode": "NM-15", "discount": { "discountType": "percent", "discountValue": "5" },
"agentInterest": { "interestType": "agentPercent", "interestValue": "7" } },
{ "positionId": "2", "name": "Universal Mirror Enduro", "itemDetails": { "itemDetailsParams":
[{ "value": "Noname", "name": "brand" }, { "value": "12mm", "name": "diameter" }]},
"quantity": { "value": 1.0, "measure": "" }, "itemAmount": 8000, "itemCurrency": "643",
"itemCode": "NM-15", "discount": { "discountType": "percent", "discountValue": "5" },
"agentInterest": { "interestType": " agentPercent ", "interestValue": "7" } },
{ "positionId": "3", "name": "Warm Grips", "itemDetails": { "itemDetailsParams":
[ { "value": "Noname", "name": "brand" }]}, "quantity": { "value": 1.0, "measure": "" },
"itemAmount": 8000, "itemCurrency": 643, "itemCode": "G-16",
"discount": { "discountType": "percent", "discountValue": "5" },
"agentInterest": { "interestType": " agentPercent ", "interestValue": "7" } }] } } }
Пример запроса POST:
amount=24000¤cy=643&language=ru&orderNumber=04f04a87d6f45rg3r3d21&returnUrl=https://3dsec.sberbank.
ru/payment/finish.html&
jsonParams={"name1":"value1"}&sessionTimeoutSecs=5400&merchantLogin=merch_child&
orderBundle={ "orderCreationDate":1373622660000, "customerDetails":
{ "email":"1234567890123456789012345678901234567890", "phone": "79851231234", "contact": "Mega Tester",
"deliveryInfo":{ "deliveryType":"courier", "country":"RU", "city":"Moscow",
"postAddress":" 50 .2" }}, "cartItems": { "items": [ { "positionId": "1",
"name": "Metzeler Enduro 3 Sahara", "itemDetails": { "itemDetailsParams":
[{ "value": "Metzeler ", "name": "brand" }, { "value": "17inch", "name": "radius" }]},
"quantity": { "value": 0.71, "measure": "" }, "itemAmount": 8000, "itemCurrency": "643",
"itemCode": "NM-15", "discount": { "discountType": "percent", "discountValue": "5" },
"agentInterest": { "interestType": "agentPercent", "interestValue": "7" } },
{ "positionId": "2", "name": "Universal Mirror Enduro", "itemDetails": { "itemDetailsParams":
[{ "value": "Noname", "name": "brand" }, { "value": "12mm", "name": "diameter" }]},
"quantity": { "value": 1.0, "measure": "" }, "itemAmount": 8000, "itemCurrency": "643",
"itemCode": "NM-15", "discount": { "discountType": "percent", "discountValue": "5" },
"agentInterest": { "interestType": " agentPercent ", "interestValue": "7" } },
{ "positionId": "3", "name": "Warm Grips", "itemDetails": { "itemDetailsParams":
[ { "value": "Noname", "name": "brand" }]}, "quantity": { "value": 1.0, "measure": "" },
"itemAmount": 8000, "itemCurrency": 643, "itemCode": "G-16",
"discount": { "discountType": "percent", "discountValue": "5" },
"agentInterest": { "interestType": " agentPercent ", "interestValue": "7" } }] } } }
Пример ответа:
{"formUrl":" ?https://3dsec.sberbank.ru/payment/789/payment_ru.html
mdOrder=ece47318-19f2-466a-93cd-bdb08c1587ec","orderId":"ece47318-19f2-466a-93cd-bdb08c1587ec"}
19.4.2.2. Двухстадийная оплата
Для регистрации заказа с предавторизацией используется запрос (см. раздел " ").registerPreAuth.do Координаты подключения
Товарная Корзина передаётся в параметре orderBundle.
Параметры запроса:
Название Тип Обязательно Описание
userName AN..30 нет (нужно
указать либо
пару логин и
пароль, либо
токен)
Логин магазина, полученный при подключении. Если вместо аутентификации по логину и паролю
используется открытый токен (параметр token), параметр передавать не нужно.userName
password AN..30 нет (нужно
указать либо
пару логин и
пароль, либо
токен)
Пароль магазина, полученный при подключении. Если для аутентификации при регистрации вместо
логина и пароля используется открытый токен (параметр token), параметр передавать неpassword
нужно.
token AN..30 нет (нужно
указать либо
пару логин и
пароль, либо
токен)
Открытый ключ, который можно использовать для регистрации заказа. Если для аутентификации
при регистрации заказа используются логин и пароль, параметр передавать не нужно.token
orderNumber AN..32 да Номер (идентификатор) заказа в системе магазина
amount N..20 да Сумма платежа в минимальных единицах валюты. Должна совпадать с общей суммой по всем
товарным позициям в Корзине.
currency N3 нет Код валюты платежа ISO 4217. Единственное допустимое значение - 643.
returnUrl AN..512 да Адрес, на который требуется перенаправить пользователя в случае успешной оплаты. Адрес
должен быть указан полностью, включая используемый протокол (например, вместо https://test.ru tes
). В противном случае пользователь будет перенаправлен по адресу следующего вида: t.ru http://<ад
.рес_платёжного_шлюза>/<адрес_продавца>
failUrl AN..512 нет Адрес, на который требуется перенаправить пользователя в случае неуспешной оплаты. Адрес
должен быть указан полностью, включая используемый протокол (например, вместо https://test.ru tes
). В противном случае пользователь будет перенаправлен по адресу следующего вида: t.ru http://<ад
.рес_платёжного_шлюза>/<адрес_продавца>
description ANS..512 нет Описание заказа в свободной форме. В процессинг банка для включения в финансовую отчётность
продавца передаются только первые 24 символа этого поля.
language A2 нет Язык в кодировке ISO 639-1. Если не указан, будет использован язык, указанный в настройках
магазина как язык по умолчанию.
pageView ANS..20 нет По значению данного параметра определяется, какие страницы платёжного интерфейса должны
загружаться для клиента. Возможные значения:
DESKTOP – для загрузки страниц, верстка которых предназначена для отображения на экранах
ПК (в архиве страниц платёжного интерфейса будет осуществляться поиск страниц с
названиями и );payment_<locale>.html ocale>.htmlerrors_<l
MOBILE – для загрузки страниц, верстка которых предназначена для отображения на экранах
мобильных устройств (в архиве страниц платёжного интерфейса будет осуществляться поиск
страниц с названиями и mobile_payment_<locale>.html ocale>.htmlmobile_errors_<l
);
Если магазин создал страницы платёжного интерфейса, добавив в название файлов страниц
произвольные префиксы, передайте значение нужного префикса в параметре дляpageView
загрузки соответствующей страницы. Например, при передаче значения в архивеiphone
страниц платёжного интерфейса будет осуществляться поиск страниц с названиями iphone_p
и .ayment_<locale>.html iphone_error_<locale>.html
Где:
locale – я . Например, для русского или длязык страницы в кодировке ISO 639-1 ru en
английского.
Если параметр отсутствует, либо не соответствует формату, то по умолчанию считается pageView=
.DESKTOP
clientId ANS..255 нет Номер (идентификатор) клиента в системе магазина. Используется для реализации функционала
связок. Может присутствовать, если магазину разрешено создание связок.
merchantLogin AN..255 нет Чтобы зарегистрировать заказ от имени дочернего мерчанта, укажите его логин в этом параметре.
jsonParams AN..1024 нет Блок для передачи дополнительных параметров мерчанта. Поля дополнительной информации для
последующего хранения, передаются в виде:
{"<name1>":"<value1>",...,"<nameN>":"<valueN>"},
Данные поля могут быть переданы в процессинг банка для последующего отображения в реестрах.*
Включение данного функционала возможно по согласованию с банком в период интеграции.
Если для продавца настроена отправка покупателю, адрес электронной почтыуведомлений
покупателя должен передаваться в этом блоке в параметре с именем .email
sessionTimeoutSecs N...9 нет Продолжительность жизни заказа в секундах.
В случае если параметр не задан, будет использовано значение, указанное в настройках мерчанта
или время по умолчанию (1200 секунд = 20 минут).
Если в запросе присутствует параметр expirationDate, то значение параметра sessionTimeout
. Secs не учитывается
expirationDate ANS нет Дата и время окончания жизни заказа. Формат: .yyyy-MM-ddTHH:mm:ss
Если этот параметр не передаётся в запросе, то для определения времени окончания жизни заказа
.используется sessionTimeoutSecs
bindingId AN..255 no Идентификатор связки, созданной ранее. Может использоваться, только если у магазина есть
разрешение на работу со связками. Если этот параметр передаётся в данном запросе, то это
означает:
1. Данный заказ может быть оплачен только с помощью связки;
2. Плательщик будет перенаправлен на платёжную страницу, где требуется только ввод CVC.
orderBundle Корзина товаров заказа
* По умолчанию в процессинг банка передаются поля:
orderNumber – номер заказа в системе магазина;
description – описание заказа (не более 24 символов, запрещены к использованию %, +, конец строки \r и
перенос строки \n).
Если в заказе передать дополнительный параметр с именем , то именно его значение будет передано вmerchantOrderId
процессинг в качестве номера заказа (вместо значения поля ).orderNumber
Параметр :orderBundle
Название Тип Обязательно Описание
orderCreationDate ANS..21 нет Дата создания заказа
customerDetails нет Блок с атрибутами данных о покупателе
cartItems да Блок с атрибутами товарных позиции орзиныК
installments Условно
Обязательно при предоставлении покупателю возможности
интернет-кредитования
Блок, в котором указаны параметры типа и срока
интернет-кредитования.
Параметры блока :installments
Название Тип Обязательно Описание
productType N..1 да Признак покупки в кредит. Возможны следующие значения:
CREDIT - кредит;
INSTALLMENT - рассрочка.
productId ANS..50 да Идентификатор товара, должен быть согласован с банком.
Параметры блока :customerDetails
Название Тип Обязательно Описание
email ANS..40 Нет Электронная почта покупателя
phone N.12 Нет Номер телефона покупателя
contact ANS..40 Нет Способ связи с покупателем
deliveryInfo Нет Блок с атрибутами адреса для доставки
Параметры блока :deliveryInfo
Название Тип Обязательно Описание
deliveryType ANS..20 нет Тип доставки
country A..2 да Страна доставки
city ANS..40 да Город доставки
postAddress ANS..255 да Адрес для доставки
Примечание: обязательность параметров указана для использования в рамках блока. Если блок необязательный и отсутствует, то и
параметры в него входящие не должны передаваться.
Параметры блока :cartItems
Название Тип Обязательно Описание
items нет Элемент массива с атрибутами товарной позиции в орзинеК
Атрибуты элемента :items
Название Тип Обязательно Описание
positionId N..12 да Уникальный идентификатор товарной позиции внутри Корзины Заказа
name ANS..100 да Наименование или описание товарной позиции в свободной форме
itemDetails нет Дополнительный блок с параметрами описания товарной позиции
quantity да Элемент описывающий общее количество товарных позиций одного positionId и их меру
измерения.
itemAmount N..18 Условно
Обязательно при
предоставлении
покупателю
возможности
интернет-кредитования
Сумма стоимости всех товарных позиций одного в минимальных единицах валюты. positionId
обязателен к передаче, только если не был передан параметр . ВitemAmount itemPrice
противном случае передача не требуется. Если же в запросе передаются обаitemAmount
параметра: и , то должен равняться itemPrice itemAmount itemAmount itemPrice *
, в противном случае запрос завершится с ошибкой.quantity
itemCurrency N3 Условно
Обязательно при
предоставлении
покупателю
возможности
интернет-кредитования
Код валюты товарной позиции ISO 4217. Если не указан, считается равным валюте заказа.
itemCode ANS..100 да Номер (идентификатор) товарной позиции в системе магазина
discount нет Дополнительный блок с атрибутами описания скидки для товарной позиции
agentInterest нет Дополнительный блок с атрибутами описания агентской комиссии за продажу товара
Атрибуты элемента :quantity
Название Тип Обязательно Описание
value N..18 да Количество товарных позиций данного positionId. Для указания дробных чисел используйте десятичную точку.
measure ANS..20 да Мера измерения количества товарной позиции
Параметры блока :itemDetails
Название Тип Обязательно Описание
itemDetailsParams Условно
Обязательно при предоставлении покупателю возможности
интернет-кредитования
Параметр описывающий дополнительную информацию
по товарной позиции
Атрибуты параметра :itemDetailsParams
Название Тип Обязательно Описание
value ANS..255 Условно
Обязательно при наличии параметра itemDetailsParams
Дополнительная информация по товарной позиции
При расчёте параметра результат округляетсяitemAmount = itemPrice*quantity
до второго знака после десятичного разделителя. Например, если результат
вычислений равен , то итоговый результат будет равен .100,255 100,26
name ANS..255 Условно
Обязательно при наличии параметра itemDetailsParams
Наименование параметра описания детализации товарной позиции
Параметры блока :discount
Название Тип Обязательно Описание
discountType ANS..20 да Тип скидки на товарную позицию
discountValue N..20 Да Значение скидки на товарную позицию
Параметры блока :agentInterest
Название Тип Обязательно Описание
interestType ANS..20 да Тип агентской комиссии за продажу товара
interestValue N..20 Да Значение агентской комиссии за продажу товара
Параметры ответа:
Название Тип Обязательно Описание
orderId ANS36 нет Номер заказа в платежной системе. Уникален в пределах системы. Отсутствует, если регистрация заказа на
удалась по причине ошибки, детализированной в .errorCode
formUrl AN..512 нет URL платежной формы, на который надо перенаправить браузер клиента. Не возвращается если
регистрация заказа не удалась по причине ошибки, детализированной в .errorCode
errorCode N3 нет Код ошибки. Может отсутствовать, если результат не привел к ошибке.
errorMessage AN..512 нет Описание ошибки на языке, переданном в параметре в запросе.language
Коды ошибок (поле ):errorCode
Значение Описание
1 Заказ с таким номером уже обработан
3 Неизвестная валюта
4 Номер заказа не может быть пуст
4 Имя мерчанта не может быть пустым
4 Отсутствует сумма
4 URL возврата не может быть пуст
4 Пароль не может быть пуст
5 Неверно указано значение одного из параметров
5 Доступ запрещён
5 Пользователь отключён
7 Системная ошибка
8 Отсутствие обязательного параметра орзиныК
8 Валюта в Корзине не совпадает с валютой заказа
8 Сумма товарных позиций в Корзине не совпадает с общей суммой заказа
8 Сумма бонусных балов к списанию в Корзине превышает допустимое количество
8 Неверный формат Корзины
8 Слишком большое либо слишком маленькое значение quantity
Пример запроса GET:
https://3dsec.sberbank.ru/sbercredit/registerPreAuth.do?amount=24000¤cy=643&language=ru&
orderNumber=01a287222222299&password=password&userName=userName&returnUrl= finish.html&https://3dsec.sberbank.ru/payment/
jsonParams={"name1":"value1"}&merchantLogin=merch_child&orderBundle={ "orderCreationDate":1373622660000,
"customerDetails":{ "email":"1234567890123456789012345678901234567890", "phone": "79851231234",
"contact": "Mega Tester", "deliveryInfo":{ "deliveryType":"courier", "country":"RU", "city":"Moscow",
"postAddress":"Земляной Вал 50А стр.2" }},
"cartItems": { "items": [ { "positionId": "1", "name": "Metzeler Enduro 3 Sahara",
"itemDetails": { "itemDetailsParams": [{ "value": "Metzeler ", "name": "brand" },
{ "value": "17inch", "name": "radius" }]}, "quantity": { "value": 0.71, "measure": "штук" },
"itemAmount": 8000, "itemCurrency": "643", "itemCode": "NM-15",
"discount": { "discountType": "percent", "discountValue": "5" },
"agentInterest": { "interestType": "agentPercent", "interestValue": "7" } },
{ "positionId": "2", "name": "Universal Mirror Enduro",
"itemDetails": { "itemDetailsParams": [{ "value": "Noname", "name": "brand" },
{ "value": "12mm", "name": "diameter" }]}, "quantity": { "value": 1.0, "measure": "штук" },
"itemAmount": 8000, "itemCurrency": "643", "itemCode": "NM-15",
"discount": { "discountType": "percent", "discountValue": "5" },
"agentInterest": { "interestType": " agentPercent ", "interestValue": "7" } },
{ "positionId": "3", "name": "Warm Grips",
"itemDetails": { "itemDetailsParams": [ { "value": "Noname", "name": "brand" }]},
"quantity": { "value": 1.0, "measure": "штук" }, "itemAmount": 8000, "itemCurrency": 643,
"itemCode": "G-16", "discount": { "discountType": "percent", "discountValue": "5" },
"agentInterest": { "interestType": " agentPercent ", "interestValue": "7" } }] } } }
Пример запроса POST:
amount=24000¤cy=643&language=ru&orderNumber=01a287222222299&returnUrl=https://3dsec.sberbank.ru/pay
finish.html&ment/
jsonParams={"name1":"value1"}&merchantLogin=merch_child&orderBundle={ "orderCreationDate":1373622660000,
"customerDetails":{ "email":"1234567890123456789012345678901234567890", "phone": "79851231234",
"contact": "Mega Tester", "deliveryInfo":{ "deliveryType":"courier", "country":"RU", "city":"Moscow",
"postAddress":" 50 .2" }}, "cartItems": { "items": [
{ "positionId": "1", "name": "Metzeler Enduro 3 Sahara",
"itemDetails": { "itemDetailsParams": [{ "value": "Metzeler ", "name": "brand" },
{ "value": "17inch", "name": "radius" }]}, "quantity": { "value": 0.71, "measure": "" },
"itemAmount": 8000, "itemCurrency": "643", "itemCode": "NM-15",
"discount": { "discountType": "percent", "discountValue": "5" },
"agentInterest": { "interestType": "agentPercent", "interestValue": "7" } },
{ "positionId": "2", "name": "Universal Mirror Enduro",
"itemDetails": { "itemDetailsParams": [{ "value": "Noname", "name": "brand" },
{ "value": "12mm", "name": "diameter" }]}, "quantity": { "value": 1.0, "measure": "" },
"itemAmount": 8000, "itemCurrency": "643", "itemCode": "NM-15",
"discount": { "discountType": "percent", "discountValue": "5" },
"agentInterest": { "interestType": " agentPercent ", "interestValue": "7" } },
{ "positionId": "3", "name": "Warm Grips",
"itemDetails": { "itemDetailsParams": [ { "value": "Noname", "name": "brand" }]},
"quantity": { "value": 1.0, "measure": "" },
"itemAmount": 8000, "itemCurrency": 643, "itemCode": "G-16",
"discount": { "discountType": "percent", "discountValue": "5" },
"agentInterest": { "interestType": " agentPercent ", "interestValue": "7" } }] } } }
Пример ответа:
{"formUrl":" ?https://3dsec.sberbank.ru/payment/merchants/789/payment_ru.html
mdOrder=fc122907-e237-440e-9f25-48bf6120984b","orderId":"fc122907-e237-440e-9f25-48bf6120984b"}
20. Приложение 8. Оплата через Google Pay
20.1. Введение
Возможны несколько вариантов реализации возможности оплаты с помощью системы Google Pay.
1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
Возможны несколько вариантов реализации возможности оплаты с помощью системы Google Pay.
Реализация способа оплаты Описание
Из мобильного приложения Оплата осуществляется из мобильного приложения с мобильного устройства пользователя. В этом
сценарии приложение запрашивает зашифрованные данные у Google Pay. Эти данные необходимо
передать в платёжный шлюз.
С веб-страницы, при этом
платёжная страница
расположена на стороне
продавца
Оплата осуществляется с веб-страницы. Пользователь выбирает оплату на сайте продавца, при
этом продавец запрашивает зашифрованные платёжные данные у системы Google Pay. Затем
продавец должен отправить эти данные в платёжный шлюз.
Оплата на платёжной странице,
которая расположена на
стороне платёжного шлюза
Оплата осуществляется с веб-страницы. Пользователь выбирает оплату на сайте продавца, после
чего продавец перенаправляет его на платёжную страницу на стороне платёжного шлюза.
20.2. Схемы взаимодействия
20.2.1. Оплата в мобильном приложении
Клиент выбирает способ оплаты Google Pay.
Приложение запрашивает Google Pay информацию о маскированных карточных данных.
Google Pay возвращает в приложение маскированные карточные данные.
Приложение отображает клиенту маскированные данные карты, добавленной в Google Pay.
Клиент подтверждает оплату с помощью добавленной в Google Pay карты.
Приложение запрашивает Google Pay зашифрованные карточные данные.
Google шифрует данные, используя открытый ключ - соответствующий ему закрытый ключ расположен в платёжном шлюзе.
Google возвращает в приложение зашифрованные данные о платеже.
Приложение отправляет в платёжный шлюз запрос на оплату Google Pay, указывая полученный от системы Google Pay токен:
Запрос на оплату Google Pay, интерфейс WS;
Запрос на оплату Google Pay, интерфейс REST.
Платёжный шлюз расшифровывает полученный токен и производит оплату.
Платёжный шлюз возвращает результат оплаты в приложение.
Приложение отображает результат оплаты клиенту.
1.
2.
3.
4.
5.
6.
7.
8.
20.2.2. Оплата на платёжной странице, которая расположена на стороне интернет-магазина
Клиент формирует заказ на сайте интернет-магазина и выбирает способ оплаты Google Pay.
Система интернет-магазина формирует запрос на оплату в Google Pay.
Система Google Pay формирует зашифрованные платёжные данные.
Система интернет-магазина получает зашифрованные платёжные данные
Система интернет-магазина формирует запрос в платёжный шлюз на оплату Google Pay, указывая полученные зашифрованные
платёжные данные:
;Запрос на оплату Google Pay, интерфейс WS
.Запрос на оплату Google Pay, интерфейс REST
Платёжный шлюз расшифровывает полученные данные и производит оплату.
РБС возвращает результат оплаты в систему интернет-магазина.
Результат оплаты отображается клиенту.
20.2.3. Оплата на платёжной странице, которая расположена на стороне платёжного шлюза
1.
2.
3.
4.
5.
6.
7.
8.
Клиент формирует заказ на сайте интернет-магазина и выбирает способ оплаты Google Pay.
Система интернет-магазина формирует запрос на оплату в Google Pay.
Система Google Pay формирует зашифрованные платёжные данные.
Система интернет-магазина получает зашифрованные платёжные данные
Система интернет-магазина формирует запрос в платёжный шлюз на оплату Google Pay, указывая полученные зашифрованные
платёжные данные:
;Запрос на оплату Google Pay, интерфейс WS
.Запрос на оплату Google Pay, интерфейс REST
Платёжный шлюз расшифровывает полученные данные и производит оплату.
РБС возвращает результат оплаты в систему интернет-магазина.
Результат оплаты отображается клиенту.
20.3. Запросы на оплату
Запрос на оплату Google Pay применяется в следующих случаях:
Интернет-магазин имеет прямую интеграцию с системой Google Pay;
Оплата производится из мобильного приложения;
Оплата производится с веб-страницы, и платёжная страница расположена на стороне продавца.
20.3.1. Запрос на оплату Google Pay, интерфейс WS
Для оплаты через Google Pay используется запрос .googlePay
Поле Обязательность Описание
Одностадийность или двухстадийсность платежа определяется значением параметра в запросе - см. описаниеpreAuth
запроса.
Для операций отмены, возврата и завершения платежа следует использовать стандартные запросы к платёжному шлюзу.
merchant Да Логин продавца в системе платёжного шлюза (выдаётся при регистрации).
orderNumber Да Номер заказа на в системе интернет-магазина (уникальный в пределах системы продавца).
description Нет Описание заказа.
language Нет Язык в кодировке ISO 639-1. Если не указан, будет использован язык, указанный в
настройках магазина как язык по умолчанию.
additionalParameters Нет Дополнительные параметры заказа, которые сохраняются для просмотра из личного
кабинета продавца. Для каждого дополнительного параметра следует использовать
следующие вложенный параметр , в который, в свою очередь, входят следующиеentry
вложенные параметры:
key - имя параметра;
value - значение параметра.
Ниже представлен пример части кода запроса с несколькими вложенными параметрами.
<entry>
<key>parameter_1</key>
<value>value_1</value>
</entry>
<entry>
<key>parameter_2</key>
<value>value_2</value>
</entry>
В случае использования внешнего MPI, платёжный шлюз ожидает, что в каждом запросе на
оплату заказа будет приходить параметр . Если значение отличается отeci eci
используемых для SSL-авторизаций, также необходимо передавать параметры и .xid cavv
preAuth Нет Параметр, определяющий необходимость предварительной авторизации (блокирования
средств на счету клиента до их списания). Доступны следующие значения:
true (истина) - параметр включён, оплата происходит с предавторизацией (происходит
блокирование средств клиента до списания);
false (ложь) - параметр выключен (списание происходит сразу).
Если параметр не указан в запросе, списание происходит сразу.
clientId Нет Номер клиента, для которого следует создать связку для проведения регулярных платежей.
Следует указывать, только если проводится технический платёж для последующих
регулярных платежей.
paymentToken Да JSON-объект, содержащий токен, полученный от Google. Должен быть в кодировке UTF-8.
JSON должен быть закодирован в base64.
ip Да IP-адрес плательщика
Если у продавца настроена фискализация, при указании в качестве
дополнительных параметров (адрес электронной почты покупателя) и/или email p
(номер сотового телефона покупателя) эти параметры в первую очередьhone
используются для отправки фискального чека.
При оплате с картами МИР с поддержкой 3-D Secure, если или ,ECI=05 ECI=06
значение должно передаваться в обязательном порядкеcavv
amount Да Сумма платежа в минимальный единицах валюты (например, в копейках).
currencyCode Нет Цифровой код валюты платежа ISO 4217. Если не указан, считается равным 643 (российский
рубль).
email Нет (см.
описание)
Адрес электронной почты. Обязателен, если у интернет-магазина настроена фискализация и
не указан номер телефона
phone Нет (см.
описание)
Номер телефона. Обязателен, если у интернет-магазина настроена фискализация и не
указан адрес электронной почты
Ниже представлен пример запроса на оплату.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:mer="http://engine.paymentgate.ru/webservices/merchant">
<soapenv:Header/>
<soapenv:Body>
<mer:googlePay>
<arg0>
<merchant>OurBestMerchantLogin</merchant>
<orderNumber>UAF-203974-DE</orderNumber>
<language>RU</language>
<preAuth>true</preAuth>
<paymentToken>\x7B\x0A\x20\x20\xE2\x80\x9C\x65\x6E\x63\x72\x79\x70\x74\x65
\x64\x4D\x65\x73\x73\x61\x67\
x65\xE2\x80\x9D\x3A\x20\xE2\x80\x9C\x5A\x57\x35\x6A\x63\x6E\x6C\x77\x64\x4
7\x56\x6B\x54\x57\x56\x7A\x63\x32\x46\
x6E\x5A\x51\x3D\x3D\xE2\x80\x9D\x2C\x0A\x20\x20\xE2\x80\x9C\x65\x70\x68\x6
5\x6D\x65\x72\x61\x6C\x50\x75\x62\x6C\x69\
x63\x4B\x65\x79\xE2\x80\x9D\x3A\x20\xE2\x80\x9C\x5A\x58\x42\x6F\x5A\x57\x3
1\x6C\x63\x6D\x46\x73\x55\x48\x56\x69\x62\
x47\x6C\x6A\x53\x32\x56\x35\xE2\x80\x9D\x2C\x0A\x20\x20\x22\x74\x61\x67\x2
2\x3A\x20\xE2\x80\x9D\x63\x32\x6C\x6E\x62\
x6D\x46\x30\x64\x58\x4A\x6C\xE2\x80\x9D\x0A\x7D</paymentToken>
<ip>127.0.0.1</ip>
<amount>230000</amount>
<currencyCode>643</currencyCode>
</arg0>
</mer:googlePay>
</soapenv:Body>
</soapenv:Envelope>
Описание параметров ответа представлено в таблице ниже.
Параметр Вложенный
параметр
Обязательный
параметр
Описание
success Не актуально Да Указывает на успешность проведения платежа. Доступны следующие значения:
true (истина) - платёж прошёл успешно;
false (ложь) - платёж не прошёл.
data
(возвращается, только если
платёж прошёл успешно)
orderId Да Уникальный для продавца номер заказа в платёжной системе.
error
(возвращается, только если
платёж не прошёл)
code Да Код ошибки.
description Да Подробное техническое объяснение ошибки - содержимое этого параметра не
предназначено для отображения пользователю.
message Да Понятное описание ошибки - предназначено для отображения пользователю.
termUrl Не актуально Нет Не используется при платежах, не требующих дополнительной аутентификации
на ACS банка-эмитента.
acsUrl Не актуально Нет Не используется при платежах, не требующих дополнительной аутентификации
на ACS банка-эмитента.
paReq Не актуально Нет Не используется при платежах, не требующих дополнительной аутентификации
на ACS банка-эмитента.
Ниже представлен пример ответа после успешной оплаты.
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<ns1:googlePayResponse
xmlns:ns1="http://engine.paymentgate.ru/webservices/merchant">
<return>
<success>true</success>
<data>
<orderId>12312312123</orderId>
</data>
<orderStatus errorCode="0"/>
</return>
</ns1:googlePayResponse>
</soap:Body>
</soap:Envelope>
Пример ответа после неуспешной оплаты.
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<ns1:googlePayResponse
xmlns:ns1="http://engine.paymentgate.ru/webservices/merchant">
<return>
<success>false</success>
<error>
<code>10</code>
<description> [orderNumber]</description>
</error>
<orderStatus errorCode="0"/>
</return>
</ns1:googlePayResponse>
</soap:Body>
</soap:Envelope>
Возможные коды ошибок представлены в таблице ниже.
Код ошибки Сообщение об ошибке
0 Обработка запроса прошла без системных ошибок
1 Недостаточно средств на карте
5 Доступ запрещён
Пользователь должен сменить свой пароль
7 Системная ошибка
10 Некорректное значение параметра [paymentToken]
Некорректное значение параметра [orderNumber]
Некорректное значение параметра [merchant]
Некорректное значение параметра [ip]
Расшифровка переданных данных неуспешна
Отсутствует приватный ключ
20.3.2. Запрос на оплату Google Pay, интерфейс REST
Запрос на оплату с помощью Google Pay в платёжный шлюз
Для регистрации заказа используется запрос (см. ).payment.do Координаты подключения
Описание параметров представлено в таблице ниже.
Параметр Обязательно Описание
merchant Да Имя входа продавца в системе платёжного шлюза.
orderNumber Да Уникальный номер заказа на стороне продавца.
description Нет Описание заказа.
language Нет Язык в кодировке ISO 639-1. Если не указан, будет использован язык, указанный в
настройках магазина как язык по умолчанию.
additionalParameters Нет Дополнительные параметры заказа, которые сохраняются для просмотра из личного
кабинета продавца. Дополнительные параметры следует указывать в следующем
формате.
"_": "_"
Каждую новую пару имени и значения параметра следует отделять запятой.
Для операций отмены, возврата и завершения платежа следует использовать стандартные запросы к платёжному шлюзу.
Если у продавца настроена фискализация, при указании в качестве
дополнительных параметров (адрес электронной почты покупателя)email
и/или (номер сотового телефона покупателя) эти параметры в первуюphone
очередь используются для отправки фискального чека.
preAuth Нет Параметр, определяющий необходимость предварительной авторизации (блокирования
средств на счету клиента до их списания). Доступны следующие значения:
true (истина) - параметр включён, оплата происходит с предавторизацией
(происходит блокирование средств клиента до списания);
false (ложь) - параметр выключен (списание происходит сразу).
Если параметр не указан в запросе, списание происходит сразу.
clientId Нет Номер клиента, для которого следует создать связку для проведения регулярных
платежей. Следует указывать, только если проводится технический платёж для
последующих регулярных платежей.
paymentToken Да Токен, полученный от Google Pay и закодированный в Base64.
ip Да IP-адрес плательщика.
amount Да Сумма платежа в минимальный единицах валюты (например, в копейках).
currencyCode Нет Цифровой код валюты платежа ISO 4217. Если не указан, считается равным 643
(российский рубль).
email Нет (см.
описание)
Адрес электронной почты. Обязателен, если у интернет-магазина настроена
фискализация и не указан номер телефона.
phone Нет (см.
описание)
Номер телефона. Обязателен, если у интернет-магазина настроена фискализация и не
указан адрес электронной почты.
Ниже представлен пример запроса на оплату.
{
"merchant": "OurBestMerchantLogin",
"orderNumber": "UAF-203974-DE",
"language": "RU",
"preAuth": true,
"description" : "Test description",
"additionalParameters":
{
"firstParamName": "firstParamValue",
"secondParamName": "secondParamValue"
},
"paymentToken":
"eyJtZXJjaGFudCI6ICJrdXBpdmlwIiwib3JkZXJOdW1iZXIiOiAyMDUxOTIzMzkxLCJwYXltZ
W50VG9rZW4iOiAie1wiZXBoZW1lcmFsUHVibGljS2V5XCI6XCJrZXlcIixcImVuY3J5cHRlZE1
lc3NhZ2VcIjpcIm1lc3NhZ2VcIixcInRhZ1wiOlwidGFnXCJ9In0=",
"ip" : "127.0.0.1",
"amount" : "230000",
"currencyCode" : 643
}
Описание параметров ответа приведены в таблице ниже.
Для корректной обработки запроса необходимо добавить заголовок с определением типа содержимого - Content-Type:
.application/json
Описание параметров ответа приведены в таблице ниже.
Параметр Вложенный
параметр
Обязательный
параметр
Описание
success Не актуально Да Указывает на успешность проведения платежа. Доступны следующие значения:
true (истина) - платёж прошёл успешно;
false (ложь) - платёж не прошёл.
data
(возвращается, только если
платёж прошёл успешно)
orderId Да Уникальный для продавца номер заказа в платёжной системе.
error
(возвращается, только если
платёж не прошёл)
code Да Код ошибки.
description Да Подробное техническое объяснение ошибки - содержимое этого параметра не
предназначено для отображения пользователю.
message Да Понятное описание ошибки - предназначено для отображения пользователю.
termUrl Не актуально Нет Не используется при платежах, не требующих дополнительной аутентификации
на ACS банка-эмитента.
acsUrl Не актуально Нет Не используется при платежах, не требующих дополнительной аутентификации
на ACS банка-эмитента.
paReq Не актуально Нет Не используется при платежах, не требующих дополнительной аутентификации
на ACS банка-эмитента.
Примеры и описание ответа
Успешная оплата
{
"success":true,
"data": {
"orderId": "12312312123"
}
Неуспешная оплата
{
"error": {
"code": 1,
"description":
"Processing Error",
"message":
" "
},
"success": false
}
Описание возможных кодов ошибок представлено в таблице ниже.
Код ошибки Сообщение об ошибке
0 Обработка запроса прошла без системных ошибок
1 Недостаточно средств на карте
5 Доступ запрещён
Пользователь должен сменить свой пароль
7 Системная ошибка
10 Некорректное значение параметра [paymentToken]
Некорректное значение параметра [orderNumber]
Некорректное значение параметра [merchant]
Некорректное значение параметра [ip]
Расшифровка переданных данных неуспешна
Отсутствует приватный ключ
