Сценарии приема платежей через Яндекс.Кассу
Существует два сценария приема платежей через Яндекс.Кассу в мобильных приложениях: с помощью платежных форм Яндекс.Кассы и с помощью API для приложений. Платежные формы проще интегрировать, они позволяют принимать платежи всеми способами, доступными по договору с Кассой. Но получать данные от Яндекс.Денег в этом случае можно только на сервере или по электронной почте. API позволяет принимать платежи только из кошелька пользователя и с произвольных банковских карт, но дает возможность обрабатывать информацию о платеже прямо в приложении.
Сценарии можно комбинировать.
Этот сценарий отличается простотой интеграции и большим количеством способов оплаты. Использование платежных форм Яндекс.Кассы в мобильном приложении состоит из нескольких шагов:
- Инициализация WebView с POST-параметрами в соответствии с платежной формой.
- Обработка HTTP-запросов по проверке заказа и уведомлении о переводе на стороне сервера (если подключение осуществляется по HTTP-схеме, способы подключения: HTTP-протокол или Модуль в CMS).
Обработка перенаправления со страницы информации о платеже по кнопке «Перейти на сайт магазина» (при этом закрывается WebView).
Вы можете включить автоматическое перенаправление пользователя со страниц успешного платежа и ошибки, через несколько секунд после оплаты. Узнать о том, как включить перенаправление, можно у менеджера Яндекс.Кассы.
Tip. Вы можете принимать платежи в мобильном приложении с помощью WebView, так же, как через платежную форму на сайте по протоколу приема платежей для магазинов. Логику передачи информации о платеже с серверного приложения до мобильного приложения вы можете реализовать самостоятельно, если это необходимо. Идентификатор успешной оплаты приходит в уведомлении о переводе.- Процесс платежа
Пользователь инициирует платеж (например, нажимает кнопку «Оплатить» в процессе заказа) и попадает на страницу с информацией о платеже.
Платеж с внешней (произвольной) банковской карты Платеж со счета После того, как пользователь нажал на кнопку «Оплатить», Яндекс.Деньги отправляют в магазин запрос на проверку заказа и присылают уведомление о переводе (если требуется). HTTP-запрос на проверку заказа проверяет корректность параметров платежа, уведомление о переводе сообщает магазину об успешной оплате. После оплаты пользователь попадает на страницу успеха или ошибки.
Платеж совершен успешно Платеж завершился с ошибкой
Интеграция с помощью API для приложений позволяет контролировать процесс платежа в приложении, получать статус платежа с сервера Яндекс.Денег, сохранять данные пользователя для следующих платежей. С помощью этого сценария можно принимать платежи двумя способами: из кошелька в Яндекс.Деньгах и с произвольной банковской карты.
Процесс интеграции зависит от способа оплаты.
В любом случае сначала необходимо зарегистрировать приложение в кошельке Яндекс.Денег (кошелек можно создать специально для регистрации).
Платежи из кошелька в Яндекс.Деньгах
Для оплаты этим способом пользователь должен авторизоваться на сайте Яндекс.Денег. Он может заплатить из кошелька и с привязанных к нему банковских карт. Для проведения платежа приложению необходимо:
- Пройти авторизацию на сервере Яндекс.Денег и получить access_token.
- Инициализировать оплату с помощью метода request-payment.
- Провести платеж с помощью метода process-payment и обработать уведомления checkOrder и paymentAviso, если магазин подключен к Кассе по HTTP-схеме.
Платежи с банковских карт
Для оплаты этим способом пользователю не нужно регистрироваться на сайте Яндекс.Денег. Он может заплатить с произвольной банковской карты. Для проведения платежа приложению необходимо:
- Получить идентификатор экземпляра приложения.
- Инициализировать оплату с помощью метода request-external-payment.
- Провести платеж с помощью метода process-external-payment и обработать уведомления checkOrder и paymentAviso, если магазин подключен к Кассе по HTTP-схеме.
Процесс платежа с банковской карты выглядит так же, как при оплате через платежную форму (см. выше).
Note.Параметры оплаты в методах request-payment и request-external-payment в целом совпадают с параметрами в платежных формах. Исключение: вам не нужно передавать shopId и paymentType, а в pattern_id необходимо передавать scid. Остальные параметры передаются так же, как при интеграции с платежной формой.
Note.Если вы уже подключили Яндекс.Кассу, то вам не нужно связываться с вашим менеджером и оформлять дополнительные документы. Вы можете использовать для интеграции API для приложений в частном порядке, как это написано во введении.
- SDK
Вы можете использовать программную реализацию API для приложений c помощью библиотек:
Во всех ветках есть ссылки на документацию.
Обязательные параметры | ||
receiver | string | Номер кошелька в Яндекс.Деньгах, на который нужно зачислять деньги отправителей. |
quickpay-form | string | Возможные значения:
|
targets | До 150 символов | Назначение платежа. |
paymentType | string | Способ оплаты. Возможные значения:
|
sum | CurrencyAmount | Сумма перевода (спишется с отправителя). |
Необязательные параметры | ||
formcomment | string До 50 символов | Название перевода в истории отправителя (для переводов из кошелька или с привязанной карты). Отображается в кошельке отправителя. Удобнее всего формировать его из названий магазина и товара. Например: Мой магазин: валенки белые |
short-dest | string | Название перевода на странице подтверждения. Рекомендуем делать его таким же, как formcomment. |
label | string До 64 символов | Метка, которую сайт или приложение присваивает конкретному переводу. Например, в качестве метки можно указывать код или идентификатор заказа. |
comment | string До 200 символов | Поле, в котором можно передать комментарий отправителя перевода. |
successURL | string, URL path | URL-адрес для редиректа после совершения перевода. |
need-fio | boolean | Нужны ФИО отправителя. |
need-email | boolean | Нужна электронная почты отправителя. |
need-phone | boolean | Нужен телефон отправителя. |
need-address | boolean | Нужен адрес отправителя. |
Обязательные параметры | |||
shopId | long | Идентификатор магазина, выдается при подключении к Яндекс.Кассе. | |
scid | long | Идентификатор витрины магазина, выдается при подключении к Яндекс.Кассе. | |
sum | CurrencyAmount | Сумма заказа. Note.Сумма заказа может не передаваться только в одном случае: при оплате наличными через терминалы, по коду платежа (paymentType=GP). Тогда код платежа становится многоразовым. При каждом платеже по этому коду магазину перечисляется сумма, внесенная пользователем в терминал. | |
customerNumber | normalizedString | 128 символов | Идентификатор плательщика в системе магазина. В качестве идентификатора может использоваться номер договора плательщика, логин плательщика и т. п. Допустимы повторные оплаты по одному и тому же идентификатору плательщика. Допустимые символы:
|
Необязательные параметры | |||
orderNumber | normalizedString | 64 символа | Уникальный номер заказа в системе магазина. Уникальность контролируется Яндекс.Кассой в сочетании с параметром shopId. Если платеж с таким номер заказа уже был успешно проведен или в процессе платежа возникла ошибка, то повторные попытки оплаты будут отвергнуты Яндекс.Кассой. |
shopArticleId | long | Идентификатор товара, выдается при подключении к Яндекс.Кассе. Применяется, если магазин использует несколько платежных форм для разных товаров. | |
shopSuccessURL | string, URL path | 250 символов | URL, на который будет вести ссылка Вернуться в магазин со страницы успешного платежа. В зависимости от настроек магазина: См. Параметры подключения |
shopFailURL | string, URL path | 250 символов | URL, на который будет вести ссылка Вернуться в магазин со страницы ошибки платежа. В зависимости от настроек магазина: См. Параметры подключения |
shopDefaultUrl | string, URL path | 250 символов | URL, на который будет вести ссылка Вернуться в магазин, когда процесс платежа на стороне Яндекс.Кассы завершен, но для завершения оплаты необходимы дополнительные действия пользователя. Страницы, на которых отображается эта ссылка: Если этот параметр задан, то на этот же URL будет вести ссылка Вернуться в магазин со страницы подтверждения оплаты. Если shopDefaultUrl не задан, эта ссылка ведет на Адрес сайта из настроек. |
cps_email | string | 100 символов | Адрес электронной почты плательщика. Если он передан, то соответствующее поле на странице подтверждения платежа будет предзаполнено (шаг 3 на схеме платежа). Допустимо передавать только адрес электронной почты (проверяется соответствие). Restriction.Этот параметр не передается в запросах checkOrder и paymentAviso. |
cps_phone | string | 15 символов, только цифры | Номер мобильного телефона плательщика. Если он передан, то соответствующее поле на странице подтверждения платежа будет предзаполнено (шаг 3 на схеме платежа). Restriction.Этот параметр не передается в запросах checkOrder и paymentAviso. |
paymentType | normalizedString | 5 символов | Способ оплаты. Рекомендуем передавать в этом поле пустое значение, в этом случае выбор способа оплаты будет происходить на стороне Яндекс.Кассы. Примеры: Полный список значений Restriction.Если в платежной форме указан способ оплаты, который не разрешен для магазина, плательщик не сможет совершить платеж. |
ym_merchant_receipt | string | Данные для формирования чека в формате JSON. Параметр передается и является обязательным, если вы настроили взаимодействие со своей онлайн-кассой через Яндекс.Кассу и передаете в платежной форме данные для формирования чека. | |
Дополнительные параметры для B2B-платежей (paymentType=2S) | |||
payment_purpose | string |
Виджет Яндекс.Кассы — Прием платежей по API Яндекс.Кассы
Виджет Яндекс.Кассы позволяет встроить на сайт готовую платежную форму. Пользователю будет доступно несколько способов оплаты: кошелек в Яндекс.Деньгах и привязанные к нему банковские карты, произвольная банковская карта, Apple Pay, Google Pay и Сбербанк Онлайн. С помощью виджета пользователь сможет сохранить в вашем магазине банковскую карту или кошелек в Яндекс.Деньгах для автоплатежей.
Платежная форма виджета Яндекс.Кассы
Платежная форма автоматически подстраивается под размеры устройства пользователя, проверяет вводимые данные и подсказывает пользователю, если что-то введено некорректно.
Чтобы принять платеж с помощью виджета, достаточно создать платеж по API Яндекс.Кассы, инициализировать виджет и отобразить форму на странице оплаты.
Для интеграции:
- Ознакомьтесь со сценарием проведения платежа в виджете.
- Настройте способы оплаты.
- Подготовьте страницу оплаты.
- Реализуйте проведение платежей.
- При необходимости реализуйте проведение автоплатежей.
- Настройте обработку ошибок инициализации виджета.
- Пользователь переходит к оплате.
- Вы отправляете Яндекс.Кассе запрос на создание платежа.
- Яндекс.Касса возвращает вам созданный объект платежа с токеном для инициализации виджета.
- Вы инициализируете виджет и отображаете форму на странице оплаты.
- Пользователь выбирает способ оплаты, вводит данные.
- При необходимости виджет перенаправляет пользователя на страницу подтверждения платежа (например, для аутентификации по 3-D Secure).
- Пользователь подтверждает платеж.
- Виджет перенаправляет пользователя на страницу завершения оплаты на вашей стороне.
- Вы отображаете нужную информацию, в зависимости от статуса платежа.
Готово!
Виджет поддерживает следующие способы оплаты:
- кошелек в Яндекс.Деньгах и привязанные к нему карты,
- произвольная банковская карта,
- Apple Pay,
- Google Pay,
- Сбербанк Онлайн.
Кошельком в Яндекс.Деньгах и с привязанных к нему карт может оплатить только пользователь, авторизованный на Яндексе.
По умолчанию доступна оплата кошельком в Яндекс.Деньгах и с привязанных карт. Уточните у менеджера Яндекс.Кассы, какие еще способы оплаты вам разрешены.
Чтобы в виджете работала оплата с помощью Apple Pay и Google Pay, ваш сайт должен использовать HTTPS и действующий TLS/SSL-сертификат (минимальная версия — TLS v1.2). Для подключения Apple Pay выполните дополнительные настройки.
Шаг 1. Сообщите вашему менеджеру Яндекс.Кассы адрес сайта, на котором будет размещаться виджет.
Шаг 2. Скачайте файл merchant.ru.yandex.kassa и разместите его на своем сайте по адресу:https://<домен вашего сайта>/.well-known/apple-developer-merchantid-domain-association
Путь к файлу должен быть строго таким — с точкой и дефисами. Точка в названии означает, что это скрытая папка.
Шаг 3. Чтобы оплата с помощью Apple Pay всегда была доступна в виджете, обновляйте TLS/SSL-сертификат не позднее, чем за 8 дней до окончания его срока действия.
Для приема платежей подготовьте страницу оплаты: подключите библиотеку и разместите виджет.
Шаг 1. Подключите скрипт из CDN. Библиотека будет доступна в глобальной области видимости под именемYandexCheckout
.Шаг 2. На страницу оплаты добавьте HTML-элемент, в котором хотите разместить форму. Задайте для данного элемента атрибутid
.Шаг 3. Для инициализации виджета создайте новый экземпляр классаYandexCheckout
и передайте в негоconfirmation_token
, который нужно получить в Яндекс.Кассе перед проведением платежа,return_url
, на который пользователь вернется после оплаты, и callback-функцию, которая будет принимать код ошибки. Шаг 4. Чтобы отобразить платежную форму, вызовите методrender
. Передайте в него значение атрибутаid
, в котором нужно разместить форму.
<script src="https://kassa.yandex.ru/checkout-ui/v2.js"></script>
<div></div>
<script>
const checkout = new window.YandexCheckout({
confirmation_token: 'confirmation-token',
return_url: 'https://merchant.site',
error_callback(error) {
}
});
checkout.render('payment-form');
</script>
Чтобы провести платеж:
- Создайте платеж в Яндекс.Кассе
- Инициализируйте виджет
- Завершите оплату
amount
с суммой платежа, объектconfirmation
с типомembedded
и, при необходимости, параметрdescription
с описанием транзакции, которое пользователь увидит при оплате. Также передайте параметрtrue
. Это значит, что вы получите деньги сразу после оплаты (при значенииfalse
нужная сумма заблокируется на счете пользователя, и после этого вы можете ее списать в удобное вам время).В запросе можно передать любые другие параметры, кромеpayment_method_data
,payment_method_id
,payment_token
,airline
.curl https://payment.yandex.net/api/v3/payments \
-X POST \
-u <Идентификатор магазина>:<Секретный ключ> \
-H 'Idempotence-Key: <Ключ идемпотентности>' \
-H 'Content-Type: application/json' \
-d '{
"amount": {
"value": "2.00",
"currency": "RUB"
},
"confirmation": {
"type": "embedded"
},
"capture": true,
"description": "Заказ №72"
}'
{
"id": "22d6d597-000f-5000-9000-145f6df21d6f",
"status": "pending",
"paid": false,
"amount": {
"value": "2.00",
"currency": "RUB"
},
"confirmation": {
"type": "embedded",
"confirmation_token": "ct-24301ae5-000f-5000-9000-13f5f1c2f8e0"
},
"created_at": "2018-07-10T14:25:27.535Z",
"description": "Заказ №72",
"metadata": {},
"recipient": {
"account_id": "100001",
"gateway_id": "1000001"
},
"refundable": false,
"test": false
}
Токен одноразовый, срок действия — 1 час. Если пользователь не оплатит в течение часа, виджет не инициализируется, токен нужно будет запрашивать заново. Если пользователь оплатит и вернется к форме, она отобразится с ошибкой.
Чтобы заново запросить токен, создайте платеж еще раз и инициализируйте виджет с новым токеном.Когда пользователь введет данные для оплаты и подтвердит платеж, Яндекс.Касса перенаправит его наreturn_url
, который вы передадите при инициализации виджета. Вам нужно самостоятельно узнать, как завершился платеж — успехом или неудачей — и отобразить пользователю нужную информацию.С помощью виджета Яндекс.Кассы вы можете сохранять способ оплаты, чтобы использовать его для автоплатежей, например, для ежемесячной оплаты подписки.По умолчанию автоплатежи работают только в тестовом магазине. Если хотите использовать их в вашем реальном магазине, напишите менеджеру Яндекс.Кассы.Сохранение способа оплаты позволяет привязать карту или кошелек в Яндекс.Деньгах к вашему магазину. С помощью виджета вы можете проводить платежи с безусловным или с условным сохранением способа.
- Вы на сайте предупреждаете пользователя, что сохраните его платежные данные, и рассказываете, как будете их использовать, например, с какой регулярностью вы будете списывать деньги и на какую сумму, как пользователь может отказаться от повторных списаний в вашем магазине. Вы на своей стороне получаете от пользователя согласие на проведение автоплатежей.
- Виджет отображает пользователю только два способа оплаты: произвольной банковской картой или из кошелька в Яндекс.Деньгах (если пользователь авторизован на Яндексе). Когда пользователь выберет способ оплаты, виджет ему сообщит, что способ оплаты будет привязан к вашему магазину. При успешной оплате данные карты или кошелька автоматически сохранятся в Яндекс.Кассе.
Пример использования: подписка на регулярные платежи.
Платеж с безусловным сохранением способа оплаты
- Вы на сайте рассказываете о возможности сохранить платежные данные, о том, как вы будете их использовать и как потом от этого отказаться.
- Виджет отображает пользователю все доступные способы оплаты. Если пользователь выберет произвольную карту или оплату из кошелька в Яндекс.Деньгах, виджет предложит ему сохранить данные для вашего магазина. Если пользователь согласится, при успешной оплате данные способа будут сохранены в Яндекс.Кассе, и вы сможете использовать идентификатор сохраненного способа оплаты для последующих платежей. Если не согласится, платеж пройдет без привязки данных к магазину.
Пример использования: привязка платежного средства к магазину для ускорения процесса оплаты при последующих платежах.
Платеж с условным сохранением способа оплаты
curl https://payment.yandex.net/api/v3/payments \
-X POST \
-u <Идентификатор магазина>:<Секретный ключ> \
-H 'Idempotence-Key: <Ключ идемпотентности>' \
-H 'Content-Type: application/json' \
-d '{
"amount": {
"value": "2.00",
"currency": "RUB"
},
"confirmation": {
"type": "embedded"
},
"capture": true,
"save_payment_method": true,
"description": "Заказ №72"
}'
Шаг 2. В ответе от Яндекс.Кассы получите confirmation_token — токен для инициализации виджета.{
"id": "25564507-000f-5000-9000-19878c91d156",
"status": "pending",
"paid": false,
"amount": {
"value": "2.00",
"currency": "RUB"
},
"confirmation": {
"type": "embedded",
"confirmation_token": "ct-25564507-000f-5000-9000-19878c91d156"
},
"created_at": "2019-11-07T14:59:19.351Z",
"description": "Заказ №72",
"metadata": {},
"recipient": {
"account_id": "100001",
"gateway_id": "1000001"
},
"refundable": false,
"test": false
}
Шаг 4. Далее проводите платеж как обычно.
Шаг 2. В ответе от Яндекс.Кассы получитеcurl https://payment.yandex.net/api/v3/payments \ -X POST \ -u <Идентификатор магазина>:<Секретный ключ> \ -H 'Idempotence-Key: <Ключ идемпотентности>' \ -H 'Content-Type: application/json' \ -d '{ "amount": { "value": "2.00", "currency": "RUB" }, "confirmation": { "type": "embedded" }, "capture": true, "description": "Заказ №72" }'
confirmation_token
— токен для инициализации виджета.{
"id": "25564507-000f-5000-9000-19878c91d156",
"status": "pending",
"paid": false,
"amount": {
"value": "2.00",
"currency": "RUB"
},
"confirmation": {
"type": "embedded",
"confirmation_token": "ct-2557c659-000f-5000-9000-12714806d854"
},
"created_at": "2019-11-07T14:59:19.351Z",
"description": "Заказ №72",
"metadata": {},
"recipient": {
"account_id": "100001",
"gateway_id": "1000001"
},
"refundable": false,
"test": false
}
Шаг 4. Далее проводите платеж как обычно.
Шаг 1. Дождитесь, когда пользователь подтвердит оплату, и платеж перейдет в статусsucceeded
(илиwaiting_for_capture
, если это платеж в две стадии). Чтобы узнать статус платежа, подождите, когда придет уведомление от Яндекс.Кассы, или периодически отправляйте запросы, чтобы получить информацию о платеже .Шаг 2. Убедитесь, что способ оплаты сохранен: в объекте платежа значениеpayment_method.saved
изменилось наtrue
.{
"id": "25564507-000f-5000-9000-19878c91d156",
"status": "succeeded",
"paid": true,
"amount": {
"value": "2.00",
"currency": "RUB"
},
"authorization_details": {
"rrn": "10000000000",
"auth_code": "000000"
},
"captured_at": "2018-07-18T17:20:50.825Z",
"created_at": "2018-07-18T17:18:39.345Z",
"description": "Заказ №72",
"metadata": {},
"payment_method": {
"type": "bank_card",
"id": "25564507-000f-5000-9000-19878c91d156",
"saved": true,
"card": {
"first6": "555555",
"last4": "4444",
"expiry_month": "07",
"expiry_year": "2022",
"card_type": "MasterCard",
"issuer_country": "RU",
"issuer_name": "Sberbank"
},
"title": "Bank card *4444"
},
"refundable": true,
"refunded_amount": {
"value": "0.00",
"currency": "RUB"
},
"recipient": {
"account_id": "100001",
"gateway_id": "1000001"
},
"test": false
}
Шаг 3. Сохраните идентификатор способа оплатыpayment_method.id
. Его нужно будет использовать в качестве идентификатора сохраненного способа оплаты при последующих платежах.Готово!
Теперь вы можете проводить автоплатежи. Проведение платежа сохраненным способом оплаты нужно реализовать самостоятельно.Вы можете проводить платежи без сохранения способа оплаты. Пользователь сможет оплатить любым доступным способом. Способ оплаты не сохранится.
Чтобы провести платеж без сохранения способа оплаты:
curl https://payment.yandex.net/api/v3/payments \
-X POST \
-u <Идентификатор магазина>:<Секретный ключ> \
-H 'Idempotence-Key: <Ключ идемпотентности>' \
-H 'Content-Type: application/json' \
-d '{
"amount": {
"value": "2.00",
"currency": "RUB"
},
"confirmation": {
"type": "embedded"
},
"capture": true,
"save_payment_method": false,
"description": "Заказ №72"
}'
Шаг 2. В ответе от Яндекс.Кассы получитеconfirmation_token
— токен для инициализации виджета.{
"id": "25564507-000f-5000-9000-19878c91d156",
"status": "pending",
"paid": false,
"amount": {
"value": "2.00",
"currency": "RUB"
},
"confirmation": {
"type": "embedded",
"confirmation_token": "ct-25564507-000f-5000-9000-19878c91d156"
},
"created_at": "2019-11-07T14:59:19.351Z",
"description": "Заказ №72",
"metadata": {},
"recipient": {
"account_id": "100001",
"gateway_id": "1000001"
},
"refundable": false,
"test": false
}
Шаг 4. Далее проводите платеж как обычно.
Если инициализация виджета закончилась неудачей, Яндекс.Касса передаст в callback-функцию код ошибки.
Быстрый стартПроведение платежейВходящие уведомленияАвтоплатежиPC | Яндекс.Деньги | Возможен, полный и частичный | 1 час |
AC | Банковская карта | Возможен, полный и частичный | 1 час |
MC | Баланс телефона | Возможен только полный возврат | 1 час |
GP | Наличные | Невозможен | Без ограничения |
EP | ЕРИП (Беларусь) | Невозможен | Без ограничения |
WM | WebMoney | Возможен, полный и частичный | 1 час |
SB | Сбербанк Онлайн | Возможен только полный возврат | 8 часов |
MP | Мобильный терминал (mPOS) | Возможен (деньги возвращаются плательщику на следующий день) | 1 час |
AB | Альфа-Клик | Возможен (деньги возвращаются плательщику на следующий день) | 8 часов |
MA | MasterPass | Возможен, полный и частичный | 1 час |
TB | Тинькофф | Возможен, полный и частичный | 1 час |
QW | QIWI Wallet | Возможен, полный и частичный | 1 час |
CR | Заплатить по частям | , полный и частичный | |
2S | Сбербанк Бизнес Онлайн (B2B-платежи) | Невозможен | 72 часа |