Sorry, you need to enable JavaScript to visit this website.

You are here

Передача корзины товаров (кассовый чек 54-ФЗ)

1. Введение

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

2. Требования к запросам через Merchant API. Протоколы SOAP и REST

2.1. Требования к формированию запросов регистрации заказа с Корзиной

В запросах на регистрацию заказа (с предавторизацией или без) Корзина товаров передаётся в параметре <orderBundle>.

  • Все товарные позиции Корзины должны быть выражены в одной и той же валюте (если валюта позиции указывается), и должны совпадать с валютой Заказа.
  • Сумма всех товарных позиций Корзины должна быть равна сумме Заказа;
  • По каждой товарной позиции производится проверка переданного значения <quantity>. В случае если значение слишком большое или слишком маленькое, то запрос завершается ошибкой.
  • Все параметры Корзины валидируются на соответствие требуемому формату (длине).

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

2.2. Требования к формированию запросов завершения заказа с Корзиной

При завершении заказов Корзина передаётся в элементе <depositItems>.

  • В случае завершения на полную предавторизованную сумму передача Корзины необязательна.
  • Сумма завершения (в деньгах) в Корзине не должна превышать предавторизованную денежную сумму заказа.
  • При завершении заказа на сумму отличную от суммы предавторизации (кроме передачи значения «0») обязательно должна передаваться Корзина товаров.
  • Все товарные позиции Корзины должны быть выражены в одной и той же валюте (если валюта позиций указывается), и должны совпадать с валютой оригинального Заказа.
  • В Корзине запрещены для передачи новые товарные позиции, отсутствующие в оригинальном заказе. Происходит проверка наличия указанного товара в Корзине запроса на завершение в изначальном заказе. Необходимо совпадение элементов <positionId>, <name>, <itemCode>. Если хотя бы одно из значений не совпадает, считается, что данная товарная позиция отсутствует в Корзине заказа на регистрацию.
  • Значение элемента <quantity> в Корзине запроса на завершение не должно превышать значение аналогичного параметра в Корзине заказа на регистрацию.
  • Значение элемента <itemAmount> блока <items> не должно превышать значение аналогичного параметра в оригинальном заказе.
  • По каждой товарной позиции производится проверка переданного значения <quantity>. В случае если значение слишком большое или слишком маленькое, то запрос завершается ошибкой.
  • Все параметры Корзины валидируются на соответствие требуемому формату (длине).

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

2.3. Требования к формированию запросов возврата заказа с Корзиной

В запросе на возврат Корзина указывается в блоке <refundItems>.

  • В случае полного возврата Заказа, передача Корзины товаров необязательна.
  • При возврате заказа на сумму отличную от суммы списания (кроме передачи значения «0») обязательно должна передаваться Корзина товаров.
  • В случае проведения нескольких возвратов по заказам с Корзиной, все они должны осуществляться только по алгоритму возврата с Корзиной.
  • Сумма возврата (в деньгах) в Корзине не должна превышать подтвержденную денежную сумму оригинального заказа.
  • Все товарные позиции Корзины должны быть выражены в одной и той же валюте (если валюта позиций указывается), совпадающей с валютой оригинального Заказа.
  • В Корзине запрещены для передачи товарные позиции, отсутствующие в оригинальном заказе. Происходит проверка наличия указанного товара в Корзине запроса на возврат в изначальном заказе. Необходимо совпадение элементов <positionId>, <name>, <itemCode>. Если хотя бы одно из значений не совпадает, считается, что данная товарная позиция отсутствует в оригинальном заказе.
  • Значение элемента <quantity> в Корзине запроса на завершение не должно превышать значение аналогичного параметра в Корзине заказа на регистрацию.
  • Значение элемента <itemAmount> блока <items> не должно превышать значение аналогичного параметра в оригинальном заказе.
  • Все параметры Корзины валидируются на соответствие требуемому формату (длине).

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

 

 

3. Интерфейс на WebService-ах

3.1. Запросы, используемые при одностадийной оплате

3.1.1. Запрос регистрации заказа

Для регистрации заказа в системе используется запрос registerOrder . Состав товарной Корзины передаётся в параметре <orderBundle> .

Раздел " Требования к формированию запросов регистрации заказа с Корзиной " содержит список условий, необходимых для корректного формирования запроса.

 

 

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

Название

Тип

Обязательно

Описание

merchantOrderNumber

ANS..32

да

Номер (идентификатор) заказа в системе магазина, уникален для каждого магазина в пределах системы. Если номер заказа генерируется на стороне платёжного шлюза, этот параметр передавать необязательно.

description

ANS..512

нет

Описание заказа в свободной форме. В процессинг банка для включения в финансовую отчётность продавца передаются только первые 24 символа этого поля.

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

 

amount

N..20

да

Сумма платежа в минимальных единицах валюты

currency

N3

нет

Код валюты платежа ISO 4217. Если не указан, считается равным коду валюты по умолчанию.

language

A2

нет

Язык в кодировке ISO 639-1. Если не указан, будет использован язык, указанный в настройках магазина как язык по умолчанию (default language).

pageView

ANS..20

нет

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

  • DESKTOP – для загрузки страниц, верстка которых предназначена для отображения на экранах ПК (в архиве страниц платёжного интерфейса будет осуществляться поиск страниц с названиями payment_<locale>.html и errors_<l ocale>.html );
  • MOBILE – для загрузки страниц, верстка которых предназначена для отображения на экранах мобильных устройств (в архиве страниц платёжного интерфейса будет осуществляться поиск страниц с названиями mobile_payment_<locale>.html и mobile_errors_<l ocale>.html );
  • Если магазин создал страницы платёжного интерфейса, добавив в название файлов страниц произвольные префиксы, передайте значение нужного префикса в параметре pageView для загрузки соответствующей страницы. Например, при передаче значения iphone в архиве страниц платёжного интерфейса будет осуществляться поиск страниц с названиями iphone_payment_ <locale>.html и iphone_error_ <locale>.html .

Где:

locale – я зык страницы в кодировке ISO 639-1 . Например, ru для русского или en для английского.

Если параметр отсутствует, либо не соответствует формату, то по умолчанию считается pageView=DESKTOP .

sessionTimeoutSecs

N...9

нет

Продолжительность жизни заказа в секундах.

В случае если параметр не задан, будет использовано значение, указанное в настройках мерчанта или время по умолчанию (1200 секунд = 20 минут).

Если в запросе присутствует параметр expirationDate, то значение параметра sessionTimeoutSecs не учитывается.

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 вместо test.ru ). В противном случае пользователь будет перенаправлен по адресу следующего вида: http://<адрес_платёжного_шлюза>/<адрес_продавца> .

params

 

нет

Тэг с атрибутами для передачи дополнительных параметров мерчанта.

Поля дополнительной информации для последующего хранения. Для передачи N параметров, в запросе должно находиться N тэгов params, где атрибут name содержит название, а атрибут value содержит значение:

Название

Тип

Обязательно

Описание

name

AN..20

да

Название дополнительного параметра

value

AN..1024

да

Значение дополнительного параметра

Данные поля могут быть переданы в процессинг банка для последующего отображения в реестрах.*

Включение данного функционала возможно по согласованию с банком в период интеграции.

Если для продавца настроена отправка уведомлений покупателю, адрес электронной почты покупателя должен передаваться в этом тэге в параметре с именем email.

clientId

ANS..255

нет

Номер (идентификатор) клиента в системе магазина. Используется для реализации функционала связок. Может присутствовать, если магазину разрешено создание связок.

merchantLoginAN..255нетЧтобы зарегистрировать заказ от имени дочернего мерчанта, укажите его логин в этом параметре.

oderBundle

  

Тэг, содержащий Корзину товаров заказа. Описание его атрибутов представлено ниже.

taxSystemN..2да - для фискализации (для магазинов без настроек фискализации параметр не обязателен)

Система налогообложения, доступны следующие значения:

  • 0 - общая;
  • 1 - упрощённая, доход;
  • 2 - упрощённая, доход минус расход;
  • 3 - единый налог на вменённый доход;
  • 4 - единый сельскохозяйственный налог;
  • 5 - патентная система налогообложения.

* По умолчанию в процессинг банка передаются поля:

      • merchantOrderNumber – номер заказа в системе магазина;
      • description – описание заказа (не более 99 символов, запрещены к использованию %, +, конец строки \r и перенос строки \n).

Если в заказе передать дополнительный параметр с именем merchantOrderId , то именно его значение будет передано в процессинг в качестве номера заказа (вместо значения поля orderNumber ).

Параметр orderBundle :

Название

Тип

Обязательно

Описание

orderCreationDate

ANS..21

нет

Дата создания заказа

customerDetails

 

нет

Тэг с атрибутами данных о покупателе. Описание его атрибутов представлено ниже.

cartItems

 

да

Тэг с атрибутами товарных позиции Корзины. Описание его атрибутов представлено ниже.

Параметры блока customerDetails :

Название

Тип

Обязательно

Описание

email

ANS..40

Нет

Электронная почта покупателя.

Обязательно следует передать один из двух параметров: email или phone .

phone

ANS.12

Нет

Номер телефона покупателя.

Обязательно следует передать один из двух параметров: email или phone .

contact

ANS..40

Нет

Способ связи с покупателем.

deliveryInfo

 

Нет

Тэг с атрибутами адреса для доставки. Описание его атрибутов представлено ниже.

Параметры блока deliveryInfo :

Название

Тип

Обязательно

Описание

deliveryType

ANS..20

нет

Тип доставки

country

A..2

да

Страна доставки (в соответствии с ISO 3166-1)

city

ANS..40

да

Город доставки

postAddress

ANS..255

да

Адрес для доставки

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

Название

Тип

Обязательно

Описание

items

 

да

Тэг с параметрами, содержащими информацию по одной товарной позиции в Корзине.

Номер товарной позиции указывается в виде атрибута тэга:

Название

Тип

Обязательно

Описание

positionId

ANS..12

да

Уникальный идентификатор товарной позиции внутри Корзины Заказа

По каждой товарной позиции в запросе должен передаваться отдельный тэг items. Описание параметров тэга представлено ниже.

Параметры тэга items :

Название

Тип

Обязательно

Описание

name

ANS..100

да

Наименование или описание товарной позиции в свободной форме

itemDetails

 

нет

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

quantity

N..18

да

Элемент описывающий общее количество товарных позиций одного positionId и их меру измерения. Для указания дробных чисел используйте десятичную точку. Описание его атрибутов представлено ниже.

itemAmount

N..18

да

Сумма стоимости всех товарных позиций одного positionId в деньгах в минимальных единицах валюты.

itemCurrency

N..3

нет

Код валюты товарной позиции ISO 4217. Если не указан, считается равным валюте заказа.

itemCode

ANS..100

да

Номер (идентификатор) товарной позиции в системе магазина. Параметр должен быть уникальным в рамках запроса.

discount

 

нет

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

agentInterest

 

нет

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

tax  да - для фискализации (для магазинов без настроек фискализации параметр не обязателен)Тэг с параметрами для описания налога.
itemPriceN..18да - для фискализации (для магазинов без настроек фискализации параметр не обязателен)Стоимость одной товарной позиции данного positionId в деньгах в минимальных единицах валюты. Обязательно для мерчантов с фискализацией

 

 

Параметры тэга itemDetails :

Название

Тип

Обязательно

Описание

itemDetailsParams

ANS..255

нет

Параметр описывающий дополнительную информацию по товарной позиции. Описание его атрибутов представлено ниже.

Атрибуты параметра itemDetailsParams :

Название

Тип

Обязательно

Описание

name

AN..255

Условно

Обязательно при наличии параметра itemDetailsParams

Наименование параметра описания детализации товарной позиции

Атрибуты элемента quantity :

Название

Тип

Обязательно

Описание

measure

ANS..20

да

Мера измерения количества товарной позиции

Параметры блока discount :

Название

Тип

Обязательно

Описание

discountType

ANS..20

да

Тип скидки на товарную позицию

discountValue

N..20

Да

Значение скидки на товарную позицию

Параметры блока agentInterest :

