Зачисление переводов (makeDeposition)

Операция для отправки перевода на кошелек в Яндекс.Деньгах, на рублевый банковский счет, банковскую карту или счет мобильного телефона.

Получатель перевода определяется значением параметра dstAccount. В параметрах paymentParams передаются данные, необходимые для зачисления соответсвующим способом. Среди них передается согласие получателя с офертой Яндекс.Денег (pof_offerAccepted). Вам необходимо разместить на своей стороне ссылку на оферту: https://money.yandex.ru/pay/doc.xml?offerid=default.

Note.

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

  • корректность и существование идентификатора пользователя (номера счета или телефона);
  • лимиты;
  • отсутствие запретов на проведение операции.

При приеме запроса testDeposition зачисление перевода не производится.

Проверка паспортных данных получателя

В запросах зачисления на банковский счет или банковскую карту обязательно передаются персональные данные получателя. Перед зачислением сервис Яндекс.Денег проверяет эти данные по базе действующих паспортов ГУМВ МВД (это требует законодательство РФ).

Проверка проводится сразу после запроса makeDepostion. Днем проверка занимает примерно 10 минут, ночью (с 1:00 до 6:00) — до 3 часов. Паспортные данные нужно проверить один раз, после этого запросы по этим данным будут проходить быстро.

  1. Сначала в ответ на запрос придет «в обработке» (status=1). Это значит, что Яндекс.Деньги проверяют данные.
  2. Через 10 минут можно отправить повторный запрос, чтобы узнать статус зачисления:
    1. в случае успеха в ответ вернется status=0;
    2. если выплата не пройдет, придет уведомление errorDepositionNotification.

Если данные не пройдут проверку, сервис Яндекс.Денег вернет ошибку зачисления (error=48) с пояснением ошибки.

Формат взаимодействия

Описан в Протоколе зачислений на кошельки. См. Формат взаимодействия

Адрес для отправки запросов
https://server:port/webservice/deposition/api/testDeposition
https://server:port/webservice/deposition/api/makeDeposition

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

Параметр

Тип

Описание

Обязательные параметры
dstAccountYMAccount

Идентификатор получателя перевода.

Зависит от того, куда вы отправляете перевод:

clientOrderIdClientTransactionNumber

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

requestDTxs:dateTime

Дата и время формирования запроса операции на стороне и по часам контрагента.

amountCurrencyAmount

Сумма перевода, например: 12.34

currencyCurrencyCode

Код валюты перевода. Возможные значения:

  • 643 — российский рубль;
  • 10643 - рубли в тестовой среде Яндекс.Денег.
agentIdxs:long

Идентификатор контрагента, выдается Яндекс.Деньгами.

contract

xs:normalizedString,

до 128 символов

Основание для зачисления перевода.
Необязательные параметры
paymentParamsxs:complexType

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

Параметр

Тип

Описание

Обязательные параметры
dstAccountYMAccount

Идентификатор получателя перевода.

Зависит от того, куда вы отправляете перевод:

clientOrderIdClientTransactionNumber

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

requestDTxs:dateTime

Дата и время формирования запроса операции на стороне и по часам контрагента.

amountCurrencyAmount

Сумма перевода, например: 12.34

currencyCurrencyCode

Код валюты перевода. Возможные значения:

  • 643 — российский рубль;
  • 10643 - рубли в тестовой среде Яндекс.Денег.
agentIdxs:long

Идентификатор контрагента, выдается Яндекс.Деньгами.

contract

xs:normalizedString,

до 128 символов

Основание для зачисления перевода.
Необязательные параметры
paymentParamsxs:complexType

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

Параметры ответа сервиса Яндекс.Денег

Параметр

Тип

Описание

statusxs:int

Результат выполнения операции. По значению этого поля на стороне контрагента необходимо принимать решение о состоянии запроса. См. Коды состояний запроса

errorxs:int

Код ошибки выполнения запроса. Дополнительная расшифровка поля status.

clientOrderIdClientTransactionNumber

Значение параметра clientOrderId запроса.

processedDTxs:dateTime

Время обработки запроса по часам сервера Яндекс.Денег. В случае успеха зачисления — фактическое время зачисления денег.

balancexs:decimal

Разница между суммой обеспечения, которую контрагент перечислил на счет шлюза в Яндекс.Деньгах, и суммой, которую Яндекс.Деньги перечислили пользователям по запросам контрагента. Данный параметр передается в ответе только на запрос makeDeposition и только если зачисление выполнено успешно.

