| Правильная ссылка на эту статью: |
Регламент передачи информации
Статья неактуальнаСтатья неактуальнаИнтерфейс в виде XML-запросов к сертификационному Web-серверу системы.¶
Интерфейс №1¶
Интерфейсы системы, основаны на обращениях (запросах) к специальному Web-cерверу системы по протоколу https (SSL 128 бит) в формате XML с использованием специального модуля аутентификации для ключей WM Keeper WinPro .
Аутентификация запроса производится на основании сформированной подписи, находящейся в параметре <sign type="">...</sign> и созданной с использованием ключей WM Keeper WinPro (Classic).
Для использования интерфейса необходимо последовательно произвести два XML-запроса.¶
- Предварительный запрос на возможность проведения платежа.
- Запрос на проведение платежа.
Принимается кодировка UTF-8.
Предварительный запрос на возможность проведения платежа.¶
Запрос необходимо выполнять до приема денежных средств от Плательщика. При выполнении этого запроса контролируются исправность технических средств (наличие связи, работоспособность и т.д.), обеспеченность средствами для реализации, наличие номера мобильного телефона Плательщика. Также осуществляется проверка Учетного реквизита Плательщика на возможность реализации именно на этот Учетный реквизит (существует, не заблокирован, не превышен текущий лимит и т.п).
Следует учитывать, что предварительный запрос уменьшает текущий лимит Плательщика на сумму, переданную в запросе. Такое резервирование действует до завершения платежа или в течение суток. Поэтому количество предварительных запросов должно соответствовать количеству запросов на зачисление во избежание превышения лимита.
- URL для передачи запроса – https://w3s.kkb.ru/ATM/XML/PrePayment1.ashx
- метод - POST
- формат запроса:
<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> .
- URL для передачи запроса – https://w3s.kkb.ru/ATM/XML/Payment1.ashx
- метод - POST
- формат запроса:
<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
Валидация параметров платежа.
Интерфейс в виде XML-запросов к сертификационному Web-серверу системы.¶
Интерфейс №1¶
Интерфейсы системы, основаны на обращениях (запросах) к специальному Web-cерверу системы по протоколу https (SSL 128 бит) в формате XML с использованием специального модуля аутентификации для ключей WM Keeper WinPro .
Аутентификация запроса производится на основании сформированной подписи, находящейся в параметре <sign type="">...</sign> и созданной с использованием ключей WM Keeper WinPro (Classic).
Для использования интерфейса необходимо последовательно произвести два XML-запроса.¶
- Предварительный запрос на возможность проведения платежа.
- Запрос на проведение платежа.
Принимается кодировка UTF-8.
Предварительный запрос на возможность проведения платежа.¶
Запрос необходимо выполнять до приема денежных средств от Плательщика. При выполнении этого запроса контролируются исправность технических средств (наличие связи, работоспособность и т.д.), обеспеченность средствами для реализации, наличие номера мобильного телефона Плательщика. Также осуществляется проверка Учетного реквизита Плательщика на возможность реализации именно на этот Учетный реквизит (существует, не заблокирован, не превышен текущий лимит и т.п).
Следует учитывать, что предварительный запрос уменьшает текущий лимит Плательщика на сумму, переданную в запросе. Такое резервирование действует до завершения платежа или в течение суток. Поэтому количество предварительных запросов должно соответствовать количеству запросов на зачисление во избежание превышения лимита.
- URL для передачи запроса – https://w3s.kkb.ru/ATM/XML/PrePayment1.ashx
- метод - POST
- формат запроса:
<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> .
- URL для передачи запроса – https://w3s.kkb.ru/ATM/XML/Payment1.ashx
- метод - POST
- формат запроса:
<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
Валидация параметров платежа.