Название

Тип

Обязательно

Описание

interestType

ANS..20

да

Тип агентской комиссии за продажу товара

interestValue

N..20

Да

Значение агентской комиссии за продажу товара

Состав блока tax

НазваниеТипОбязательноОписание
taxTypeN..2да

Ставка НДС, доступны следующие значения:

  • 0 – без НДС;
  • 1 – НДС по ставке 0%;
  • 2 – НДС чека по ставке 10%;
  • 3 – НДС чека по ставке 18%;
  • 4 – НДС чека по расчётной ставке 10/110;
  • 5 – НДС чека по расчётной ставке 18/118.

Обязательно для мерчантов с фискализацией

taxSum

N..18

нетСумма налога, высчитанная продавцом. Указывается в минимальных единицах валюты.

 

 

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

Название

Тип

Обязательно

Описание

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

Несуществующий идентификатор бонусной программы.

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>
            <taxSystem>0</taxSystem>

            <!--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>
                     <tax>
                     <taxType>1</taxType>
                     <taxSum>111</taxSum>
                     </tax>
                     <itemPrice>8000</itemPrice>
                  </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>
                     <tax>
                     <taxType>1</taxType>
                     <taxSum>111</taxSum>
                     </tax>
                     <itemPrice>8000</itemPrice>
                  </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>
                     <tax>
                     <taxType>1</taxType>
                     <taxSum>111</taxSum>
                     </tax>
                     <itemPrice>8000</itemPrice>
                  </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=531eaa8d-b32d-46dd-8e48-64b873886e70</formUrl>
         </return>
      </ns1:registerOrderResponse>
   </soap:Body>
</soap:Envelope>

 

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

 

 

 

3.1.3. Запрос полного возврата средств оплаты заказа

Для запроса полного возврата средств оплаты используется запрос refundOrder . По этому запросу средства по указанному заказу будут возвращены плательщику. Запрос закончится ошибкой в случае, если средства по этому заказу не были списаны.

Данную операцию можно осуществлять, если есть соответствующие права в системе.

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

Название

Тип

Обязательно

Описание

orderId

AN..64

да

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

refundAmount

N..5

да

Сумма возврата в валюте заказа (в минимальных единицах). Должна быть равна сумме заказа.

language

A2

нет

Язык в кодировке ISO 639-1. Если не указан, считается, что язык – русский. Сообщение ошибке будет возвращено именно на этом языке.

params

 

нет

Дополнительный тэг с атрибутами для передачи дополнительных параметров мерчанта *

* Поля дополнительной информации для последующего хранения. Данные поля могут быть переданы в процессинг банка для последующего отображения в реестрах.**

Включение данного функционала возможно по согласованию с банком в период интеграции. Для передачи N параметров, в запросе должно находиться N тэгов Params, где атрибут name содержит название, а атрибут value содержит значение:

Название

Тип

Обязательно

Описание

name

AN..20

да

Название дополнительного параметра

value

AN..1024

да

Значение дополнительного параметра

** По умолчанию в процессинг банка передаются поля номер заказа orderNumber и его описание description (не более 99 символов, запрещены к использованию %, +, конец строки \r и перенос строки \n)

 

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

Название

Тип

Обязательно

Описание

errorCode

N3

да

Код ошибки

errorMessage

AN..512

нет

Описание ошибки на языке, переданном в параметре Language в запросе.

Коды ошибок (поле errorCode):

Значение

Описание

0

Обработка запроса прошла без системных ошибок

5

Доступ запрещён

5

Пользователь должен изменить свой пароль

5

Не указан номер заказа

5

Неверная сумма

6

Неверный номер заказа

7

Платёж должен быть в корректном состоянии

7

Сумма возврата превышает сумму списания

7

Системная ошибка

8

Указанная сумма возврата не совпадает с полной суммой заказа. Для частичного возврата необходима Корзина

 

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

<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="3b32da16-1171-42c0-9d4e-bb6e243ff11d" refundAmount="24000">
            <!--Optional:-->

            <!--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="0"/>
      </ns1:refundOrderResponse>
   </soap:Body>
</soap:Envelope>


3.1.4. Запрос частичного возврата средств оплаты заказа

Для частичного возврата средств используется запрос refundOrder с обязательным указанием Корзины возвращаемых товаров. По этому запросу средства по заказу будут возвращены плательщику.

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

Раздел " Требования к формированию запросов возврата заказа с Корзиной " содержит список условий, необходимых для корректного формирования запроса.

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

Название

Тип

Обязательно

Описание

orderId

AN..64

да

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

refundAmount

N..5

да

Сумма возврата в валюте заказа (в минимальных единицах). Должна совпадать с общей суммой всех возвращаемых товарных позиций.

language

A2

нет

Язык в кодировке ISO 639-1. Если не указан, считается, что язык – русский. Сообщение ошибке будет возвращено именно на этом языке.

params

 

нет

Дополнительный тэг с атрибутами для передачи дополнительных параметров мерчанта *

refundItems

  

Тэг для передачи информации о возвращаемых товарах - номер позиции товара в запросе, название, детали, единица измерения, количество, валюта, код товара, скидка, выгода агента.

* Поля дополнительной информации для последующего хранения. Данные поля могут быть переданы в процессинг банка для последующего отображения в реестрах.**

Включение данного функционала возможно по согласованию с банком в период интеграции. Для передачи N параметров, в запросе должно находиться N тэгов Params, где атрибут name содержит название, а атрибут value содержит значение:

Название

Тип

Обязательно

Описание

name

AN..20

да

Название дополнительного параметра

value

AN..1024

да

Значение дополнительного параметра

** По умолчанию в процессинг банка передаются поля номер заказа orderNumber и его описание description (не более 99 символов, запрещены к использованию %, +, конец строки \r и перенос строки \n)

 

Параметры refundItems :

Название

Тип

Обязательно

Описание

items

 

да

Элемент массива с атрибутами товарной позиции в Корзине


Атрибуты элемента items :

Название

Тип

Обязательно

Описание

positionId

ANS..12

да

Уникальный идентификатор товарной позиции внутри Корзины Заказа

name

ANS..100

да

Наименование или описание товарной позиции в свободной форме

itemDetails

 

нет

Дополнительный тэг с параметрами описания товарной позиции

quantity

N..18

да

Элемент описывающий общее количество товарных позиций одного positionId и их меру измерения

itemAmount

N..18

да

Возвращаемая сумма по данному positionId в минимальных единицах валюты. Может быть равна или меньше суммы оплаты по данному positionId.

itemCurrency

N..3

нет

Код валюты товарной позиции ISO 4217. Если не указан, считается равным валюте заказа.

itemCode

ANS..100

да

Номер (идентификатор) товарной позиции в системе магазина

discount

 

нет

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

agentInterest

 

нет

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

tax нетДополнительный тэг с атрибутами описания налога. Если для магазина указаны настройки фискализации, данный блок может передаваться, но не является обязательным (значения параметров данного блока проверяться не будут).
itemPriceN..18нетСтоимость одной товарной позиции одного positionId в деньгах в минимальных единицах валюты. Если для магазина указаны настройки фискализации, данное поле может передаваться, но не является обязательным (значение данного поля проверяться не будет).




Параметры тэга itemDetails :

Название

Тип

Обязательно

Описание

itemDetailsParams

ANS..255

нет

Параметр описывающий дополнительную информацию по товарной позиции




Атрибуты параметра itemDetailsParams :

Название

Тип

Обязательно

Описание

name

AN..255

Условно

Обязательно при наличии параметра itemDetailsParams

Наименование параметра описания детализации товарной позиции




Атрибуты элемента quantity :

Название

Тип

Обязательно

Описание

measure

ANS..20

да

Мера измерения количества товарной позиции





Параметры блока discount :

Название

Тип

Обязательно

Описание

discountType

ANS..20

да

Тип скидки на товарную позицию

discountValue

N..20

Да

Значение скидки на товарную позицию




Параметры блока agentInterest :

Название

Тип

Обязательно

Описание

interestType

ANS..20

да

Тип агентской комиссии за продажу товара

interestValue

N..20

Да

Значение агентской комиссии за продажу товара

Состав блока tax

НазваниеТипОбязательноОписание
taxTypeN..2да

Ставка НДС, доступны следующие значения:

  • 0 – без НДС;
  • 1 – НДС по ставке 0%;
  • 2 – НДС чека по ставке 10%;
  • 3 – НДС чека по ставке 18%;
  • 4 – НДС чека по расчетной ставке 10/110;
  • 5 – НДС чека по расчетной ставке 18/118.
taxSum

N..18

нетСумма налога, высчитанная продавцом. Указывается в минимальных единицах валюты.


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

Название

Тип

Обязательно

Описание

errorCode

N3

да

Код ошибки.

errorMessage

AN..512

нет

Описание ошибки на языке, переданном в параметре Language в запросе. Может отсутствовать при errorCode=0.



Коды ошибок (поле errorCode):

Значение

Описание

0

Успешно

5

Доступ запрещён

5

Пользователь должен изменить свой пароль

5

[orderId] не задан

5

Неверная сумма

6

Неверный номер заказа

7

Платёж должен быть в корректном состоянии

7

Сумма возврата превышает сумму списания

7

Системная ошибка

8

Отсутствует обязательный параметр Корзины товаров

8

Валюта в Корзине не совпадает с валютой заказа

8

Неверная товарная позиция для возврата

8

Превышено количество возвращаемой товарной позиции в Корзине

8

Превышена стоимость возвращаемой товарной позиции




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

<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="531eaa8d-b32d-46dd-8e48-64b873886e70" refundAmount="10000">
            <!--Optional:-->
            <refundItems>
               <!--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>7000</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>
                     <tax>
                     <taxType>1</taxType>
                     <taxSum>111</taxSum>
                     </tax>
                     <itemPrice>7000</itemPrice>
                  </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>3000</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>
                     <tax>
                     <taxType>1</taxType>
                     <taxSum>111</taxSum>
                     </tax>
                     <itemPrice>3000</itemPrice>
                  </items>

            </refundItems>
            <!--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="0"/>
      </ns1:refundOrderResponse>
   </soap:Body>
</soap:Envelope>

 

3.2. Запросы, используемые при двухстадийной оплате

3.2.1. Запрос регистрации заказа с предавторизацией

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

Раздел " Требования к формированию запросов регистрации заказа с Корзиной " содержит список условий, необходимых для корректного формирования запроса.

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

Название

Тип

Обязательно

Описание

merchantOrderNumber

ANS..32

да

Номер (идентификатор) заказа в системе магазина, уникален для каждого магазина в пределах системы. Если номер заказа генерируется на стороне платёжного шлюза, этот параметр передавать необязательно.

description

ANS..512

нет

Описание заказа в свободной форме. В процессинг банка для включения в финансовую отчётность продавца передаются только первые 24 символа этого поля.

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

 

amount

N..20

да

Сумма платежа в копейках (или центах)

currency

N3

нет

Код валюты платежа ISO 4217. Если не указан, считается равным коду валюты по умолчанию.

language

A2

нет

Язык в кодировке ISO 639-1. Если не указан, будет использован язык, указанный в настройках магазина как язык по умолчанию.

pageView

ANS..20

нет

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

  • DESKTOP – для загрузки страниц, верстка которых предназначена для отображения на экранах ПК (в архиве страниц платёжного интерфейса будет осуществляться поиск страниц с названиями payment_<locale>.html и errors_<l ocale>.html );
  • MOBILE – для загрузки страниц, верстка которых предназначена для отображения на экранах мобильных устройств (в архиве страниц платёжного интерфейса будет осуществляться поиск страниц с названиями mobile_payment_<locale>.html и mobile_errors_<l ocale>.html );
  • Если магазин создал страницы платёжного интерфейса, добавив в название файлов страниц произвольные префиксы, передайте значение нужного префикса в параметре pageView для загрузки соответствующей страницы. Например, при передаче значения iphone в архиве страниц платёжного интерфейса будет осуществляться поиск страниц с названиями iphone_payment_ <locale>.html и iphone_error_ <locale>.html .

Где:

