Зачисление переводов (makeDeposition) — [Архив] Выплаты через ЮKassa

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

Это старая версия API. Переходите на API ЮKassa.

Для перевода денег получателям выплат нужно использовать запрос makeDeposition. Вы можете делать выплаты физическим лицам и самозанятым. Деньги можно переводить на кошельки ЮMoney, рублевые банковские счета, банковские карты и счета мобильных телефонов.

Если вы проводите выплаты с расчетного счета, используйте инструкции из статьи Выплаты с расчетного счета.

Особенности

Данные для зачисления переводов получателям выплат необходимо передавать в запросе makeDeposition. Что важно учесть:

Выплаты по виду или получателю	Особенности
Выплаты на кошельки	—
Выплаты на банковские карты или банковские счета	Вам нужно получить согласие пользователя с офертой ЮKassa. Перед зачислением перевода ЮKassa дополнительно проверяет персональные данные пользователя, переданные в запросе. При выплатах на банковский счет банк может отказать в переводе. В этом случае ЮKassa вернет выплату и пришлет вам уведомление о неуспешном переводе.
Выплаты на номера мобильных телефонов	Вам нужно получить согласие пользователя с офертой ЮKassa. При выплате оператор мобильной связи может отказать в переводе. В этом случае ЮKassa вернет выплату и пришлет вам уведомление о неуспешном переводе.
Выплаты самозанятым	Вам нужно получить данные для регистрации чека в налоговой и разрешение формировать чеки от имени пользователя. Подробнее о выплатах самозанятым Можно делать все виды выплат — на кошельки ЮMoney, номера мобильных телефонов, банковские карты и счета.

Согласие с офертой ЮKassa

Только для выплат на банковские счета, карты и номера мобильных телефонов

Если вы делаете выплаты на банковские карты, банковские счета и номера мобильных телефонов, вам необходимо получить от пользователя согласие с офертой ЮKassa. Для этого разместите на своей стороне ссылку на оферту и реализуйте получение от пользователя подтверждения, что он согласен с условиями.

Ссылка на оферту ЮKassa

https://yoomoney.ru/pay/page?id=526623

После получения согласия передавайте в запросе makeDeposition параметр pof_offerAccepted.

Проверка паспортных данных получателя

Только для выплат на банковские счета и карты

В запросах зачисления на банковский счет или банковскую карту обязательно передаются персональные данные получателя. Перед зачислением ЮKassa проверяет эти данные по базе действующих паспортов ГУВМ МВД (это требует законодательство РФ).

Если всё хорошо, ЮKassa вернет status=0.

Если данные не пройдут проверку, ЮKassa вернет status=3, ошибку зачисления (error=48) с пояснением ошибки.

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

Адрес для отправки запросов

https://payouts.yookassa.ru:9094/webservice/deposition/api/makeDeposition

Общие параметры запроса

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

Выплаты на кошельки ЮMoney
Выплаты на банковскую карту
Выплаты на банковский счет
Выплаты на баланс мобильного телефона
Выплаты самозанятым (для всех способов получения выплат)

Описание общих параметров

Параметр	Тип	Описание
dstAccount	YMAccount	Идентификатор получателя перевода. Зависит от того, куда вы отправляете перевод: на кошелек ЮMoney; банковскую карту; банковский счет; баланс мобильного телефона. Обязательный параметр
clientOrderId	ClientTransactionNumber	Идентификатор операции. Должен быть уникальным для вашей системы на протяжении всей истории операций. Рекомендуемые значения: целое положительное число в десятичной системе счисления. Обязательный параметр
requestDT	xs:dateTime	Дата и время формирования запроса операции на стороне и по часам вашей системы. Обязательный параметр
amount	CurrencyAmount	Сумма перевода, например: `12.34` Обязательный параметр
currency	CurrencyCode	Код валюты перевода. Возможное значение — `643` (российский рубль). Обязательный параметр
agentId	xs:long	Идентификатор вашего шлюза. Выдается ЮKassa. Обязательный параметр
contract	xs: normalizedString, до 128 символов	Основание для зачисления перевода. При выплатах самозанятым — описание услуги, оказанной получателем выплаты (для печати в чеке). Обязательный параметр
paymentParams	xs: complexType	Дополнительные данные для выплат. Возможные значения описаны в разделах Выплаты на банковскую карту, Выплаты на банковский счет и Выплаты самозанятым. Необязательный параметр

Пример запроса

Запрос на зачисление с указанием paymentParams (makeDeposition)

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>

Формат ответа

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

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

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

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

Ответ об успешном зачислении (makeDeposition)

XML
<makeDepositionResponse clientOrderId="12345"
                          status="0"
                          processedDT="2011-07-01T20:38:01.000Z"
                          balance="1000.00"/>

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

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

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

Тестирование выплат Уведомление о неуспешном переводе Запрос баланса Реестры успешных и возвращенных выплат Выплаты с расчетного счета