Зачисление переводов (makeDeposition)
Для перевода денег получателям выплат нужно использовать запрос
makeDeposition
. Вы можете делать выплаты физическим лицам и самозанятым. Деньги можно переводить на кошельки ЮMoney, рублевые банковские счета, банковские карты и счета мобильных телефонов.
 
Особенности
Данные для зачисления переводов получателям выплат необходимо передавать в запросе makeDeposition. Что важно учесть:
Выплаты по виду или получателюОсобенности
Выплаты на кошельки
  • Перед выплатой рекомендуется проверить возможность зачисления перевода с помощью запроса testDeposition.
Выплаты на банковские карты или банковские счета
Выплаты на номера мобильных телефонов
Выплаты самозанятым
  • Вам нужно получить данные для регистрации чека в налоговой и разрешение формировать чеки от имени пользователя. Подробнее о выплатах самозанятым
  • Можно делать все виды выплат — на кошельки ЮMoney, номера мобильных телефонов, банковские карты и счета.
 
Согласие с офертой ЮKassa
Только для выплат на банковские счета, карты и номера мобильных телефонов
Если вы делаете выплаты на банковские карты, банковские счета и номера мобильных телефонов, вам необходимо получить от пользователя согласие с офертой ЮKassa. Для этого разместите на своей стороне ссылку на оферту и реализуйте получение от пользователя подтверждения, что он согласен с условиями.
Ссылка на оферту ЮKassa
https://yoomoney.ru/pay/page?id=526623
После получения согласия передавайте в запросе makeDeposition параметр
pof_offerAccepted
.
 
Проверка паспортных данных получателя
Только для выплат на банковские счета и карты
В запросах зачисления на банковский счет или банковскую карту обязательно передаются персональные данные получателя. Перед зачислением ЮKassa проверяет эти данные по базе действующих паспортов ГУВМ МВД (это требует законодательство РФ).
Если всё хорошо, ЮKassa вернет
status=0
.
Если данные не пройдут проверку, ЮKassa вернет
status=3
, ошибку зачисления (
error=48
) с пояснением ошибки и пришлет уведомление errorDepositionNotification.
 
Проверка возможности зачислений (testDeposition)
Только для выплат на кошельки ЮMoney
Если вы собираетесь сделать выплату на кошелек ЮMoney, перед тем как отправлять деньги пользователю, необходимо проверить возможность зачисления перевода с помощью запроса
testDeposition
. С помощью этого запроса вы проверите:
  • корректность и существование кошелька получателя выплаты;
  • лимиты;
  • отсутствие запретов на проведение операции.
В 
testDeposition
такой же набор параметров, как и в запросе
makeDeposition
для реального зачисления переводов. Отличаются только адреса для отправки запросов. При приеме запроса
testDeposition
перевод на кошелек не зачисляется.
 
Формат запроса
 
Адреса для отправки запросов
makeDeposition
https://payouts.yookassa.ru:9094/webservice/deposition/api/makeDeposition
testDeposition (проверка возможности зачисления при выплатах на кошельки ЮMoney)
https://payouts.yookassa.ru:9094/webservice/deposition/api/testDeposition
 
Общие параметры запроса
Здесь описаны только общие параметры, которые есть в каждом запросе на зачисление перевода. Параметры, специфичные для конкретного вида или получателя выплаты, описаны в соответствующих статьях:
Описание общих параметров
ПараметрТипОписание
dstAccountYMAccount
Идентификатор получателя перевода. Зависит от того, куда вы отправляете перевод:
Обязательный параметр
clientOrderIdClientTransactionNumber
Идентификатор операции. Должен быть уникальным для вашей системы на протяжении всей истории операций. Рекомендуемые значения: целое положительное число в десятичной системе счисления.
Обязательный параметр
requestDTxs:dateTime
Дата и время формирования запроса операции на стороне и по часам вашей системы.
Обязательный параметр
amountCurrencyAmount
Сумма перевода, например:
12.34
Обязательный параметр
currencyCurrencyCode
Код валюты перевода. Возможное значение —
643
(российский рубль).
Обязательный параметр
agentIdxs:long
Идентификатор вашего шлюза. Выдается ЮKassa.
Обязательный параметр
contractxs: normalizedString,
до 128 символов
Основание для зачисления перевода. При выплатах самозанятым — описание услуги, оказанной получателем выплаты (для печати в чеке).
Обязательный параметр
paymentParamsxs: complexType
Дополнительные данные для выплат. Возможные значения описаны в разделах Выплаты на банковскую карту, Выплаты на банковский счет и Выплаты самозанятым.
Необязательный параметр
 
Примеры запросов
Запрос проверки возможности зачисления (testDeposition)
XML
<testDepositionRequest agentId="123"
                         clientOrderId="12345"
                         requestDT="2011-07-01T20:38:00.000Z"
                         dstAccount="410011234567"
                         amount="10.00"
                         currency="643"
                         contract="Выигрыш в игре Сфера"/>
Запрос на зачисление с указанием 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>
 
Формат ответа
Здесь описаны только общие параметры, которые есть в каждом ответе на зачисление перевода. При выплатах самозанятым в ответе дополнительно возвращаются параметры, связанные с регистрацией чека.
 
