Зачисление переводов на кошельки (makeDeposition)
Операция используется для зачисления перевода на кошелек получателя в ЮMoney. Идентификатор получателя (например, номер кошелька) передается в параметре
dstAccount
. В параметрах
paymentParams
передаются данные, необходимые для зачисления на соответствующий кошелек.
 
Проверка возможности зачисления (testDeposition)
Перед тем, как отправлять деньги пользователю, необходимо проверять возможность зачисления перевода с помощью запроса
testDeposition
. Этот запрос позволяет проверить возможность перечисления указанной суммы нужному пользователю, в том числе:
  • корректность и существование идентификатора получателя (номера кошелька или телефона);
  • лимиты;
  • отсутствие запретов на проведение операции.
В запросах
testDeposition
и 
makeDeposition
одинаковый набор параметров. При приеме запроса
testDeposition
зачисление перевода не производится.
 
Лимиты зачислений
Лимит шлюза
У вашего платежного шлюза есть лимит на разовое зачисление и суточный лимит на максимальную сумму зачислений. Оба лимита индивидуальные — уточнить их размеры можно у вашего менеджера ЮMoney.
Если превышен лимит на разовое зачисление, сообщите пользователю, что ему нужно пополнить кошелек ЮMoney на меньшую сумму. Если превышен суточный лимит, повторите зачисление на следующий день: лимит сбрасывается раз в сутки.
Лимиты кошелька
Для кошельков есть лимиты на минимальный и максимальный размер зачисления и на общую сумму зачислений за месяц.
Минимальный размер зачисления — 1 рубль. Максимальный размер зачисления зависит от остатка в кошельке: после пополнения остаток не должен превышать определенную сумму:
  • для анонимного кошелька — 15 000 рублей;
  • для именного кошелька — 60 000 рублей;
  • для идентифицированного кошелька — 500 000 рублей.
Если превышен лимит на максимальный размер зачисления, сообщите пользователю, что ему нужно изменить статус кошелька или пополнить кошелек ЮMoney на меньшую сумму.
Общая сумма зачислений за месяц не может превышать 600 000 рублей для кошельков с любым статусом.
 
Зачисления на анонимные кошельки
Законодательство РФ накладывает ограничения на пополнение анонимных кошельков. Информацию о доступных способах зачисления переводов уточняйте у вашего менеджера ЮMoney.
Если кошелек анонимный и его нельзя пополнить выбранным способом, например, банковской картой или наличными, ЮMoney вернут ошибку (
error=57
) при попытке зачислить перевод.
 
Запрос makeDeposition или testDeposition
 
Адреса для отправки запросов
testDeposition
https://deposit.yoomoney.ru:9094/webservice/deposition/api/testDeposition
makeDeposition
https://deposit.yoomoney.ru:9094/webservice/deposition/api/makeDeposition
 
Параметры запросов
ПараметрТипОписание
dstAccountYMAccount
Идентификатор получателя перевода: номер кошелька, телефон или код платежа.
  • Номер кошелька пользователя в ЮMoney, например
    4100175017397
    . Длина — от 11 до 20 цифр.
  • Номер телефона, привязанный к кошельку ЮMoney (деньги зачисляются в этот кошелек). Допускаются мобильные номера российских и зарубежных операторов. Рекомендуемое представление — номер вида
    79217575400
    , от 11 до 15 цифр без дополнительных символов и пробелов. Если номер начинается с +, % или другого символа, он обрезается и используются только цифры.
  • Код платежа формируется в сервисе ЮMoney. Формат: ряд цифр без пробелов, может начинаться с 
    255
    ,
    256
    ,
    257
    . Длина — до 20 цифр.
Обязательный параметр
clientOrderIdClientTransactionNumber
Идентификатор операции. Должен быть уникальным для контрагента на протяжении всей истории операций. Рекомендуемые значения: целое положительное число в десятичной системе счисления.
Обязательный параметр
requestDTxs:dateTime
Дата и время формирования запроса операции на стороне и по часам контрагента.
Обязательный параметр
amountCurrencyAmount
Сумма перевода, например:
12.34
Обязательный параметр
currencyCurrencyCode
Код валюты перевода.
Фиксированное значение:
643
 — рубль Российской Федерации.