locale – я зык страницы в кодировке ISO 639-1 . Например, ru для русского или en для английского.

Если параметр отсутствует, либо не соответствует формату, то по умолчанию считается pageView=DESKTOP .

sessionTimeoutSecs

N...9

нет

Продолжительность жизни заказа в секундах.

В случае если параметр не задан, будет использовано значение, указанное в настройках мерчанта или время по умолчанию (1200 секунд = 20 минут).

Если в запросе присутствует параметр expirationDate, то значение параметра sessionTimeoutSecs не учитывается.

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 вместо test.ru ). В противном случае пользователь будет перенаправлен по адресу следующего вида: http://<адрес_платёжного_шлюза>/<адрес_продавца> .

params

 

нет

Тэг с атрибутами для передачи дополнительных параметров мерчанта.

Поля дополнительной информации для последующего хранения. Для передачи N параметров, в запросе должно находиться N тэгов params, где атрибут name содержит название, а атрибут value содержит значение:

НазваниеТипОбязательноОписание

name

AN..20

да

Название дополнительного параметра

value

AN..1024

да

Значение дополнительного параметра

 

Данные поля могут быть переданы в процессинг банка для последующего отображения в реестрах.*

Включение данного функционала возможно по согласованию с банком в период интеграции.

Если для продавца настроена отправка уведомлений покупателю, адрес электронной почты покупателя должен передаваться в этом тэге в параметре с именем email.

clientId

ANS..255

нет

Номер (идентификатор) клиента в системе магазина. Используется для реализации функционала связок. Может присутствовать, если магазину разрешено создание связок.

merchantLogin

AN..255

нет

Чтобы зарегистрировать заказ от имени дочернего мерчанта, укажите его логин в этом параметре.

oderBundle

  

Корзина товаров заказа

taxSystemN..2да - для фискализации (для магазинов без настроек фискализации параметр не обязателен)

Система налогообложения, доступны следующие значения:

  • 0 - общая;
  • 1 - упрощённая, доход;
  • 2 - упрощённая, доход минус расход;
  • 3 - единый налог на вменённый доход;
  • 4 - единый сельскохозяйственный налог;
  • 5 - патентная система налогообложения.

* По умолчанию в процессинг банка передаются поля:

      • merchantOrderNumber – номер заказа в системе магазина;
      • description – описание заказа (не более 99 символов, запрещены к использованию %, +, конец строки \r и перенос строки \n).

Если в заказе передать дополнительный параметр с именем merchantOrderId , то именно его значение будет передано в процессинг в качестве номера заказа (вместо значения поля orderNumber ).

Параметр orderBundle :

Название

Тип

Обязательно

Описание

orderCreationDate

ANS..21

нет

Дата создания заказа

customerDetails

 

нет

Тэг с атрибутами данных о покупателе

cartItems

 

да

Тэг с атрибутами товарных позиции Корзины

Параметры блока customerDetails :

Название

Тип

Обязательно

Описание

email

ANS..40

Нет

Электронная почта покупателя.

Обязательно следует передать один из двух параметров: email или phone .

phone

ANS.12

Нет

Номер телефона покупателя.

Обязательно следует передать один из двух параметров: email или phone .

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 в копейках (или центах)

itemCurrency

N..3

нет

Код валюты товарной позиции ISO 4217. Если не указан, считается равным валюте заказа.

itemCode

ANS..100

да

Номер (идентификатор) товарной позиции в системе магазина

discount

 

нет

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

agentInterest

 

нет

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

tax  да - для фискализации (для магазинов без настроек фискализации параметр не обязателен)Дополнительный тэг с атрибутами описания налога.
itemPriceN..18да - для фискализации (для магазинов без настроек фискализации параметр не обязателен)Стоимость одной товарной позиции данного positionId в деньгах в минимальных единицах валюты. Обязательно для мерчантов с фискализацией

 

Параметры тэга itemDetails :

Название

Тип

Обязательно

Описание

itemDetailsParams

ANS..255

нет

Параметр описывающий дополнительную информацию по товарной позиции

Атрибуты параметра itemDetailsParams :

Название

Тип

Обязательно

Описание

name

AN..255

Условно

Обязательно при наличии параметра itemDetailsParams

Наименование параметра описания детализации товарной позиции

Атрибуты элемента quantity :

Название

Тип

Обязательно

Описание

measure

ANS..20

да

Мера измерения количества товарной позиции

Параметры блока discount :

Название

Тип

Обязательно

Описание

discountType

ANS..20

да

Тип скидки на товарную позицию

discountValue

N..20

Да

Значение скидки на товарную позицию

Параметры блока agentInterest :

Название

Тип

Обязательно

Описание

interestType

ANS..20

да

Тип агентской комиссии за продажу товара

interestValue

N..20

Да

Значение агентской комиссии за продажу товара

Состав блока tax

НазваниеТипОбязательноОписание
taxTypeN..2да

Ставка НДС, доступны следующие значения:

  • 0 – без НДС;
  • 1 – НДС по ставке 0%;
  • 2 – НДС чека по ставке 10%;
  • 3 – НДС чека по ставке 18%;
  • 4 – НДС чека по расчетной ставке 10/110;
  • 5 – НДС чека по расчетной ставке 18/118.

Обязательно для мерчантов с фискализацией

taxSum

N..18

НетСумма налога, высчитанная продавцом. Указывается в минимальных единицах валюты.

 

 

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

Название

Тип

Обязательно

Описание

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>
            <taxSystem>0</taxSystem>

             <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>
                     <tax>
                     <taxType>1</taxType>
                     <taxSum>111</taxSum>
                     </tax>
                     <itemPrice>8000</itemPrice>
                  </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>
                     <tax>
                     <taxType>1</taxType>
                     <taxSum>111</taxSum>
                     </tax>
                     <itemPrice>8000</itemPrice>
                  </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>
                     <tax>
                     <taxType>1</taxType>
                     <taxSum>111</taxSum>
                     </tax>
                     <itemPrice>8000</itemPrice>
                  </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=8c76c56b-426c-435d-a24c-1c0927dd6fca</formUrl>
         </return>
      </ns1:registerOrderPreAuthResponse>
   </soap:Body>
</soap:Envelope>

 

3.2.2. Завершение на полную сумму предавторизации

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

Данную операцию можно осуществлять, если есть соответствующие права в системе.

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

Название

Тип

Обязательно

Описание

orderId

AN..64

да

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

depositAmount

N..5

да

Для завершения на полную сумму предавторизации в запросе необходимо передать полную сумму заказа в деньгах или 0.
Если не указать параметр "depositAmount", завершение также произойдет на всю предавторизованную сумму.

language

A2

нет

Язык в кодировке ISO 639-1. Если не указан, считается, что язык – русский. Сообщение ошибке будет возвращено именно на этом языке.

 

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

Название

Тип

Обязательно

Описание

errorCode

N3

да

Код ошибки.

errorMessage

AN..512

нет

Описание ошибки на языке, переданном в параметре Language в запросе.

 

Коды ошибок (поле errorCode):

Значение

Описание

0

Обработка запроса прошла без системных ошибок

5

Сумма депозита превышает захолдированную сумму

5

Сумма депозита должна быть больше нуля или не менее одного рубля

5

Доступ запрещён

5

Пользователь должен сменить свой пароль

6

Неверный номер заказа

6

[orderId] не задан

7

Платёж должен быть в корректном состоянии

7

Системная ошибка

8

Указанная сумма завершения не совпадает с полной суммой заказа. Необходима Корзина для завершения на неполную сумму предавторизации

 

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

<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="8c76c56b-426c-435d-a24c-1c0927dd6fca" depositAmount=" ">
            <!--Optional:-->

            <!--Zero or more repetitions:-->
            <params name=" " value=" "/>
         </order>
      </mer:depositOrder>
   </soapenv:Body>
</soapenv:Envelope>

 

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

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns1:depositOrderResponse xmlns:ns1="http://engine.paymentgate.ru/webservices/merchant">
         <return errorCode="0"/>
      </ns1:depositOrderResponse>
   </soap:Body>
</soap:Envelope>

 

 

3.2.3. Запрос завершения на частичную сумму предавторизации

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

Данную операцию можно осуществлять, если есть соответствующие права в системе.

Раздел " Требования к формированию запросов завершения заказа с Корзиной " содержит список условий, необходимых для корректного формирования запроса.

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

Название

Тип

Обязательно

Описание

orderId

AN..64

да

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

depositAmount

N..5

да

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

language

A2

нет

Язык в кодировке ISO 639-1. Если не указан, считается, что язык – русский. Сообщение ошибке будет возвращено именно на этом языке.

depositItems

 

да

Тэг с атрибутами товарных позиции Корзины

 

Параметры блока depositItems :

Название

Тип

Обязательно

Описание

items

 

да

Элемент массива с атрибутами товарной позиции в Корзине




Атрибуты элемента items :

Название

Тип

Обязательно

Описание

positionId

ANS..12

да

Уникальный идентификатор товарной позиции внутри Корзины Заказа

name

ANS..100

да

Наименование или описание товарной позиции в свободной форме

itemDetails

 

нет

Дополнительный тэг с параметрами описания товарной позиции

quantity

N..18

да

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

itemAmount

N..18

да

Сумма завершения по данному positionId в минимальных единицах валюты.

itemCurrency

N..3

нет

Код валюты товарной позиции ISO 4217. Если не указан, считается равным валюте заказа.

itemCode

ANS..100

да

Номер (идентификатор) товарной позиции в системе магазина

discount

 

нет

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

agentInterest

 

нет

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

tax да - для фискализации (для магазинов без настроек фискализации параметр не обязателен)Дополнительный тэг с атрибутами описания налога.
itemPriceN..18да - для фискализации (для магазинов без настроек фискализации параметр не обязателен)Стоимость одной товарной позиции данного positionId в деньгах в минимальных единицах валюты. Обязательно для мерчантов с фискализацией




Параметры тэга itemDetails :

Название

Тип

Обязательно

Описание

itemDetailsParams

ANS..255

нет

Параметр описывающий дополнительную информацию по товарной позиции




Атрибуты параметра itemDetailsParams :

Название

Тип

Обязательно

Описание

name

AN..255

Условно

Обязательно при наличии параметра itemDetailsParams

Наименование параметра описания детализации товарной позиции


Атрибуты элемента quantity :

Название

Тип

Обязательно

Описание

measure

ANS..20

да

Мера измерения количества товарной позиции





Параметры блока discount :

Название

Тип

Обязательно

Описание

discountType

ANS..20

да

Тип скидки на товарную позицию

discountValue

N..20

Да

Значение скидки на товарную позицию




Параметры блока agentInterest :

Название

Тип

Обязательно

Описание

interestType

ANS..20

да

Тип агентской комиссии за продажу товара

interestValue

N..20

Да

Значение агентской комиссии за продажу товара

 

Состав блока tax

НазваниеТипОбязательноОписание
taxTypeN..2да

Ставка НДС, доступны следующие значения:

  • 0 – без НДС;
  • 1 – НДС по ставке 0%;
  • 2 – НДС чека по ставке 10%;
  • 3 – НДС чека по ставке 18%;
  • 4 – НДС чека по расчетной ставке 10/110;
  • 5 – НДС чека по расчетной ставке 18/118.

Обязательно для мерчантов с фискализацией

taxSum

N..18

НетСумма налога, высчитанная продавцом. Указывается в минимальных единицах валюты.

 

 

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

Название

Тип

Обязательно

Описание

errorCode

N3

да

Код ошибки.

errorMessage

AN..512

нет

Описание ошибки на языке, переданном в параметре Language в запросе. Отсутствует при errorCode=0

 

Коды ошибок (поле errorCode):

Значение

Описание

0

Обработка запроса прошла без системных ошибок

5

Сумма депозита должна быть больше нуля или не менее одного рубля

5

Доступ запрещён

5

Пользователь должен сменить свой пароль

6

Неверный номер заказа

6

[orderId] не задан

7

Платёж должен быть в корректном состоянии

7

Системная ошибка

8

Отсутствует обязательный параметр Корзины

