Виджет ЮKassa: быстрый старт — Прием платежей по API ЮKassa

Docs

Подключить ЮKassa

Быстрый старт для виджета ЮKassa

С помощью этой статьи вы проведете свой первый платеж с использованием виджета ЮKassa.

В статье описан самый простой сценарий интеграции. Подробные инструкции — в разделе Интеграция.

Как проходит платеж

Пользователь переходит на страницу оплаты.
Вы инициализируете виджет на странице оплаты и отображаете платежную форму.
Пользователь выбирает способ оплаты, вводит данные и подтверждает платеж.
ЮKassa перенаправляет пользователя на вашу страницу завершения оплаты.
Вы отображаете пользователю информацию в зависимости от статуса платежа.

Готово!

Как подготовиться к проведению платежа

Вам понадобятся инструменты для взаимодействия с ЮKassa по API и две страницы для проведения платежа.

Подготовка к взаимодействию по API

При оплате вам нужно взаимодействовать с ЮKassa по API. Подготовьте удобные для вас инструменты тестирования запросов к API.

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

Этот платеж рекомендуется проводить в тестовый магазин ЮKassa. При оплате в тестовом магазине всё проходит, как при настоящих платежах, но деньги никуда не переводятся. Если у вас пока нет тестового магазина, создайте и настройте его в личном кабинете и получите его идентификатор и секретный ключ. Подробнее о тестовом режиме

Если вы хотите оценить возможности API, но у вас пока нет личного кабинета в ЮKassa, зарегистрируйтесь по этой ссылке. Это самый простой способ получить тестовый магазин. Указывать данные компании и подписывать договор не нужно.

Страницы для проведения платежа

Для проведения платежа вам нужно подготовить страницу оплаты и страницу завершения оплаты.

Страница оплаты — страница на вашем сайте, на которой вы отобразите платежную форму, а пользователь введет свои данные для платежа. На эту страницу нужно встроить виджет. Для проведения этого платежа создайте тестовую страницу: скопируйте код ниже и сохраните его в файл формата HTML.

Страница завершения оплаты — страница на вашем сайте, на которую виджет перенаправит пользователя после платежа и в случае успеха, и в случае неудачи. URL этой страницы необходимо указать в скрипте для инициализации виджета на странице оплаты, в параметре return_url. Для проведения этого платежа можете использовать любую страницу, например главную вашего сайта.

Код тестовой страницы оплаты

HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html>
 <head>
  <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
  <title>Прием платежа с помощью виджета ЮKassa</title>

  
  <script src="https://yookassa.ru/checkout-widget/v1/checkout-widget.js"></script>
 </head>
 <body>
  <p>Ниже отобразится платежная форма. Если вы еще не создавали платеж и не передавали токен для инициализации виджета, появится сообщение об ошибке.</p>

  
  <div id="payment-form"></div>

  <p>Данные банковской карты для оплаты в <b>тестовом магазине</b>:</p>
  <ul>
   <li>номер — <b>5555 5555 5555 4477</b></li>
   <li>срок действия — <b>01/30</b> (или другая дата, больше текущей)</li>
   <li>CVC — <b>123</b> (или три любые цифры)</li>
   <li>код для прохождения 3-D Secure — <b>123</b> (или три любые цифры)</li>
  </ul>
  <p><a href=https://yookassa.ru/developers/payment-acceptance/testing-and-going-live/testing#test-bank-card>Другие тестовые банковские карты</a></p>

  <script>
  //Инициализация виджета. Все параметры обязательные.
  const checkout = new window.YooMoneyCheckoutWidget({
      confirmation_token: 'ct-287e0c37-000f-5000-8000-16961d35b0fd', //Токен, который перед проведением оплаты нужно получить от ЮKassa
      return_url: 'https://example.com/', //Ссылка на страницу завершения оплаты, это может быть любая ваша страница

      //При необходимости можно изменить цвета виджета, подробные настройки см. в документации
       //customization: {
        //Настройка цветовой схемы, минимум один параметр, значения цветов в HEX
        //colors: {
            //Цвет акцентных элементов: кнопка Заплатить, выбранные переключатели, опции и текстовые поля
            //control_primary: '#00BF96', //Значение цвета в HEX

            //Цвет платежной формы и ее элементов
            //background: '#F2F3F5' //Значение цвета в HEX
        //}
      //},
      error_callback: function(error) {
          console.log(error)
      }
  });

  //Отображение платежной формы в контейнере
  checkout.render('payment-form');
  </script>
 </body>
</html>

Как провести тестовый платеж

Шаг 1. Создайте платеж