Обязательный параметр
agentIdxs:long
Идентификатор контрагента, выдается ЮMoney.
Обязательный параметр
contractxs:normalizedString,
до 128 символов
Основание для зачисления перевода.
Обязательный параметр
depositionPointIdxs:int
Идентификатор точки, в которой пользователь пополнил кошелек, —
id
объекта
point
, переданный в запросе
addDepositionPoints
при формировании списка точек пополнения.
Обязательный параметр при зачислении переводов банковскими платежными агентами
senderPhonexs:string,
от 11 до 15 цифр без дополнительных символов и пробелов
Номер телефона плательщика. Допускаются мобильные номера российских и зарубежных операторов. Пример:
79217575400
. Используется для зачислений на анонимные кошельки. Подробности уточняйте у вашего менеджера ЮMoney.
Необязательный параметр
senderPhoneHashxs:string,
SHA-256, 64 символа
Хэш номера телефона плательщика. Используется для зачислений на анонимные кошельки. Подробности уточняйте у вашего менеджера ЮMoney.
Необязательный параметр
paymentParamsxs:complexType
Элемент запроса для передачи дополнительных параметров перевода.
Необязательный параметр
Данные при пополнении кошелька банковской картой (передаются в 
paymentParams
). Обязательность параметров указана в договоре или дополнительном соглашении с ЮMoney
cardBinxs:string,
6 цифр
Используется при пополнении кошелька банковской картой. BIN банковской карты плательщика.
Обязательный параметр, если это указано в договоре или дополнительном соглашении с ЮMoney
panMaskxs:string,
11 символов
Используется при пополнении кошелька банковской картой. Маскированный номер банковской карты плательщика. Передается в виде последовательности из первых 6 цифр и последних 4 цифр с разделителем
*
. Например,
666666*4444
Обязательный параметр, если это указано в договоре или дополнительном соглашении с ЮMoney
cardProductxs:string,
до 4 символов
Используется при пополнении кошелька банковской картой. Тип банковской карты плательщика. Возможные значения зависят от конкретной платежной системы. Например, если у плательщика Дебетовая карта бизнес платежной системы Мир, необходимо передать значение
MDB
.
Обязательный параметр, если это указано в договоре или дополнительном соглашении с ЮMoney
 
Примеры запросов
Запрос проверки возможности зачисления
XML
<testDepositionRequest
    agentId="123"
    clientOrderId="12345"
    requestDT="2011-07-01T20:38:00.000Z"
    dstAccount="410011234567"
    amount="10.00"
    currency="643"
    contract="Зачисление на кошелек"
/>
Запрос на зачисление с указанием paymentParams
XML
<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
XML
<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
XML
<makeDepositionRequest
                    agentId="123"
                    clientOrderId="12345"
                    requestDT="2019-09-10T10:48:15.060Z"
                    dstAccount="410011234567"
                    amount="100.00"
                    currency="643"
                    contract="Зачисление на кошелек"
                    senderPhoneHash="0f3d61ebdfb23ced56b5e5aa5f5e7fccab63b059bc3e25638faa6ed9deba7c2f"
/>
 
Ответ на запрос
 
Параметры ответа
ПараметрТипОписание
statusxs:intРезультат выполнения операции. По значению этого поля на стороне контрагента необходимо принимать решение о состоянии запроса. См. Коды состояний запроса
errorxs:intКод ошибки выполнения запроса. Дополнительная расшифровка поля
status
.
clientOrderIdClientTransactionNumberЗначение параметра
clientOrderId
из запроса. Отсутствует в ответе, если не удалось разобрать запрос (коды ошибок 10, 50, 51, 53, 55) или если в запросе параметр
clientOrderId
отсутствует или неверно задан (error=18).
processedDTxs:dateTimeВремя обработки запроса по часам сервера ЮMoney. В случае успеха зачисления — фактическое время зачисления денег.
balancexs:decimal
Разница между суммой обеспечения, которую контрагент перечислил на счет шлюза в ЮMoney, и суммой, которую ЮMoney перечислили пользователям по запросам контрагента.
Данный параметр передается в ответе только на запрос
makeDeposition
и только если зачисление выполнено успешно.
techMessagexs:stringОпциональное поле. Может содержать дополнительный поясняющий текст к отказам в приеме перевода. Этот текст содержит техническую информацию и не должен отображаться в каком-либо интерфейсе пользователя.
identificationxs:string
Поле содержит информацию о статусе кошелька в сервисе ЮMoney.
Возможные значения:
  • anonymous
     — анонимный;
  • reviewed
     — именной;
  • identified
     — идентифицированный.
 
