Wiki

Регламент передачи информации

Интерфейс в виде XML-запросов к сертификационному Web-серверу системы.

Интерфейс №1

Интерфейсы системы, основаны на обращениях (запросах) к специальному Web-cерверу системы по протоколу https (SSL 128 бит) в формате XML с использованием специального модуля аутентификации для ключей WM Keeper WinPro .

Аутентификация запроса производится на основании сформированной подписи, находящейся в параметре <sign type="">...</sign> и созданной с использованием ключей WM Keeper WinPro (Classic).

Для использования интерфейса необходимо последовательно произвести два XML-запроса.

  1. Предварительный запрос на возможность проведения платежа.
  2. Запрос на проведение платежа.

    Принимается кодировка UTF-8.

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

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

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

<w3s.request>
<wmid></wmid>
<gatewaysid></gatewaysid>
<sign type=”1”></sign>
    <payment  id="" >
               <price></price>
               <purse></purse>
               <phone></phone>
               <sourcetype></sourcetype>
        </payment>
</w3s.request>
  • параметры запроса:
название назначение примечание
wmid WMID подписавшего запрос используется при авторизации с ключами WM Keeper WinPro или сертификатом X.509 WM Keeper WebPro
gatewaysid номер шлюза необходимо передавать в запросе номер шлюза, только если одним и тем же WMIDом подписываются запросы на разные шлюзы. Если WMIDом подписываются запросы только по одному шлюзу, тег необязателен.
sign подпись запроса формируется из параметров: wmid+ price+phone+purse
sign/@type тип подписи запроса 1 - подпись сформирована с использованием специального модуля аутентификации для ключей WM Keeper WinPro, 2 - подпись сформирована с использованием сертификата X.509 WM Keeper WebPro в кодировке base64
payment/@id уникальный номер транзакции в системе БАНКА 1, формируемый вызывающим запрос. Задается целым десятичным числом, заключенным в двойные кавычки и содержит не более 18 цифр. Уникальность «id» позволяет выполнять запрос повторно с тем же номером транзакции и параметрами в случае не получения ответа на запрос (обрыв связи и т.д.).
payment/price определяет сумму, принятую от Плательщика;"число с плавающей точкой (разделитель - .(точка) ) и для десяти с половиной может выглядеть так: 10.5 незначащие нули в конце и точка, если число целое, должны отсутствовать, например, 10.50 - не верно, 10.5 - верно, 9. - не верно, 9 - верно
payment/purse учетный реквизит Плательщика в системе БАНКА 2 строка – 13 символов, первый символ латинская буква R или P и 12 цифр; пробелы не допускаются, цифры могут быть номером R-кошелька, P-кошелька, WMID или телефоном, если начинаются с 07
payment/phone номер мобильного телефона Плательщика, используется для идентификации Плательщика Задается десятичным числом, начиная с кода страны (Россия: 7) и содержит не более 14 цифр; пробелы не допускаются
payment/sourcetype тип источника средств для пополнения наличные - 0, банковский счет - 1, ЭДС -2, счет мобильного телефона - 3. Параметр обязательный!
  • формат ответа:
<w3s.response>
    <retval></retval>
    <retdesc></retdesc>
        <payment  id="">
               <price></price>
               <purse></purse>
               <phone></phone>
               <limit></limit>
               <wmid></wmid>
               <rest></rest>
         </payment>
