Для перевода денег получателям выплат нужно использовать запрос
makeDeposition
. Вы можете делать выплаты физическим лицам и самозанятым. Деньги можно переводить на кошельки ЮMoney, рублевые банковские счета, банковские карты и счета мобильных телефонов.Данные для зачисления переводов получателям выплат необходимо передавать в запросе makeDeposition. Что важно учесть:
Выплаты по виду или получателю | Особенности |
---|---|
Выплаты на кошельки | — |
Выплаты на банковские карты или банковские счета |
|
Выплаты на номера мобильных телефонов |
|
Выплаты самозанятым |
|
Если вы делаете выплаты на банковские карты, банковские счета и номера мобильных телефонов, вам необходимо получить от пользователя согласие с офертой Ю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 | Идентификатор получателя перевода. Зависит от того, куда вы отправляете перевод: Обязательный параметр |
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)
<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. Возможные значения:
|
invoiceId | xs:string | Внутренний идентификатор выплаты в ЮKassa. Это технический параметр, при обработке ответа его следует проигнорировать. Значение параметра не должно отображаться в каком-либо интерфейсе пользователя. Необязательный параметр |
Ответ об успешном зачислении (makeDeposition)
<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
означает, что у вас нет прав для выполнения запрашиваемой операции.