Метод request-payment

Создание платежа, проверка параметров и возможности приема платежа магазином или перевода средств на счет пользователя ЮMoney.

Требуемые права токена:

для платежа в магазин: payment.to-pattern («шаблон платежа») или payment-shop.
для перевода средств на счета других пользователей: payment.to-account («идентификатор получателя», «тип идентификатора») или payment-p2p.

Запрос

Платеж в магазин

Параметры для платежа в магазин уточняются контрагентом при подключении через ЮKassa. Дополнительная информация о параметрах платежа описана в протоколе приема платежей для магазинов.

Параметр	Тип	Описание
pattern_id	string	Идентификатор шаблона платежа. Соответствует номеру витрины `scid` магазина.
`*`	string	Параметры шаблона платежа, требуемые магазином.

Перевод средств на счета других пользователей

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

Параметр	Тип	Описание
pattern_id	string	Фиксированное значение: `p2p`.
to	string	Идентификатор получателя перевода (номер счета, номер телефона или email).
amount	amount	Сумма к оплате (столько заплатит отправитель).
amount_due	amount	Сумма к получению (придет на счет получателя после оплаты).
comment	string	Комментарий к переводу, отображается в истории отправителя.
message	string	Комментарий к переводу, отображается получателю.
label	string	Метка платежа. Необязательный параметр.

Пример запроса при переводе средств на счет другого пользователя

POST /api/request-payment HTTP/1.1
Host: yoomoney.ru
Authorization: Bearer 410012345678901.0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123
Content-Type: application/x-www-form-urlencoded
Content-Length: 234

pattern_id=p2p&to=41001101140&amount=1000.00&message=%D0%9D%D0%B0%D0%B7%D0%B2%D0%B0%D0%BD%D0%B8%D0%B5%20%D0%BF%D0%BB%D0%B0%D1%82%D0%B5%D0%B6%D0%B0&comment=%D0%A1%D0%BE%D0%BE%D0%B1%D1%89%D0%B5%D0%BD%D0%B8%D0%B5%20%D0%BF%D0%BE%D0%BB%D1%83%D1%87%D0%B0%D1%82%D0%B5%D0%BB%D1%8E

Пример запроса при переводе средств на счет другого пользователя по номеру привязанного телефона

POST /api/request-payment HTTP/1.1
Host: yoomoney.ru
Authorization: Bearer 410012345678901.0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123
Content-Type: application/x-www-form-urlencoded
Content-Length: 256

pattern_id=p2p&to=79219990099&identifier_type=phone&amount=1000.00&message=%d0%97%d0%b0+%d0%b2%d0%ba%d1%83%d1%81%d0%bd%d1%8b%d0%b9+%d0%b1%d1%83%d0%b1%d0%bb%d0%b8%d0%ba&comment=%d0%ba%d1%83%d0%bf%d0%b8%d1%82%d0%b5+%d0%b1%d1%83%d0%b1%d0%bb%d0%b8%d0%ba%d0%b8!

Комиссия за перевод

Сумма перевода зачисляется получателю за вычетом комиссии за перевод. Отправитель перевода может указать только один из параметров:

amount — сумма, которую заплатит отправитель (с учетом комиссии сервиса);
amount_due — сумма к получению, которая будет зачислена на счет получателя.

После отправки request-payment можно показывать пользователю комиссию за платеж. В ответе на запрос придет contract_amount, для расчета комиссии подставьте его в формулу:

Комиссия = contract_amount - amount_due

Комиссия округляется математически до копеек (2 знака после запятой). Комиссия меньше копейки всегда округляется в большую сторону — до 1 копейки.

Метка платежа

Любому переводу можно присвоить метку платежа — label. Метка платежа — это некоторый идентификатор, присваиваемый приложением.

Впоследствии можно выбрать из истории переводы по указанной метке. Например, в качестве метки платежа можно указывать код или идентификатор некой сущности в приложении. Допустимо использовать значения длиной до 64 символов. Значение метки чувствительно к регистру символов.

Ответ

Метод возвращает следующие параметры:

Параметр	Тип	Описание
status	string	Код результата выполнения операции. Возможные значения: `success` — успешное выполнение; `refused` — отказ в проведении платежа, объяснение причины отказа содержится в поле `error`. Это конечное состояние платежа.
error	string	Код ошибки при проведении платежа (пояснение к полю `status`). Присутствует только при ошибках.
money_source	object	Доступные для приложения методы проведения платежа, см. Доступные методы платежа. Присутствует только при успешном выполнении метода.
request_id	string	Идентификатор запроса платежа. Присутствует только при успешном выполнении метода.
contract_amount	amount	Сумма к списанию со счета в валюте счета плательщика (столько заплатит пользователь вместе с комиссией). Присутствует при успешном выполнении метода или ошибке `not_enough_funds`.
balance	amount	Текущий баланс счета пользователя. Присутствует при выполнении следующих условий: метод выполнен успешно; токен авторизации обладает правом `account-info`.
recipient_account_status	string	Статус пользователя. Возможные значения: `anonymous` — анонимный счет; `named` — именной счет; `identified` — идентифицированный счет
recipient_account_type	string	Тип счета получателя. Параметр присутствует при успешном выполнении метода в случае перевода средств на счет в ЮMoney другого пользователя.
account_unblock_uri	string	Адрес, на который необходимо отправить пользователя для разблокировки счета. Поле присутствует в случае ошибки `account_blocked`.
ext_action_uri	string	Адрес, на который необходимо отправить пользователя для совершения необходимых действий в случае ошибки `ext_action_required`.

При выполнении запроса ЮMoney, как правило, связываются с сервером магазина, поэтому время ответа метода может составлять до 30 секунд. Во время работы метода request-payment приложение должно показывать пользователю сообщение о том, что приложение ожидает ответа от магазина.

