Перевод на банковский счет
advertisement
Протокол обмена информацией при
осуществлении переводов: зачисления на
счета Яндекс.Денег, мобильные телефоны,
банковские счета и карты
Протокол 3.1.1, редакция от 30.07.2015
Оглавление
1.
2.
Общие сведения .................................................................................................................................. 2
1.1
Назначение документа ............................................................................................................... 2
1.2
Формирование запроса .............................................................................................................. 2
1.3
Получение ответа ........................................................................................................................ 3
Методы протокола .............................................................................................................................. 3
2.1
2.1.1
Формат запросов ИС............................................................................................................ 4
2.1.2
Формат ответов Оператора ................................................................................................ 6
2.2
Запрос баланса Контрагента (balance) ....................................................................................... 7
2.2.1
Формат запроса ИС .............................................................................................................. 7
2.2.2
Формат ответа Оператора................................................................................................... 8
2.3
3.
Зачисление переводов (makeDeposition). ................................................................................. 3
Уведомление Контрагента о неуспешном статусе перевода (errorDepositionNotification) .. 8
2.3.1
Формат запроса Оператора ................................................................................................ 9
2.3.2
Формат ответа ИС ................................................................................................................ 9
Зачисление переводов на банковский счет, карту, мобильный телефон ...................................... 9
3.1
Перевод на банковскую карту ..................................................................................................10
3.1.1
4.
Синоним номера банковской карты ................................................................................11
3.2
Перевод на банковский счет ....................................................................................................13
3.3
Перевод на счет мобильного телефона ..................................................................................14
Справочники ......................................................................................................................................15
4.1
Состояния обработки запроса (status) .....................................................................................15
4.2
Коды ошибок обработки запросов (error)...............................................................................15
4.3
Типы данных ..............................................................................................................................16
2
1. Общие сведения
1.1 Назначение документа
Данный документ описывает взаимодействие информационной системы (далее – ИС) Контрагента
с ООО НКО «Яндекс.Деньги» (далее – Оператор, Яндекс.Деньги), необходимое для уведомления о
зачислении средств пользователям.
Зачисления могут быть совершены не только на счета Яндекс.Денег, но и на рублевые банковские
счета, банковские карты, счета мобильных телефонов.
Процесс взаимодействия позволяет:
1. Проверять возможность зачисления переводов (testDeposition).
2. Передавать запросы на зачисление переводов (makeDeposition).
3. Отслеживать баланс средств Контрагента по договору, заключенному с Оператором
(balance).
4. Получать уведомления о неуспешном статусе переводов на банковский счет, карту,
мобильный телефон (errorDepositionNotification).
1.2 Формирование запроса
Контрагент должен получить сертификат, с использованием которого он будет подключаться и
формировать запросы к Оператору. См. документ «Процедура обмена сертификатами».
Контрагент и Оператор взаимодействуют с помощью протокола HTTPS. Для выполнения каждой из
операций Контрагент передает отдельный HTTP-запрос, содержащий криптопакет формата PKCS#7.
На каждый запрос о зачислении сервер Оператора отвечает сообщением о результате операции,
помещенным в криптопакет PKCS#7.
Также используется криптографическая защита канала связи на базе протокола SSL (HTTPS), с
аутентификацией по клиентскому сертификату. Кроме того, ограничивается список IP-адресов, с
которых допустимо присылать запросы на сервер Оператора.
Формирование запроса к серверу Оператора состоит из следующих шагов:
1. Распоряжение на исполнение операции.
Распоряжение формируется как документ по стандарту XML 1.0 (Fifth Edition):
http://www.w3.org/TR/xml/. Документ должен быть сформирован в кодировке UTF-8 согласно
стандарту: http://www.ietf.org/rfc/rfc2279.txt.
2. Формирование криптопакета.
Сформированный документ помещается в криптоконтейнер формата PKCS#7 согласно стандарту
http://www.ietf.org/rfc/rfc5652.txt. Криптоконтейнер должен содержать АСП (цифровую подпись,
аналог собственноручной подписи). Криптоконтейнер не должен содержать цепочки
сертификации. Компрессия данных не используется. Шифрование не используется. Криптопакет
должен быть закодирован в формате PEM (OpenSSL). Сертификат Контрагента, используемый при
изготовлении криптопакета, должен соответствовать стандарту X.509 Version 3
(http://www.ietf.org/rfc/rfc2459.txt).
3. Передача запроса серверу Оператора.
ИС формирует POST-запрос по протоколу HTTP/1.1 (http://www.ietf.org/rfc/rfc2616.txt,
http://www.ietf.org/rfc/rfc2818.txt, http://www.ietf.org/rfc/rfc4346.txt). Криптопакет может быть
передан одним из двух способов:
a) Криптопакет помещается в тело POST-запроса, MIME-тип: application/pkcs7-mime.
b) Криптопакет передается как multipart-data вложение. MIME-тип: application/pkcs7-mime.
POST-запрос должен иметь только один 'part', криптопакет должен быть вложен как файл.
Такой запрос может быть отправлен из стандартной HTML-формы для file upload (отправки
файла на сервер). См. http://www.ietf.org/rfc/rfc2388.txt.
Для авторизации запросов сервер Оператора проверяет АСП криптопакета.
3
Защита от ошибочных повторов операций зачисления обеспечивается наличием уникального
номера операции (clientOrderId).
Пример сформированного запроса:
POST /webservice/deposition/api/makeDeposition HTTP/1.1
Content-Type: application/pkcs7-mime
Content-Length: 572
-----BEGIN PKCS7----MIAGCSqGSIb3DQEHAqCAMIACAQExCzAJBgUrDgMCGgUAMIAGCSqGSIb3DQEHAaCA
JIAEDEhlbGxvIFdvcmxkIQAAAAAAADGCAS8wggErAgEBMCowJTEWMBQGA1UECgwN
Qm91bmN5IENhc3RsZTELMAkGA1UEBhMCQVUCAQIwCQYFKw4DAhoFAKBdMBgGCSqG
SIb3DQEJAzELBgkqhkiG9w0BBwEwHAYJKoZIhvcNAQkFMQ8XDTEwMDgwNjE1MzE0
M1owIwYJKoZIhvcNAQkEMRYEFC73veYIzlQE6X1fBC+V+J8cIyhxMA0GCSqGSIb3
DQEBAQUABIGAEgIfi0XDEZwbdC8i0I5EPUnFe1PUnBMiRs3heYxdK+oXaG6v3axO
Zr+VNG3tnW1W8M2xWtOcM4PdSTwx98WR1mWN8XDb2Wl9HiG6CGbmE7k4TgcDKhcg
iZmLV+7anBv302qTprTbKY9vChaaVwclSdQBkjPvxhlPnpBM0C9YdYQAAAAAAAA=
-----END PKCS7-----
1.3 Получение ответа
Результат выполнения запроса возвращается Оператором в ответе на HTTP-запрос. MIME-тип:
application/pkcs7-mime. Данные помещены в криптоконтейнер формата PKCS#7. Криптоконтейнер
содержит АСП (цифровую подпись, аналог собственноручной подписи). Криптоконтейнер не
содержит цепочки сертификации. Компрессия данных не используется. Шифрование не
используется. Криптопакет закодирован в формате PEM (OpenSSL). Криптоконтейнер содержит
XML-документ с результатом обработки запроса.
При получении ответа сервера Контрагент выполняет проверку подписи ответа, чтобы убедиться,
что ответ отправлен сервером Оператора, а также что его содержимое не было изменено третьей
стороной. Следует также учитывать, что в ответе могут быть дополнительные поля, не описанные в
данном протоколе, но не нарушающие совместимость.
Таблица 1.3.1. Возможные HTTP-коды ответа
HTTP-код
Описание
200 OK
Запрос принят к обработке. Отправлен ответ в соответствии с
настоящим протоколом. MIME-тип: application/pkcs7-mime.
Запрос не принят к обработке. Тело запроса испорчено, сервер не
смог прочитать или разобрать запрос.
Возможные причины:
запрос невозможно разобрать;
неверный MIME-тип (Content-Type).
Сертификат Контрагента не зарегистрирован у Оператора, либо в
настоящий момент шлюз отключен.
Технические проблемы Оператора. Обратитесь в службу поддержки.
Запрос отправлен методом, отличным от POST.
400 Bad Request
403 Forbidden
500 Internal Server Error
501 Not Implemented
2. Методы протокола
2.1 Зачисление переводов (makeDeposition).
Операция используется для того, чтобы инициировать зачисление перевода на счет Оператора.
Обратите внимание: Предварительно необходимо осуществлять проверку возможности
зачисления перевода (операция testDeposition) до принятия средств от клиента. Запрос
testDeposition позволяет проверить возможность зачисления указанной суммы получателю, в том
числе корректность и существование идентификатора пользователя (номера счета или телефона),
4
лимиты и отсутствие запретов на проведение операции. При приеме запроса testDeposition
зачисление перевода не производится.
Шаблон адреса операций:
https://server:port/webservice/deposition/api/testDeposition
https://server:port/webservice/deposition/api/makeDeposition
Правила формирования и обработки запросов на зачисление переводов:
1.
Каждое зачисление должно быть сформировано с уникальным значением идентификатора
(clientOrderId).
2. Если на операцию «зачисление» получен ответ «Успех» (status=0), то перевод зачислен
успешно.
3. Если запрос отправлен с уже ранее обработанным идентификатором (clientOrderId) и
остальные параметры запроса, кроме requestDT, совпадают с предыдущей попыткой, то
Оператор вернет результат обработки ранее отправленного запроса.
4. Если запрос отправлен с уже ранее обработанным идентификатором (clientOrderId) и какиелибо параметры, кроме requestDT, имеют отличные от первой попытки значения, то Оператор
отвергает такой запрос и возвращает в ответе status=3, error=26.
5. Оператор обрабатывает полученный запрос немедленно. В случае если запрос невозможно
обработать в течение нескольких секунд, возвращается ответ «в процессе обработки»
(status=1). В этом случае результат операции неизвестен, и ИC следует повторить запрос с теми
же данными для получения окончательного ответа. Рекомендуется следующий режим
повтора: первый повтор через 1 минуту, следующие три с промежутком в 5 минут, далее не
более одного раза в 30 минут. Аналогичный режим повтора рекомендуется в случае
неполучения ответа от Оператора или получения ответа HTTP status 500.
6. При неполучении ответа от Оператора, а также при нечетком ответе (например: HTTP status
500) ИС Контрагента следует повторить запрос с теми же данными для получения
окончательного ответа. Рекомендуется режим повтора как в предыдущем пункте.
7. Статус транзакции, находящейся в обработке (status=1), может измениться как на «успех»
(status=0), так и на «отвергнут» (status=3).
8. Если перевод отвергнут Оператором, то в ответе возвращается status=3 и error= с кодом
причины отказа. В некоторых случаях может присутствовать поле techMessage, содержащее
дополнительную поясняющую информацию в виде текста произвольного формата. Этот текст
предназначен для анализа техническими специалистами и не должен отображаться в какомлибо интерфейсе пользователя.
9. Если перевод отвергнут с ошибкой status=3 error=45, Контрагенту необходимо перечислить
принятые переводы на расчетный счет Оператора, убедиться, что баланс увеличился (отправив
запрос баланса), и провести переводы с НОВЫМИ идентификаторами операций (clientOrderId).
10. Ошибка status=3 error=21 означает, что запрашиваемая операция запрещена для данного
Контрагента.
2.1.1
Формат запросов ИС
Таблица 2.1.1.1. Параметры запроса операций testDeposition, makeDeposition (все параметры
обязательные, кроме отмеченных символом «*»)
Параметр
Тип
Описание
clientOrderId
ClientTransactionNumber
Идентификатор
операции.
Должен
быть
уникальным для Контрагента на протяжении всей
истории операций. Рекомендуемые значения: целое
положительное число в десятичной системе
счисления.
5
requestDT
xs:dateTime
dstAccount
YMAccount
amount
currency
CurrencyAmount
CurrencyCode
agentId
subAgentId (*)
xs:long
xs:long
contract
xs:normalizedString,
128 символов
xs:normalizedString, до 64 Идентификатор сервиса. Выдается Оператором.
символов
xs:compexType
Элемент запроса для передачи дополнительных
параметров перевода. Возможные значения
представлены в разделе 3 «Зачисление переводов на
банковский счет, карту, мобильный телефон».
serviceId (*)
paymentParams
(*)
Дата и время формирования запроса операции на
стороне ИС, по часам Контрагента.
Идентификатор получателя перевода.
В качестве идентификатора может использоваться:
счет пользователя в Яндекс.Деньгах (вида
4100175017397; длина существующих в
Яндекс.Деньгах Счетов на данный момент
варьируется от 11 до 16 цифр);
номер телефона пользователя, привязанный
к Счету в Яндекс.Деньгах (допускаются
номера российских операторов,
рекомендуемое представление – 10значные номера вида 9217575400, без
дополнительных символов и пробелов);
код платежа в пользу 3-х лиц (номера,
начинающиеся с «255», «256», «257»; список
периодически расширяется). Ряд значений
описан в разделе 3 «Зачисление переводов
на банковский счет, карту, мобильный
телефон».
Сумма перевода, например: 12.34
Код валюты перевода. Возможные значения:
643 — рубль Российской Федерации;
10643 – рубли для тестовой среды
Оператора.
Идентификатор Контрагента. Выдается Оператором.
Уникальный
идентификатор
канала
приема
переводов. Указывается только в случае разделения
переводов по нескольким каналам. Выдается
Оператором.
до Основание для зачисления перевода.
Пример запроса проверки возможности зачисления:
<?xml version="1.0" encoding="UTF-8"?>
<testDepositionRequest agentId="123"
clientOrderId="12345"
requestDT="2011-07-01T20:38:00.000Z"
dstAccount="410011234567"
amount="10.00"
currency="643"
contract="Выигрыш в игре Сфера"/>
Пример запроса на зачисление c указанием subAgentId и serviceId:
6
<?xml version="1.0" encoding="UTF-8"?>
<makeDepositionRequest agentId="123"
subAgentId="456"
clientOrderId="12345"
requestDT="2011-07-01T20:38:00.000Z"
dstAccount="410011234567"
amount="10.00"
currency="643"
contract="Выигрыш в игре Сфера">
<serviceId>456</serviceId>
</makeDepositionRequest>
Пример запроса на зачисление с указанием paymentParams:
<?xml version="1.0" encoding="UTF-8"?>
<makeDepositionRequest agentId="200225"
clientOrderId="272517"
requestDT="2013-04-12T00:01:54.000Z"
dstAccount="2570066957329"
amount="249.00"
currency="643"
contract="">
<paymentParams>
<pof_offerAccepted>1</pof_offerAccepted>
<PROPERTY1>905</PROPERTY1>
<PROPERTY2>2075556</PROPERTY2>
<smsPhoneNumber>79653457676</smsPhoneNumber>
</paymentParams>
</makeDepositionRequest>
2.1.2
Формат ответов Оператора
Таблица 2.1.2.1. Параметры ответа операций testDeposition, makeDeposition
Параметр
Тип
Описание
status
xs:int
error
xs:int
clientOrderId
processedDT
ClientTransactionNumber
xs:dateTime
balance
xs:decimal
techMessage
xs:string
Результат выполнения операции. По значению этого
поля ИС Контрагента должна принимать решение о
состоянии запроса. См. табл. 4.1.1 «Коды состояний
запроса».
Код ошибки выполнения запроса (см. табл. 4.2.1).
Является дополнительной расшифровкой к полю
status. В случае успеха поле отсутствует.
Копия параметра clientOrderId запроса.
Время обработки запроса по часам сервера
Оператора. В случае успеха операции зачисления —
фактическое время зачисления средств на счет.
Разница между суммой переводов, принятых
Контрагентом в пользу Оператора, и суммой средств,
перечисленных Контрагентом на расчетный счет
Оператора. Может быть отрицательной. Данный
параметр передается в ответе только на запрос
makeDeposition и только если зачисление
выполнено успешно.
Опциональное
поле.
Может
содержать
дополнительный поясняющий текст к отказам в
приеме перевода. Этот текст содержит техническую
информацию и не должен отображаться в какомлибо интерфейсе пользователя.
7
identification
xs:string
При выполнении перевода на банковский счет, карту,
мобильный телефон причина отказа в приеме
перевода содержится только в ответе на запрос
makeDeposition.
Поле содержит информацию о статусе счета в
системе Оператора. Может отсутствовать в ответе.
Возможные значения:
anonymous – не идентифицированный;
reviewed – упрощенно
идентифицированный;
identified – идентифицированный.
Актуальная информация о статусах пользователей
доступна по ссылке:
https://money.yandex.ru/doc.xml?id=526544
Пример ответа о возможности зачисления:
<?xml version="1.0" encoding="UTF-8"?>
<testDepositionResponse clientOrderId="12345"
status="0"
processedDT="2011-07-01T20:38:01.000Z"/>
Пример ответа об успешном зачислении:
<?xml version="1.0" encoding="UTF-8"?>
<makeDepositionResponse clientOrderId="12345"
status="0"
processedDT="2011-07-01T20:38:01.000Z"
balance="1000.00"/>
2.2 Запрос баланса Контрагента (balance)
В ответе на запрос Оператор возвращает разницу между суммой переводов, принятых
Контрагентом в пользу Оператора, и суммой средств, перечисленных Контрагентом на расчетный
счет Оператора. Может быть отрицательной.
Шаблон адреса операций: https://server:port/webservice/deposition/api/balance
2.2.1
Формат запроса ИС
Таблица 2.2.1.1 Параметры запроса операции balance
Параметр
Тип
Описание
clientOrderId
ClientTransactionNumber
requestDT
xs:dateTime
agentId
xs:long
Идентификатор
операции.
Должен
быть
уникальным для Контрагента на протяжении всей
истории операций. Рекомендуемые значения:
целое положительное число в десятичной системе
счисления.
Дата и время формирования запроса операции на
стороне ИС, по часам Контрагента.
Идентификатор Контрагента. Выдается Оператором.
Пример запроса проверки баланса:
<?xml version="1.0" encoding="UTF-8"?>
<balanceRequest agentId="123"
clientOrderId="12345"
requestDT="2011-07-01T20:38:00.000Z"/>
8
2.2.2
Формат ответа Оператора
Таблица 2.2.2.1 Параметры ответа операции balance
Параметр
Тип
Описание
status
xs:int
error
xs:int
clientOrderId
processedDT
ClientTransactionNumber
xs:dateTime
balance
xs:decimal
Результат выполнения операции. По значению
этого поля ИС Контрагента должна принимать
решение о состоянии запроса. См. табл. 4.1.1
«Коды состояний запроса».
Код ошибки выполнения запроса (см. табл. 4.2.1).
Является дополнительной расшифровкой к полю
status. В случае успеха поле отсутствует.
Копия параметра clientOrderId запроса.
Время обработки запроса по часам сервера
Оператора.
Разница между суммой переводов, принятых
Контрагентом в пользу Оператора, и суммой
средств, перечисленных Контрагентом на
расчетный счет Оператора. Может быть
отрицательной.
Пример ответа о состоянии баланса:
<?xml version="1.0" encoding="UTF-8"?>
<balanceResponse clientOrderId="12345"
status="0"
processedDT="2011-07-01T20:38:01.000Z"
balance="1000.00"/>
2.3 Уведомление Контрагента о неуспешном статусе перевода
(errorDepositionNotification)
Данный запрос позволяет сообщить Контрагенту о неуспешном статусе (возврате) перевода на
банковский счет, карту, мобильный телефон (см. раздел 3). Возврат осуществляется в случае:
для перевода на банковскую карту - банк-эмитент карты получателя отверг платеж;
для перевода на банковский счет - банк отверг платеж, необходимо проверить корректность
реквизитов;
для перевода на мобильный телефон – оператор сотовой связи отверг платеж.
Правила формирования и обработки запросов о неуспешном статусе перевода:
1. Уведомление о неуспешном статусе перевода Оператор передает ИС Контрагента отдельным
HTTP-запросом, содержащим криптопакет формата PKCS#7. На каждое уведомление ИС
Контрагента отвечает сообщением о результате операции, помещенным в криптопакет PKCS#7.
Правила формирования запроса и ответа определены в разделах 1.2 и 1.3. Оператор
отправляет
уведомление
на
указанный
в
технической
анкете
адрес
(errorDepositionNotificationUrl).
2. ИС Контрагента должна отвечать на запросы Оператора в течение 10 секунд. Уведомление
считается доставленным если ответ ИС Контрагента имеет статус «Успех» (status=0).
3. При длительном многократном отсутствии ответа Контрагента (либо при многократных
технических ошибках) ИС Оператора будет повторять попытки доставки уведомления в течение
суток: первый раз – через 2 минуты, потом через 4, 10 и далее, с увеличением интервала.
4. Уведомление содержит идентификатор операции (clientOrderId), полученный от ИС
Контрагента в запросе на зачисление перевода (makeDeposition).
9
2.3.1
Формат запроса Оператора
Таблица 2.3.1.1 Параметры запроса операции errorDepositionNotification
Параметр
Тип
Описание
clientOrderId
ClientTransactionNumber
requestDT
xs:dateTime
dstAccount
amount
YMAccount
CurrencyAmount
Идентификатор операции, полученный от ИС
Контрагента в запросе на зачисление перевода
(makeDeposition)
Дата и время формирования запроса операции на
стороне Оператора, по часам Оператора.
Идентификатор получателя перевода.
Сумма перевода, например: 12.34.
currency
CurrencyCode
error
xs:string
Код валюты перевода. Возможные значения:
643 — рубль Российской Федерации;
10643 — рубли для тестовой среды
Оператора.
Код ошибки операции (см. табл. 4.2.1).
Пример запроса errorDepositionNotification:
<?xml version="1.0" encoding="UTF-8"?>
<errorDepositionNotificationRequest clientOrderId="12345"
requestDT="2011-07-01T20:38:00.000Z"
dstAccount="410011234567"
amount="10.00"
currency="643"
error="31"/>
2.3.2
Формат ответа ИС
Таблица 2.3.2.1 Параметры ответа операции errorDepositionNotification
Параметр
Тип
Описание
status
xs:int
clientOrderId
processedDT
ClientTransactionNumber
xs:dateTime
Результат выполнения операции. По значению
этого поля Оператор принимает решение о
состоянии запроса. См. табл. 4.1.1 «Коды
состояний запроса».
Копия параметра clientOrderId запроса.
Время обработки запроса по часам ИС
Контрагента.
Пример ответа на запрос errorDepositionNotification:
<?xml version="1.0" encoding="UTF-8"?>
<errorDepositionNotificationResponse clientOrderId="12345"
status="0"
processedDT="2011-07-01T20:38:01.000Z"/>
3.
Зачисление переводов на банковский счет, карту, мобильный телефон
Помимо зачисления средств на счета Оператора возможно выполнение переводов на рублевый
банковский счет, банковскую карту или счет мобильного телефона, в зависимости от значения
параметра dstAccount. В параметрах paymentParams передаются данные, необходимые для
зачисления на соответствующий счет. Среди них всегда обязательно передается согласие
получателя с офертой Яндекс.Денег (pof_offerAccepted). Ссылку на оферту Контрагент должен
разместить на своем сайте (URL указан в Договоре).
10
В запросах на зачисления на банковский счет или банковскую карту для соответствия требованиям
российского законодательства обязательно передаются персональные данные плательщика.
3.1 Перевод на банковскую карту
Идентификатор получателя перевода dstAccount="25700130535186". В параметрах запроса
Оператору Контрагент передает набор данных получателя: синоним банковской карты, паспортные
данные.
Таблица 3.1.1 Параметры элемента paymentParams
Параметр
Тип
Описание
Данные карты:
skr_destinationCardSynonim xs:string, до 100 символов
Получение и хранение полного
номера карты попадает под
действие стандарта PSI DSS,
поэтому для переводов
используется синоним
банковской карты. См. раздел
3.1.1
Подтверждение принятия оферты:
pof_offerAccepted
xs:int, 1 символ
Флаг принятия оферты
пользователем (1 — принята).
Персональные данные плательщика:
pdr_lastName
xs:string, до 100 кириллических Фамилия плательщика.
или
латинских
символов
символов
pdr_firstName
xs:string, до 100 кириллических Имя плательщика.
или
латинских
символов
символов
pdr_middleName
xs:string, до 100 кириллических Отчество плательщика.
или
латинских
символов
символов, необязательный
pdr_docNumber
xs:long, 10 символов
Серия и номер паспорта
гражданина РФ (без пробелов).
pdr_docIssueYear
xs:int, 4 символа
Год выдачи паспорта в
формате ГГГГ
pdr_docIssueMonth
xs:int, 2 символа
Месяц выдачи паспорта в
формате ММ
pdr_docIssueDay
xs:int, 2 символа
День выдачи паспорта в
формате ДД
smsPhoneNumber
xs:long, до 20 символов
Номер телефона плательщика
международном формате
(79...).
pdr_birthDate
xs:string, 10 символов
Дата рождения в формате
ДД.ММ.ГГГГ
pdr_birthPlace
xs:string, до 100 кириллических Место рождения плательщика.
символов
pdr_docIssuedBy
xs:string, до 100 кириллических Кем выдан паспорт
символов
плательщика.
pdr_country
xs:int
Цифровой код страны (РФ –
643).
pdr_city
xs:string, до 30 кириллических Город регистрации
символов
плательщика.
11
pdr_address
pdr_postcode
xs:string, до 100 кириллических Адрес регистрации
символов
плательщика.
xs:long, 6 символов
Индекс плательщика.
Пример запроса для зачисления средств на банковскую карту:
<?xml version="1.0" encoding="UTF-8"?>
<makeDepositionRequest agentId="200225"
clientOrderId="272517"
requestDT="2013-04-12T00:01:54.000Z"
dstAccount="25700130535186"
amount="249.00"
currency="643"
contract="">
<paymentParams>
<skr_destinationCardSynonim>b0af887ae9ad01fe01ca65df7cff19a7b5fcbf8b_scn</skr_destin
ationCardSynonim>
<pdr_firstName>Владимир</pdr_firstName>
<pdr_middleName>Владимирович</pdr_middleName>
<pdr_lastName>Владимиров</pdr_lastName>
<pdr_docType>21</pdr_docType>
<pdr_docNumber>4002109067</pdr_docNumber>
<pdr_postcode>194044</pdr_postcode>
<pdr_country>643</pdr_country>
<pdr_city>Санкт-Петербург</pdr_City>
<pdr_address>Большой пр, ПС, д.12</pdr_address>
<pdr_birthDate>24.05.1987</pdr_birthDate>
<pdr_birthPlace>Новосибирск</pdr_birthPlace>
<pdr_docIssueYear>1999</pdr_docIssueYear>
<pdr_docIssueMonth>7</pdr_docIssueMonth>
<pdr_docIssueDay>30</pdr_docIssueDay>
<pdr_docIssuedBy>ТП №20 по СПб и ЛО</pdr_docIssuedBy>
<pof_offerAccepted>1</pof_offerAccepted>
<smsPhoneNumber>79653457676</smsPhoneNumber>
</paymentParams>
</makeDepositionRequest>
Обратите внимание: в случае возникновения ошибки при выполнении перевода на банковскую
карту ответ Оператора может содержать следующий дополнительный поясняющий текст
(techMessage):
notRegistrationRecord – Не хватает обязательных параметров (pdr_). Дополнительно
указывается перечень недостающих полей.
Банк отклонил перевод денег на данную карту.
Банк отклонил операцию.
Превышен лимит операций.
3.1.1
Синоним номера банковской карты
Получение и хранение номера банковской карты подпадает под действие стандарта PCI DSS.
Поэтому Оператор хранит данные банковских карт на своей стороне и предоставляет Контрагенту
синонимы карт skr_destinationCardSynonim и их маски skr_destinationCardPanmask для
отображения пользователю, а также дополнительные параметры карты, которые удалось
определить в процессе обработки. Контрагент может хранить синонимы, маски и дополнительные
параметры карты на своей стороне без опасения утечки: их публикация не приводит к финансовым
или имиджевым потерям.
Контрагент на своем сайте размещает форму ввода данных карты. После подтверждения ввода
данные формы передаются по адресу https://paymentcard.yamoney.ru/gates/card/storeCard
методом POST. Сервис обрабатывает полученные данные и при помощи метода GET перенаправит
плательщика на адрес, указанный в skr_successUrl или skr_errorUrl. В случае успеха к адресу
добавляются синоним, маска и дополнительные параметры карты плательщика.
12
Параметр
skr_destinationCardNumber
skr_responseFormat
skr_errorUrl
skr_successUrl
Таблица 3.1.1.1 Параметры запроса на получение синонима карты
Тип
Описание
xs:string, до 25 символов
Номер банковской карты.
xs:string, до 8 символов
Формат ответа на запрос.
Возможные значения: redirect
либо json. Если параметр не
передан – по умолчанию
используется redirect.
xs:string, до 250 символов
Адрес редиректа при ошибке.
xs:string, до 250 символов
Адрес редиректа при успехе.
Пример кода страницы для сохранения номера карты на стороне Яндекс.Денег и получения ее
синонима:
<html>
<body>
<form action=https://paymentcard.yamoney.ru/gates/card/storeCard method=post>
<input type=text name=skr_destinationCardNumber> <br>
<input type=hidden name=skr_responseFormat value=redirect> <br>
<input type=text name="skr_errorUrl" value="http://money.yandex.ru"> <br>
<input type=text name="skr_successUrl" value="http://money.yandex.ru"> <br>
<input type=submit value="Сохранить">
</body>
</html>
Параметр
skr_destinationCardPanmask
skr_destinationCardSynonim
reason
Дополнительные параметры
skr_destinationCardBankName
skr_destinationCardCountryCode
skr_destinationCardPaymentSystem
skr_destinationCardProductName
skr_destinationCardProductCode
Таблица 3.1.1.2 Параметры ответа на запрос
Тип
Описание
xs:string, до 25 символов
Маска банковской карты.
xs:string, до 100 символов Синоним банковской карты.
xs:string, до 100 символов Результат обработки данных:
success при успехе,
cardinvalid
при
неуспехе.
xs:string, до 200 символов
Наименование
банка,
выпустившего карту.
xs:string, 3 символа
Цифровой
код
страны
выпуска карты.
xs:string, до 100 символов Наименование платежной
системы карты.
xs:string,
до
1000 Наименование карточного
символов
продукта.
xs:string, до 20 символов
Код карточного продукта.
Пример ответа redirect формата:
[skr_successUrl]/?skr_destinationCardProductCode=P&skr_destinationCardProductName=V
isa+Gold&skr_destinationCardSynonim=4878b27eaec2022c5a6a4e82d971a6271bf6fcd8_scn&sk
r_destinationCardType=Visa&skr_destinationCardCountryCode=616&skr_destinationCardBa
nkName=Norwegian+Visa-Bankgroup&skr_destinationCardPanmask=444444******4448
Пример ответа json формата при успешном сохранении номера карты:
{"storeCard":{"skr_destinationCardSynonim":"e651e9fd23d00efa97fc713682fcc7f86faeb846
_scn","skr_destinationCardPanmask":"471408*****1089"}}
Пример ответа json формата при неуспешном сохранении номера карты:
13
{"storeCard":{"reason":"cardinvalid"}}
Синоним номера карты, полученный в ответе от Оператора, Контрагент использует в запросах на
зачисление переводов (см. выше). Оператор по полученному синониму определяет номер карты
получателя.
3.2 Перевод на банковский счет
Идентификатор получателя перевода dstAccount="2570066962077". В параметрах запроса
Оператору Контрагент передает набор данных получателя: номер банковского счета, паспортные
данные.
Таблица 3.2.1 Параметры запроса
Имя поля paymentParams Тип
Описание
Реквизиты счета:
CustAccount
xs:long, 20 символов
Номер банковского счета
получателя.
BankName
xs:string, кириллические
Наименование банка.
символы
BankCity
xs:string, кириллические
Город отделения банка.
символы
BankBIK
xs:long, 9 символов
БИК банка.
BankCorAccount
xs:long, 20 символов
payment_purpose
xs:string, до 100 кириллических
символов
Подтверждение принятия оферты:
pof_offerAccepted
xs:int, 1 символ
Персональные данные плательщика:
pdr_lastName
xs:string, до 100 кириллических
или латинских символов
символов
pdr_firstName
xs:string, до 100 кириллических
или латинских символов
символов
pdr_middleName
xs:string, до 100 кириллических
или латинских символов
символов, необязательный
pdr_docNumber
xs:long, 10 символов
pdr_docIssueYear
xs:int, 4 символа
pdr_docIssueMonth
xs:int, 2 символа
pdr_docIssueDay
xs:int, 2 символа
pdr_address
xs:string, до 100 кириллических
символов
xs:string, до 20 символов
smsPhoneNumber
Корреспондентский счет
отделения банка.
Назначение платежа или иные
сведения для банка (может
быть пустым).
Флаг принятия оферты
пользователем (1 — принята).
Фамилия плательщика.
Имя плательщика.
Отчество плательщика.
Серия и номер паспорта
гражданина РФ (без пробелов).
Год выдачи паспорта в
формате ГГГГ
Месяц выдачи паспорта в
формате ММ
День выдачи паспорта в
формате ДД
Адрес регистрации
плательщика.
Номер телефона плательщика
международном формате
(79...).
14
Обратите внимание: впараметре payment_purpose Контрагент по своему усмотрению может
указать для банка любые дополнительные данные для зачисления перевода.
Пример запроса на зачисление перевода на банковский счет:
<?xml version="1.0" encoding="UTF-8"?>
<makeDepositionRequest agentId="200225"
clientOrderId="272517"
requestDT="2013-04-12T00:01:54.000Z"
dstAccount="2570066962077"
amount="249.00"
currency="643"
contract="">
<paymentParams>
<CustAccount>40817810255030943620</CustAccount>
<BankBIK>042809679</BankBIK>
<BankName>ОТДЕЛЕНИЕ 8607 СБЕРБАНКА РОССИИ</BankName>
<BankCity>ТВЕРЬ</BankCity>
<BankINN>7707083893</BankINN>
<BankCorAccount>30101810700000000679</BankCorAccount>
<pdr_firstName>Владимир</pdr_firstName>
<pdr_middleName>Владимирович</pdr_middleName>
<pdr_lastName>Владимиров</pdr_lastName>
<pof_offerAccepted>1</pof_offerAccepted>
<pdr_docType>21</pdr_docType>
<pdr_docNumber>4002109067</pdr_docNumber>
<pdr_docIssueYear>1999</pdr_docIssueYear>
<pdr_docIssueMonth>7</pdr_docIssueMonth>
<pdr_docIssueDay>30</pdr_docIssueDay>
<smsPhoneNumber>79653457676</smsPhoneNumber>
</paymentParams>
</makeDepositionRequest>
3.3 Перевод на счет мобильного телефона
Протокол позволяет Контрагенту направлять запросы на зачисления средств на счета абонентов
российских сотовых операторов МегаФон, Билайн, МТС, Теле2. Оператор определяется значением
dstAccount.
Таблица 3.3.1. Идентификаторы получателя
Тип счета получателя
Счет мобильного телефона абонента Мегафон
Счет мобильного телефона абонента Билайн
Счет мобильного телефона абонента МТС
Счет мобильного телефона абонента Tele2
Имя поля paymentParams Тип
Номер мобильного телефона получателя:
PROPERTY1
xs:string, 3 цифры
PROPERTY2
xs:string, 7 цифр
Подтверждение принятия оферты:
pof_offerAccepted
xs:int
dstAccount
2570066959438
2570066957329
2570066959750
25700583516540
Описание
Код оператора сотовой связи.
Номер телефона.
Флаг принятия оферты
пользователем (1 — принята).
Пример запроса на зачисление перевода на счет мобильного телефона:
15
<?xml version="1.0" encoding="UTF-8"?>
<makeDepositionRequest agentId="200225"
clientOrderId="272517"
requestDT="2013-04-12T00:01:54.000Z"
dstAccount="2570066957329"
amount="249.00"
currency="643"
contract="">
<paymentParams>
<pof_offerAccepted>1</pof_offerAccepted>
<PROPERTY1>905</PROPERTY1>
<PROPERTY2>2075556</PROPERTY2>
</paymentParams>
</makeDepositionRequest>
4. Справочники
4.1 Состояния обработки запроса (status)
Таблица 4.1.1. Коды состояний обработки запросов
Код
состояния
0
1
3
Описание
Успех. Обработка завершена. Запрос выполнен успешно.
В обработке. Запрос в процессе обработки. Возвращается, если истекло время
ожидания завершения обработки запроса. Требуется повторить запрос для
уточнения результата.
Отвергнут. Обработка завершена. Запрос обработан и отвергнут. При
выполнении запросов к серверу Оператора причина отказа передается в
параметре error.
4.2 Коды ошибок обработки запросов (error)
Таблица 4.2.1. Ошибки, возвращаемые при обработке запросов
Код
Описание ошибки
ошибки
Ошибки параметров запроса
10
Ошибка синтаксического разбора XML-документа. Синтаксис документа нарушен,
либо отсутствуют обязательные элементы XML.
11
Отсутствует или неверно задан идентификатор Контрагента (agentId).
12
Отсутствует или неверно задан идентификатор канала приема переводов
(subAgentId).
14
Отсутствует или неверно задана валюта (currency).
15
Отсутствует или неверно задано время формирования документа (requestDT).
16
Отсутствует или неверно задан идентификатор получателя средств (dstAccount).
17
Отсутствует или неверно задана сумма (amount).
18
Отсутствует или неверно задан номер транзакции (clientOrderId).
19
Отсутствует или неверно задано поле текст контракта (contract).
21
Запрашиваемая операция запрещена для данного типа подключения Контрагента.
26
Операция с таким номером транзакции (clientOrderId), но другими параметрами уже
выполнялась.
50
Невозможно открыть криптосообщение, ошибка целостности пакета.
51
АСП не подтверждена (данные подписи не совпадают с документом).
53
Запрос подписан неизвестным Оператору сертификатом.
55
Истек срок действия сертификата ИС Контрагента.
Ошибки обработки зачисления
40
Счет закрыт.
16
41
42
43
44
45
46
48
Счет в Яндекс.Деньгах заблокирован. Данная операция для счета запрещена.
Счета с таким идентификатором не существует.
Превышено ограничение на единовременно зачисляемую сумму.
Превышено ограничение на максимальную сумму зачислений за период времени.
Недостаточно средств для проведения операции.
Сумма операции слишком мала.
Ошибка запроса зачисления перевода на банковский счет, карту, мобильный
телефон.
201
Превышен лимит остатка на счете получателя.
Прочие ошибки
30
Технические проблемы на стороне Оператора. Рекомендуется повторять запрос с
разумным интервалом (см. рекомендации в разделе 1.3).
31
Получатель перевода отклонил платеж (под получателем понимается сотовый
оператор или процессинговый банк).
Общее описание лимитов по операциям: https://money.yandex.ru/doc.xml?id=527096
Информация о комиссиях: https://money.yandex.ru/doc.xml?id=524834
4.3 Типы данных
Таблица 4.3.1. Определения типов данных протокола
Тип
Описание
xs:int
32-bit целое знаковое число. Int32, определенный в стандарте:
http://www.w3.org/TR/xmlschema-2/#int.
64-bit целое знаковое число. Int64, определенный в стандарте:
http://www.w3.org/TR/xmlschema-2/#long.
Десятичное число с фиксированной точкой, определенное в
стандарте: http://www.w3.org/TR/xmlschema-2/#decimal.
Текстовая
строка,
определенная
в
стандарте:
http://www.w3.org/TR/xmlschema-2/#string.
Текстовая
строка,
определенная
в
стандарте:
http://www.w3.org/TR/xmlschema-2/#normalizedString.
Временная метка в формате согласно рекомендациям:
http://www.w3.org/TR/xmlschema-2/#dateTime
ISO8601:2004
Формат определяется как:
YYYY-MM-DDThh:mm:ss.fZZZZZ
Расшифровка формата:
xs:long
xs:decimal
xs:string
xs:normalizedString
xs:dateTime
YYYY
MM
DD
T
h
mm
ss
f
год, точно 4 цифры
месяц, точно 2 цифры (01=январь и т.д.)
день месяца, точно 2 цифры (от 01 до 31)
латинский символ «T», должен быть в верхнем регистре
часы, точно 2 цифры (24-часовой формат, от 00 до 24)
минуты, точно 2 цифры (от 00 до 59)
секунды, точно 2 цифры (от 00 до 59)
дробная часть секунды (от одной до 6 цифр),
может отсутствовать, в этом случае следует опускать и
разделитель «.»
17
ZZZZZ
xs:date
ClientTransactionNumber
описатель временной зоны, обязательный параметр,
может принимать значения:
Z – UTC, символ "Z" должен быть в верхнем
регистре;
+hh:mm или -hh:mm – смещение относительно UTC
(показывает, что указано локальное время,
которое на данное число часов и минут опережает
или отстает от UTC)
Примеры:
2011-07-24T19:00:00+04:00 – 19 часов 00 минут 24 июля 2011
года, часовой пояс – UTC + 4 часа;
2004-07-24T15:00:00Z – тот же момент времени в каноническом
представлении;
2004-07-24T15:00:00.666Z – тот же мидентиомент времени плюс 666
миллисекунд.
Дата
в
формате,
согласно
стандарту
http://www.w3.org/TR/xmlschema-2/#date.
Формат определяется как:
YYYY-MM-DD
Расшифровка формата:
YYYY
год, точно 4 цифры
MM
месяц, точно 2 цифры (01=январь и т.д.)
DD
день месяца, точно 2 цифры (от 01 до 31)
Пример:
2011-07-01 — 1 июля 2011 года.
Уникальный идентификатор операции. Должен быть уникальным
для Контрагента на протяжении всей истории операций. Значением
параметра должна быть строка длиной от 1 до 24 символов,
содержащая символы, принадлежащие множеству значений: 0-9 A-Z
a-z . , \ | / - + = # ~ ( ) { } [ ] : ; Рекомендуемые значения: целое
положительное линейно нарастающее число в десятичной системе
счисления.
<xs:simpleType name="ClientTransactionNumber">
<xs:restriction base="xs:normalizedString">
<xs:minLength value="1"/>
<xs:maxLength value="24"/>
<xs:pattern value="[0-9A-Za-z.,\\|/\+=#~(){}\[\]:;]+"/>
</xs:restriction>
</xs:simpleType>
YMAccount
Идентификатор получателя перевода, строка десятичных цифр
длиной до 33 символов.
<xs:simpleType name="YMAccount">
<xs:restriction base="xs:normalizedString">
<xs:maxLength value="33"/>
<xs:pattern value="[0-9]+"/>
</xs:restriction>
</xs:simpleType>
18
CurrencyAmount
Сумма. Положительное десятичное число с фиксированной точкой,
кол-во цифр после точки точно равно двум.
<xs:simpleType name="CurrencyAmount">
<xs:restriction base="xs:decimal">
<xs:minExclusive value="0"/>
<xs:maxInclusive value="9999999999999"/>
<xs:fractionDigits value="2"/>
</xs:restriction>
</xs:simpleType>
CurrencyCode
Код валюты. Возможные значения:
643 — рубль Российской Федерации;
10643 – рубли для тестовой среды Оператора
<xs:simpleType name="CurrencyCode">
<xs:restriction base="xs:int">
</xs:restriction>
</xs:simpleType>
