Виджет Яндекс.Кассы
Виджет Яндекс.Кассы позволяет встроить на сайт готовую платежную форму. Пользователю будет доступно несколько способов оплаты: кошелек в Яндекс.Деньгах и привязанные к нему банковские карты, произвольная банковская карта, Apple Pay, Google Pay и Сбербанк Онлайн. С помощью виджета пользователь сможет сохранить в вашем магазине банковскую карту или кошелек в Яндекс.Деньгах для автоплатежей.
Платежная форма виджета Яндекс.Кассы
Платежная форма автоматически подстраивается под размеры устройства пользователя, проверяет вводимые данные и подсказывает пользователю, если что-то введено некорректно.
Чтобы принять платеж с помощью виджета, достаточно создать платеж по API Яндекс.Кассы, инициализировать виджет и отобразить форму на странице оплаты.
Для интеграции:
  1. Ознакомьтесь со сценарием проведения платежа в виджете.
  2. Настройте способы оплаты.
  3. Подготовьте страницу оплаты.
  4. Реализуйте проведение платежей.
  5. При необходимости реализуйте проведение автоплатежей.
  6. Настройте обработку ошибок инициализации виджета.
 Сценарий проведения платежа
  1. Пользователь переходит к оплате.
  2. Вы отправляете Яндекс.Кассе запрос на создание платежа.
  3. Яндекс.Касса возвращает вам созданный объект платежа с токеном для инициализации виджета.
  4. Вы инициализируете виджет и отображаете форму на странице оплаты.
  5. Пользователь выбирает способ оплаты, вводит данные.
  6. При необходимости виджет перенаправляет пользователя на страницу подтверждения платежа (например, для аутентификации по 3-D Secure).
  7. Пользователь подтверждает платеж.
  8. Виджет перенаправляет пользователя на страницу завершения оплаты на вашей стороне.
  9. Вы отображаете нужную информацию, в зависимости от статуса платежа.
Готово!
 Настройка способов оплаты
Виджет поддерживает следующие способы оплаты:
  • кошелек в Яндекс.Деньгах и привязанные к нему карты,
  • произвольная банковская карта,
  • Apple Pay,
  • Google Pay,
  • Сбербанк Онлайн.
Кошельком в Яндекс.Деньгах и с привязанных к нему карт может оплатить только пользователь, авторизованный на Яндексе.
 Общие настройки
По умолчанию доступна оплата кошельком в Яндекс.Деньгах и с привязанных карт. Уточните у менеджера Яндекс.Кассы, какие еще способы оплаты вам разрешены.
Чтобы в виджете работала оплата с помощью Apple Pay и Google Pay, ваш сайт должен использовать HTTPS и действующий TLS/SSL-сертификат (минимальная версия — TLS v1.2). Для подключения Apple Pay выполните дополнительные настройки.
 Подключение Apple Pay
Шаг 1. Сообщите вашему менеджеру Яндекс.Кассы адрес сайта, на котором будет размещаться виджет.
Шаг 2. Скачайте файл merchant.ru.yandex.kassa.txt и разместите его на своем сайте по адресу:
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-функцию, которая будет принимать код ошибки.
confirmation_token
нужно получать в Яндекс.Кассе для каждого платежа.
Шаг 4. Чтобы отобразить платежную форму, вызовите метод
render
. Передайте в него значение атрибута
id
, в котором нужно разместить форму.
HTML
<!--Подключение библиотеки-->
<script src="https://kassa.yandex.ru/checkout-ui/v2.js"></script>

<!--HTML-элемент, в котором будет отображаться платежная форма-->
<div id="payment-form"></div>

<script>
//Инициализация виджета. Все параметры обязательные.
const checkout = new window.YandexCheckout({
    confirmation_token: 'confirmation-token', //Токен, который перед проведением оплаты нужно получить от Яндекс.Кассы
    return_url: 'https://merchant.site', //Ссылка на страницу завершения оплаты
    error_callback(error) {
        //Обработка ошибок инициализации
    }
});

//Отображение платежной форме в заданном элементе
checkout.render('payment-form');
</script>
 Проведение платежа
Чтобы провести платеж:
  1. Создайте платеж в Яндекс.Кассе
  2. Инициализируйте виджет
  3. Завершите оплату
Если хотите протестировать виджет, создайте платеж для вашего тестового магазина и заплатите одной из тестовых карт. Подробнее о тестировании платежей
 Шаг 1. Создайте платеж
Для создания платежа отправьте Яндекс.Кассе запрос, передайте в нём данные для аутентификации запроса, ключ идемпотентности, объект
amount
с суммой платежа, объект
confirmation
с типом
embedded
и, при необходимости, параметр
description
с описанием транзакции, которое пользователь увидит при оплате. Также передайте параметр
capture
со значением
true
. Это значит, что вы получите деньги сразу после оплаты (при значении
false
нужная сумма заблокируется на счете пользователя, и после этого вы можете ее списать в удобное вам время).
В запросе можно передать любые другие параметры, кроме
payment_method_data
,
payment_method_id
,
payment_token
,
airline
.
cURL
PHP
Python
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"
      }'
 Шаг 2. Инициализируйте виджет