</w3s.request>
название назначение примечание
retval код состояния или ошибки 0 - означает успешное прохождение запроса. Значение других кодов возврата говорит о неудачном прохождении запроса. Возможные коды возврата: 1 – неисправность технических средств; 2 – не хватает средств обеспечения для выполнения зачисления.
Повторять запрос на проведение платежа нужно после устранения причины, вызвавшей ошибку и обязательно с соответствующим этому платежу уникальным номером транзакции в системе БАНКА 1 (id - уникальный номер). Если в ответе на запрос получен <retval> =0, то при повторном запросе с теми же параметрами запроса, будет получен аналогичный ответ с теми же атрибутами. Если в ответе на запрос получен <retval> =1 или <retval> =2, то после устранении причины отказа, при повторном запросе с теми же параметрами платеж будет зачислен.
retdesc текстовое описание ошибки/пусто текст описания ошибки. произвольная строка от 0 до 255 символов, кодировка win-1251
payment/@id уникальный номер транзакции в системе БАНКА 1, формируемый вызывающим запрос. Задается целым десятичным числом, заключенным в двойные кавычки и содержит не более 18 цифр. Уникальность «id» позволяет выполнять запрос повторно с тем же номером транзакции и параметрами в случае не получения ответа на запрос (обрыв связи и т.д.).
payment/price определяет сумму, принятую от Плательщика;"число с плавающей точкой (разделитель - .(точка) ) и для десяти с половиной может выглядеть так: 10.5 незначащие нули в конце и точка, если число целое, должны отсутствовать, например, 10.50 - не верно, 10.5 - верно, 9. - не верно, 9 - верно
payment/purse учетный реквизит Плательщика в системе БАНКА 2 строка – 13 символов, первый символ латинская буква R или P и 12 цифр
payment/phone номер мобильного телефона Плательщика, используется для идентификации Плательщика Задается десятичным числом, начиная с кода страны (Россия: 7) и содержит не более 14 цифр; пробелы не допускаются
payment/limit максимально возможная сумма реализации
на Учетный реквизит Плательщика
возвращается сумма, которая может в данный момент быть передана на Учетный реквизит Плательщика в соответствии с лимитами, устанавливаемыми БАНКОМ 2. Если нет ограничений по лимиту, будет возвращено значение 99999999, например: <limit>99999999</limit>
payment/wmid наименование или идентификатор определяет идентификатор БАНКА 2 в системе БАНКА 1 (12 цифр). Пробелы не допускаются
payment/rest остаток средств обеспечения сумма средств обеспечения БАНКА 2, возможных для приема платежа. Незначащие нули в конце и точка, если число целое, должны отсутствовать, например, 10.50 - не верно, 10.5 - верно, 9. - не верно, 9 - верно

Запрос на проведение платежа

Запрос на проведение платежа выполняется после успешного выполнения Предварительного запроса. При выполнении этого запроса принимаются все платежи, за исключением двух ситуаций неисправность технических средств и недостаток средств обеспечения для реализации платежа. Если при выполнении этого запроса был получен отрицательный ответ, необходимо, после устранения причин повторять этот запрос с тем же номером уникальным id (во избежание двойного зачисления) до получения положительного ответа. Платеж считается принятым, если при выполнении запроса был получен положительный ответ <retval>0<retval> .

<w3s.request>
<wmid></wmid>
<gatewaysid></gatewaysid>     
<sign type=”1”></sign>
        <payment id=""  test="1/0">
                <price></price>
                <purse></purse>
                <phone></phone>
                <sourcetype></sourcetype>
                <cheque></cheque>
                <date></date>
                <kiosk_id></kiosk_id>
                <gatewaysid></gatewaysid>
        </payment>
</w3s.request>
  • параметры запроса:
