API ЮKassa
Помощь
Подключить ЮKassa
Зачисление переводов (makeDeposition)
Для перевода денег получателям выплат нужно использовать запрос makeDeposition. Вы можете делать выплаты физическим лицам и самозанятым. Деньги можно переводить на кошельки ЮMoney, рублевые банковские счета, банковские карты и счета мобильных телефонов.
Особенности
Данные для зачисления переводов получателям выплат необходимо передавать в запросе makeDeposition. Что важно учесть:
Выплаты по виду или получателюОсобенности
Выплаты на кошельки
Выплаты на банковские карты или банковские счета
Выплаты на номера мобильных телефонов
Выплаты самозанятым
  • Вам нужно получить данные для регистрации чека в налоговой и разрешение формировать чеки от имени пользователя. Подробнее о выплатах самозанятым
  • Можно делать все виды выплат — на кошельки Ю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
Общие параметры запроса
Здесь описаны только общие параметры, которые есть в каждом запросе на зачисление перевода. Параметры, специфичные для конкретного вида или получателя выплаты, описаны в соответствующих статьях:
Описание общих параметров
ПараметрТипОписание
dstAccountYMAccount
Идентификатор получателя перевода. Зависит от того, куда вы отправляете перевод:
Обязательный параметр
clientOrderIdClientTransactionNumber
Идентификатор операции. Должен быть уникальным для вашей системы на протяжении всей истории операций. Рекомендуемые значения: целое положительное число в десятичной системе счисления.
Обязательный параметр
requestDTxs:dateTime
Дата и время формирования запроса операции на стороне и по часам вашей системы.
Обязательный параметр
amountCurrencyAmount
Сумма перевода, например: 12.34
Обязательный параметр
currencyCurrencyCode
Код валюты перевода. Возможное значение — 643 (российский рубль).
Обязательный параметр
agentIdxs:long
Идентификатор вашего шлюза. Выдается ЮKassa.
Обязательный параметр
contractxs: normalizedString,
до 128 символов
Основание для зачисления перевода. При выплатах самозанятым — описание услуги, оказанной получателем выплаты (для печати в чеке).
Обязательный параметр
paymentParamsxs: 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>
Формат ответа
Здесь описаны только общие параметры, которые есть в каждом ответе на зачисление перевода. При выплатах самозанятым в ответе дополнительно возвращаются параметры, связанные с регистрацией чека.
Параметры ответа
ПараметрТипОписание
statusxs:intРезультат выполнения операции. По значению этого поля вам необходимо принимать решение о состоянии запроса. См. Коды состояний запроса
errorxs:intКод ошибки выполнения запроса. Дополнительная расшифровка поля status.
clientOrderIdClientTransactionNumberЗначение параметра clientOrderId из запроса. Отсутствует в ответе, если не удалось разобрать запрос (коды ошибок 10, 50, 51, 53, 55) или если в запросе параметр clientOrderId отсутствует или неверно задан (error=18).
processedDTxs:dateTimeВремя обработки запроса по часам сервера ЮKassa. В случае успеха зачисления — фактическое время зачисления денег.
balancexs:decimal
Разница между суммой обеспечения, которую вы перечислили на баланс шлюза в ЮKassa, и суммой, которую ЮKassa перечислила получателям по вашим запросам.
techMessagexs:string
Может содержать дополнительный поясняющий текст к отказам в приеме перевода. Этот текст содержит техническую информацию и не должен отображаться в каком-либо интерфейсе пользователя.
Необязательный параметр
identificationxs:string
Поле содержит информацию о статусе кошелька ЮMoney. Присутствует только при зачислениях на кошелек ЮMoney.
Возможные значения:
  • anonymous — анонимный;
  • reviewed — именной;
  • identified — идентифицированный.
invoiceIdxs:string
Внутренний идентификатор выплаты в ЮKassa. Это технический параметр, при обработке ответа его следует проигнорировать. Значение параметра не должно отображаться в каком-либо интерфейсе пользователя.
Необязательный параметр
Пример ответа
Ответ об успешном зачислении (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 означает, что у вас нет прав для выполнения запрашиваемой операции.
Что почитать еще
Тестирование выплатУведомление о неуспешном переводеЗапрос балансаРеестры успешных и возвращенных выплатВыплаты с расчетного счета