8

Сумма депозита больше чем сумма при регистрации

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:depositOrder>
         <order language="ru" orderId="76d7885f-562a-4bac-abc3-18ecaaaca797" depositAmount="20777">
            <!--Optional:-->
            <depositItems>

               <!--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>7777</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>
                     <tax>
                     <taxType>1</taxType>
                     <taxSum>111</taxSum>
                     </tax>
                     <itemPrice>7777</itemPrice>
                  </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>5000</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>
                     <tax>
                     <taxType>1</taxType>
                     <taxSum>111</taxSum>
                     </tax>
                     <itemPrice>5000</itemPrice>
                  </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>
                     <tax>
                     <taxType>1</taxType>
                     <taxSum>111</taxSum>
                     </tax>
                     <itemPrice>8000</itemPrice>
                  </items>

            </depositItems>

            <!--Zero or more repetitions:-->
            <params name=" " value=" "/>
         </order>

      </mer:depositOrder>
   </soapenv:Body>
</soapenv:Envelope>

 

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

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns1:depositOrderResponse xmlns:ns1="http://engine.paymentgate.ru/webservices/merchant">
         <return errorCode="0"/>
      </ns1:depositOrderResponse>
   </soap:Body>
</soap:Envelope>

 

3.2.4. Запрос отмены оплаты заказа

Для запроса отмены заказа используется запрос 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>

 

 

 

3.2.5. Запрос полного возврата средств оплаты заказа

Для запроса полного возврата средств оплаты используется запрос refundOrder . По этому запросу средства по указанному заказу будут возвращены плательщику. Запрос закончится ошибкой в случае, если средства по этому заказу не были списаны.

Данную операцию можно осуществлять, если есть соответствующие права в системе.

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

Название

Тип

Обязательно

Описание

orderId

AN..64

да

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

refundAmount

N..5

да

Сумма возврата в валюте заказа (в минимальных единицах). Должна быть равна сумме заказа.

language

A2

нет

Язык в кодировке ISO 639-1. Если не указан, считается, что язык – русский. Сообщение ошибке будет возвращено именно на этом языке.

params

 

нет

Дополнительный тэг с атрибутами для передачи дополнительных параметров мерчанта *

* Поля дополнительной информации для последующего хранения. Данные поля могут быть переданы в процессинг банка для последующего отображения в реестрах.**

Включение данного функционала возможно по согласованию с банком в период интеграции. Для передачи N параметров, в запросе должно находиться N тэгов Params, где атрибут name содержит название, а атрибут value содержит значение:

Название

Тип

Обязательно

Описание

name

AN..20

да

Название дополнительного параметра

value

AN..1024

да

Значение дополнительного параметра

** По умолчанию в процессинг банка передаются поля номер заказа orderNumber и его описание description (не более 99 символов, запрещены к использованию %, +, конец строки \r и перенос строки \n)

 

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

Название

Тип

Обязательно

Описание

errorCode

N3

да

Код ошибки.

errorMessage

AN..512

нет

Описание ошибки на языке, переданном в параметре Language в запросе.

 

Коды ошибок (поле errorCode):

Значение

Описание

0

Обработка запроса прошла без системных ошибок

5

Доступ запрещён

5

Пользователь должен изменить свой пароль

5

Не указан номер заказа

5

Неверная сумма

6

Неверный номер заказа

7

Платёж должен быть в корректном состоянии

7

Сумма возврата превышает сумму списания

7

Системная ошибка

8

Указанная сумма возврата не совпадает с полной суммой заказа. Для частичного возврата необходима Корзина

 

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

<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="3b32da16-1171-42c0-9d4e-bb6e243ff11d" refundAmount="24000">
            <!--Optional:-->

            <!--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="0"/>
      </ns1:refundOrderResponse>
   </soap:Body>
</soap:Envelope>

 

3.2.6. Запрос частичного возврата средств оплаты заказа

Для частичного возврата средств используется запрос refundOrder с обязательным указанием Корзины возвращаемых товаров. По этому запросу средства по заказу будут возвращены плательщику.

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

Раздел " Требования к формированию запросов возврата заказа с Корзиной " содержит список условий, необходимых для корректного формирования запроса.

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

Название

Тип

Обязательно

Описание

orderId

AN..64

да

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

refundAmount

N..5

да

Сумма возврата в валюте заказа (в минимальных единицах). Должна совпадать с общей суммой всех возвращаемых товарных позиций.

language

A2

нет

Язык в кодировке ISO 639-1. Если не указан, считается, что язык – русский. Сообщение ошибке будет возвращено именно на этом языке.

params

 

нет

Дополнительный тэг с атрибутами для передачи дополнительных параметров мерчанта *

refundItems

  

Тэг для передачи информации о возвращаемых товарах - номер позиции товара в запросе, название, детали, единица измерения, количество, валюта, код товара, скидка, выгода агента.

* Поля дополнительной информации для последующего хранения. Данные поля могут быть переданы в процессинг банка для последующего отображения в реестрах.**

Включение данного функционала возможно по согласованию с банком в период интеграции. Для передачи N параметров, в запросе должно находиться N тэгов Params, где атрибут name содержит название, а атрибут value содержит значение:

Название

Тип

Обязательно

Описание

name

AN..20

да

Название дополнительного параметра

value

AN..1024

да

Значение дополнительного параметра

** По умолчанию в процессинг банка передаются поля номер заказа orderNumber и его описание description (не более 99 символов, запрещены к использованию %, +, конец строки \r и перенос строки \n)

 

Параметры refundItems :

Название

Тип

Обязательно

Описание

items

 

да

Элемент массива с атрибутами товарной позиции в Корзине




Атрибуты элемента items :

Название

Тип

Обязательно

Описание

positionId

ANS..12

да

Уникальный идентификатор товарной позиции внутри Корзины Заказа

name

ANS..100

да

Наименование или описание товарной позиции в свободной форме

itemDetails

 

нет

Дополнительный тэг с параметрами описания товарной позиции

quantity

N..18

да

Элемент описывающий общее количество товарных позиций одного positionId и их меру измерения

itemAmount

N..18

да

Возвращаемая сумма по данному positionId в минимальных единицах валюты. Может быть меньше суммы оплаты по данному positionId.

itemCurrency

N..3

нет

Код валюты товарной позиции ISO 4217. Если не указан, считается равным валюте заказа.

itemCode

ANS..100

да

Номер (идентификатор) товарной позиции в системе магазина

discount

 

нет

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

agentInterest

 

нет

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

itemPrice

N..18

нет

Стоимость одной товарной позиции одного positionId в деньгах в минимальных единицах валюты. Если для магазина указаны настройки фискализации, данное поле может передаваться, но не является обязательным (значение данного поля проверяться не будет).

Атрибуты элемента quantity :

Название

Тип

Обязательно

Описание

measure

ANS..20

да

Мера измерения количества товарной позиции


Параметры тэга itemDetails :

Название

Тип

Обязательно

Описание

itemDetailsParams

ANS..255

нет

Параметр описывающий дополнительную информацию по товарной позиции


Атрибуты параметра itemDetailsParams :

Название

Тип

Обязательно

Описание

name

AN..255

да

Наименование параметра описания детализации товарной позиции



Параметры тэга discount :

Название

Тип

Обязательно

Описание

discountType

ANS..20

да

Тип скидки на товарную позицию

discountValue

N..20

Да

Значение скидки на товарную позицию


Параметры тэга agentInterest :

Название

Тип

Обязательно

Описание

interestType

ANS..20

да

Тип агентской комиссии за продажу товара

interestValue

N..20

Да

Значение агентской комиссии за продажу товара


Параметры тэга tax

НазваниеТипОбязательноОписание
taxTypeN..2да

Ставка НДС; доступны следующие значения:

  • 0 – без НДС;
  • 1 – НДС по ставке 0%;
  • 2 – НДС чека по ставке 10%;
  • 3 – НДС чека по ставке 18%;
  • 4 – НДС чека по расчетной ставке 10/110;
  • 5 – НДС чека по расчетной ставке 18/118.

Обязательно для мерчантов с фискализацией

taxSystemN..18нетСумма налога, высчитанная продавцом. Указывается в минимальных единицах валюты.


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

Название

Тип

Обязательно

Описание

errorCode

N3

да

Код ошибки.

errorMessage

AN..512

нет

Описание ошибки на языке, переданном в параметре Language в запросе. Может отсутствовать при errorCode=0.



Коды ошибок (поле errorCode):

Значение

Описание

0

Успешно

5

Доступ запрещён

5

Пользователь должен изменить свой пароль

5

[orderId] не задан

5

Неверная сумма

6

Неверный номер заказа

7

Платёж должен быть в корректном состоянии

7

Сумма возврата превышает сумму списания

7

Системная ошибка

8

Отсутствует обязательный параметр Корзины товаров

8

Валюта в Корзине не совпадает с валютой заказа

8

Неверная товарная позиция для возврата

8

Превышено количество возвращаемой товарной позиции в Корзине

8

Превышена стоимость возвращаемой товарной позиции


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

<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="531eaa8d-b32d-46dd-8e48-64b873886e70" refundAmount="10000">
            <!--Optional:-->
            <refundItems>
               <!--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>7000</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>
                     <tax>
                        <taxType>1</taxType>
                        <taxSum>111</taxSum>
                     </tax>
                     <itemPrice>7000</itemPrice>

                  </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>3000</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>
                     <tax>
                        <taxType>1</taxType>
                        <taxSum>111</taxSum>
                     </tax>
                     <itemPrice>3000</itemPrice>
                  </items>

            </refundItems>
            <!--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="0"/>
      </ns1:refundOrderResponse>
   </soap:Body>
</soap:Envelope>

 

 

 

4. Интерфейс REST

4.1. Запросы, используемые при одностадийной оплате

4.1.1. Запрос регистрации заказа

Для регистрации заказа в схеме приёма платежа на стороне платёжной системы используется запрос register.do (см. раздел " Координаты подключения ").

Товарная Корзина передаётся в параметре orderBundle .

Раздел " Требования к формированию запросов регистрации заказа с Корзиной " содержит список условий, необходимых для корректного формирования запроса.



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

Название

Тип

Обязательно

Описание

userName

AN..30

да

Логин магазина, полученный при подключении

password

AN..30

да

Пароль магазина, полученный при подключении

orderNumber

AN..32

да

Номер (идентификатор) заказа в системе магазина

amount

N..20

да

Сумма платежа в минимальных единицах валюты. Должна совпадать с общей суммой по всем товарным позициям в Корзине.

currency

N3

нет

Код валюты платежа ISO 4217.Если не указан, считается равным коду валюты по умолчанию.

returnUrl

AN..512

да