Параметры ответа
ПараметрТипОписание
statusxs:intРезультат выполнения операции. По значению этого поля вам необходимо принимать решение о состоянии запроса. См. Коды состояний запроса
errorxs:intКод ошибки выполнения запроса. Дополнительная расшифровка поля
status
.
clientOrderIdClientTransactionNumberЗначение параметра
clientOrderId
из запроса. Отсутствует в ответе, если не удалось разобрать запрос (коды ошибок 
10
,
50
,
51
,
53
,
55
) или если в запросе параметр
clientOrderId
отсутствует или неверно задан (
error=18
).
processedDTxs:dateTimeВремя обработки запроса по часам сервера ЮKassa. В случае успеха зачисления — фактическое время зачисления денег.
balancexs:decimal
Разница между суммой обеспечения, которую вы перечислили на баланс шлюза в ЮKassa, и суммой, которую ЮKassa перечислила получателям по вашим запросам.
Данный параметр передается в ответе только на запрос
makeDeposition
и только если зачисление выполнено успешно.
techMessagexs:string
Опциональное поле. Может содержать дополнительный поясняющий текст к отказам в приеме перевода. Этот текст содержит техническую информацию и не должен отображаться в каком-либо интерфейсе пользователя.
При выполнении перевода на банковский счет, карту, мобильный телефон причина отказа в приеме перевода содержится только в ответе на запрос
makeDeposition
.
identificationxs:string
Поле содержит информацию о статусе кошелька ЮMoney. Присутствует только при зачислениях на кошелек ЮMoney.
Возможные значения:
  • anonymous
     — анонимный;
  • reviewed
     — именной;
  • identified
     — идентифицированный.
 
Примеры ответов
Ответ о возможности зачисления (testDeposition)
XML
<testDepositionResponse clientOrderId="12345"
                          status="0"
                          processedDT="2011-07-01T20:38:01.000Z"/>
Ответ об успешном зачислении (makeDeposition)
XML
<makeDepositionResponse clientOrderId="12345"
                          status="0"
                          processedDT="2011-07-01T20:38:01.000Z"
                          balance="1000.00"/>
 
Правила формирования и обработки запросов
  1. Каждое зачисление должно быть сформировано с уникальным значением идентификатора (
    clientOrderId
    ).
  2. Если на операцию зачисления получен ответ Успех (
    status=0
    ), значит перевод зачислен успешно. В некоторых случаях при успехе перевода ЮKassa может вернуть в ответе поле
    error
    с дополнительным пояснением к статусу операции.
  3. Если запрос отправлен с уже ранее обработанным идентификатором (
    clientOrderId
    ) и значения параметров
    dstAccount
    и 
    amount
    совпадают с предыдущей попыткой, то ЮKassa вернет результат обработки ранее отправленного запроса.
  4. Если запрос отправлен с уже ранее обработанным идентификатором (
    clientOrderId
    ) и значения параметров
    dstAccount
    и 
    amount
    отличаются от предыдущей попытки, то ЮKassa отвергает такой запрос и возвращает в ответе
    status=3
    ,
    error=26
    .
  5. ЮKassa обрабатывает полученный запрос немедленно. В случае, если запрос невозможно обработать в течение нескольких секунд, возвращается ответ В обработке (
    status=1
    ). В этом случае результат операции неизвестен, и вам следует повторить запрос с теми же данными для получения окончательного ответа. Рекомендуется следующий режим повтора: первый повтор через 1 минуту, следующие три с промежутком в 5 минут, далее не более одного раза в 30 минут. Аналогичный режим повтора рекомендуется в случае, если ответ от ЮKassa не приходит или в ответе приходит HTTP status 500.
  6. Если ответ от ЮKassa не получен или получен нечеткий ответ (например: HTTP status 500), вам следует повторить запрос с теми же данными для получения окончательного ответа. Рекомендуется режим повтора, как в предыдущем пункте.
  7. Статус транзакции, находящейся в обработке (
    status=1
    ), может измениться как на Успех (
    status=0
    ), так и на Отвергнут (
    status=3
    ).
  8. Если ЮKassa отвергла перевод, то в ответе возвращается
    status=3
    и 
    error
    с кодом причины отказа. В некоторых случаях может присутствовать поле
    techMessage
    , содержащее дополнительную информацию в виде текста произвольного формата. Этот текст предназначен для анализа техническими специалистами и не должен отображаться в каком-либо интерфейсе пользователя.
  9. Если перевод отвергнут с ошибкой
    status=3 error=45
    , вам необходимо перечислить принятые переводы на баланс шлюза ЮKassa, убедиться, что баланс увеличился (отправив запрос баланса), и провести переводы с новыми идентификаторами операций (
    clientOrderId
    ).
  10. Ответ
    status=3 error=21
    означает, что у вас нет прав для выполнения запрашиваемой операции.
  11. Ответ
    status=0 error=43
    означает, что перевод прошел успешно, баланс вашего шлюза уменьшился на сумму перевода, при этом ЮKassa направила смс или электронное письмо получателю с описанием действий, необходимых для получения денег.
 
Что почитать еще
Тестирование выплатУведомление о неуспешном переводеЗапрос балансаРеестры успешных и возвращенных выплат