Зачисление переводов (makeDeposition) — Протокол зачислений на кошельки ЮMoney

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

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

Параметр	Тип	Описание
dstAccount	YMAccount	Идентификатор получателя перевода: номер кошелька, телефон или код платежа. Номер кошелька пользователя в ЮMoney, например `4100175017397`. Длина — от 11 до 20 цифр. Номер телефона, привязанный к кошельку ЮMoney (деньги зачисляются в этот кошелек). Допускаются мобильные номера российских и зарубежных операторов. Рекомендуемое представление — номер вида `79217575400`, от 11 до 15 цифр без дополнительных символов и пробелов. Если номер начинается с +, % или другого символа, он обрезается и используются только цифры. Код платежа формируется в сервисе ЮMoney. Формат: ряд цифр без пробелов, может начинаться с `255`, `256`, `257`. Длина — до 20 цифр. Обязательный параметр
clientOrderId	ClientTransactionNumber	Идентификатор операции. Должен быть уникальным для контрагента на протяжении всей истории операций. Рекомендуемые значения: целое положительное число в десятичной системе счисления. Обязательный параметр
requestDT	xs:dateTime	Дата и время формирования запроса операции на стороне и по часам контрагента. Обязательный параметр
amount	CurrencyAmount	Сумма перевода, например: `12.34` Подробнее про лимиты Обязательный параметр
currency	CurrencyCode	Код валюты перевода. Фиксированное значение: `643` — рубль Российской Федерации. Обязательный параметр
agentId	xs:long	Идентификатор контрагента. Выдается ЮMoney. Обязательный параметр
subAgentId	xs:long	Уникальный идентификатор канала приема переводов. Выдается ЮMoney. Обязательный параметр, если вы разделяете переводы по нескольким каналам
contract	xs:normalizedString, до 128 символов	Основание для зачисления перевода. Обязательный параметр
depositionPointId	xs:int	Только для банковских платежных агентов Идентификатор точки, в которой пользователь пополнил кошелек, — `id` объекта `point`, переданный в запросе `addDepositionPoints` при формировании списка точек пополнения. Обязательный параметр при зачислении переводов банковскими платежными агентами
senderPhone	xs:string, от 11 до 15 цифр без дополнительных символов и пробелов	Номер телефона плательщика. Допускаются мобильные номера российских и зарубежных операторов. Пример: `79217575400`. Используется для зачислений на анонимные кошельки. Подробности уточняйте у вашего менеджера ЮMoney. Необязательный параметр
senderPhoneHash	xs:string, SHA-256, 64 символа	Хэш номера телефона плательщика. Используется для зачислений на анонимные кошельки. Подробности уточняйте у вашего менеджера ЮMoney. Необязательный параметр
paymentParams	xs:complexType	Элемент запроса для передачи дополнительных параметров перевода. Необязательный параметр
Данные при пополнении кошелька банковской картой (передаются в `paymentParams`). Обязательность параметров указана в договоре или дополнительном соглашении с ЮMoney
cardBin	xs:string, 6 цифр	Используется при пополнении кошелька банковской картой. BIN банковской карты плательщика. Обязательный параметр, если это указано в договоре или дополнительном соглашении с ЮMoney
panMask	xs:string, 11 символов	Используется при пополнении кошелька банковской картой. Маскированный номер банковской карты плательщика. Передается в виде последовательности из первых 6 цифр и последних 4 цифр с разделителем ``. Например, `6666664444` Обязательный параметр, если это указано в договоре или дополнительном соглашении с ЮMoney
cardProduct	xs: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"
/>

Запрос на зачисление с указанием subAgentId

XML
<makeDepositionRequest
  agentId="123"
  subAgentId="456"
  clientOrderId="12345"
  requestDT="2019-09-10T10:48:15.060Z"
  dstAccount="410011234567"
  amount="100.00"
  currency="643"
  contract="Зачисление на кошелек"
/>

Ответ на запрос

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

