П Платёжка Документация
Войти

Виджет на сайте

Виджет встраивается в страницу оформления заказа и показывает сумму, состав заказа и переключатель «СБП / Карта»: QR-код СБП открыт сразу, карта — по вкладке. Карту покупатель вводит на защищённой форме платёжного центра, которая открывается внутри виджета; реквизиты карты не проходят через ваш сайт.

Платёж создаёт ваш сервер запросом POST /payments с секретным ключом — сумма и состав заказа в браузере не меняются. В браузер уходит только id платежа.

Подключение

  1. При оформлении заказа создайте платёж: POST /payments с amount, order_id, customer (email или телефон — для чека) и return_url.
  2. Выведите страницу оформления с id платежа в коде виджета:
<script src="https://platezhka.online/platezhka.js"></script>
<div id="platezhka"></div>
<script>
  Platezhka.widget({
    container: "#platezhka",
    payment: "<id платежа из ответа POST /payments>",
    onSuccess: function (p) { /* покупатель оплатил — заказ подтвердит вебхук payment.succeeded */ },
    onFail: function (p) { /* p.status: canceled | expired */ }
  });
</script>

Без JavaScript-вызова: <div data-platezhka-payment="<id>"></div> — скрипт сам найдёт контейнер.

  1. Примите вебхук payment.succeeded (или payment.authorized при холде) и отметьте заказ оплаченным. Колбэк onSuccess в браузере — только для интерфейса: покупатель мог закрыть вкладку, а оплата пройти.

Параметры Platezhka.widget

ПараметрОписание
containerСелектор или элемент, куда вставить виджет. Обязателен.
paymentid платежа из ответа POST /payments. Обязателен (можно передать url: payment_url).
onSuccess(p)Платёж оплачен или захолдирован: p.status — succeeded или authorized, p.receipt_url — чек, если уже готов.
onFail(p)Платёж закрыт без оплаты: canceled (отказ банка — текст уже показан покупателю) или expired.
onStatus(p)Любая смена статуса, включая промежуточные.
redirectПосле оплаты виджет показывает «Оплачено» с отсчётом 10 секунд и кнопкой «Вернуться в магазин сейчас», затем страница переходит на return_url с payment_id. redirect: false — остаться на странице и обработать onSuccess самим (кнопка в виджете продолжает работать).
height, maxWidthНачальная высота (px) и максимальная ширина контейнера; высоту виджет дальше подбирает сам.

Вызов возвращает объект с iframe, reload() и destroy().

Что происходит внутри

  • Виджет — iframe с нашим адресом /pay/{id}/embed; стили сайта на него не влияют, цвет кнопок и логотип задаются в кабинете (Интеграция → Виджет).
  • Ширина — по контейнеру: до 720px одна колонка (телефон), шире — заказ слева и оплата справа; удобный максимум — 800px. Высоту виджет сообщает сам.
  • QR СБП запрашивается у платёжного центра при первом показе и живёт 72 часа; при повторных показах тот же. На телефоне кнопка «Открыть в приложении банка» ведёт по ссылке НСПК.
  • Вкладка «Карта» открывает форму ввода карты и 3-D Secure внутри виджета. Если банк запрещает показывать свою страницу во вложенном окне, над формой есть ссылка «Открыть в окне».
  • Статус обновляется сам: push от нашего сервера и опрос раз в несколько секунд. Если платёжный центр задерживает уведомление, виджет сам опрашивает заказ.
  • method: "card" в POST /payments открывает вкладку «Карта» сразу, QR — по вкладке «СБП». save_payment_method: true оставляет только СБП (автосписания).
  • Срок оплаты — expires_at или «Срок оплаты» из настроек; после истечения виджет показывает «Срок оплаты истёк» и зовёт onFail.

Безопасность

  • Секретный ключ API остаётся на сервере. Доступ к оплате конкретного заказа даёт только его id — такой же, как в payment_url.
  • В кабинете (Интеграция → Виджет → «Сайты, где стоит виджет») можно перечислить адреса своих сайтов — тогда встроить виджет на другом домене нельзя (заголовок Content-Security-Policy: frame-ancestors).
  • Если на вашем сайте есть своя Content-Security-Policy, добавьте в script-src и frame-src адрес https://platezhka.online.
  • Сообщения о статусе из виджета (postMessage) — для интерфейса; истина — вебхук и GET /payments/{id}.
Объекты API Платежи