название назначение примечание
wmid WMID подписавшего запрос используется при авторизации с ключами WM Keeper WinPro или сертификатом X.509 WM Keeper WebPro
gatewaysid номер шлюза необходимо передавать в запросе номер шлюза, только если одним и тем же WMIDом подписываются запросы на разные шлюзы. Если WMIDом подписываются запросы только по одному шлюзу, тег необязателен.
sign подпись запроса формируется из параметров: wmid+ price+phone+purse
sign/@type тип подписи запроса 1 - подпись сформирована с использованием специального модуля аутентификации для ключей WM Keeper WinPro 2 - подпись сформирована с использованием сертификата X.509 WM Keeper WebPro в кодировке base64
payment/@id уникальный номер транзакции в системе БАНКА 1, формируемый вызывающим запрос Значение идентично уникальному номеру транзакции в предзапросе и задается целым десятичным числом, заключенным в двойные кавычки и содержит не более 18 цифр. Уникальность «id» позволяет выполнять запрос повторно с тем же номером транзакции и параметрами в случае не получения ответа на запрос (обрыв связи и т.д.).
payment/@test определяет режим запроса Задается значениями "0" или "1". «test» равен "1"- платеж проводится в
тестовом режиме, «test» равен "0" - платеж реальный. Например: < payment> id="93578" test="0" </payment>. При этом номер id должен быть уникальным для тестовых и реальных запросов. Если id был использован для тестового запроса, его нельзя использовать для реального запроса
payment/price определяет сумму, принятую от Плательщика;"число с плавающей точкой (разделитель - .(точка) ) и для десяти с половиной может выглядеть так: 10.5 незначащие нули в конце и точка, если число целое, должны отсутствовать, например, 10.50 - не верно, 10.5 - верно, 9. - не верно, 9 - верно
payment/purse учетный реквизит Плательщика в системе БАНКА 2 строка – 13 символов, первый символ латинская буква R или P и 12 цифр; пробелы не допускаются, цифры могут быть номером R-кошелька, P-кошелька, WMID или телефоном, если начинаются с 07
payment/phone номер мобильного телефона Плательщика, используется для идентификации Плательщика Задается десятичным числом, начиная с кода страны (Россия: 7) и содержит не более 14 цифр; пробелы не допускаются
payment/cheque определяет номер документа выданный Плательщику БАНКОМ 1 Задается целым десятичным числом и содержит не более 16 цифр; пробелы не допускаются
payment/date дата приема платежа по "часам" БАНКА 1 Имеет формат YYYYMMDD HH:mm:ss, где YYYY – число года, MM – число месяца, DD – число дня, HH – часы, mm – минуты, ss – секунды. Например: <date> 20071030 12:04:03; пробелы не допускаются
payment/kiosk_id идентификатор точки приема платежа БАНКА 1 Уникальный идентификатор автомата или банкомата или терминала и т.п. Задается целым десятичным числом и содержит не более 16 цифр; пробелы не допускаются
payment/gatewaysid идентификатор Уникальный номер, выдающийся после заключения договора, константа. Параметр не обязательный
payment/sourcetype тип источника средств для пополнения наличные - 0, банковский счет - 1, ЭДС -2, счет мобильного телефона - 3. Параметр обязательный!
  • формат ответа:
<w3s.response>
    <retval></retval>
    <retdesc></retdesc>
    <payment id=""  test="1/0">
                <number></number>
                <price></ price>
                <amount></amount>
                <bonus></bonus>
                <rest>/rest>
                <purse></purse>
                <phone></phone>
                <cheque></cheque>
                <date></date>
                <kiosk_id></kiosk_id>
                <wmtranid></wmtranid>
                <wmdate></wmdate>
        </payment>
</w3s.request>
  • параметры ответа