Адрес, на который требуется перенаправить пользователя в случае успешной оплаты. Адрес должен быть указан полностью, включая используемый протокол (например, https://test.ru вместо test.ru ). В противном случае пользователь будет перенаправлен по адресу следующего вида: http://<адрес_платёжного_шлюза>/<адрес_продавца> .

failUrl

AN..512

нет

Адрес, на который требуется перенаправить пользователя в случае неуспешной оплаты. Адрес должен быть указан полностью, включая используемый протокол (например, https://test.ru вместо test.ru ). В противном случае пользователь будет перенаправлен по адресу следующего вида: http://<адрес_платёжного_шлюза>/<адрес_продавца> .

description

ANS..512

нет

Описание заказа в свободной форме. В процессинг банка для включения в финансовую отчётность продавца передаются только первые 24 символа этого поля.

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

language

A2

нет

Язык в кодировке ISO 639-1. Если не указан, будет использован язык, указанный в настройках магазина как язык по умолчанию (default language)

pageView

ANS..20

нет

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

  • DESKTOP – для загрузки страниц, верстка которых предназначена для отображения на экранах ПК (в архиве страниц платёжного интерфейса будет осуществляться поиск страниц с названиями payment_<locale>.html и errors_<l ocale>.html );
  • MOBILE – для загрузки страниц, верстка которых предназначена для отображения на экранах мобильных устройств (в архиве страниц платёжного интерфейса будет осуществляться поиск страниц с названиями mobile_payment_<locale>.html и mobile_errors_<l ocale>.html );
  • Если магазин создал страницы платёжного интерфейса, добавив в название файлов страниц произвольные префиксы, передайте значение нужного префикса в параметре pageView для загрузки соответствующей страницы. Например, при передаче значения iphone в архиве страниц платёжного интерфейса будет осуществляться поиск страниц с названиями iphone_payment_ <locale>.html и iphone_error_ <locale>.html .

Где:

locale – я зык страницы в кодировке ISO 639-1 . Например, ru для русского или en для английского.

Если параметр отсутствует, либо не соответствует формату, то по умолчанию считается pageView=DESKTOP .

clientId

ANS..255

нет

Номер (идентификатор) клиента в системе магазина. Используется для реализации функционала связок. Может присутствовать, если магазину разрешено создание связок.

merchantLoginAN..255нетЧтобы зарегистрировать заказ от имени дочернего мерчанта, укажите его логин в этом параметре.

jsonParams

AN..1024

нет

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

{"<name1>":"<value1>",...,"<nameN>":"<valueN>"} ,

Данные поля могут быть переданы в процессинг банка для последующего отображения в реестрах.*

Включение данного функционала возможно по согласованию с банком в период интеграции.

Если для продавца настроена отправка уведомлений покупателю, адрес электронной почты покупателя должен передаваться в этом блоке в параметре с именем email.

sessionTimeoutSecs

N...9

нет

Продолжительность жизни заказа в секундах.

В случае если параметр не задан, будет использовано значение, указанное в настройках мерчанта или время по умолчанию (1200 секунд = 20 минут).

Если в запросе присутствует параметр expirationDate , то значение параметра sessionTimeoutSecs не учитывается.

expirationDate

ANS

нет

Дата и время окончания жизни заказа. Формат: yyyy-MM-ddTHH:mm:ss .

Если этот параметр не передаётся в запросе, то для определения времени окончания жизни заказа используется sessionTimeoutSecs.

bindingId

AN..255

нет

Идентификатор связки, созданной ранее. Может использоваться, только если у магазина есть разрешение на работу со связками. Если этот параметр передаётся в данном запросе, то это означает:
1. Данный заказ может быть оплачен только с помощью связки;
2. Плательщик будет перенаправлен на платёжную страницу, где требуется только ввод CVC.

orderBundle

  

Блок, содержащий Корзину товаров заказа. Описание его атрибутов представлено в таблице "Параметр orderBundle" ниже.

taxSystemN..2да - для фискализации (для магазинов без настроек фискализации параметр не обязателен)

Система налогообложения, доступны следующие значения:

0 - общая;

1 - упрощённая, доход;

2 - упрощённая, доход минус расход;

3 - единый налог на вменённый доход;

4 - единый сельскохозяйственный налог;

5 - патентная система налогообложения.

* По умолчанию в процессинг банка передаются поля:

    • orderNumber – номер заказа в системе магазина;
    • description – описание заказа (не более 99 символов, запрещены к использованию %, +, конец строки \r и перенос строки \n).

Если в заказе передать дополнительный параметр с именем merchantOrderId , то именно его значение будет передано в процессинг в качестве номера заказа (вместо значения поля orderNumber ).


Параметры блока orderBundle :

Название

Тип

Обязательно

Описание

orderCreationDate

ANS..21

нет

Дата создания заказа

customerDetails

 

нет

Блок с атрибутами данных о покупателе. Описание его атрибутов представлено ниже.

cartItems

 

да

Блок с атрибутами товарных позиции К орзины. Описание его атрибутов представлено ниже.


Параметры блока customerDetails :

Название

Тип

Обязательно

Описание

email

ANS..40

Нет

Электронная почта покупателя.

Обязательно следует передать один из двух параметров: email или phone .

phone

N.12

Нет

Номер телефона покупателя.

Обязательно следует передать один из двух параметров: email или phone .

contact

ANS..40

Нет

Способ связи с покупателем.

deliveryInfo

 

Нет

Блок с атрибутами адреса для доставки. Описание его атрибутов представлено ниже.


Параметры блока deliveryInfo :

Название

Тип

Обязательно

Описание

deliveryType

ANS..20

нет

Тип доставки

country

A..2

да

Страна доставки

city

ANS..40

да

Город доставки

postAddress

ANS..255

да

Адрес для доставки

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

Название

Тип

Обязательно

Описание

items

 да

Массив блоков, описывающих товарные позиции в Корзине. Описание параметров блоков представлено ниже.

Информация по каждой товарной позиции Корзины передаётся в отдельном блоке, входящем в состав items.


Параметры блока, входящего в состав items :

Название

Тип

Обязательно

Описание

positionId

N..12

да

Уникальный идентификатор товарной позиции внутри Корзины Заказа

name

ANS..100

да

Наименование или описание товарной позиции в свободной форме

itemDetails

 

нет

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

quantity

 

да

Элемент описывающий общее количество товарных позиций одного positionId и их меру измерения. Описание его атрибутов представлено ниже.

itemAmount

N..18

да

Сумма стоимости всех товарных позиций одного positionId в деньгах в минимальных единицах валюты

itemCurrency

N3

нет

Код валюты товарной позиции ISO 4217. Если не указан, считается равным валюте заказа.

itemCode

ANS..100

да

Номер (идентификатор) товарной позиции в системе магазина. Параметр должен быть уникальным в рамках запроса.

discount

 

нет

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

agentInterest

 

нет

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

tax  

да - для фискализации (для магазинов без настроек фискализации параметр не обязателен)

Дополнительный блок с атрибутами описания налога.

itemPrice

N..18

да - для фискализации (для магазинов без настроек фискализации параметр не обязателен)

Стоимость одной товарной позиции данного positionId в деньгах в минимальных единицах валюты. Обязательно для мерчантов с фискализацией



Атрибуты элемента quantity :

Название

Тип

Обязательно

Описание

value

N..18

да

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

measure

ANS..20

да

Мера измерения количества товарной позиции




Параметры блока itemDetails :

Название

Тип

Обязательно

Описание

itemDetailsParams

 

нет

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


Параметры блока, входящего в состав itemDetailsParams :

Название

Тип

Обязательно

Описание

value

ANS..255

да

Дополнительная информация по товарной позиции

name

ANS..255

да

Наименование параметра описания детализации товарной позиции

Параметры блока discount :

Название

Тип

Обязательно

Описание

discountType

ANS..20

да

Тип скидки на товарную позицию

discountValue

N..20

Да

Значение скидки на товарную позицию

Параметры блока agentInterest :

Название

Тип

Обязательно

Описание

interestType

ANS..20

да

Тип агентской комиссии за продажу товара

interestValue

N..20

Да

Значение агентской комиссии за продажу товара


Параметры блока tax

НазваниеТипОбязательноОписание
taxTypeN..2да

Ставка НДС, доступны следующие значения:

  • 0 – без НДС;
  • 1 – НДС по ставке 0%;
  • 2 – НДС чека по ставке 10%;
  • 3 – НДС чека по ставке 18%;
  • 4 – НДС чека по расчетной ставке 10/110;
  • 5 – НДС чека по расчетной ставке 18/118.

Обязательно для мерчантов с фискализацией

taxSum

N..18

нетСумма налога, высчитанная продавцом. Указывается в минимальных единицах валюты.

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

Название

Тип

Обязательно

Описание

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

Дополнительный параметр amount_bonus запрещено передавать, если в запросе присутствует К орзина.

8

Слишком большое либо слишком маленькое значение quantity.


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

https://server/application_context/rest/register.do?amount=24000&currency=643&language=ru&
orderNumber=04f04a87d6f4а5rg3r3d21&password=password&returnUrl=https://server/applicaton_context/finish.html&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" }, "tax": {"taxType": 1,"taxSum": 111},
"itemPrice": 11267 },
{ "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" },"tax": {"taxType": 1,"taxSum": 111},
"itemPrice": 8000 },
{ "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" },"tax": {"taxType": 1,"taxSum": 111},
"itemPrice": 8000  }] } } 


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

amount=24000&currency=643&language=ru&orderNumber=04f04a87d6f4а5rg3r3d21&returnUrl=https://server/applicaton_context/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" },"tax": {"taxType": 1,"taxSum": 111}, "itemPrice": 11267 },
{ "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" },"tax": {"taxType": 1,"taxSum": 111}, "itemPrice": 8000 },
{ "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" },"tax": {"taxType": 1,"taxSum": 111}, "itemPrice": 8000  }]
}
}

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

