Зачисление переводов на кошельки (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 символов

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

Идентификатор точки, в которой пользователь пополнил кошелек, — id объекта point, переданный в запросе addDepositionPoints при формировании списка точек пополнения.

Обязательный параметр при зачислении переводов банковскими платежными агентами
senderPhone

xs:string,

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

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

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

senderPhoneHash

xs:string,

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

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

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

paymentParams xs:complexType

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

Данные при пополнении кошелька банковской картой (передаются в paymentParams)

cardBin

xs:string,

6 цифр

BIN банковской карты плательщика.

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

panMask

xs:string,

11 символов

Маскированный номер банковской карты плательщика. Передается в виде последовательности из первых 6 цифр и последних 4 цифр с разделителем *. Например, 666666*4444

Необязательный параметр

cardProduct

xs:string,

до 4 символов

Тип банковской карты плательщика. Возможные значения зависят от конкретной платежной системы. Например, если у плательщика Дебетовая карта бизнес платежной системы Мир, необходимо передать значение MDB.

Необязательный параметр

Параметр

Тип

Описание

Обязательные параметры
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 символов

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

Идентификатор точки, в которой пользователь пополнил кошелек, — id объекта point, переданный в запросе addDepositionPoints при формировании списка точек пополнения.

Обязательный параметр при зачислении переводов банковскими платежными агентами
senderPhone

xs:string,

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

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

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

senderPhoneHash

xs:string,

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

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

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

paymentParams xs:complexType

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

Данные при пополнении кошелька банковской картой (передаются в paymentParams)

cardBin

xs:string,

6 цифр

BIN банковской карты плательщика.

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

panMask

xs:string,

11 символов

Маскированный номер банковской карты плательщика. Передается в виде последовательности из первых 6 цифр и последних 4 цифр с разделителем *. Например, 666666*4444

Необязательный параметр

cardProduct

xs:string,

до 4 символов

Тип банковской карты плательщика. Возможные значения зависят от конкретной платежной системы. Например, если у плательщика Дебетовая карта бизнес платежной системы Мир, необходимо передать значение MDB.

Необязательный параметр

Примеры запросов
Запрос проверки возможности зачисления
<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>
Запрос на зачисление с указанием cardBin в paymentParams
<makeDepositionRequest 
     agentId="321" 
     clientOrderId="123456" 
     requestDT="2019-11-19T09:41:14.925271+03:00" 
     dstAccount="410011234567" 
     amount="1.01" 
     currency="643" 
     contract="Зачисление на кошелек">
     <paymentParams>
         <cardBin>999999</cardBin>
         <panMask>999999*3456</panMask>
         <cardProduct>SAP</cardProduct>
     </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

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

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

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

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 означает, что перевод прошел успешно, баланс контрагента уменьшился на сумму перевода, при этом сервис Яндекс.Денег направил смс или электронное письмо получателю с описанием действий, необходимых для получения денег.
  12. Если в запросе на зачисление перевода с банковской карты вы передали cardBin, а сервис Яндекс.Денег отверг перевод с ошибкой status=3 error=49, это означает, что плательщик пытался пополнить баланс кошелька с корпоративной карты.

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

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

Коды ошибок

Типы данных

Зачисление переводов банковскими платежными агентами