Оплата в навыках

Внимание. Возможность находится в закрытом бета-тестировании. Прием заявок на участие приостановлен.

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

Поддерживаются:

  • Поисковое приложение Яндекса для iOS и Android
  • Умные колонки с Алисой
  • Яндекс Модуль
  • Яндекс Браузер для iOS и Android

Подключение оплаты в навыке

  1. Зарегистрируйтесь на сервисе Яндекс Оплата и выберите возможность принимать оплату в Алисе.
  2. Дождитесь, пока окончится модерация. После нее вам станут доступны тестовые платежи.
  3. В разделе Доступ к оплате скопируйте идентификатор.
  4. В консоли разработчика навыка Алисы на вкладке Оплата в поле Токен укажите идентификатор, полученный на шаге 3, добавьте опциональные описания, нажмите Отправить.
  5. Вернитесь в кабинет Яндекс Оплаты и в разделе Доступ к оплате подтвердите доступ для сервиса Алиса.
  6. На странице оплат в консоли разработчика навыка будет сформирован публичный ключ. Он поможет проверить подпись подтверждения об оплате.
  7. Добавьте в навык поддержку директивы start_purchase и запросов подтверждения оплаты.

Сценарий оплаты

  1. В результате взаимодействия с пользователем навык активирует процесс оплаты.
  2. Навык возвращает ответ с директивой start_purchase .
  3. Пользователь подтверждает оплату товара или услуги и ждет подтверждения от навыка.
  4. Навык подтверждает свою часть сделки.
  5. Если навык в ответе возвращает директиву confirm_purchase , то деньги пользователя списываются. С этого момента навык считает, что оплата совершена. Если от навыка приходит ответ другого формата или возникают иные проблемы, то деньги не списываются.
  6. После подтверждения оплаты пользователь возвращается в навык. Он видит ответ навыка на подтверждение оплаты.

Запуск сценария оплаты

Чтобы начать процесс оплаты, навык должен вернуть ответ с директивой start_purchase:

{
  "response": {
    "text": "...",
    "tts": "...",
    "end_session": false,
    "directives": {
      "start_purchase": {
        "purchase_request_id": "d432de19be8347d09f656d9fe966e2f9",
        "image_url": "http://url_to_image_purchase.png",
        "caption": "caption",
        "description": "description",
        "currency": "RUB",
        "type": "BUY",
        "payload": {"value": "payload"},
        "merchant_key": "d1112abf-27d2-4005-8b47-6861555715d3",
        "test_payment": false,
        "products": [
          {
            "product_id": "5e4cf57a-8497-11ea-bc55-0242ac130209",
            "title": "title 1",
            "user_price": "120",
            "price": "110",
            "quantity": "2",
            "nds_type": "nds_20"
          },
          {
            "product_id": "9dc7c16a-9439-11ea-bb37-0242ac130002",
            "title": "title 2",
            "user_price": "420",
            "price": "510",
            "quantity": "2",
            "nds_type": "nds_20"
          }
        ]
      }
    }
  },
  "version": "1.0"
}
Директива start_purchase

Директива запускает сценарий оплаты для пользователя.

Параметр Обязательный Описание
purchase_request_id Да Произвольная строка. Максимум 40 символов.
image_url Нет URL изображения заказа.
caption Да Название заказа. Максимум 512 символов.
description Да Описание заказа. Максимум 2048 символов.
currency Да Код валюты в кодировке ISO 4217. Доступные значения: RUB.
type Да Тип оплаты. Доступные значения: BUY.
payload Да JSON-объект произвольной валидной формы. Будет содержаться в запросе к навыку во время подтверждения оплаты. Максимум 4096 байт.
merchant_key Да Токен продавца, зарегистрированного на сервисе Яндекс Оплата.
test_payment Нет Признак тестовой оплаты.
products Да Массив продуктов, входящих в заказ (за исключением доставки).
Параметр Обязательный Описание
purchase_request_id Да Произвольная строка. Максимум 40 символов.
image_url Нет URL изображения заказа.
caption Да Название заказа. Максимум 512 символов.
description Да Описание заказа. Максимум 2048 символов.
currency Да Код валюты в кодировке ISO 4217. Доступные значения: RUB.
type Да Тип оплаты. Доступные значения: BUY.
payload Да JSON-объект произвольной валидной формы. Будет содержаться в запросе к навыку во время подтверждения оплаты. Максимум 4096 байт.
merchant_key Да Токен продавца, зарегистрированного на сервисе Яндекс Оплата.
test_payment Нет Признак тестовой оплаты.
products Да Массив продуктов, входящих в заказ (за исключением доставки).
Массив products

Продукты в заказе будут отображены на карточке.

Параметр Обязательный Описание
product_id Да UUID-идентификатор продукта.
title Да Название предложения. Будет добавлено к изображению заказа и напечатано в чеке. Максимум 256 символов.
user_price Да Стоимость единицы продукта для пользователя. Если отличается от price, будет отображено как специальное предложение со скидкой. Неотрицательное число. Не больше значения price. Если currency = RUB, то user_price означает количество рублей. Возможно передать копейки. Пример: 12.45.
price Да Базовая стоимость до скидки. Неотрицательное число. Если currency = RUB, то price означает количество рублей. Возможно передать копейки. Пример: 12.45.
nds_type Да НДС для выдачи чеков. Возможные значения: nds_20, nds_10, nds_0, nds_none.
quantity Да Количество товара данной позиции. Будет умножено на значение user_price при формировании окончательной стоимости (округляется в сторону нуля). Положительное число. Может быть дробным. Пример: 0.5.
Параметр Обязательный Описание
product_id Да UUID-идентификатор продукта.
title Да Название предложения. Будет добавлено к изображению заказа и напечатано в чеке. Максимум 256 символов.
user_price Да Стоимость единицы продукта для пользователя. Если отличается от price, будет отображено как специальное предложение со скидкой. Неотрицательное число. Не больше значения price. Если currency = RUB, то user_price означает количество рублей. Возможно передать копейки. Пример: 12.45.
price Да Базовая стоимость до скидки. Неотрицательное число. Если currency = RUB, то price означает количество рублей. Возможно передать копейки. Пример: 12.45.
nds_type Да НДС для выдачи чеков. Возможные значения: nds_20, nds_10, nds_0, nds_none.
quantity Да Количество товара данной позиции. Будет умножено на значение user_price при формировании окончательной стоимости (округляется в сторону нуля). Положительное число. Может быть дробным. Пример: 0.5.