Параметр	Тип	Описание
status	xs:int	Результат выполнения операции. По значению этого поля на стороне контрагента необходимо принимать решение о состоянии запроса. См. Коды состояний запроса
error	xs:int	Код ошибки выполнения запроса. Дополнительная расшифровка поля `status`.
clientOrderId	ClientTransactionNumber	Значение параметра `clientOrderId` из запроса. Отсутствует в ответе, если не удалось разобрать запрос (коды ошибок 10, 50, 51, 53, 55) или если в запросе параметр `clientOrderId` отсутствует или неверно задан (`error=18`).
processedDT	xs:dateTime	Время обработки запроса по часам сервера ЮMoney. В случае успеха зачисления — фактическое время зачисления денег.
balance	xs:decimal	Разница между суммой обеспечения, которую контрагент перечислил на счет шлюза в ЮMoney, и суммой, которую ЮMoney перечислили пользователям по запросам контрагента. Данный параметр передается в ответе только на запрос `makeDeposition` и только если зачисление выполнено успешно.
techMessage	xs:string	Опциональное поле. Может содержать дополнительный поясняющий текст к отказам в приеме перевода. Этот текст содержит техническую информацию и не должен отображаться в каком-либо интерфейсе пользователя.
identification	xs: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"
/>

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

Каждое зачисление должно быть сформировано с уникальным значением идентификатора (clientOrderId).
Если на операцию зачисления получен ответ Успех (status=0), значит, перевод зачислен успешно. В некоторых случаях при успехе перевода сервис ЮMoney может вернуть в ответе поле error с дополнительным пояснением к статусу операции.
Если запрос отправлен с уже ранее обработанным идентификатором (clientOrderId) и значения параметров dstAccount и amount совпадают с предыдущей попыткой, то сервис ЮMoney вернет результат обработки ранее отправленного запроса.
Если запрос отправлен с уже ранее обработанным идентификатором (clientOrderId) и значения параметров dstAccount и amount отличаются от предыдущей попытки, то сервис ЮMoney отвергает такой запрос и возвращает в ответе status=3, error=26.
Сервис ЮMoney обрабатывает полученный запрос немедленно. В случае, если запрос невозможно обработать в течение нескольких секунд, возвращается ответ В обработке (status=1). В этом случае результат операции неизвестен, и системе контрагента следует повторить запрос с теми же данными для получения окончательного ответа. Рекомендуется следующий режим повтора: первый повтор через 1 минуту, следующие три с промежутком в 5 минут, далее не более одного раза в 30 минут. Аналогичный режим повтора рекомендуется в случае, если ответ от сервиса ЮMoney не приходит или в ответе приходит HTTP status 500.
Если ответ от сервиса ЮMoney не получен или получен нечеткий ответ (например: HTTP status 500), системе контрагента следует повторить запрос с теми же данными для получения окончательного ответа. Рекомендуется режим повтора, как в предыдущем пункте.
Статус транзакции, находящейся в обработке (status=1), может измениться как на Успех (status=0), так и на Отвергнут (status=3).
Если перевод отвергнут сервисом ЮMoney, то в ответе возвращается status=3 и error с кодом причины отказа. В некоторых случаях может присутствовать поле techMessage, содержащее дополнительную информацию в виде текста произвольного формата. Этот текст предназначен для анализа техническими специалистами и не должен отображаться в каком-либо интерфейсе пользователя.
Если перевод отвергнут с ошибкой status=3 error=45, системе контрагента необходимо перечислить принятые переводы на расчетный счет ЮMoney, убедиться, что баланс увеличился (отправив запрос баланса), и провести переводы с новыми идентификаторами операций (clientOrderId).
Ответ status=3 error=21 означает, что запрашиваемая операция запрещена для данного контрагента.
Если в запросе на зачисление перевода с банковской карты вы передали cardBin, а сервис ЮMoney отверг перевод с ошибкой status=3 error=49, это означает, что плательщик пытался пополнить баланс кошелька с корпоративной карты.

Что почитать еще

Коды состояний запроса Коды ошибок Типы данных Зачисление переводов банковскими платежными агентами