Метод request-payment
Создание платежа, проверка параметров и возможности приема платежа магазином или перевода средств на счет пользователя ЮMoney.
  • для платежа в магазин:
    payment.to-pattern
    («шаблон платежа») или
    payment-shop
    .
  • для перевода средств на счета других пользователей:
    payment.to-account
    («идентификатор получателя», «тип идентификатора») или
    payment-p2p
    .
 
Запрос
 
Платеж в магазин
Параметры для платежа в магазин уточняются контрагентом при подключении через ЮKassa. Дополнительная информация о параметрах платежа описана в протоколе приема платежей для магазинов.
ПараметрТипОписание
pattern_idstringИдентификатор шаблона платежа. Соответствует номеру витрины
scid
магазина.
*stringПараметры шаблона платежа, требуемые магазином.
 
Перевод средств на счета других пользователей
Параметры запроса:
ПараметрТипОписание
pattern_idstringФиксированное значение:
p2p
.
tostringИдентификатор получателя перевода (номер счета, номер телефона или email).
amountamountСумма к оплате (столько заплатит отправитель).
amount_dueamountСумма к получению (придет на счет получателя счет после оплаты).
commentstringКомментарий к переводу, отображается в истории отправителя.
messagestringКомментарий к переводу, отображается получателю.
labelstringМетка платежа. Необязательный параметр.
codeprobooleanЗначение параметра
true
 — признак того, что перевод защищен кодом протекции. По умолчанию параметр отсутствует (обычный перевод).
expire_periodint
Число дней, в течении которых:
  • получатель перевода может ввести код протекции и получить перевод на свой счет,
  • получатель перевода до востребования может получить перевод.
Значение параметра должно находиться в интервале от 1 до 365. Необязательный параметр. По умолчанию
1
.
Пример запроса при переводе средств на счет другого пользователя
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 символов. Значение метки чувствительно к регистру символов.
 
Платеж за сотовую связь
Параметры запроса:
ПараметрТипОписание
pattern_idstringФиксированное значение:
phone-topup
phone-numberstring
Номер телефона в формате ITU-T E.164, полный номер, начиная с 
7
.
Поддерживаются номера только российских сотовых операторов. Пример:
79219990099
amountamountСумма платежа. С этой суммы может быть взята комиссия, размер комиссии зависит от оператора.
Номер телефона в формате ITU-T E.164 — это строка десятичных цифр, длиной до 15 символов включительно, представляющая собой полный международный номер телефона пользователя, без знака '+'. Например номер телефона
+7(921)999-00-99
будет записан как:
79219990099
Пример запроса при платеже за сотовую связь
POST /api/request-payment HTTP/1.1
Host: yoomoney.ru
Authorization: Bearer 410012345678901.0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123
Content-Type: application/x-www-form-urlencoded
Content-Length: 61

pattern_id=phone-topup&phone-number=79219990099&amount=300.00
 
Ответ
Метод возвращает следующие параметры:
ПараметрТипОписание
statusstring
Код результата выполнения операции. Возможные значения:
  • success
     — успешное выполнение;
  • refused
     — отказ в проведении платежа, объяснение причины отказа содержится в поле
    error
    . Это конечное состояние платежа.
errorstringКод ошибки при проведении платежа (пояснение к полю
status
). Присутствует только при ошибках.
money_sourceobjectДоступные для приложения методы проведения платежа, см. Доступные методы платежа. Присутствует только при успешном выполнении метода.
request_idstringИдентификатор запроса платежа. Присутствует только при успешном выполнении метода.
contract_amountamountСумма к списанию со счета в валюте счета плательщика (столько заплатит пользователь вместе с комиссией). Присутствует при успешном выполнении метода или ошибке
not_enough_funds
.
balanceamount
Текущий баланс счета пользователя. Присутствует при выполнении следующих условий:
  • метод выполнен успешно;
  • токен авторизации обладает правом
    account-info
    .
recipient_account_statusstring
Статус пользователя. Возможные значения:
  • anonymous
     — анонимный счет;
  • named
     — именной счет;
  • identified
     — идентифицированный счет
recipient_account_typestringТип счета получателя. Параметр присутствует при успешном выполнении метода в случае перевода средств на счет в ЮMoney другого пользователя.
protection_codestringКод протекции для данного перевода. Параметр присутствует, если был указан входной параметр
codepro=true
. Строка из 4-х десятичных цифр, может включать в себя ведущие нули. Параметр должен обрабатываться как строка.
account_unblock_uristringАдрес, на который необходимо отправить пользователя для разблокировки счета. Поле присутствует в случае ошибки
account_blocked
.
ext_action_uristringАдрес, на который необходимо отправить пользователя для совершения необходимых действий в случае ошибки
ext_action_required
.
При выполнении запроса ЮMoney, как правило, связываются с сервером магазина, поэтому время ответа метода может составлять до 30 секунд. Во время работы метода
request-payment
приложение должно показывать пользователю сообщение о том, что приложение ожидает ответа от магазина.
Успешное выполнение метода
request-payment
не является гарантией успешного завершения процесса платежа, так как авторизация платежа выполняется при вызове метода
process-payment
.
 
Доступные методы платежа
Поле ответа
money_source
содержит список доступных методов для проведения данного платежа. Каждый метод содержит набор атрибутов.
Если для данного платежа невозможен ни один из нижеописанных методов, поле
money_source
будет пустым.
Возможные методы проведения платежа:
  • wallet
     — платеж со счета пользователя;
  • cards
     — платеж с банковских карт, привязанных к счету.
Атрибуты метода платежа со счета пользователя:
АтрибутТипОписание
allowedbooleanПризнак того, что данный метод платежа разрешен пользователем.
Атрибуты метода платежа с банковской карты:
АтрибутТипОписание
allowedbooleanПризнак того, что данный метод платежа разрешен пользователем.
csc_requiredbooleanПризнак необходимости требования CVV2/CVC2 кода для авторизации оплаты по банковской карте.
itemobjectОписание банковской карты, привязанной к счету.
Параметры описания банковской карты:
АтрибутТипОписание
idstringИдентификатор привязанной к счету банковской карты. Его необходимо указать в методе
process-payment
для совершения платежа выбранной картой.
pan_fragmentstringФрагмент номера банковской карты. Поле присутствует только для привязанной банковской карты. Может отсутствовать, если неизвестен.
typestring
Тип карты. Может отсутствовать, если неизвестен. Возможные значения:
  • 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
.
illegal_param_expire_periodНедопустимое значение параметра
expire_period
.
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Права на выполнение операций