{"formUrl":"https://server/application_context/789/payment_ru.html?
mdOrder=ece47318-19f2-466a-93cd-bdb08c1587ec","orderId":"ece47318-19f2-466a-93cd-bdb08c1587ec"}

 

4.1.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/application_context/rest/reverse.do?language=ru&orderId=9231a838-ac68-4a3e-bddb-d9781433d852&password=password&userName=userName

 


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

language=ru&orderId=9231a838-ac68-4a3e-bddb-d9781433d852



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

{"errorCode":"0","errorMessage":"Успешно"}

 

 

 

4.1.3. Запрос полного возврата средств оплаты заказа

Для запроса полного возврата средств оплаты используется запрос refund.do . По этому запросу средства по указанному заказу будут возвращены плательщику. Запрос закончится ошибкой в случае, если средства по этому заказу не были списаны.

Данную операцию можно осуществлять, если есть соответствующие права в системе.

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

Название

Тип

Обязательно

Описание

userName

AN..30

да

Логин магазина, полученный при подключении

password

AN..30

да

Пароль магазина, полученный при подключении

orderId

AN..64

да

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

amount

N..5

да

Сумма возврата в валюте заказа (в минимальных единицах). Должна быть равна сумме заказа в деньгах.

language

A2

нет

Язык в кодировке ISO 639-1. Сообщение ошибке будет возвращено именно на этом языке.

jsonParams

AN..1024

нет

Поля дополнительной информации для последующего хранения, вида {"param":value,"param2":value 2}. Данные поля могут быть переданы в процессинг банка для последующего отображения в реестрах.* Включение данного функционала возможно по согласованию с банком в период интеграции.

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

Название

Тип

Обязательно

Описание

errorCode

N3

да

Код ошибки.

errorMessage

AN..512

нет

Описание ошибки на языке, переданном в параметре Language в запросе.

Коды ошибок (поле errorCode):

Значение

Описание

0

Обработка запроса прошла без системных ошибок

5

Доступ запрещён

5

Пользователь должен изменить свой пароль

5

Не указан номер заказа

5

Неверная сумма

6

Неверный номер заказа

7

Платёж должен быть в корректном состоянии

7

Сумма возврата превышает сумму списания

7

Системная ошибка

8

Указанная сумма возврата не совпадает с полной суммой заказа. Для частичного возврата необходима К орзина

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

https://3dsec.sberbank.ru/payment/rest/refund.do?language=ru&
orderId=c84105aa-0713-44e1-ae3b-4c5e09d49a7d&password=password&userName=login&
jsonParams={"name1":"value1"}&amount=24000

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

language=ru&orderId=c84105aa-0713-44e1-ae3b-4c5e09d49a7d&jsonParams={"name1":"value1"}&amount=24000

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

{"errorCode":"0","errorMessage":"Успешно"}
4.1.4. Запрос частичного возврата средств оплаты заказа

Для возврата средств оплаты заказа используется запрос refund.do (см. раздел " Координаты подключения ").

Данную операцию можно осуществлять, если есть соответствующие права в системе.

Раздел " Требования к формированию запросов возврата заказа с Корзиной " содержит список условий, необходимых для корректного формирования запроса.

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

Название

Тип

Обязательно

Описание

userName

AN..30

да

Логин магазина, полученный при подключении

password

AN..30

да

Пароль магазина, полученный при подключении

orderId

AN..64

да

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

amount

N..20

да

Сумма возврата в валюте заказа (в минимальных единицах). Должна совпадать с общей суммой всех возвращаемых товарных позиций.

refundItems

  

Корзина товаров заказа

language

A2

нет

Язык в кодировке ISO 639-1. Сообщение ошибке будет возвращено на этом языке

jsonParams

AN..1024

нет

Поля дополнительной информации для последующего хранения, вида {"param":value,"param2":value 2}. Данные поля могут быть переданы в процессинг банка для последующего отображения в реестрах.* Включение данного функционала возможно по согласованию с банком в период интеграции.

Параметр refundItems :

Название

Тип

Обязательно

Описание

items

 

нет

Массив блоков, описывающих товарные позиции в Корзине. Описание параметров блоков представлено ниже.

Информация по каждой товарной позиции Корзины передаётся в отдельном блоке, входящем в состав items.

Параметры блока, входящего в состав items :

Название

Тип

Обязательно

Описание

positionId

N..12

да

Уникальный идентификатор товарной позиции внутри Корзины Заказа

name

ANS..100

да

Наименование или описание товарной позиции в свободной форме

itemDetails

 

нет

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

quantity

 

да

Элемент описывающий общее количество товарных позиций одного positionId и их меру измерения

itemAmount

N..18

да

Возвращаемая сумма по данному positionId в минимальных единицах валюты. Может быть меньше суммы оплаты по данному positionId.

itemCurrency

N3

нет

Код валюты товарной позиции ISO 4217. Если не указан, считается равным валюте заказа.

itemCode

ANS..100

да

Номер (идентификатор) товарной позиции в системе магазина

discount

 

нет

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

agentInterest

 

нет

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

tax

 

нет

Дополнительный тэг с атрибутами описания налога. Если для магазина указаны настройки фискализации, данный блок может передаваться, но не является обязательным (значения параметров данного блока проверяться не будут).

itemPrice

N..18

нет

Стоимость одной товарной позиции одного positionId в деньгах в минимальных единицах валюты. Если для магазина указаны настройки фискализации, данное поле может передаваться, но не является обязательным (значение данного поля проверяться не будет).

Параметры блока quantity :

Название

Тип

Обязательно

Описание

value

N..18

да

Количество товарных позиций одного positionId

measure

ANS..20

да

Мера измерения количества товарной позиции

Параметры блока itemDetails :

Название

Тип

Обязательно

Описание

itemDetailsParams

 

нет

Массив блоков, в каждом из которых передаётся информация об определённой характеристике товарной позиции.

Параметры блока, входящего в состав itemDetailsParams :

Название

Тип

Обязательно

Описание

value

ANS..255

да

Дополнительная информация по товарной позиции

name

ANS..255

да

Наименование параметра описания детализации товарной позиции

Параметры блока discount :

Название

Тип

Обязательно

Описание

discountType

ANS..20

да

Тип скидки на товарную позицию

discountValue

N..20

Да

Значение скидки на товарную позицию

Параметры блока agentInterest :

Название

Тип

Обязательно

Описание

interestType

ANS..20

да

Тип агентской комиссии за продажу товара

interestValue

N..20

Да

Значение агентской комиссии за продажу товара

Параметры блока tax

НазваниеТипОбязательноОписание
taxTypeN..2да

Ставка НДС, доступны следующие значения:

  • 0 – без НДС;
  • 1 – НДС по ставке 0%;
  • 2 – НДС чека по ставке 10%;
  • 3 – НДС чека по ставке 18%;
  • 4 – НДС чека по расчетной ставке 10/110;
  • 5 – НДС чека по расчетной ставке 18/118.
taxSum

N..18

нетСумма налога, высчитанная продавцом. Указывается в минимальных единицах валюты.

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

Название

Тип

Обязательно

Описание

errorCode

N3

да

Код ошибки. Возможные значения и их описание представлены в таблице ниже.

errorMessage

AN..512

нет

Описание ошибки на языке, переданном в параметре language или языке по умолчанию.

Коды ошибок (поле ErrorCode):

Классификация:

Значение

Описание

0

Обработка запроса прошла без системных ошибок

5

Ошибка значение параметра запроса

5

Неверный формат параметра refungItems

6

Незарегистрированный OrderId

7

Системная ошибка

Расшифровка:

Значение

Описание

5

Авторизация отклонена

5

Доступ запрещён

6

Неверный номер заказа

7

Платёж должен быть в корректном состоянии

7

Неверная сумма депозита (менее одного рубля)

7

Ошибка системы

8

Неверный формат параметра refundItems

8

Отсутствует обязательный параметр К орзины

8

Валюта в К орзине не совпадает с валютой заказа

8

Сумма товарных позиций в К орзине не совпадает с общей суммой заказа

8

Слишком большое либо слишком маленькое значение quantity

8

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

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

https://3dsec.sberbank.ru/payment/rest/refund.do?language=ru&orderId=830603cd-a886-483a-9a23-c37fb8018096&
 password=password&userName=login&jsonParams={"name1":"value1"}&amount=9000&
refundItems={"items": [  { "positionId": "2", "name": "Universal Mirror Enduro", "itemDetails":
{ "itemDetailsParams": [{ "value": "Noname", "name": "brand" }, { "value": "12mm", "name": "diameter" }]},
"quantity": { "value": 1.0, "measure": "штук" },
"itemAmount": 6000, "itemCurrency": "643", "itemCode": "NM-15",
"discount": { "discountType": "percent", "discountValue": "5" },
"agentInterest": { "interestType": " agentPercent ", "interestValue": "7" },"tax": {"taxType": 1,"taxSum": 111}, "itemPrice": 6000 },
{ "positionId": "3", "name": "Warm Grips", "itemDetails": { "itemDetailsParams":
[ { "value": "Noname", "name": "brand" }]}, "quantity": { "value": 1.0, "measure": "штук" },
"itemAmount": 3000, "itemCurrency": 643, "itemCode": "G-16",
"discount": { "discountType": "percent", "discountValue": "5" },
"agentInterest": { "interestType": " agentPercent ", "interestValue": "7" },"tax": {"taxType": 1,"taxSum": 111}, "itemPrice": 3000}] }

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

language=ru&orderId=830603cd-a886-483a-9a23-c37fb8018096&jsonParams={"name1":"value1"}&amount=9000& refundItems={"items": [  { "positionId": "2", "name": "Universal Mirror Enduro", "itemDetails": { "itemDetailsParams": [{ "value": "Noname", "name": "brand" }, { "value": "12mm", "name": "diameter" }]}, "quantity": { "value": 1.0, "measure": "штук" }, "itemAmount": 6000, "itemCurrency": "643", "itemCode": "NM-15", "discount": { "discountType": "percent", "discountValue": "5" }, "agentInterest": { "interestType": " agentPercent ", "interestValue": "7" }, "tax": {"taxType": 1,"taxSum": 111}, "itemPrice": 6000 },  { "positionId": "3", "name": "Warm Grips", "itemDetails": { "itemDetailsParams": [ { "value": "Noname", "name": "brand" }]}, "quantity": { "value": 1.0, "measure": "штук" }, "itemAmount": 3000, "itemCurrency": 643, "itemCode": "G-16", "discount": { "discountType": "percent", "discountValue": "5" }, "agentInterest": { "interestType": " agentPercent ", "interestValue": "7" }, "tax": {"taxType": 1,"taxSum": 111}, "itemPrice": 6000}] }

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

{"errorCode":"0","errorMessage":"Успешно"}

 

4.2. Запросы, используемые при двухстадийной оплате

4.2.1. Запрос регистрации заказа с предавторизацией

Для регистрации заказа с предавторизацией используется запрос registerPreAuth.do (см. раздел " Координаты подключения ").

Товарная Корзина передаётся в параметре orderBundle.

Раздел " Требования к формированию запросов регистрации заказа с Корзиной " содержит список условий, необходимых для корректного формирования запроса.

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

Название

Тип

Обязательно

Описание

userName

AN..30

да

Логин магазина, полученный при подключении

password

AN..30

да

Пароль магазина, полученный при подключении

orderNumber

AN..32

да

Номер (идентификатор) заказа в системе магазина

amount

N..20

да

Сумма платежа в минимальных единицах валюты. Должна совпадать с общей суммой по всем товарным позициям в К орзине.

currency

N3

нет

Код валюты платежа ISO 4217.Если не указан, считается равным коду валюты по умолчанию.

returnUrl

AN..512

да

Адрес, на который требуется перенаправить пользователя в случае успешной оплаты. Адрес должен быть указан полностью, включая используемый протокол (например, https://test.ru вместо test.ru ). В противном случае пользователь будет перенаправлен по адресу следующего вида: http://<адрес_платёжного_шлюза>/<адрес_продавца> .

failUrl

AN..512

нет

Адрес, на который требуется перенаправить пользователя в случае неуспешной оплаты. Адрес должен быть указан полностью, включая используемый протокол (например, https://test.ru вместо test.ru ). В противном случае пользователь будет перенаправлен по адресу следующего вида: http://<адрес_платёжного_шлюза>/<адрес_продавца> .

description

ANS..512

нет

Описание заказа в свободной форме. В процессинг банка для включения в финансовую отчётность продавца передаются только первые 24 символа этого поля.

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

language

A2

нет

Язык в кодировке ISO 639-1. Если не указан, будет использован язык, указанный в настройках магазина как язык по умолчанию.

pageView

ANS..20

нет

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

  • DESKTOP – для загрузки страниц, верстка которых предназначена для отображения на экранах ПК (в архиве страниц платёжного интерфейса будет осуществляться поиск страниц с названиями payment_<locale>.html и errors_<l ocale>.html );
  • MOBILE – для загрузки страниц, верстка которых предназначена для отображения на экранах мобильных устройств (в архиве страниц платёжного интерфейса будет осуществляться поиск страниц с названиями mobile_payment_<locale>.html и mobile_errors_<l ocale>.html );
  • Если магазин создал страницы платёжного интерфейса, добавив в название файлов страниц произвольные префиксы, передайте значение нужного префикса в параметре pageView для загрузки соответствующей страницы. Например, при передаче значения iphone в архиве страниц платёжного интерфейса будет осуществляться поиск страниц с названиями iphone_payment_ <locale>.html и iphone_error_ <locale>.html .

Где:

locale – я зык страницы в кодировке ISO 639-1 . Например, ru для русского или en для английского.

Если параметр отсутствует, либо не соответствует формату, то по умолчанию считается pageView=DESKTOP .

clientId

ANS..255

нет

Номер (идентификатор) клиента в системе магазина. Используется для реализации функционала связок. Может присутствовать, если магазину разрешено создание связок.

merchantLoginAN..255нетЧтобы зарегистрировать заказ от имени дочернего мерчанта, укажите его логин в этом параметре.

jsonParams

AN..1024

нет

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

{"<name1>":"<value1>",...,"<nameN>":"<valueN>"} ,

Данные поля могут быть переданы в процессинг банка для последующего отображения в реестрах.*

Включение данного функционала возможно по согласованию с банком в период интеграции.

Если для продавца настроена отправка уведомлений покупателю, адрес электронной почты покупателя должен передаваться в этом блоке в параметре с именем email.

sessionTimeoutSecs

N...9

нет

Продолжительность жизни заказа в секундах.

В случае если параметр не задан, будет использовано значение, указанное в настройках мерчанта или время по умолчанию (1200 секунд = 20 минут).

Если в запросе присутствует параметр expirationDate, то значение параметра sessionTimeoutSecs не учитывается.

expirationDate

ANS

нет

Дата и время окончания жизни заказа. Формат: yyyy-MM-ddTHH:mm:ss .

Если этот параметр не передаётся в запросе, то для определения времени окончания жизни заказа используется sessionTimeoutSecs.

bindingId

AN..255

no

Идентификатор связки, созданной ранее. Может использоваться, только если у магазина есть разрешение на работу со связками. Если этот параметр передаётся в данном запросе, то это означает:

1. Данный заказ может быть оплачен только с помощью связки;

2. Плательщик будет перенаправлен на платёжную страницу, где требуется только ввод CVC.

orderBundle

  

Корзина товаров заказа

taxSystemN..2да - для фискализации (для магазинов без настроек фискализации параметр не обязателен)

Система налогообложения, доступны следующие значения:

  • 0 - общая;
  • 1 - упрощённая доход;
  • 2 - упрощённая доход минус расход;
  • 3 - единый налог на вменённый доход;
  • 4 - единый сельскохозяйственный налог;
  • 5 - патентная система налогообложения.

* По умолчанию в процессинг банка передаются поля:

      • orderNumber – номер заказа в системе магазина;
      • description – описание заказа (не более 99 символов, запрещены к использованию %, +, конец строки \r и перенос строки \n).

Если в заказе передать дополнительный параметр с именем merchantOrderId , то именно его значение будет передано в процессинг в качестве номера заказа (вместо значения поля orderNumber ).

Параметр orderBundle :

Название

Тип

Обязательно

Описание

orderCreationDate

ANS..21

нет

Дата создания заказа

customerDetails

 

нет

Блок с атрибутами данных о покупателе

cartItems

 

да

Блок с атрибутами товарных позиции К орзины

Параметры блока customerDetails :

Название

Тип

Обязательно

Описание

email

ANS..40

Нет

Электронная почта покупателя.

Обязательно следует передать один из двух параметров: email или phone .

phone

N.12

Нет

Номер телефона покупателя.

Обязательно следует передать один из двух параметров: email или phone .

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 в деньгах в минимальных единицах валюты

itemCurrency

N3

нет

Код валюты товарной позиции ISO 4217. Если не указан, считается равным валюте заказа.

itemCode

ANS..100

да

Номер (идентификатор) товарной позиции в системе магазина

discount

 

нет

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

agentInterest

 

нет

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

tax  

да - для фискализации (для магазинов без настроек фискализации параметр не обязателен)

Дополнительный блок с атрибутами описания налога.

itemPrice

N..18

да - для фискализации (для магазинов без настроек фискализации параметр не обязателен)

Стоимость одной товарной позиции данного positionId в деньгах в минимальных единицах валюты. Обязательно для мерчантов с фискализацией

 

Атрибуты элемента quantity :

Название

Тип

Обязательно

Описание

value

N..18

да

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

measure

ANS..20

да

Мера измерения количества товарной позиции

Параметры блока itemDetails :

Название

Тип

Обязательно

Описание

itemDetailsParams

 

нет

Параметр описывающий дополнительную информацию по товарной позиции

Атрибуты параметра itemDetailsParams :

Название

Тип

Обязательно

Описание

value

ANS..255

да

Дополнительная информация по товарной позиции

name

ANS..255

да

Наименование параметра описания детализации товарной позиции

Параметры блока discount :

Название

Тип

Обязательно

Описание

discountType

ANS..20

да

Тип скидки на товарную позицию

discountValue

N..20

Да

Значение скидки на товарную позицию

Параметры блока agentInterest :

Название

Тип

Обязательно

Описание

interestType

ANS..20

да

Тип агентской комиссии за продажу товара

interestValue

N..20

Да

Значение агентской комиссии за продажу товара

Параметры блока tax

Название

Тип

Обязательно

Описание

taxType

N..2да

Ставка НДС, доступны следующие значения:

  • 0 – без НДС;
  • 1 – НДС по ставке 0%;
  • 2 – НДС чека по ставке 10%;
  • 3 – НДС чека по ставке 18%;
  • 4 – НДС чека по расчетной ставке 10/110;
  • 5 – НДС чека по расчетной ставке 18/118.

Обязательно для мерчантов с фискализацией

taxSum

N..18

нет

Сумма налога, высчитанная продавцом. Указывается в минимальных единицах валюты.

 

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

Название

Тип

Обязательно

Описание

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

Слишком большое либо слишком маленькое значение quantity

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

https://server/application_context/rest/registerPreAuth.do?amount=24000&currency=643&language=ru&
orderNumber=01a287222222299&password=password&userName=userName&returnUrl=https://server/applicaton_context/finish.html&
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" }, "tax": {"taxType": 1,"taxSum": 111}, "itemPrice": 11267 },
{ "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" }, "tax": {"taxType": 1,"taxSum": 111}, "itemPrice": 8000 },
{ "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" }, "tax": {"taxType": 1,"taxSum": 111}, "itemPrice": 8000  }] } }



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

