Choco One-Click Widget

Встраиваемый виджет для быстрой оплаты с bottom sheet интерфейсом.

Установка

npm i choco-one-click-payment

Использование

ESM:

import ChocoOneClickWidget from 'choco-one-click-payment';

const widget = new ChocoOneClickWidget({
  clientId: '12345678',
  trackId: 'your-track-id',
  terminalId: 1234,
  amount: 10000,
  environment: 'stage',
  onSuccess: (data) => console.log('Success', data),
  onError: (error) => console.error('Error', error),
  onCancel: () => console.log('Cancelled'),
  onConfirmPay: (method) => console.log('payment button was pressed', method?.type),
  onPaymentMethodSelected: (method) => console.log('payment method selected', method?.type),
  onKaspiLink: ({ action_link }) => {
    // Клиент сам выбирает, как открыть ссылку:
    // window.open(action_link, '_blank');
    window.location.href = action_link;
  },
  onUserEvent: ({ eventName, eventProperties }) => {
    console.log('User event', eventName, eventProperties);
  },
});

await widget.init();

Инициализация без trackId (способ оплаты будет заблокирован до вызова updateTrackId):

const widget = new ChocoOneClickWidget({
  clientId: '12345678',
  terminalId: 1234,
  amount: 10000,
  environment: 'stage',
  onSuccess: (data) => console.log('Success', data),
  onError: (error) => console.error('Error', error),
});

await widget.init();

// Когда trackId станет известен
await widget.updateTrackId('your-track-id');

CommonJS:

const ChocoOneClickWidget = require('choco-one-click-payment');

Поведение init()

• clientId обязателен. Без него вызывается onError и init() возвращает false.
• Запрос на контекст оплаты (context) не отправляется, если нет ни trackId, ни accessToken (из localStorage). В этом случае показывается виджет с заблокированным выбором способа оплаты; кнопка «Оплатить» активна.
• Если есть trackId или accessToken — запрашиваются токены (при необходимости) и context, подключается WebSocket, отображается полный виджет.

Параметры конфигурации

| Параметр | Тип | Обязательный | Описание | |----------|-----|--------------|----------| | clientId | string | да | OAuth2 client_id приложения | | trackId | string | нет | Идентификатор для получения access token | | terminalId | number | да | ID терминала Choco | | amount | number | да | Сумма в тиынах (1₸ = 100 тиынов) | | merchantOrderId | string | нет | Уникальный ID заказа в вашей системе | | currency | string | нет | Код валюты (по умолчанию KZT) | | environment | 'production' | 'stage' | нет | Окружение API (по умолчанию production) | | backlink | string | нет | URL для возврата после оплаты (Kaspi Pay, 3DS) | | locale | string | нет | Язык: ru, en, kk (по умолчанию ru) | | preorderId | number | нет | Preorder ID | | containerSelector | string | нет | CSS-селектор элемента для embedded-режима. Если не передан или элемент не найден — виджет монтируется sticky поверх страницы | | color | string | нет | Акцентный цвет (по умолчанию #2F2F2F) | | onlyKaspiAvailable | boolean | нет | Только Kaspi в списке способов оплаты | | disableKaspi | boolean | нет | Скрыть Kaspi среди способов оплаты | | bonuses | { availableBonus: number, amount: number, percent: number } | нет | Бонусы: availableBonus — сумма к списанию (вычитается из amount при включённом тоггле); amount и percent — только для отображения в тоггле |

Callbacks

| Параметр | Описание | |----------|----------| | onSuccess | Вызывается при успешной оплате | | onError | Вызывается при ошибке | | onCancel | Вызывается при отмене/закрытии | | onConfirmPay | Callback перед оплатой; получает выбранный method, для подтверждения вызовите widget.pay() | | onPaymentMethodSelected | Вызывается при выборе способа оплаты; получает выбранный method | | onKaspiLink | Вызывается для kaspi_pay при получении action_link/action_url; позволяет клиенту самому открыть ссылку | | onAppliedBonus | Вызывается при включении/выключении бонусов тоггл-переключателем | | onUserEvent | Вызывается при пользовательских событиях виджета (one_click_pay_cta_rendered, one_click_pay_method_resolved, one_click_pay_cta_tapped) |

Методы

| Метод | Описание | |-------|----------| | init() | Инициализация виджета. Возвращает Promise<boolean>. | | destroy() | Уничтожает виджет (WebSocket, DOM). | | close() | Закрывает виджет и вызывает onCancel. | | openPaymentSheet() | Открывает bottom sheet выбора способа оплаты. | | closePaymentSheet() | Закрывает bottom sheet. | | updateAmount(amount) | Обновляет сумму (в тиынах) и текст кнопки. | | updateAvailableBonus(availableBonus) | Обновляет доступную к списанию сумму бонусов (в тиынах). Пересчитывает итоговую сумму. Работает только если bonuses переданы в конфиге. | | updateLocale(locale) | Меняет язык интерфейса. | | updateTrackId(trackId) | Обновляет trackId, запрашивает токены и context, перерисовывает виджет. Возвращает Promise<boolean>. | | setLoading(boolean) | Включает/выключает состояние загрузки. | | setDisabled(boolean) | Блокирует/разблокирует интеракции. | | setPreorderId(preorderId) | Обновляет preorderId в рантайме. | | setMerchantOrderId(merchantOrderId) | Обновляет merchantOrderId в рантайме. | | ChocoOneClickWidget.logout() | Очищает auth токены из localStorage (webPayToken, webPayRefreshToken) без создания экземпляра. | | widget.logout() | Экземплярный alias для ChocoOneClickWidget.logout(). | | onConfirmPay(callback) | Регистрирует callback подтверждения оплаты. Callback получает выбранный method. | | onPaymentMethodSelected(callback) | Регистрирует callback изменения выбранного способа оплаты. | | onKaspiLink(callback) | Регистрирует callback для обработки ссылки Kaspi Pay (action_link/action_url). | | onUserEvent(callback) | Регистрирует callback для пользовательских событий виджета. | | pay() | Подтверждает оплату и запускает создание заказа (после onConfirmPay). |

Режим монтирования: embedded vs sticky

По умолчанию виджет монтируется как sticky-плашка поверх страницы (фиксированная снизу).

Если передать containerSelector и элемент с таким селектором существует в DOM — виджет монтируется внутрь этого элемента (embedded-режим). Если селектор не передан или элемент не найден — применяется fallback: sticky поверх страницы.

new ChocoOneClickWidget({
  // ...
  containerSelector: "#checkout-widget-slot",
});

<div id="checkout-widget-slot"></div>

Отображение «вместо» для Apple Pay / Google Pay

Когда выбран Apple Pay или Google Pay, виджет показывает итоговую сумму к оплате и опциональную строку «вместо X» (зачёркнутая полная цена).

Строка появляется когда итоговая сумма к оплате меньше переданного amount — то есть когда активен тоггл баланса или тоггл бонусов. В строке «вместо» всегда отображается исходный amount (сумма до любых скидок).

Обработка ссылки Kaspi Pay

Для способа оплаты kaspi_pay виджет больше не обязан делать редирект сам. Если передан onKaspiLink, ссылка передается в callback, а клиент сам решает, как именно ее открыть (в текущей вкладке, новой вкладке, через webview и т.д.).

Сборка пакета (для разработчиков)

npm install
npm run build

Сборка генерирует:

• index.js (UMD/CJS)
• index.esm.js (ESM)
• index.d.ts (типы TypeScript)