Метод request-payment

Описание

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

Требуемые права для платежа в магазин: payment.to-pattern («шаблон платежа») или payment-shop.

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

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

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

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

Входные параметры для перевода средств на счета других пользователей

Параметр Тип Описание
pattern_id string Фиксированное значение: p2p.
to string Идентификатор получателя перевода (номер счета, номер телефона или email).
amount amount Сумма к оплате (столько заплатит отправитель).
amount_due amount Сумма к получению (придет на счет получателя счет после оплаты).
comment string Комментарий к переводу, отображается в истории отправителя.
message string Комментарий к переводу, отображается получателю.
label string Метка платежа. Необязательный параметр.
codepro boolean Значение параметра true - признак того, что перевод защищен кодом протекции. По умолчанию параметр отсутствует (обычный перевод).
hold_for_pickup boolean Признак разрешения отправки перевода до востребования. Если параметр присутствует и имеет значение true, то это режим перевода до востребования.
expire_period int Число дней, в течении которых:
  • получатель перевода может ввести код протекции и получить перевод на свой счет,
  • получатель перевода до востребования может получить перевод.
Значение параметра должно находиться в интервале от 1 до 365. Необязательный параметр. По умолчанию 1.
Совет.

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

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

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

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

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

Совет.

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

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

Входные параметры для платежа за сотовую связь

Параметр Тип Описание
pattern_id string Фиксированное значение: phone-topup
phone-number string

Номер телефона в формате ITU-T E.164, полный номер, начиная с 7.

Поддерживаются номера только российских сотовых операторов. Пример: 79219990099

amount amount Сумма платежа. С этой суммы может быть взята комиссия, размер комиссии зависит от оператора.
Совет.

Номер телефона в формате ITU-T E.164 — это строка десятичных цифр, длиной до 15 символов включительно, представляющая собой полный международный номер телефона пользователя, без знака '+'. Например номер телефона +7(921)999-00-99 будет записан как: 79219990099

Тестовый платеж

Тестовый платеж позволяет проверить работу вашего приложения без совершения настоящих платежей.

В тестовом режиме можно провести любой вид платежа, для этого к параметрам метода необходимо добавить отладочные параметры:

Параметр Тип Описание
test_payment boolean Признак тестового платежа - значение поля true
test_card string Необязательное поле. Признак наличия тестовой банковской карты — значение поля available
test_result string

Желаемый результат работы тестового платежа, возможные значения:

  • success — успешное выполнение;
  • код ошибки из таблицы — метод возвратит указанный код ошибки;
  • иное значение — метод возвратит ошибку illegal_params
Совет.

Сервер Яндекс.Денег проверяет все параметры метода и может отвечать определённой ошибкой, если эти параметры некорректны, вне зависимости от значения параметра test_result.

Возвращает

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

Параметр Тип Описание
status string Код результата выполнения операции (см. таблицу).
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 Тип счета получателя. Параметр присутствует при успешном выполнении метода в случае перевода средств на счет в Яндекс.Деньгах другого пользователя.
protection_code string Код протекции для данного перевода. Параметр присутствует, если был указан входной параметр codepro=true. Строка из 4-х десятичных цифр, может включать в себя ведущие нули. Параметр должен обрабатываться как строка.
account_unblock_uri string Адрес, на который необходимо отправить пользователя для разблокировки счета. Поле присутствует в случае ошибки account_blocked.
ext_action_uri string Адрес, на который необходимо отправить пользователя для совершения необходимых действий в случае ошибки ext_action_required.

Код результата выполнения операции:

Код Описание
success Успешное выполнение.
refused Отказ в проведении платежа, объяснение причины отказа содержится в поле error. Это конечное состояние платежа.
hold_for_pickup Получатель перевода не найден, будет отправлен перевод до востребования. Успешное выполнение.

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

Код Описание
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 В авторизации платежа отказано. Возможные причины:
  • транзакция с текущими параметрами запрещена для данного пользователя;
  • пользователь не принял Соглашение об использовании сервиса Яндекс.Деньги.
limit_exceeded Превышен один из лимитов на операции:
  • на сумму операции для выданного токена авторизации;
  • сумму операции за период времени для выданного токена авторизации;
  • ограничений Яндекс.Денег для различных видов операций.
account_blocked Счет пользователя заблокирован. Для разблокировки счета необходимо отправить пользователя по адресу, указанному в поле account_unblock_uri.
ext_action_required

В настоящее время данный тип платежа не может быть проведен. Для получения возможности проведения таких платежей пользователю необходимо перейти на страницу по адресу ext_action_uri и следовать инструкции на данной странице. Это могут быть следующие действия:

  • ввести идентификационные данные,
  • принять оферту,
  • выполнить иные действия согласно инструкции.
все прочие значения Техническая ошибка, повторите вызов операции позднее.
Важно. При выполнении запроса Яндекс.Деньги, как правило, связываются с сервером магазина, поэтому время ответа метода может составлять до 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 — счет пользователя в Яндекс.Деньгах;
  • professional — профессиональный счет в Яндекс.Деньгах.

Примеры

Пример запроса при платеже за сотовую связь:

POST /api/request-payment HTTP/1.1
Host: money.yandex.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

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

POST /api/request-payment HTTP/1.1
Host: money.yandex.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: money.yandex.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!

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

{
  "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
}

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

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