Операция для отправки перевода на кошелек ЮMoney, на рублевый банковский счет, банковскую карту или счет мобильного телефона.
Получатель перевода определяется значением параметра
dstAccount
. В параметрах paymentParams
передаются данные, необходимые для зачисления соответствующим способом. Среди них передается согласие получателя с офертой ЮKassa (pof_offerAccepted
). Вам необходимо разместить на своей стороне ссылку на оферту:https://yoomoney.ru/pay/page?id=526623
Перед тем, как отправлять деньги пользователю, необходимо проверять возможность зачисления перевода с помощью запроса
testDeposition
. Этот запрос позволяет проверить возможность перечисления указанной суммы нужному пользователю, в том числе:- корректность и существование идентификатора пользователя (номера счета или телефона);
- лимиты;
- отсутствие запретов на проведение операции.
При приеме запроса
testDeposition
зачисление перевода не производится.В запросах зачисления на банковский счет или банковскую карту обязательно передаются персональные данные получателя. Перед зачислением сервис ЮKassa проверяет эти данные по базе действующих паспортов ГУВМ МВД (это требует законодательство РФ).
Если всё хорошо, сервис ЮKassa вернет
status=0
.Если данные не пройдут проверку, сервис ЮKassa вернет
status=3
, ошибку зачисления (error=48
) с пояснением ошибки и пришлет уведомление errorDepositionNotification.testDeposition
https://payouts.yookassa.ru:9094/webservice/deposition/api/testDeposition
makeDeposition
https://payouts.yookassa.ru:9094/webservice/deposition/api/makeDeposition
Параметр | Тип | Описание |
---|---|---|
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 | Элемент запроса для передачи дополнительных параметров перевода. Возможные значения описаны в разделах Выплаты на банковскую карту, Выплаты на банковский счет, Выплаты на счет мобильного телефона. Необязательный параметр |
Запрос проверки возможности зачисления
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>
Параметр | Тип | Описание |
---|---|---|
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 перечислили пользователям по запросам контрагента. Данный параметр передается в ответе только на запрос makeDeposition и только если зачисление выполнено успешно. |
techMessage | xs:string | Опциональное поле. Может содержать дополнительный поясняющий текст к отказам в приеме перевода. Этот текст содержит техническую информацию и не должен отображаться в каком-либо интерфейсе пользователя. При выполнении перевода на банковский счет, карту, мобильный телефон причина отказа в приеме перевода содержится только в ответе на запрос makeDeposition . |
identification | xs:string | Поле содержит информацию о статусе кошелька в сервисе ЮMoney. Присутствует только при зачислениях в кошелек ЮMoney. Возможные значения:
|
Ответ о возможности зачисления
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), значит, перевод зачислен успешно. В некоторых случаях при успехе перевода сервис ЮKassa может вернуть в ответе полеerrorс дополнительным пояснением к статусу операции.
- Если запрос отправлен с уже ранее обработанным идентификатором (clientOrderId) и значения обязательных параметров (clientOrderId,dstAccountиamount) совпадают с предыдущей попыткой, то сервис ЮKassa вернет результат обработки ранее отправленного запроса.
- Если запрос отправлен с уже ранее обработанным идентификатором (clientOrderId) и значения обязательных параметров (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означает, что запрашиваемая операция запрещена для данного контрагента.
- Ответ status=0 error=43означает, что перевод прошел успешно, баланс контрагента уменьшился на сумму перевода, при этом сервис ЮKassa направил смс или электронное письмо получателю с описанием действий, необходимых для получения денег.