techMessagexs:string

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

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

identificationxs:string

Поле содержит информацию о статусе кошелька в сервисе Яндекс.Денег. Присутствует только при зачислениях в кошелек на Яндексе.

Возможные значения:

  • anonymous — не идентифицированный;
  • reviewed — упрощенно идентифицированный;
  • identified — идентифицированный.

Подробнее о статусах пользователей

Параметр

Тип

Описание

statusxs:int

Результат выполнения операции. По значению этого поля на стороне контрагента необходимо принимать решение о состоянии запроса. См. Коды состояний запроса

errorxs:int

Код ошибки выполнения запроса. Дополнительная расшифровка поля status.

clientOrderIdClientTransactionNumber

Значение параметра clientOrderId запроса.

processedDTxs:dateTime

Время обработки запроса по часам сервера Яндекс.Денег. В случае успеха зачисления — фактическое время зачисления денег.

balancexs:decimal

Разница между суммой обеспечения, которую контрагент перечислил на счет шлюза в Яндекс.Деньгах, и суммой, которую Яндекс.Деньги перечислили пользователям по запросам контрагента. Данный параметр передается в ответе только на запрос makeDeposition и только если зачисление выполнено успешно.

techMessagexs:string

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

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

identificationxs:string

Поле содержит информацию о статусе кошелька в сервисе Яндекс.Денег. Присутствует только при зачислениях в кошелек на Яндексе.

Возможные значения:

  • anonymous — не идентифицированный;
  • reviewed — упрощенно идентифицированный;
  • identified — идентифицированный.

Подробнее о статусах пользователей

Примеры

Примеры запросов
Запрос проверки возможности зачисления
<testDepositionRequest agentId="123"
                         clientOrderId="12345"
                         requestDT="2011-07-01T20:38:00.000Z"
                         dstAccount="410011234567"
                         amount="10.00"
                         currency="643"
                         contract="Выигрыш в игре Сфера"/>
Запрос на зачисление с указанием paymentParams
<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>
Примеры ответов
Ответ о возможности зачисления
<testDepositionResponse clientOrderId="12345"
                          status="0"
                          processedDT="2011-07-01T20:38:01.000Z"/>
Ответ об успешном зачислении
<makeDepositionResponse clientOrderId="12345"
                          status="0"
                          processedDT="2011-07-01T20:38:01.000Z"
                          balance="1000.00"/>

Правила формирования и обработки запросов

  1. Каждое зачисление должно быть сформировано с уникальным значением идентификатора (clientOrderId).
  2. Если на операцию зачисления получен ответ Успех (status=0), значит, перевод зачислен успешно. В некоторых случаях при успехе перевода сервис Яндекс.Денег может вернуть в ответе поле error с дополнительным пояснением к статусу операции.
  3. Если запрос отправлен с уже ранее обработанным идентификатором (clientOrderId) и значения обязательных параметров (clientOrderId, dstAccount и amount) совпадают с предыдущей попыткой, то сервис Яндекс.Денег вернет результат обработки ранее отправленного запроса.
  4. Если запрос отправлен с уже ранее обработанным идентификатором (clientOrderId) и значения обязательных параметров (clientOrderId, dstAccount и amount) отличаются от предыдущей попытки, то сервис Яндекс.Денег отвергает такой запрос и возвращает в ответе status=3, error=26.
  5. Сервис Яндекс.Денег обрабатывает полученный запрос немедленно. В случае, если запрос невозможно обработать в течение нескольких секунд, возвращается ответ В обработке (status=1). В этом случае результат операции неизвестен, и магазину следует повторить запрос с теми же данными для получения окончательного ответа. Рекомендуется следующий режим повтора: первый повтор через 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 означает, что запрашиваемая операция запрещена для данного контрагента.
  11. Ответ status=0 error=43 означает, что перевод прошел успешно, баланс контрагента уменьшился на сумму перевода, при этом сервис Яндекс.Денег направил смс или электронное письмо получателю с описанием действий, необходимых для получения денег.

Смотрите также

Перевод на кошелек в Яндекс.Деньгах

Перевод на банковскую карту

Перевод на банковский счет

Перевод на счет мобильного телефона

Реестры принятых и возвращенных переводов