Примеры ответов
Ответ о возможности зачисления
XML
<testDepositionResponse clientOrderId="12345"
                          status="0"
                          processedDT="2011-07-01T20:38:01.000Z"/>
Ответ об успешном зачислении
XML
<makeDepositionResponse clientOrderId="12345"
                          status="0"
                          processedDT="2011-07-01T20:38:01.000Z"
                          balance="1000.00"/>
 
Правила формирования и обработки запросов
  1. Каждое зачисление должно быть сформировано с уникальным значением идентификатора (
    clientOrderId
    ).
  2. Если на операцию зачисления получен ответ Успех (
    status=0
    ), значит, перевод зачислен успешно. В некоторых случаях при успехе перевода сервис ЮMoney может вернуть в ответе поле
    error
    с дополнительным пояснением к статусу операции.
  3. Если запрос отправлен с уже ранее обработанным идентификатором (
    clientOrderId
    ) и значения параметров
    dstAccount
    и 
    amount
    совпадают с предыдущей попыткой, то сервис ЮMoney вернет результат обработки ранее отправленного запроса.
  4. Если запрос отправлен с уже ранее обработанным идентификатором (
    clientOrderId
    ) и значения параметров
    dstAccount
    и 
    amount
    отличаются от предыдущей попытки, то сервис ЮMoney отвергает такой запрос и возвращает в ответе
    status=3
    ,
    error=26
    .
  5. Сервис ЮMoney обрабатывает полученный запрос немедленно. В случае, если запрос невозможно обработать в течение нескольких секунд, возвращается ответ В обработке (
    status=1
    ). В этом случае результат операции неизвестен, и системе контрагента следует повторить запрос с теми же данными для получения окончательного ответа. Рекомендуется следующий режим повтора: первый повтор через 1 минуту, следующие три с промежутком в 5 минут, далее не более одного раза в 30 минут. Аналогичный режим повтора рекомендуется в случае, если ответ от сервиса ЮMoney не приходит или в ответе приходит HTTP status 500.
  6. Если ответ от сервиса ЮMoney не получен или получен нечеткий ответ (например: HTTP status 500), системе контрагента следует повторить запрос с теми же данными для получения окончательного ответа. Рекомендуется режим повтора, как в предыдущем пункте.
  7. Статус транзакции, находящейся в обработке (
    status=1
    ), может измениться как на Успех (
    status=0
    ), так и на Отвергнут (
    status=3
    ).
  8. Если перевод отвергнут сервисом ЮMoney, то в ответе возвращается
    status=3
    и 
    error
    с кодом причины отказа. В некоторых случаях может присутствовать поле
    techMessage
    , содержащее дополнительную информацию в виде текста произвольного формата. Этот текст предназначен для анализа техническими специалистами и не должен отображаться в каком-либо интерфейсе пользователя.
  9. Если перевод отвергнут с ошибкой
    status=3 error=45
    , системе контрагента необходимо перечислить принятые переводы на расчетный счет ЮMoney, убедиться, что баланс увеличился (отправив запрос баланса), и провести переводы с новыми идентификаторами операций (
    clientOrderId
    ).
  10. Ответ
    status=3 error=21
    означает, что запрашиваемая операция запрещена для данного контрагента.
  11. Ответ
    status=0 error=43
    означает, что перевод прошел успешно, баланс контрагента уменьшился на сумму перевода, при этом сервис ЮMoney направил смс или электронное письмо получателю с описанием действий, необходимых для получения денег.
  12. Если в запросе на зачисление перевода с банковской карты вы передали
    cardBin
    , а сервис ЮMoney отверг перевод с ошибкой
    status=3 error=49
    , это означает, что плательщик пытался пополнить баланс кошелька с корпоративной карты.
 
Что почитать еще
Коды состояний запросаКоды ошибокТипы данныхЗачисление переводов банковскими платежными агентами