После ответа в описанном формате будет инициирован сценарий оплаты, в процессе которого пользователь выберет способ оплаты и подтвердит платеж.

Запрос на подтверждение оплаты в навыке

Для подтверждения оплаты будет отправлен запрос к навыку с объектом request и типом Purchase.Confirmation:

...,
"request": {
  "type": "Purchase.Confirmation",
  "purchase_request_id": "d432de19be8347d09f656d9fe966e2f9",
  "purchase_token": "token_value",
  "order_id": "eeb59d64-9e6a-11ea-bb37-0242ac130002",
  "purchase_timestamp": 1590399311,
  "purchase_payload": {"value": "payload"},
  "signed_data": "purchase_request_id=d432de19be8347d09f656d9fe966e2f9&purchase_token=token_value&order_id=eeb59d64-9e6a-11ea-bb37-0242ac130002&...",
  "signature": "Pi6JNCFeeleRa..."
}
...
Объект request
Параметр Обязательный Описание
purchase_request_id Да UUID-идентификатор заказа, переданный при запуске сценария оплаты.
purchase_token Да UUIDv4-идентификатор транзакции.
order_id Да Идентификатор заказа. Остается неизменным для всех платежей в рамках подписки.
purchase_timestamp Да Время совершения оплаты. Равно количеству миллисекунд, прошедших с 01.01.1970 00:00:00 GMT.
purchase_payload Да JSON-объект, полученный при запуске сценария оплаты.
signed_data Да Строка, использованная для подписи. Формат: purchase_request_id=[value]&purchase_token=[value]&order_id=[value]&purchase_timestamp=[value].
signature Да Подпись, полученная путем хеширования значения поля signed_data с помощью алгоритма SHA256 с RSA и приватного ключа. Закодирован в base64.
Параметр Обязательный Описание
purchase_request_id Да UUID-идентификатор заказа, переданный при запуске сценария оплаты.
purchase_token Да UUIDv4-идентификатор транзакции.
order_id Да Идентификатор заказа. Остается неизменным для всех платежей в рамках подписки.
purchase_timestamp Да Время совершения оплаты. Равно количеству миллисекунд, прошедших с 01.01.1970 00:00:00 GMT.
purchase_payload Да JSON-объект, полученный при запуске сценария оплаты.
signed_data Да Строка, использованная для подписи. Формат: purchase_request_id=[value]&purchase_token=[value]&order_id=[value]&purchase_timestamp=[value].
signature Да Подпись, полученная путем хеширования значения поля signed_data с помощью алгоритма SHA256 с RSA и приватного ключа. Закодирован в base64.

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

Подтверждение оплаты навыком

В ответ на запрос необходимо вернуть код 200 и директиву confirm_purchase. Если код ответа отличается от 200, это будет трактоваться как ошибка и деньги не спишутся.

{
  "response": {
    "text": "Спасибо за покупку. Мне включить эту книгу?",
    "tts": "Спасибо за покупку. Мне включить эту книгу?",
    "end_session": false,
    "directives": {
      "confirm_purchase": {}
    }
  },
  "version": "1.0"
}

Значения text и tts, полученные на данном этапе, будут показаны пользователю после возвращения в навык.

Завершение оплаты

После подтверждения оплаты пользователю будут показаны значения text и tts из ответа навыка при подтверждении оплаты. Если в результате оплаты произошла ошибка, то пользователь увидит сообщение.

Оплата через умную колонку

Если пользователь начал оплачивать с помощью колонки, ему придет пуш-уведомление на телефон с просьбой оплатить через приложение Яндекса. После этого он оплачивает, как описано в разделе Сценарий оплаты.

Когда пользователь завершит оплату, Алиса озвучит ответ навыка на запрос подтверждения оплаты.

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

Тестовый платеж ведет на страницу, где используются тестовые карты известных платежных систем. Платеж при этом проходит, но реальные деньги с карты пользователя не списываются.

Чтобы выполнить тестовый платеж:

  1. Добавьте в директиву start_purchase свойство test_payment:true — признак тестовой оплаты.
  2. Проведите оплату обычным образом.
  3. Нажмите на пуш-уведомление и откройте форму тестовой оплаты.
  4. Для завершения оплаты укажите одну из тестовых карт.
Тестовые карты
Номер Тип карты
5555 5555 5555 4477 MasterCard (с 3-D Secure)
5555 5555 5555 4444 MasterCard
6759 6498 2643 8453 Maestro
4111 1111 1111 1111 Visa
4175 0010 0000 0017 Visa Electron
3700 000000 00002 American Express
3528 0007 0000 0000 JCB
3670 010200 0000 Diners Club
Номер Тип карты
5555 5555 5555 4477 MasterCard (с 3-D Secure)
5555 5555 5555 4444 MasterCard
6759 6498 2643 8453 Maestro
4111 1111 1111 1111 Visa
4175 0010 0000 0017 Visa Electron
3700 000000 00002 American Express
3528 0007 0000 0000 JCB
3670 010200 0000 Diners Club