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

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

Note.

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

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

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

Шаблон адреса операций
https://server:port/webservice/deposition/api/testDeposition
https://server:port/webservice/deposition/api/makeDeposition

Формат запросов

В запросах testDeposition и makeDeposition одинаковый набор параметров.

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

Параметр

Тип

Описание

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

Идентификатор получателя перевода: номер кошелька, телефон или код платежа.

Номер кошелька пользователя в Яндекс.Деньгах, например 4100175017397. Длина — от 11 до 16 цифр.

Номер телефона, привязанный к кошельку в Яндекс.Деньгах (деньги зачисляются в этот кошелек). Допускаются мобильные номера российских и зарубежных операторов. Рекомендуемое представление — номер вида 79217575400, от 11 до 15 цифр без дополнительных символов и пробелов. Если номер начинается с +, % или другого символа, он обрезается и используются только цифры.

Код платежа формируется в сервисе Яндекс.Денег. Формат: ряд цифр без пробелов, может начинаться с 255 , 256 , 257 , 50 , 51 .

clientOrderIdClientTransactionNumber

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

requestDTxs:dateTime

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

amountCurrencyAmount

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

currencyCurrencyCode

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

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

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

contract

xs:normalizedString,

до 128 символов

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

Элемент запроса для передачи дополнительных параметров перевода.

Параметр

Тип

Описание

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

Идентификатор получателя перевода: номер кошелька, телефон или код платежа.

Номер кошелька пользователя в Яндекс.Деньгах, например 4100175017397. Длина — от 11 до 16 цифр.

Номер телефона, привязанный к кошельку в Яндекс.Деньгах (деньги зачисляются в этот кошелек). Допускаются мобильные номера российских и зарубежных операторов. Рекомендуемое представление — номер вида 79217575400, от 11 до 15 цифр без дополнительных символов и пробелов. Если номер начинается с +, % или другого символа, он обрезается и используются только цифры.

Код платежа формируется в сервисе Яндекс.Денег. Формат: ряд цифр без пробелов, может начинаться с 255 , 256 , 257 , 50 , 51 .

clientOrderIdClientTransactionNumber

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

requestDTxs:dateTime

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

amountCurrencyAmount

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

currencyCurrencyCode

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

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

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

contract

xs:normalizedString,

до 128 символов

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

Элемент запроса для передачи дополнительных параметров перевода.

Примеры запросов
Запрос проверки возможности зачисления
<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>

Формат ответов Яндекс.Денег

В ответах на запросы testDeposition и makeDeposition одинаковый набор параметров.

Параметры ответа

Параметр

Тип

Описание

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 - идентифицированный.

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

Примеры ответов
Ответ о возможности зачисления
<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 означает, что перевод прошел успешно, баланс контрагента уменьшился на сумму перевода, при этом сервис Яндекс.Денег направил смс или электронное письмо получателю с описанием действий, необходимых для получения денег.

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

Коды состояний запроса

Коды ошибок

Типы данных