amount=24000&currency=643&language=ru&orderNumber=01a287222222299&returnUrl=https://server/applicaton_context/finish.html&
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" }, "tax": {"taxType": 1,"taxSum": 111}, "itemPrice": 11267 },
{ "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" }, "tax": {"taxType": 1,"taxSum": 111}, "itemPrice": 8000 },
{ "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" }, "tax": {"taxType": 1,"taxSum": 111}, "itemPrice": 11267  }] } }

 

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

{"formUrl":"https://3dsec.sberbank.ru/payment/merchants/789/payment_ru.html?
mdOrder=fc122907-e237-440e-9f25-48bf6120984b","orderId":"fc122907-e237-440e-9f25-48bf6120984b"}

 

4.2.2. Запрос завершения на полную сумму

Для запроса списания полной суммы предавторизации используется запрос deposit.do .

Данную операцию можно осуществлять, если есть соответствующие права в системе.

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

Название

Тип

Обязательно

Описание

userName

AN..30

да

Логин магазина, полученный при подключении

password

AN..30

да

Пароль магазина, полученный при подключении

orderId

AN..64

да

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

amount

N..5

да

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

language

A2

нет

Язык в кодировке ISO 639-1. Сообщение ошибке будет возвращено именно на этом языке.

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

Название

Тип

Обязательно

Описание

errorCode

N3

да

Код ошибки.

errorMessage

AN..512

нет

Описание ошибки на языке, переданном в параметре Language в запросе.

Коды ошибок (поле errorCode):

Значение

Описание

0

Обработка запроса прошла без системных ошибок

5

Сумма депозита превышает захолдированную сумму

5

Сумма депозита должна быть больше нуля или не менее одного рубля

5

Доступ запрещён

5

Пользователь должен сменить свой пароль

6

Неверный номер заказа

6

[orderId] не задан

7

Платёж должен быть в корректном состоянии

7

Системная ошибка

8

Указанная сумма завершения не совпадает с полной суммой заказа. Необходима К орзина для завершения на неполную сумму предавторизации

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

https://3dsec.sberbank.ru/payment/rest/deposit.do?language=ru&
orderId=f57db9df-5885-483d-8d5e-8e592d60ec9d&password=password&userName=login&amount=0

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

currency=643&language=ru&orderId=f57db9df-5885-483d-8d5e-8e592d60ec9d&amount=0

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

{"errorCode":"0","errorMessage":"Успешно"}
4.2.3. Завершение на частичную сумму предавторизации

Для запроса списания полной суммы предавторизации используется запрос deposit.do .

Данную операцию можно осуществлять, если есть соответствующие права в системе.

Раздел " Требования к формированию запросов завершения заказа с Корзиной " содержит список условий, необходимых для корректного формирования запроса.

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

Название

Тип

Обязательно

Описание

userName

AN..30

да

Логин магазина, полученный при подключении

password

AN..30

да

Пароль магазина, полученный при подключении

orderId

AN..64

да

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

amount

N..5

да

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

language

A2

нет

Язык в кодировке ISO 639-1. Сообщение ошибке будет возвращено именно на этом языке.

depositItems

 

да

Тэг с атрибутами товарных позиции К орзины

Параметры блока depositItems :

Название

Тип

Обязательно

Описание

items

 

да

Массив блоков, описывающих товарные позиции в Корзине. Описание параметров блоков представлено ниже.

Информация по каждой товарной позиции Корзины передаётся в отдельном блоке, входящем в состав items .


Параметры блока, входящего в состав items :

Название

Тип

Обязательно

Описание

positionId

ANS..12

да

Уникальный идентификатор товарной позиции внутри Корзины Заказа

name

ANS..100

да

Наименование или описание товарной позиции в свободной форме

itemDetails

 

нет

Дополнительный тэг с параметрами описания товарной позиции

quantity

N..18

да

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

itemAmount

N..18

да

Сумма завершения по данному positionId в минимальных единицах валюты.

itemCurrency

N..3

нет

Код валюты товарной позиции ISO 4217. Если не указан, считается равным валюте заказа.

itemCode

ANS..100

да

Номер (идентификатор) товарной позиции в системе магазина

discount

 

нет

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

agentInterest

 

нет

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

tax 

да - для фискализации (для магазинов без настроек фискализации параметр не обязателен)

Дополнительный блок с атрибутами описания налога.

itemPrice

N..18

да - для фискализации (для магазинов без настроек фискализации параметр не обязателен)

Стоимость одной товарной позиции данного positionId в деньгах в минимальных единицах валюты. Обязательно для мерчантов с фискализацией

Параметры блока quantity :

Название

Тип

Обязательно

Описание

value

N..18

да

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

measure

ANS..20

да

Мера измерения количества товарной позиции

Параметры блока itemDetails :

Название

Тип

Обязательно

Описание

itemDetailsParams

ANS..255

нет

Массив блоков, в каждом из которых передаётся информация об определённой характеристике товарной позиции.

Параметры блока, входящего в состав itemDetailsParams :

Название

Тип

Обязательно

Описание

name

AN..255

да

Наименование параметра описания детализации товарной позиции

Параметры блока discount :

Название

Тип

Обязательно

Описание

discountType

ANS..20

да

Тип скидки на товарную позицию

discountValue

N..20

Да

Значение скидки на товарную позицию

Параметры блока agentInterest :

Название

Тип

Обязательно

Описание

interestType

ANS..20

да

Тип агентской комиссии за продажу товара

interestValue

N..20

Да

Значение агентской комиссии за продажу товара


Параметры блока tax

НазваниеТипОбязательноОписание
taxTypeN..2да

Ставка НДС, доступны следующие значения:

  • 0 – без НДС;
  • 1 – НДС по ставке 0%;
  • 2 – НДС чека по ставке 10%;
  • 3 – НДС чека по ставке 18%;
  • 4 – НДС чека по расчетной ставке 10/110;
  • 5 – НДС чека по расчетной ставке 18/118.

Обязательно для мерчантов с фискализацией

taxSum

N..18

нетСумма налога, высчитанная продавцом. Указывается в минимальных единицах валюты.

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

Название

Тип

Обязательно

Описание

errorCode

N3

да

Код ошибки.

errorMessage

AN..512

нет

Описание ошибки на языке, переданном в параметре Language в запросе. Отсутствует при errorCode=0

Коды ошибок (поле errorCode):

Значение

Описание

0

Обработка запроса прошла без системных ошибок

5

Сумма депозита должна быть больше нуля или не менее одного рубля

5

Доступ запрещён

5

Пользователь должен сменить свой пароль

6

Неверный номер заказа

6

[orderId] не задан

7

Платёж должен быть в корректном состоянии

7

Системная ошибка

8

Отсутствует обязательный параметр К орзины

8

Сумма депозита больше чем сумма при регистрации

8

Валюта в К орзине не совпадает с валютой заказа

8

Сумма товарных позиций в К орзине не совпадает с общей суммой заказа

8

Оригинальный заказ не содержит товарной позиции с данным номером

8

Слишком большое либо слишком маленькое значение quantity

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

https://3dsec.sberbank.ru/payment/rest/deposit.do?userName=login&password=password&
orderId=9659c922-f0fa-4b4f-9b09-8a754ad99c63&amount=4441&depositItems={"items": [
{ "positionId": "2", "name": "Universal Mirror Enduro",
"itemDetails": { "itemDetailsParams": [{ "value": "Noname", "name": "brand" },
{ "value": "12mm", "name": "diameter" }]}, "quantity": { "value": 1.0, "measure": "штук" },
"itemAmount": 3330, "itemCurrency": "643", "itemCode": "NM-15",
"discount": { "discountType": "percent", "discountValue": "5" },
"agentInterest": { "interestType": " agentPercent ", "interestValue": "7" }, "tax": {"taxType": 1,"taxSum": 111}, "itemPrice": 3330 },
{ "positionId": "3", "name": "Warm Grips",
"itemDetails": { "itemDetailsParams": [ { "value": "Noname", "name": "brand" }]},
"quantity": { "value": 1.0, "measure": "штук" }, "itemAmount": 1111, "itemCurrency": 643,
"itemCode": "G-16", "discount": { "discountType": "percent", "discountValue": "5" },
"agentInterest": { "interestType": " agentPercent ", "interestValue": "7" }, "tax": {"taxType": 1,"taxSum": 111}, "itemPrice": 1111}] }

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

orderId=9659c922-f0fa-4b4f-9b09-8a754ad99c63&amount=4441&depositItems={"items": [
{ "positionId": "2", "name": "Universal Mirror Enduro",
"itemDetails": { "itemDetailsParams": [{ "value": "Noname", "name": "brand" },
{ "value": "12mm", "name": "diameter" }]}, "quantity": { "value": 1.0, "measure": "штук" },
"itemAmount": 3330, "itemCurrency": "643", "itemCode": "NM-15",
"discount": { "discountType": "percent", "discountValue": "5" },
"agentInterest": { "interestType": " agentPercent ", "interestValue": "7" }, "tax": {"taxType": 1,"taxSum": 111}, "itemPrice": 3330 },
{ "positionId": "3", "name": "Warm Grips",
"itemDetails": { "itemDetailsParams": [ { "value": "Noname", "name": "brand" }]},
"quantity": { "value": 1.0, "measure": "штук" }, "itemAmount": 1111, "itemCurrency": 643,
"itemCode": "G-16", "discount": { "discountType": "percent", "discountValue": "5" },
"agentInterest": { "interestType": " agentPercent ", "interestValue": "7" }, "tax": {"taxType": 1,"taxSum": 111}, "itemPrice": 1111}] }

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

{"errorCode":"0","errorMessage":"Success"}

 

4.2.4. Запрос отмены оплаты заказа

Для запроса отмены оплаты заказа используется запрос 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/application_context/rest/reverse.do?language=ru&orderId=9231a838-ac68-4a3e-bddb-d9781433d852&password=password&userName=userName

 


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

language=ru&orderId=9231a838-ac68-4a3e-bddb-d9781433d852



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

{"errorCode":"0","errorMessage":"Успешно"}

 

 

 

4.2.5. Запрос полного возврата средств оплаты заказа

Для запроса полного возврата средств оплаты используется запрос refund.do . По этому запросу средства по указанному заказу будут возвращены плательщику. Запрос закончится ошибкой в случае, если средства по этому заказу не были списаны.

Данную операцию можно осуществлять, если есть соответствующие права в системе.

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

Название

Тип

Обязательно

Описание

userName

AN..30

да

Логин магазина, полученный при подключении

password

AN..30

да

Пароль магазина, полученный при подключении

orderId

AN..64

да

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

amount

N..5

да

Сумма возврата в валюте заказа (в минимальных единицах). Должна быть равна сумме заказа в деньгах.

language

A2

нет

Язык в кодировке ISO 639-1. Сообщение ошибке будет возвращено именно на этом языке.

jsonParams

AN..1024

нет

Поля дополнительной информации для последующего хранения, вида {"param":value,"param2":value 2}. Данные поля могут быть переданы в процессинг банка для последующего отображения в реестрах.* Включение данного функционала возможно по согласованию с банком в период интеграции.

 

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

Название

Тип

Обязательно

Описание

errorCode

N3

да

Код ошибки.

errorMessage

AN..512

нет

Описание ошибки на языке, переданном в параметре Language в запросе.

Коды ошибок (поле errorCode):

Значение

Описание

0

Обработка запроса прошла без системных ошибок

5

Доступ запрещён

5

Пользователь должен изменить свой пароль

5

Не указан номер заказа

5

Неверная сумма

6

Неверный номер заказа

7

Платёж должен быть в корректном состоянии

7

Сумма возврата превышает сумму списания

7

Системная ошибка

8

Указанная сумма возврата не совпадает с полной суммой заказа. Для частичного возврата необходима К орзина

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

https://3dsec.sberbank.ru/payment/rest/refund.do?language=ru&
orderId=c84105aa-0713-44e1-ae3b-4c5e09d49a7d&password=password&userName=login&
jsonParams={"name1":"value1"}&amount=24000

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

language=ru&orderId=c84105aa-0713-44e1-ae3b-4c5e09d49a7d&jsonParams={"name1":"value1"}&amount=24000

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

{"errorCode":"0","errorMessage":"Успешно"}
4.2.6. Запрос частичного возврата средств оплаты заказа

Для возврата средств оплаты заказа используется запрос refund.do (см. раздел " Координаты подключения ").

Данную операцию можно осуществлять, если есть соответствующие права в системе.

Раздел " Требования к формированию запросов возврата заказа с Корзиной " содержит список условий, необходимых для корректного формирования запроса.

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

Название

Тип

Обязательно

Описание

userName

AN..30

да

Логин магазина, полученный при подключении

password

AN..30

да

Пароль магазина, полученный при подключении

orderId

AN..64

да

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

amount

N..20

да

Сумма возврата в валюте заказа (в минимальных единицах). Должна совпадать с общей суммой всех возвращаемых товарных позиций.

refundItems

  

Корзина товаров заказа

language

A2

нет

Язык в кодировке ISO 639-1. Сообщение ошибке будет возвращено на этом языке

jsonParams

AN..1024

нет

Поля дополнительной информации для последующего хранения, вида {"param":value,"param2":value 2}. Данные поля могут быть переданы в процессинг банка для последующего отображения в реестрах.* Включение данного функционала возможно по согласованию с банком в период интеграции.

 

Параметры блока refundItems :

Название

Тип

Обязательно

Описание

items

 

нет

Массив блоков, описывающих товарные позиции в Корзине. Описание параметров блоков представлено ниже.

Информация по каждой товарной позиции Корзины передаётся в отдельном блоке, входящем в состав items .

Параметры блока, входящего в items :

Название

Тип

Обязательно

Описание

positionId

N..12

да

Уникальный идентификатор товарной позиции внутри Корзины Заказа

name

ANS..100

да

Наименование или описание товарной позиции в свободной форме

itemDetails

 

нет

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

quantity

 

да

Элемент описывающий общее количество товарных позиций одного positionId и их меру измерения

itemAmount

N..18

да

Возвращаемая сумма по данному positionId в минимальных единицах валюты. Может быть меньше суммы оплаты по данному positionId.

itemCurrency

N3

нет

Код валюты товарной позиции ISO 4217. Если не указан, считается равным валюте заказа.

itemCode

ANS..100

да

Номер (идентификатор) товарной позиции в системе магазина

discount

 

нет

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

agentInterest

 

нет

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

tax

 

нет

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

itemPrice

N..18

нет

Cтоимость одной товарной позиции одного positionId в деньгах в минимальных единицах валюты. Если для магазина указаны настройки фискализации, данное поле может передаваться, но не является обязательным (значение данного поля проверяться не будет).

Параметры блока quantity :

Название

Тип

Обязательно

Описание

value

N..18

да

Количество товарных позиций одного positionId

measure

ANS..20

да

Мера измерения количества товарной позиции

Параметры блока itemDetails :

Название

Тип

Обязательно

Описание

itemDetailsParams

 

нет

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

Параметры блока, входящего в состав itemDetailsParams :

Название

Тип

Обязательно

Описание

value

ANS..255

да

Дополнительная информация по товарной позиции

name

ANS..255

да

Наименование параметра описания детализации товарной позиции

Параметры блока discount :

Название

Тип

Обязательно

Описание

discountType

ANS..20

да

Тип скидки на товарную позицию

discountValue

N..20

Да

Значение скидки на товарную позицию

Параметры блока agentInterest :

Название

Тип

Обязательно

Описание

interestType

ANS..20

да

Тип агентской комиссии за продажу товара

interestValue

N..20

Да

Значение агентской комиссии за продажу товара


Параметры блока tax

Название

Тип

Обязательно

Описание

taxType

N..2

да

Ставка НДС, доступны следующие значения:

  • 0 – без НДС;
  • 1 – НДС по ставке 0%;
  • 2 – НДС чека по ставке 10%;
  • 3 – НДС чека по ставке 18%;
  • 4 – НДС чека по расчетной ставке 10/110;
  • 5 – НДС чека по расчетной ставке 18/118.

Обязательно для мерчантов с фискализацией

taxSum

N..18

нет

Сумма налога, высчитанная продавцом. Указывается в минимальных единицах валюты.

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

Название

Тип

Обязательно

Описание

errorCode

N3

да

Код ошибки.

errorMessage

AN..512

нет

Описание ошибки на языке, переданном в параметре language или языке по умолчанию.

Коды ошибок (поле ErrorCode):

Классификация:

Значение

Описание

0

Обработка запроса прошла без системных ошибок

5

Ошибка значение параметра запроса

5

Неверный формат параметра refungItems

6

Незарегистрированный OrderId

7

Системная ошибка

Расшифровка:

Значение

Описание

5

Авторизация отклонена

5

Доступ запрещён

6

Неверный номер заказа

7

Платёж должен быть в корректном состоянии

7

Неверная сумма депозита (менее одного рубля)

7

Ошибка системы

8

Неверный формат параметра refundItems

8

Отсутствует обязательный параметр К орзины

8

Валюта в К орзине не совпадает с валютой заказа

8

Сумма товарных позиций в К орзине не совпадает с общей суммой заказа

8

Слишком большое либо слишком маленькое значение quantity

8

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

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

https://3dsec.sberbank.ru/payment/rest/refund.do?language=ru&orderId=830603cd-a886-483a-9a23-c37fb8018096&
 password=password&userName=login&jsonParams={"name1":"value1"}&amount=9000&
refundItems={"items": [  { "positionId": "2", "name": "Universal Mirror Enduro", "itemDetails":
{ "itemDetailsParams": [{ "value": "Noname", "name": "brand" }, { "value": "12mm", "name": "diameter" }]},
"quantity": { "value": 1.0, "measure": "штук" },
"itemAmount": 6000, "itemCurrency": "643", "itemCode": "NM-15",
"discount": { "discountType": "percent", "discountValue": "5" },
"agentInterest": { "interestType": " agentPercent ", "interestValue": "7" }, "tax": {"taxType": 1,"taxSum": 111}, "itemPrice": 6000 },
{ "positionId": "3", "name": "Warm Grips", "itemDetails": { "itemDetailsParams":
[ { "value": "Noname", "name": "brand" }]}, "quantity": { "value": 1.0, "measure": "штук" },
"itemAmount": 3000, "itemCurrency": 643, "itemCode": "G-16",
"discount": { "discountType": "percent", "discountValue": "5" },
"agentInterest": { "interestType": " agentPercent ", "interestValue": "7" }, "tax": {"taxType": 1,"taxSum": 111}, "itemPrice": 3000}] }}

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

