Зачисление переводов (makeDeposition)
Получатель перевода определяется значением параметра
dstAccount
. В параметрах
paymentParams
передаются данные, необходимые для зачисления соответствующим способом. Среди них передается согласие получателя с офертой ЮKassa (
pof_offerAccepted
). Вам необходимо разместить на своей стороне ссылку на оферту:
https://yoomoney.ru/pay/page?id=526623
 
Проверка возможности зачислений (testDeposition)
Перед тем, как отправлять деньги пользователю, необходимо проверять возможность зачисления перевода с помощью запроса
testDeposition
. Этот запрос позволяет проверить возможность перечисления указанной суммы нужному пользователю, в том числе:
  • корректность и существование идентификатора пользователя (номера счета или телефона);
  • лимиты;
  • отсутствие запретов на проведение операции.
При приеме запроса
testDeposition
зачисление перевода не производится.
 
Проверка паспортных данных получателя
В запросах зачисления на банковский счет или банковскую карту обязательно передаются персональные данные получателя. Перед зачислением сервис Ю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
 
Параметры запросов
ПараметрТипОписание
dstAccountYMAccount
Идентификатор получателя перевода. Зависит от того, куда вы отправляете перевод:
Обязательный параметр
clientOrderIdClientTransactionNumber
Идентификатор операции. Должен быть уникальным для контрагента на протяжении всей истории операций. Рекомендуемые значения: целое положительное число в десятичной системе счисления.
Обязательный параметр
requestDTxs:dateTime
Дата и время формирования запроса операции на стороне и по часам контрагента.
Обязательный параметр
amountCurrencyAmount
Сумма перевода, например:
12.34
Обязательный параметр
currencyCurrencyCode
Код валюты перевода. Возможное значение —
643
(российский рубль).
Обязательный параметр
agentIdxs:long
Идентификатор контрагента, выдается ЮKassa.
Обязательный параметр
contractxs:normalizedString,
до 128 символов
Основание для зачисления перевода.
Обязательный параметр
paymentParamsxs: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>
 
Ответ на запрос
 
Параметры ответа
ПараметрТипОписание
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
     — идентифицированный.
 
Примеры ответов
Ответ о возможности зачисления
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"/>
 
Правила формирования и обработки запросов
  1. Каждое зачисление должно быть сформировано с уникальным значением идентификатора (
    clientOrderId
    ).
  2. Если на операцию зачисления получен ответ Успех (
    status=0
    ), значит, перевод зачислен успешно. В некоторых случаях при успехе перевода сервис ЮKassa может вернуть в ответе поле
    error
    с дополнительным пояснением к статусу операции.
  3. Если запрос отправлен с уже ранее обработанным идентификатором (
    clientOrderId
    ) и значения обязательных параметров (
    clientOrderId
    ,
    dstAccount
    и 
    amount
    ) совпадают с предыдущей попыткой, то сервис ЮKassa вернет результат обработки ранее отправленного запроса.
  4. Если запрос отправлен с уже ранее обработанным идентификатором (
    clientOrderId
    ) и значения обязательных параметров (
    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 направил смс или электронное письмо получателю с описанием действий, необходимых для получения денег.
 
Что почитать еще
Перевод на кошелек ЮMoneyПеревод на банковскую картуПеревод на банковский счетПеревод на счет мобильного телефонаРеестры успешных и возвращенных выплат