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

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

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

status=0

Если данные не пройдут проверку, сервис ЮKassa вернет

status=3

, ошибку зачисления (

error=48

) с пояснением ошибки и пришлет уведомление errorDepositionNotification.

Запрос makeDeposition или testDeposition

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

testDeposition

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

makeDeposition

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

Параметры запросов

Параметр	Тип	Описание
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	Элемент запроса для передачи дополнительных параметров перевода. Возможные значения описаны в разделах Выплаты на банковскую карту, Выплаты на банковский счет, Выплаты на счет мобильного телефона. Необязательный параметр

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

Запрос проверки возможности зачисления

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. Возможные значения: anonymous — анонимный; reviewed — именной; identified — идентифицированный. Подробнее о статусах кошелька

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

Ответ о возможности зачисления

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 направил смс или электронное письмо получателю с описанием действий, необходимых для получения денег.

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

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

Проверка возможности зачислений (testDeposition)

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

Запрос makeDeposition или testDeposition

Ответ на запрос

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