language=ru&orderId=830603cd-a886-483a-9a23-c37fb8018096&jsonParams={"name1":"value1"}&amount=9000& refundItems={"items": [  { "positionId": "2", "name": "Universal Mirror Enduro", "itemDetails": { "itemDetailsParams": [{ "value": "Noname", "name": "brand" }, { "value": "12mm", "name": "diameter" }]}, "quantity": { "value": 1.0, "measure": "штук" }, "itemAmount": 6000, "itemCurrency": "643", "itemCode": "NM-15", "discount": { "discountType": "percent", "discountValue": "5" }, "agentInterest": { "interestType": " agentPercent ", "interestValue": "7" }, "tax": {"taxType": 1,"taxSum": 111}, "itemPrice": 6000 },  { "positionId": "3", "name": "Warm Grips", "itemDetails": { "itemDetailsParams": [ { "value": "Noname", "name": "brand" }]}, "quantity": { "value": 1.0, "measure": "штук" }, "itemAmount": 3000, "itemCurrency": 643, "itemCode": "G-16", "discount": { "discountType": "percent", "discountValue": "5" }, "agentInterest": { "interestType": " agentPercent ", "interestValue": "7" }, "tax": {"taxType": 1,"taxSum": 111}, "itemPrice": 3000}] }

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

{"errorCode":"0","errorMessage":"Успешно"}

 

 

 

 

5. Координаты подключения

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

 

Описание тестового сервиса (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