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

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

Note.

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

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

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

Зачисления на анонимные кошельки

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

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

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

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

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

Параметр

Тип

Описание

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

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

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

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

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

clientOrderId ClientTransactionNumber

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

requestDT xs:dateTime

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

amount CurrencyAmount

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

currency CurrencyCode

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

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

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

contract

xs:normalizedString,

до 128 символов

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

xs:string,

от 11 до 15 цифр без дополнительных символов и пробелов

Номер телефона плательщика. Допускаются мобильные номера российских и зарубежных операторов. Пример: 79217575400.

Используется для зачислений на анонимные кошельки. Подробности уточняйте у вашего менеджера Яндекс.Денег.

senderPhoneHash

xs:string,

SHA-256, 64 символа

Хэш номера телефона плательщика.

Используется для зачислений на анонимные кошельки. Подробности уточняйте у вашего менеджера Яндекс.Денег.

paymentParams xs:complexType

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

Параметр

Тип

Описание

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

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

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

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

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

clientOrderId ClientTransactionNumber

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

requestDT xs:dateTime

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

amount CurrencyAmount

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

currency CurrencyCode

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

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

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

contract

xs:normalizedString,

до 128 символов

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

xs:string,

от 11 до 15 цифр без дополнительных символов и пробелов

Номер телефона плательщика. Допускаются мобильные номера российских и зарубежных операторов. Пример: 79217575400.

Используется для зачислений на анонимные кошельки. Подробности уточняйте у вашего менеджера Яндекс.Денег.

senderPhoneHash

xs:string,

SHA-256, 64 символа

Хэш номера телефона плательщика.

Используется для зачислений на анонимные кошельки. Подробности уточняйте у вашего менеджера Яндекс.Денег.

paymentParams xs: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>
Запрос на зачисление с senderPhoneHash
<makeDepositionRequest 
                    agentId="123"
                    clientOrderId="12345"
                    requestDT="2019-09-10T10:48:15.060Z"
                    dstAccount="410011234567"
                    amount="100.00"
                    currency="643"
                    contract="Зачисление на кошелек"
                    senderPhoneHash="0f3d61ebdfb23ced56b5e5aa5f5e7fccab63b059bc3e25638faa6ed9deba7c2f"
/>

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

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

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

Параметр

Тип

Описание

status xs:int

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

error xs:int

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

clientOrderId ClientTransactionNumber

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

processedDT xs:dateTime

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

balance xs:decimal

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

techMessage xs:string

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

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

identification xs:string

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

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

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

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

Параметр

Тип

Описание

status xs:int

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

error xs:int

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

clientOrderId ClientTransactionNumber

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

processedDT xs:dateTime

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

balance xs:decimal

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

techMessage xs:string

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

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

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

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

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

Коды ошибок

Типы данных