Для создания платежа отправьте ЮKassa запрос, передайте в нём данные для аутентификации запроса для тестового магазина, ключ идемпотентности, сумму и описание платежа, объект confirmation с типом embedded (это значит, что для приема оплаты вы используете виджет ЮKassa). Также передайте параметр capture со значением true — так вы получите деньги сразу после оплаты (при значении false нужная сумма заблокируется на счете пользователя, и после этого вы можете ее списать в удобное вам время).

Если проводите платеж в тестовый магазин, то в нём списание и начисление денег будет только имитироваться.

cURL
curl https://api.yookassa.ru/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"
      }'

В объекте платежа ЮKassa вернет 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": "100500",
    "gateway_id": "100700"
  },
  "refundable": false,
  "test": true
}

Шаг 2. Инициализируйте виджет и отобразите платежную форму

Откройте код страницы оплаты, вставьте в скрипт для инициализации виджета значение confirmation_token, полученное от ЮKassa на предыдущем шаге. Сохраните изменения и откройте страницу в браузере — отобразится платежная форма виджета.

HTML
//Пример скрипта с переданным токеном.
<script>
//Инициализация виджета. Все параметры обязательные.
const checkout = new window.YooMoneyCheckoutWidget({
    confirmation_token: 'ct-24301ae5-000f-5000-9000-13f5f1c2f8e0', //Токен, который вы получили после создания платежа
    return_url: 'https://yookassa.ru/', //Ссылка на страницу завершения оплаты
    error_callback: function(error) {
        console.log(error)
    }
});

//Отображение платежной формы в контейнере
checkout.render('payment-form');
</script>

Шаг 3. Введите тестовые данные

Порядок действий зависит от того, в какой магазин вы проводите платеж — в тестовый или в реальный.

Платеж в тестовый магазин

Если вы проводите платеж в тестовый магазин, в виджете отобразятся два способа оплаты — из кошелька ЮMoney и банковской картой. Для оплаты можно использовать только карту.

Для проведения платежа используйте данные специальной тестовой банковской карты, например:

номер — 5555555555554477
срок действия — 01/30 (или другая дата, больше текущей)
CVC — 123 (или три любые цифры)
код для прохождения 3-D Secure — 123 (или три любые цифры)

Платеж в реальный магазин

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

Для проведения платежа выберите нужный вам способ оплаты и введите данные реального платежного средства.

Шаг 4. Завершите оплату

После подтверждения платежа виджет перенаправит вас на страницу завершения оплаты — return_url, который вы указали в скрипте инициализации виджета. При приеме оплаты от реальных пользователей вам нужно самостоятельно узнать статус платежа и отобразить пользователю соответствующую информацию.

Чтобы узнать статус платежа, периодически отправляйте запросы , чтобы получить информацию о платеже. Также вы можете настроить уведомления и дождаться, когда ЮKassa сообщит об изменении статуса.

Пример успешно завершенного платежа

JSON
{
  "id": "22d6d597-000f-5000-9000-145f6df21d6f",
  "status": "succeeded",
  "paid": true,
  "amount": {
    "value": "2.00",
    "currency": "RUB"
  },
  "authorization_details": {
    "rrn": "10000000000",
    "auth_code": "000000",
    "three_d_secure": {
      "applied": true
    }
  },
  "captured_at": "2018-07-10T14:32:08.545Z",
  "created_at": "2018-07-10T14:25:27.535Z",
  "description": "Заказ №72",
  "income_amount": {
    "value": "1.92",
    "currency": "RUB"
  },
  "metadata": {},
  "payment_method": {
    "type": "bank_card",
    "id": "22d6d597-000f-5000-9000-145f6df21d6f",
    "saved": false,
    "card": {
      "first6": "555555",
      "last4": "4477",
      "expiry_month": "01",
      "expiry_year": "2030",
      "card_type": "MasterCard",
      "issuer_country": "US"
    },
    "title": "Bank card *4477"
  },
  "recipient": {
    "account_id": "100500",
    "gateway_id": "100700"
  },
  "refundable": true,
  "refunded_amount": {
    "value": "0.00",
    "currency": "RUB"
  },
  "test": true
}

Готово! Вы провели свой первый платеж с использованием виджета.

Дальнейшие шаги

Если вы использовали тестовый магазин, получите данные для аутентификации запросов для реального магазина.
Ознакомьтесь с типовыми сценариями интеграции виджета и возможностями ЮKassa, выберите то, что нужно вам.
Разместите виджет на собственной странице оплаты или настройте отображение виджета во всплывающем окне.
Выберите, как будете взаимодействовать с пользователем после оплаты.
Настройте прием платежей.
Настройте внешний вид платежной формы: выберите язык текстов в интерфейсе и настройте цвета элементов.
Настройте обработку ошибок инициализации виджета.

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

Основы работы с API Входящие уведомления Справочник API Справочник виджета