Таблица 1.3.1. Возможные HTTP-коды ответа
HTTP-код
|
Описание
|
200 OK
|
Запрос принят к обработке. Отправлен ответ в соответствии с настоящим протоколом. MIME-тип: application/pkcs7-mime.
|
400 Bad Request
|
Запрос не принят к обработке. Тело запроса испорчено, сервер не смог прочитать или разобрать запрос.
Возможные причины:
запрос невозможно разобрать;
неверный MIME-тип (Content-Type).
|
403 Forbidden
|
Сертификат Контрагента не зарегистрирован у Оператора, либо в настоящий момент шлюз отключен.
|
500 Internal Server Error
|
Технические проблемы Оператора. Обратитесь в службу поддержки.
|
501 Not Implemented
|
Запрос отправлен методом, отличным от POST.
|
Методы протокола
Зачисление переводов (makeDeposition).
Операция используется для того, чтобы инициировать зачисление перевода на счет Оператора.
Обратите внимание: Предварительно необходимо осуществлять проверку возможности зачисления перевода (операция testDeposition) до принятия средств от клиента. Запрос testDeposition позволяет проверить возможность зачисления указанной суммы получателю, в том числе корректность и существование идентификатора пользователя (номера счета или телефона), лимиты и отсутствие запретов на проведение операции. При приеме запроса testDeposition зачисление перевода не производится.
Шаблон адреса операций:
https://server:port/webservice/deposition/api/testDeposition
https://server:port/webservice/deposition/api/makeDeposition
Правила формирования и обработки запросов на зачисление переводов:
Каждое зачисление должно быть сформировано с уникальным значением идентификатора (clientOrderId).
Если на операцию «зачисление» получен ответ «Успех» (status=0), то перевод зачислен успешно.
Если запрос отправлен с уже ранее обработанным идентификатором (clientOrderId) и остальные параметры запроса, кроме requestDT, совпадают с предыдущей попыткой, то Оператор вернет результат обработки ранее отправленного запроса.
Если запрос отправлен с уже ранее обработанным идентификатором (clientOrderId) и какие-либо параметры, кроме requestDT, имеют отличные от первой попытки значения, то Оператор отвергает такой запрос и возвращает в ответе status=3, error=26.
Оператор обрабатывает полученный запрос немедленно. В случае если запрос невозможно обработать в течение нескольких секунд, возвращается ответ «в процессе обработки» (status=1). В этом случае результат операции неизвестен, и ИC следует повторить запрос с теми же данными для получения окончательного ответа. Рекомендуется следующий режим повтора: первый повтор через 1 минуту, следующие три с промежутком в 5 минут, далее не более одного раза в 30 минут. Аналогичный режим повтора рекомендуется в случае неполучения ответа от Оператора или получения ответа HTTP status 500.
При неполучении ответа от Оператора, а также при нечетком ответе (например: HTTP status 500) ИС Контрагента следует повторить запрос с теми же данными для получения окончательного ответа. Рекомендуется режим повтора как в предыдущем пункте.
Статус транзакции, находящейся в обработке (status=1), может измениться как на «успех» (status=0), так и на «отвергнут» (status=3).
Если перевод отвергнут Оператором, то в ответе возвращается status=3 и error= с кодом причины отказа. В некоторых случаях может присутствовать поле techMessage, содержащее дополнительную поясняющую информацию в виде текста произвольного формата. Этот текст предназначен для анализа техническими специалистами и не должен отображаться в каком-либо интерфейсе пользователя.
Если перевод отвергнут с ошибкой status=3 error=45, Контрагенту необходимо перечислить принятые переводы на расчетный счет Оператора, убедиться, что баланс увеличился (отправив запрос баланса), и провести переводы с НОВЫМИ идентификаторами операций (clientOrderId).
Ошибка status=3 error=21 означает, что запрашиваемая операция запрещена для данного Контрагента.
Формат запросов ИС
Таблица 2.1.1.1. Параметры запроса операций testDeposition, makeDeposition (все параметры обязательные, кроме отмеченных символом «*»)
Параметр
|
Тип
|
Описание
|
clientOrderId
|
ClientTransactionNumber
|
Идентификатор операции. Должен быть уникальным для Контрагента на протяжении всей истории операций. Рекомендуемые значения: целое положительное число в десятичной системе счисления.
|
requestDT
|
xs:dateTime
|
Дата и время формирования запроса операции на стороне ИС, по часам Контрагента.
|
dstAccount
|
YMAccount
|
Идентификатор получателя перевода.
В качестве идентификатора может использоваться:
счет пользователя в Яндекс.Деньгах (вида 4100175017397; длина существующих в Яндекс.Деньгах Счетов на данный момент варьируется от 11 до 16 цифр);
номер телефона пользователя, привязанный к Счету в Яндекс.Деньгах (допускаются номера российских операторов, рекомендуемое представление – 10-значные номера вида 9217575400, без дополнительных символов и пробелов);
код платежа в пользу 3-х лиц (номера, начинающиеся с «255», «256», «257»; список периодически расширяется). Ряд значений описан в разделе 3 «Зачисление переводов на банковский счет, карту, мобильный телефон».
|
amount
|
CurrencyAmount
|
Сумма перевода, например: 12.34
|
currency
|
CurrencyCode
|
Код валюты перевода. Возможные значения:
643 — рубль Российской Федерации;
10643 – рубли для тестовой среды Оператора.
|
agentId
|
xs:long
|
Идентификатор Контрагента. Выдается Оператором.
|
subAgentId (*)
|
xs:long
|
Уникальный идентификатор канала приема переводов. Указывается только в случае разделения переводов по нескольким каналам. Выдается Оператором.
|
contract
|
xs:normalizedString, до 128 символов
|
Основание для зачисления перевода.
|
serviceId (*)
|
xs:normalizedString, до 64 символов
|
Идентификатор сервиса. Выдается Оператором.
|
paymentParams (*)
|
xs:compexType
|
Элемент запроса для передачи дополнительных параметров перевода. Возможные значения представлены в разделе 3 «Зачисление переводов на банковский счет, карту, мобильный телефон».
|
Пример запроса проверки возможности зачисления:
clientOrderId="12345"
requestDT="2011-07-01T20:38:00.000Z"
dstAccount="410011234567"
amount="10.00"
currency="643"
contract="Выигрыш в игре Сфера"/>
Пример запроса на зачисление c указанием subAgentId и serviceId:
subAgentId="456"
clientOrderId="12345"
requestDT="2011-07-01T20:38:00.000Z"
dstAccount="410011234567"
amount="10.00"
currency="643"
contract="Выигрыш в игре Сфера">
456
Пример запроса на зачисление с указанием paymentParams:
clientOrderId="272517"
requestDT="2013-04-12T00:01:54.000Z"
dstAccount="2570066957329"
amount="249.00"
currency="643"
contract="">
1
905
2075556
79653457676
Формат ответов Оператора
Таблица 2.1.2.1. Параметры ответа операций testDeposition, makeDeposition
Параметр
|
Тип
|
Описание
|
status
|
xs:int
|
Результат выполнения операции. По значению этого поля ИС Контрагента должна принимать решение о состоянии запроса. См. табл. 4.1.1 «Коды состояний запроса».
|
error
|
xs:int
|
Код ошибки выполнения запроса (см. табл. 4.2.1). Является дополнительной расшифровкой к полю status. В случае успеха поле отсутствует.
|
clientOrderId
|
ClientTransactionNumber
|
Копия параметра clientOrderId запроса.
|
processedDT
|
xs:dateTime
|
Время обработки запроса по часам сервера Оператора. В случае успеха операции зачисления — фактическое время зачисления средств на счет.
|
balance
|
xs:decimal
|
Разница между суммой переводов, принятых Контрагентом в пользу Оператора, и суммой средств, перечисленных Контрагентом на расчетный счет Оператора. Может быть отрицательной. Данный параметр передается в ответе только на запрос makeDeposition и только если зачисление выполнено успешно.
|
techMessage
|
xs:string
|
Опциональное поле. Может содержать дополнительный поясняющий текст к отказам в приеме перевода. Этот текст содержит техническую информацию и не должен отображаться в каком-либо интерфейсе пользователя.
При выполнении перевода на банковский счет, карту, мобильный телефон причина отказа в приеме перевода содержится только в ответе на запрос makeDeposition.
|
identification
|
xs:string
|
Поле содержит информацию о статусе счета в системе Оператора. Может отсутствовать в ответе.
Возможные значения:
anonymous – не идентифицированный;
reviewed – упрощенно идентифицированный;
identified – идентифицированный.
Актуальная информация о статусах пользователей доступна по ссылке:
https://money.yandex.ru/doc.xml?id=526544
|
Пример ответа о возможности зачисления:
status="0"
processedDT="2011-07-01T20:38:01.000Z"/>
Пример ответа об успешном зачислении:
status="0"
processedDT="2011-07-01T20:38:01.000Z"
balance="1000.00"/>
Запрос баланса Контрагента (balance)
В ответе на запрос Оператор возвращает разницу между суммой переводов, принятых Контрагентом в пользу Оператора, и суммой средств, перечисленных Контрагентом на расчетный счет Оператора. Может быть отрицательной.
Шаблон адреса операций: https://server:port/webservice/deposition/api/balance
Формат запроса ИС
Таблица 2.2.1.1 Параметры запроса операции balance
Параметр
|
Тип
|
Описание
|
clientOrderId
|
ClientTransactionNumber
|
Идентификатор операции. Должен быть уникальным для Контрагента на протяжении всей истории операций. Рекомендуемые значения: целое положительное число в десятичной системе счисления.
|
requestDT
|
xs:dateTime
|
Дата и время формирования запроса операции на стороне ИС, по часам Контрагента.
|
agentId
|
xs:long
|
Идентификатор Контрагента. Выдается Оператором.
|
Пример запроса проверки баланса:
clientOrderId="12345"
requestDT="2011-07-01T20:38:00.000Z"/>
Формат ответа Оператора
Таблица 2.2.2.1 Параметры ответа операции balance
Параметр
|
Тип
|
Описание
|
status
|
xs:int
|
Результат выполнения операции. По значению этого поля ИС Контрагента должна принимать решение о состоянии запроса. См. табл. 4.1.1 «Коды состояний запроса».
|
error
|
xs:int
|
Код ошибки выполнения запроса (см. табл. 4.2.1). Является дополнительной расшифровкой к полю status. В случае успеха поле отсутствует.
|
clientOrderId
|
ClientTransactionNumber
|
Копия параметра clientOrderId запроса.
|
processedDT
|
xs:dateTime
|
Время обработки запроса по часам сервера Оператора.
|
balance
|
xs:decimal
|
Разница между суммой переводов, принятых Контрагентом в пользу Оператора, и суммой средств, перечисленных Контрагентом на расчетный счет Оператора. Может быть отрицательной.
|
Пример ответа о состоянии баланса:
status="0"
processedDT="2011-07-01T20:38:01.000Z"
balance="1000.00"/>
Уведомление Контрагента о неуспешном статусе перевода (errorDepositionNotification)
Данный запрос позволяет сообщить Контрагенту о неуспешном статусе (возврате) перевода на банковский счет, карту, мобильный телефон (см. раздел 3). Возврат осуществляется в случае:
для перевода на банковскую карту - банк-эмитент карты получателя отверг платеж;
для перевода на банковский счет - банк отверг платеж, необходимо проверить корректность реквизитов;
для перевода на мобильный телефон – оператор сотовой связи отверг платеж.
Правила формирования и обработки запросов о неуспешном статусе перевода:
Уведомление о неуспешном статусе перевода Оператор передает ИС Контрагента отдельным HTTP-запросом, содержащим криптопакет формата PKCS#7. На каждое уведомление ИС Контрагента отвечает сообщением о результате операции, помещенным в криптопакет PKCS#7. Правила формирования запроса и ответа определены в разделах 1.2 и 1.3. Оператор отправляет уведомление на указанный в технической анкете адрес (errorDepositionNotificationUrl).
ИС Контрагента должна отвечать на запросы Оператора в течение 10 секунд. Уведомление считается доставленным если ответ ИС Контрагента имеет статус «Успех» (status=0).
При длительном многократном отсутствии ответа Контрагента (либо при многократных технических ошибках) ИС Оператора будет повторять попытки доставки уведомления в течение суток: первый раз – через 2 минуты, потом через 4, 10 и далее, с увеличением интервала.
Уведомление содержит идентификатор операции (clientOrderId), полученный от ИС Контрагента в запросе на зачисление перевода (makeDeposition).
Формат запроса Оператора
Таблица 2.3.1.1 Параметры запроса операции errorDepositionNotification
Параметр
|
Тип
|
Описание
|
clientOrderId
|
ClientTransactionNumber
|
Идентификатор операции, полученный от ИС Контрагента в запросе на зачисление перевода (makeDeposition)
|
requestDT
|
xs:dateTime
|
Дата и время формирования запроса операции на стороне Оператора, по часам Оператора.
|
dstAccount
|
YMAccount
|
Идентификатор получателя перевода.
|
amount
|
CurrencyAmount
|
Сумма перевода, например: 12.34.
|
currency
|
CurrencyCode
|
Код валюты перевода. Возможные значения:
643 — рубль Российской Федерации;
10643 — рубли для тестовой среды Оператора.
|
error
|
xs:string
|
Код ошибки операции (см. табл. 4.2.1).
|
Пример запроса errorDepositionNotification:
requestDT="2011-07-01T20:38:00.000Z"
dstAccount="410011234567"
amount="10.00"
currency="643"
error="31"/>
Формат ответа ИС
Таблица 2.3.2.1 Параметры ответа операции errorDepositionNotification
Параметр
|
Тип
|
Описание
|
status
|
xs:int
|
Результат выполнения операции. По значению этого поля Оператор принимает решение о состоянии запроса. См. табл. 4.1.1 «Коды состояний запроса».
|
clientOrderId
|
ClientTransactionNumber
|
Копия параметра clientOrderId запроса.
|
processedDT
|
xs:dateTime
|
Время обработки запроса по часам ИС Контрагента.
|
Пример ответа на запрос errorDepositionNotification:
status="0"
processedDT="2011-07-01T20:38:01.000Z"/>
Зачисление переводов на банковский счет, карту, мобильный телефон
Помимо зачисления средств на счета Оператора возможно выполнение переводов на рублевый банковский счет, банковскую карту или счет мобильного телефона, в зависимости от значения параметра dstAccount. В параметрах paymentParams передаются данные, необходимые для зачисления на соответствующий счет. Среди них всегда обязательно передается согласие получателя с офертой Яндекс.Денег (pof_offerAccepted). Ссылку на оферту Контрагент должен разместить на своем сайте (URL указан в Договоре).
В запросах на зачисления на банковский счет или банковскую карту для соответствия требованиям российского законодательства обязательно передаются персональные данные плательщика.
Перевод на банковскую карту
Идентификатор получателя перевода 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_inn
|
xs:long, 12 символов, необязательный
|
Идентификационный номер налогоплательщика
|
pdr_snils
|
xs:long, 11 символов, необязательный
|
Страховой номер индивидуального лицевого счета (СНИЛС).
|
pdr_oms
|
xs:long, 11 символов, необязательный
|
Номер полиса обязательного медицинского страхования
|
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 кириллических символов
|
Город регистрации плательщика.
|
pdr_address
|
xs:string, до 100 кириллических символов
|
Адрес регистрации плательщика.
|
pdr_postcode
|
xs:long, 6 символов
|
Индекс плательщика.
|
Пример запроса для зачисления средств на банковскую карту:
clientOrderId="272517"
requestDT="2013-04-12T00:01:54.000Z"
dstAccount="25700130535186"
amount="249.00"
currency="643"
contract="">
b0af887ae9ad01fe01ca65df7cff19a7b5fcbf8b_scn
_firstName>Владимир
_firstName>
Владимирович
Владимиров
21
4002109067
194044
643
Санкт-Петербург
Большой пр, ПС, д.12
24.05.1987
Новосибирск
1999
7
30
ТП №20 по СПб и ЛО
1
79653457676
Обратите внимание: в случае возникновения ошибки при выполнении перевода на банковскую карту ответ Оператора может содержать следующий дополнительный поясняющий текст (techMessage):
notRegistrationRecord – Не хватает обязательных параметров (pdr_). Дополнительно указывается перечень недостающих полей.
Банк отклонил перевод денег на данную карту.
Банк отклонил операцию.
Превышен лимит операций.
Синоним номера банковской карты
Получение и хранение номера банковской карты подпадает под действие стандарта PCI DSS. Поэтому Оператор хранит данные банковских карт на своей стороне и предоставляет Контрагенту синонимы карт skr_destinationCardSynonim и их маски skr_destinationCardPanmask для отображения пользователю. Контрагент может хранить синонимы и маски карты на своей стороне без опасения утечки: их публикация не приводит к финансовым или имиджевым потерям.
Контрагент на своем сайте размещает форму ввода данных карты. После подтверждения ввода данные формы передаются по адресу https://paymentcard.yamoney.ru/gates/card/storeCard методом POST. Сервис обрабатывает полученные данные и при помощи метода GET перенаправит плательщика на адрес, указанный в skr_successUrl или skr_errorUrl. В случае успеха к адресу добавляются синоним и маска карты плательщика.
Таблица 3.1.1.1 Параметры запроса на получение синонима карты
Параметр
|
Тип
|
Описание
|
skr_destinationCardNumber
|
xs:string, до 25 символов
|
Номер банковской карты.
|
skr_responseFormat
|
xs:string, до 8 символов
|
Формат ответа на запрос. Возможные значения: redirect либо json. Если параметр не передан – по умолчанию используется redirect.
|
skr_errorUrl
|
xs:string, до 250 символов
|
Адрес редиректа при ошибке.
|
skr_successUrl
|
xs:string, до 250 символов
|
Адрес редиректа при успехе.
|
Пример кода страницы для сохранения номера карты на стороне Яндекс.Денег и получения ее синонима:
|