Успешное выполнение метода request-payment не является гарантией успешного завершения процесса платежа, так как авторизация платежа выполняется при вызове метода process-payment.

Доступные методы платежа

Поле ответа money_source содержит список доступных методов для проведения данного платежа. Каждый метод содержит набор атрибутов.

Если для данного платежа невозможен ни один из нижеописанных методов, поле money_source будет пустым.

Возможные методы проведения платежа:

wallet — платеж со счета пользователя;
cards — платеж с банковских карт, привязанных к счету.

Атрибуты метода платежа со счета пользователя:

Атрибут	Тип	Описание
allowed	boolean	Признак того, что данный метод платежа разрешен пользователем.

Атрибуты метода платежа с банковской карты:

Атрибут	Тип	Описание
allowed	boolean	Признак того, что данный метод платежа разрешен пользователем.
csc_required	boolean	Признак необходимости требования CVV2/CVC2 кода для авторизации оплаты по банковской карте.
item	object	Описание банковской карты, привязанной к счету.

Параметры описания банковской карты:

Атрибут	Тип	Описание
id	string	Идентификатор привязанной к счету банковской карты. Его необходимо указать в методе `process-payment` для совершения платежа выбранной картой.
pan_fragment	string	Фрагмент номера банковской карты. Поле присутствует только для привязанной банковской карты. Может отсутствовать, если неизвестен.
type	string	Тип карты. Может отсутствовать, если неизвестен. Возможные значения: `Visa`; `MasterCard`; `American Express`; `JCB`.

Если метод платежа доступен для данного магазина и разрешен пользователем, то в ответе будет присутствовать и название метода, и признак разрешения пользователем. Например:

"wallet": {
  "allowed": true
},
"cards": {
  "allowed": true,
  "csc_required": true,
  "items": [
    {
      "id": "card-385244400",
      "pan_fragment": "5280****7918",
      "type": "MasterCard"
    },
    {
      "id": "card-385244401",
      "pan_fragment": "4008****7919",
      "type": "Visa"
    }
  ]
}

Если метод доступен, но не разрешен пользователем, то в ответе будет присутствовать название метода и признак отсутствия разрешения пользователя. Например:

"wallet": {
  "allowed": false
},
"cards": {
  "allowed": false
}

Приложение может запросить дополнительные права для осуществления платежей. Запрос дополнительных прав производится как повторная авторизация приложения пользователем.

Данные о получателе перевода

При запросе перевода на счет другого пользователя метод request-payment возвращает следующие поля:

Код	Описание
recipient_account_status	Статус пользователя. Возможные значения: `anonymous` — анонимный счет; `named` — именной счет; `identified` — идентифицированный счет.
recipient_account_type	Тип счета получателя. Возможные значения: `personal` — счет пользователя в ЮMoney; `professional` — профессиональный счет в ЮMoney.

Пример ответа при успешном выполнении

JSON
{
  "status": "success",
  "wallet": {
  "allowed": true
  },
  "cards": {
    "allowed": true,
    "csc_required": true,
    "items": [
      {
        "id": "card-385244400",
        "pan_fragment": "5280****7918",
        "type": "MasterCard"
      },
      {
        "id": "card-385244401",
        "pan_fragment": "4008****7919",
        "type": "Visa"
      }
    ]
  },
  "request_id": "1234567",
  "contract": "Оплата услуг ОАО Суперфон Поволжъе, номер +7-9xx-xxx-xx-xx, сумма 300.00 руб.",
  "balance": 1000.00
}

Коды ошибок

В случае ошибки выполнения операции возвращается ее код:

Код	Описание
illegal_params	Обязательные параметры платежа отсутствуют или имеют недопустимые значения.
illegal_param_label	Недопустимое значение параметра `label`.
illegal_param_to	Недопустимое значение параметра `to`.
illegal_param_amount	Недопустимое значение параметра `amount`.
illegal_param_amount_due	Недопустимое значение параметра `amount_due`.
illegal_param_comment	Недопустимое значение параметра `comment`.
illegal_param_message	Недопустимое значение параметра `message`.
not_enough_funds	На счете плательщика недостаточно средств. Необходимо пополнить счет и провести новый платеж.
payment_refused	Магазин отказал в приеме платежа (например, пользователь попробовал заплатить за товар, которого нет в магазине).
payee_not_found	Получатель перевода не найден. Указанный счет не существует или указан номер телефона/email, не связанный со счетом пользователя или получателя платежа.
authorization_reject	В авторизации платежа отказано. Возможные причины: транзакция с текущими параметрами запрещена для данного пользователя; пользователь не принял Соглашение об использовании сервиса ЮMoney.
limit_exceeded	Превышен один из лимитов на операции: на сумму операции для выданного токена авторизации; сумму операции за период времени для выданного токена авторизации; ограничения ЮMoney для различных видов операций.
account_blocked	Счет пользователя заблокирован. Для разблокировки счета необходимо отправить пользователя по адресу, указанному в поле `account_unblock_uri`.
account_closed	Счет пользователя закрыт.
ext_action_required	В настоящее время данный тип платежа не может быть проведен. Для получения возможности проведения таких платежей пользователю необходимо перейти на страницу по адресу `ext_action_uri` и следовать инструкции на данной странице. Это могут быть следующие действия: ввести идентификационные данные, принять оферту, выполнить иные действия согласно инструкции.
все прочие значения	Техническая ошибка, повторите вызов операции позднее.

Пример ответа при отказе

JSON
{
  "status": "refused",
  "error": "payment_refused",
  "error_description": "Абонент не существует"
}

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

Метод process-payment Права на выполнение операций