В объекте платежа  Яндекс.Касса вернет
confirmation_token
.
JSON
{
  "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
}
Используйте этот токен для создания экземпляра класса
YandexCheckout
и инициализации виджета.
Токен одноразовый, срок действия — 1 час. Если пользователь не оплатит в течение часа, виджет не инициализируется, токен нужно будет запрашивать заново. Если пользователь оплатит и вернется к форме, она отобразится с ошибкой.
Чтобы заново запросить токен, создайте платеж еще раз и инициализируйте виджет с новым токеном.
 Шаг 3. Завершите оплату
Когда пользователь введет данные для оплаты и подтвердит платеж, Яндекс.Касса перенаправит его на 
return_url
, который вы передадите при инициализации виджета. Вам нужно самостоятельно узнать, как завершился платеж — успехом или неудачей — и отобразить пользователю нужную информацию.
Чтобы узнать статус платежа, подождите, когда придет уведомление от Яндекс.Кассы, или периодически отправляйте запросы, чтобы получить информацию о платеже .
 Сохранение способа оплаты для автоплатежей
С помощью виджета Яндекс.Кассы вы можете сохранять способ оплаты, чтобы использовать его для автоплатежей, например, для ежемесячной оплаты подписки.
По умолчанию автоплатежи работают только в тестовом магазине. Если хотите использовать их в вашем реальном магазине, напишите менеджеру Яндекс.Кассы.
Если вам разрешено использование автоплатежей, вы можете проводить платежи:
 Платеж с сохранением способа оплаты
Сохранение способа оплаты позволяет привязать карту или кошелек в Яндекс.Деньгах к вашему магазину. С помощью виджета вы можете проводить платежи с безусловным или с условным сохранением способа.
Безусловное сохранение способа оплаты — сохранение способа происходит по умолчанию, пользователь не может на это повлиять. Как это выглядит:
  1. Вы на сайте предупреждаете пользователя, что сохраните его платежные данные, и рассказываете, как будете их использовать, например, с какой регулярностью вы будете списывать деньги и на какую сумму, как пользователь может отказаться от повторных списаний в вашем магазине. Вы на своей стороне получаете от пользователя согласие на проведение автоплатежей.
  2. Виджет отображает пользователю только два способа оплаты: произвольной банковской картой или из кошелька в Яндекс.Деньгах (если пользователь авторизован на Яндексе). Когда пользователь выберет способ оплаты, виджет ему сообщит, что способ оплаты будет привязан к вашему магазину. При успешной оплате данные карты или кошелька автоматически сохранятся в Яндекс.Кассе.
Пример использования: подписка на регулярные платежи.
Платеж с безусловным сохранением способа оплаты
Условное сохранение способа оплаты — сохранение способа происходит по желанию пользователя. Как это выглядит:
  1. Вы на сайте рассказываете о возможности сохранить платежные данные, о том, как вы будете их использовать и как потом от этого отказаться.
  2. Виджет отображает пользователю все доступные способы оплаты. Если пользователь выберет произвольную карту или оплату из кошелька в Яндекс.Деньгах, виджет предложит ему сохранить данные для вашего магазина. Если пользователь согласится, при успешной оплате данные способа будут сохранены в Яндекс.Кассе, и вы сможете использовать идентификатор сохраненного способа оплаты для последующих платежей. Если не согласится, платеж пройдет без привязки данных к магазину.
Пример использования: привязка платежного средства к магазину для ускорения процесса оплаты при последующих платежах.
Платеж с условным сохранением способа оплаты
 Платеж с безусловным сохранением способа оплаты
Шаг 1. Создайте платеж и передайте в нём
save_payment_method
со значением
true
.
cURL
PHP
Python
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
 — токен для инициализации виджета.
JSON
{
  "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. Далее проводите платеж как обычно.
 Платеж с условным сохранением способа оплаты
Шаг 1. Создайте платеж, передавать
save_payment_method
не нужно.
cURL
PHP
Python
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"
      }'
Шаг 2. В ответе от Яндекс.Кассы получите
confirmation_token
 — токен для инициализации виджета.
JSON
{
  "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
.
JSON
{
  "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
. Его нужно будет использовать в качестве идентификатора сохраненного способа оплаты при последующих платежах.
Готово!
Теперь вы можете проводить автоплатежи. Проведение платежа сохраненным способом оплаты нужно реализовать самостоятельно.
 Платеж без сохранения способа оплаты
Вы можете проводить платежи без сохранения способа оплаты. Пользователь сможет оплатить любым доступным способом. Способ оплаты не сохранится.
Чтобы провести платеж без сохранения способа оплаты:
Шаг 1. Создайте платеж и передайте в нём
save_payment_method
со значением
false
.
cURL
PHP
Python
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
 — токен для инициализации виджета.
JSON
{
  "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-функцию код ошибки.
Код ошибкиОписание
token_required
Токен не передан. При инициализации виджета передайте
confirmation_token
.
invalid_token
Неверный токен. Для получения токена создайте платеж.
token_expired
Истек срок действия токена. Для получения нового токена создайте платеж.
return_url_required
URL возврата не передан. При инициализации виджета передайте
return_url
.
internal_service_error
При создании платежа возникла ошибка. Повторите инициализацию виджета.
 Что почитать еще
Быстрый стартПроведение платежейВходящие уведомленияАвтоплатежи