название назначение примечание
retval код состояния или ошибки 0 - означает успешное прохождение запроса. Значение других кодов возврата говорит о неудачном прохождении запроса. Возможные коды возврата: 1 – неисправность технических средств; 2 – не хватает средств обеспечения для выполнения зачисления.
Повторять запрос на проведение платежа нужно после устранения причины, вызвавшей ошибку и обязательно с соответствующим этому платежу уникальным номером транзакции в системе БАНКА 1 (id - уникальный номер). Если в ответе на запрос получен <retval> =0, то при повторном запросе с теми же параметрами запроса, будет получен аналогичный ответ с теми же атрибутами. Если в ответе на запрос получен <retval> =1 или <retval> =2, то после устранении причины отказа, при повторном запросе с теми же параметрами платеж будет зачислен.
retdesc текстовое описание ошибки/пусто текст описания ошибки. произвольная строка от 0 до 255 символов, кодировка win-1251
payment/@id уникальный номер транзакции в системе БАНКА 1, формируемый вызывающим запрос. Задается целым десятичным числом, заключенным в двойные кавычки и содержит не более 18 цифр. Уникальность «id» позволяет выполнять запрос повторно с тем же номером транзакции и параметрами в случае не получения ответа на запрос (обрыв связи и т.д.).
payment/@test определяет режим запроса Задается значениями "0" или "1". «test» равен "1"- платеж проводится в
тестовом режиме, «test» равен "0" - платеж реальный. Например: < payment> id="93578" test="0" </payment>. При этом номер id должен быть уникальным для тестовых и реальных запросов. Если id был использован для тестового запроса, его нельзя использовать для реального запроса
payment/number шестнадцатисимвольный код платежа Задается буквами латинского алфавита (A,B,С,D,E,F) и десятичными цифрами. Например: A7634FC7634D3290
payment/price определяет сумму, принятую от Плательщика;"число с плавающей точкой (разделитель - .(точка) ) и для десяти с половиной может выглядеть так: 10.5 незначащие нули в конце и точка, если число целое, должны отсутствовать, например, 10.50 - не верно, 10.5 - верно, 9. - не верно, 9 - верно
payment/amount определяет сумму к зачислению на Учетный реквизит Плательщика незначащие нули в конце и точка, если число целое отсутствуют, например, 10.50 - не верно, 10.5 - верно, 9. - не верно, 9 - верно
payment/bonus сумма вознаграждения БАНКА 1 вознаграждение БАНКА 1 в соответствии с п. 4.1. настоящего договора. Задается десятичным числом с точностью до второго знака с разделителем «.»(точка). Сумма вознаграждения БАНКА 1, в соответствии с п. 4.1. Договора, вычисляется по формуле: bonus= price*процент БАНКА 1 по договору/100.
незначащие нули в конце и точка, если число целое, должны отсутствовать, например, 10.50 - не верно, 10.5 - верно, 9. - не верно, 9 - верно
payment/rest остаток средств обеспечения сумма средств обеспечения БАНКА 2, возможных для приема платежа. Незначащие нули в конце и точка, если число целое, должны отсутствовать, например, 10.50 - не верно, 10.5 - верно, 9. - не верно, 9 - верно
payment/purse учетный реквизит Плательщика в системе БАНКА 2 строка – 13 символов, первый символ латинская буква R или P и 12 цифр
payment/phone номер мобильного телефона Плательщика, используется для идентификации Плательщика Задается десятичным числом, начиная с кода страны (Россия: 7) и содержит не более 14 цифр; пробелы не допускаются
payment/cheque определяет номер документа выданный Плательщику БАНКОМ 1 Задается целым десятичным числом и содержит не более 16 цифр; пробелы не допускаются
payment/date дата приема платежа по "часам" БАНКА 1 Имеет формат YYYYMMDD HH:mm:ss, где YYYY – число года, MM – число месяца, DD – число дня, HH – часы, mm – минуты, ss – секунды. Например: <date> 20071030 12:04:03; пробелы не допускаются
payment/kiosk_id идентификатор точки приема платежа БАНКА 1 Уникальный идентификатор автомата или банкомата или терминала и т.п. Задается целым десятичным числом и содержит не более 16 цифр; пробелы не допускаются
payment/wmtranid транзакция БАНКА 2 настоятельно рекомендуется хранение в учетной системе БАНКА 1 связки уникального id и уникального соответствующего ему wmtranid, что позволяет 100% идентифицировать любой платеж. задается целым десятичным числом
payment/wmdate дата операции по "часам" БАНКА 2 дата операции по "часам" БАНКА 2. имеет формат YYYYMMDD HH:mm:ss, где YYYY – число года, MM – число месяца, DD – число дня, HH – часы, mm – минуты, ss – секунды

Возврат <retval>0<retval> означает успешное прохождение платежа.

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

  • возможные коды выполнения запроса:
код описание
3730, 5730, 5733 Превышен суточный лимит
3731, 5731 Превышен месячный лимит
3732, 5732 Превышен лимит количества операций пополнения в сутки

В случае многократного получения кода ошибки необходимо связаться со специалистами БАНКА 2 для выяснения состояния платежа.

Разрешается свободное использование интерфейсов.

Интерфейс №2

Check
Получение статуса платежа.

GetCategories
Справочник. Список категорий предоставляемых операторами услуг.

GetContractors
Справочник. Список доступных операторов.

GetCountries
Справочник. Список стран.

GetCurrencies
Справочник. Список валют абонентских счетов.

GetDepositAccounts
Справочник. Список депозитных счетов клиента.

GetOperationStatus
Получение информации по статусу платежа.

GetPayCurrencies
Справочник. Список валют оплаты.

GetPayment
Получение информации по платежу.

GetRegions
Справочник. Список регионов.

Pay
Запрос на проведение платежа.

Payments
Список платежей пользователя.

Refunds
Список возвратов.

Request
Запрос на проверку реквизитов платежа.

Start
Запрос на проверку реквизитов платежа.

StartWithPaymentAmount
Запрос на проверку реквизитов платежа.

Verify
Валидация параметров платежа.