ИНСТРУКЦИЯ ПО НАСТРОЙКЕ СКРИПТА ИНТЕГРАЦИИ ДЛЯ ПРИЕМА ПЛАТЕЖЕЙ (1.0)

Download OpenAPI specification:Download

License: Apache 2.0

История изменений

Описание изменений Дата
Создан документ 23.04.2025

Введение

Integration.js — это способ интеграции методов оплат в приложения мерчанта.

Скрипт позволяет добавить на сайт виджет с кнопками оплаты и открывать платежную форму в iframe, модальном или отдельном окнах.

Требования к подключению

Чтобы использовать скрипты интеграции для виджета должны быть выполнены следующие требования:

  1. Cайт должен работать по протоколу HTTPS.
  2. На сайте должны отсутствовать заголовки:
    Cross-Origin-Opener-Policy: *
    
  3. Политики CSP на сайте должны разрешать использовать:
    script-src: https://*.tinkoff.ru https://*.tcsbank.ru https://*.tbank.ru https://*.nspk.ru https://*.t-static.ru
    frame-src: https://*.tinkoff.ru https://*.tcsbank.ru https://*.tbank.ru https://*.nspk.ru https://*.t-static.ru
    img-src: https://*.tinkoff.ru https://*.tcsbank.ru https://*.tbank.ru https://*.nspk.ru https://*.t-static.ru
    connect-src: https://*.tinkoff.ru https://*.tcsbank.ru https://*.tbank.ru https://*.nspk.ru https://*.t-static.ru
    style-src: 'unsafe-inline' https://*.tinkoff.ru https://*.tcsbank.ru https://*.tbank.ru https://*.nspk.ru https://*.t-static.ru
    

Поддерживаемые версии браузеров

  • Chrome >= 63;
  • Edge >= 19;
  • Safari >= 11;
  • Firefox >= 67;
  • Opera >= 50;
  • IE - не поддерживается;
  • Samsung Internet >= 8.2;
  • Opera Mobile >= 73.

Подготовка к использованию

После подключения интернет-эквайринга зайдите в личный кабинет и выберите раздел «Магазины». Во вкладке «Терминалы» будет указан публичный ключ терминала — TerminalKey.

Где найти номер терминал в ЛК

Чтобы настроить терминал, нужно выбрать тип подключения «Универсальный» и на вкладке «Способы оплаты» включить нужные способы оплаты.

Если вы подключаете платежную форму от Т-Банка:

  1. Зайдите в личный кабинет интернет эквайринга → «Магазины».
  2. Выберите ваш магазин → «Способы оплаты» → Выберите нужный способ оплаты → «Платежная форма Т-Банка» → «Включить».

Если вы хотите настроить отдельную кнопку быстрой оплаты с помощью виджета:

  1. Зайдите в личный кабинет интернет эквайринга → «Магазины».
  2. Выберите ваш магазин → «Способы оплаты» → Выберите нужный способ оплаты → «Настроить» → «Своя платежная форма» → «Включить».

Подключение скрипта интеграции

Скрипт размещен по адресу https://acq-paymentform-integrationjs.t-static.ru/integration.js Полностью копировать скрипт в свою сборку не нужно. Рекомендуем всегда загружать скрипт из предоставленного URL. Это позволит всегда использовать актуальную версию скрипта, включая все исправления и обновления безопасности.

  1. Установите HTML-код на всех нужных страницах перед закрывающим тегом . Передайте в атрибут onload название метода, который будет отвечать за инициализацию и обработку платежей:
<script src="https://acq-paymentform-integrationjs.t-static.ru/integration.js" onload="onPaymentIntegrationLoad()" async></script>

Проведите инициализацию скрипта:

<script>
  const initConfig = { // IntegrationInitConfig интерфейс, описан в разделе "Интерфейс глобальной конфигурации"
    ...
  }    
  
  function onPaymentIntegrationLoad() {
    PaymentIntegration.init(initConfig).then().catch();
  }
</script>
Альтернативные способы инициализации Можно использовать любой из способов подключения:
Простой
<script src="https://acq-paymentform-integrationjs.t-static.ru/integration.js" onload="onPaymentIntegrationLoad()" async></script>
<script>
  const initConfig = { // IntegrationInitConfig интерфейс, описан в разделе "Интерфейс глобальной конфигурации"
    ...
  }
  
  function onPaymentIntegrationLoad() {
     PaymentIntegration.init(initConfig)
       .then(async (integration) => {
         // Место для кода взаимодействия с объектом integration
       }
     ).catch();
  }
</script>
Синхронный
<script src="https://acq-paymentform-integrationjs.t-static.ru/integration.js"></script>
<script>
  async function initPayment() {
    const integration = await PaymentIntegration.init(initConfig); // initConfig - экземпляр интерфейса IntegrationInitConfig, описан в разделе "Интерфейс глобальной конфигурации"
    // Место для кода взаимодействия с объектом integration
  }
 
  initPayment().then().catch();
</script>
Динамический
<script>
  async function loadJs(url) {
    return new Promise((resolve, reject) => {
      const element = document.createElement('script');
 
      element.src = url;
      element.type = 'text/javascript';
      element.async = true;
      element.onload = () => resolve();
      element.onerror = () => reject();
      document.body.appendChild(element);
    });
  }
 
  async function initPayment() {
    await loadJs('https://acq-paymentform-integrationjs.t-static.ru/integration.js');
 
    const integration = await PaymentIntegration.init(initConfig); // initConfig - экземпляр интерфейса IntegrationInitConfig, описан в разделе "Интерфейс глобальной конфигурации"
    //  Место для кода взаимодействия с объектом integration
  }
 
  initPayment().then().catch();
</script>
  1. Настройте нужную конфигурацию скрипта. Используйте только те ключи объекта features (модули), которые вам нужны:
<script> 
  const initConfig = {
    terminalKey: 'myTerminalKey', // <-- Значение terminalKey из личного кабинета
    product: 'eacq',
    features: {
       payment: {}, // <-- Добавьте, если нужны кнопки оплаты
       iframe: {} // <-- Добавьте, если нужно встроить платежную форму в iframe
       addcardIframe: {} // <-- Добавьте, если нужно встроить приложение привязки карты в iframe
    }
  }
</script>
Интерфейс глобальной конфигурации
export interface IntegrationInitConfig {
  /**
   * Значение terminalKey из личного кабинета
   */
  terminalKey: string;
  /**
   * Продукт, для интернет-эквайринга значение 'eacq'
   */
  product: 'eacq';
  features:  {   
    /**
    * При включении iframe ключа в конфигурацию будет загружен модуль работы с iframe для приложения привязки карты
    */
    addcardIframe?: {
      /**
       * Если используется параметр container, скрипт встроит iframe в этот элемент
       * На странице должен существовать элемент с id="paymentContainer"
       */
      container?: HTMLElement | null;
      /**
       * Возможность переопределить стандартное поведение виджета
       */
      config?: IframeIntegrationConfig; // Интерфейс описан в разделе "Конфигурация IframeIntegrationConfig" 
      /**
       * Функция paymentStartCallback должна возвращать Promise который резолвит ссылку PaymentUrl (ссылка платежной формы)
       *
       * В этой функции должен происходить вызов вашего backend-сервиса с передачей туда внутреннего orderId
       * backend-сервис находит необходимые для запроса метода "Инициировать платеж" поля (такие как сумма) внутри вашей системы и отправляет запрос в v2/Init
       * PaymentUrl из v2/Init должен быть возвращен во frontend в paymentStartCallback
       *
       * Например:
       * const res = await new PaymentIntegration.Helpers().request(URL, 'POST', INIT_PARAMS);
       * return res.PaymentURL;
       *
       * Переменная PaymentIntegration содержит класс-помощник Helpers c методом request для отправки запросов на бекенд
       * В данном примере URL - это url вашего backend-сервиса, который вызовет метод "Инициировать платеж" в интернет-эквайринге и вернет PaymentURL
       *
       * @param {OverlayType} paymentType - способ оплаты выбранный пользователем
       * @returns {Promise<string>}
       */      
      paymentStartCallback?: PaymentStartCallback;
    };
    /**
     * При включении iframe ключа в конфигурацию будет загружен модуль работы с iframe
     */
    iframe?: {
      /**
       * Если используется параметр container, скрипт встроит iframe в этот элемент
       * На странице должен существовать элемент с id="paymentContainer"
       */
      container?: HTMLElement | null;
      /**
       * Возможность переопределить стандартное поведение виджета
       */
      config?: IframeIntegrationConfig; // Интерфейс описан в разделе "Конфигурация IframeIntegrationConfig"
      /**
       * Функция paymentStartCallback должна возвращать Promise который резолвит ссылку PaymentUrl (ссылка платежной формы)
       *
       * В этой функции должен происходить вызов вашего backend-сервиса с передачей туда внутреннего orderId
       * backend-сервис находит необходимые для запроса метода "Инициировать платеж" поля (такие как сумма) внутри вашей системы и отправляет запрос в v2/Init
       * `PaymentUrl` из v2/Init должен быть возвращен во frontend в paymentStartCallback
       *
       * Например:
       * const res = await new PaymentIntegration.Helpers().request(URL, 'POST', INIT_PARAMS);
       * return res.PaymentURL;
       *
       * Переменная PaymentIntegration содержит класс-помощник Helpers c методом request для отправки запросов на backend
       * В данном примере URL - это url вашего backend-сервиса, который вызовет метод "Инициировать платеж" в интернет-эквайринге и вернет PaymentURL
       *
       * @param {OverlayType} paymentType - способ оплаты выбранный пользователем
       * @returns {Promise<string>}
       */           
      paymentStartCallback?: PaymentStartCallback;
    };
    /**
     * При включении payment ключа в конфигурацию будет загружен модуль работы с виджетами оплаты
     */
    payment?: {
      /**
       * Если используется параметр container, скрипт встроит все доступные терминалу методы оплаты в этот элемент
       * На странице должен существовать элемент с id="paymentContainer"
       */
      container?: HTMLElement | null;
      /**
       * Возможность переопределить стандартное поведение виджета
       */
      config?: PaymentIntegrationConfig; // Интерфейс описан в разделе "Конфигурация PaymentIntegrationConfig"
      /**
       * Функция paymentStartCallback должна возвращать Promise который резолвит ссылку PaymentUrl (ссылка платежной формы)
       *
       * В этой функции должен происходить вызов вашего backend-сервиса с передачей туда внутреннего orderId
       * backend-сервис находит необходимые для запроса метода "Инициировать платеж" поля (такие как сумма) внутри вашей системы и отправляет запрос в v2/Init
       * PaymentUrl из v2/Init должен быть возвращен во frontend в paymentStartCallback
       *
       * Например:
       * const res = await new PaymentIntegration.Helpers().request(URL, 'POST', INIT_PARAMS);
       * return res.PaymentURL;
       *
       * Переменная PaymentIntegration содержит класс-помощник Helpers c методом request для отправки запросов на backend
       * В данном примере URL - это url вашего backend-сервиса, который вызовет метод "Инициировать платеж" в интернет-эквайринге и вернет PaymentURL
       *
       * @param {OverlayType} paymentType - способ оплаты выбранный пользователем
       * @returns {Promise<string>}
       */  
      paymentStartCallback?: PaymentStartCallback;
    };
  };
}
Пример конфигурации для кнопок оплаты
<script>
  const initConfig = {
    /**
     * Значение terminalKey из личного кабинета
     */
    terminalKey: 'myTerminalKey',
    product: 'eacq',
    features: {
      payment: {
        /**
         * Если используется параметр container, скрипт встроит все доступные терминалу методы оплаты в этот элемент
         * На странице должен существовать элемент с id="paymentContainer"
         */
        container: document.getElementById('paymentContainer'),
        /**
         * Функция paymentStartCallback должна возвращать Promise который резолвит ссылку PaymentUrl (ссылка платежной формы)
         *
         * В этой функции должен происходить вызов вашего backend-сервиса с передачей туда внутреннего orderId
         * backend-сервис находит необходимые для запроса метода "Инициировать платеж" поля (такие как сумма) внутри вашей системы и отправляет запрос в v2/Init
         * PaymentUrl из v2/Init должен быть возвращен во frontend в paymentStartCallback
         *
         * Например:
         * const res = await new PaymentIntegration.Helpers().request(URL, 'POST', INIT_PARAMS);
         * return res.PaymentURL;
         *
         * Переменная PaymentIntegration содержит класс-помощник Helpers c методом request для отправки запросов на бекенд
         * В данном примере URL - это url вашего backend-сервиса, который вызовет метод "Инициировать платеж" в интернет-эквайринге и вернет PaymentURL
         *
         * @param {OverlayType} paymentType - способ оплаты выбранный пользователем
         * @returns {Promise<string>}
         */
        paymentStartCallback: async () => {
          const res = await new PaymentIntegration.Helpers().request(URL, 'POST', INIT_PARAMS); // <-- URL это url вашего backend, который вызовет метод "Инициировать платеж" в интернет-эквайринге
          return res.PaymentURL;
        },
      },
    },
  };
  function onPaymentIntegrationLoad() {
    PaymentIntegration.init(initConfig).then().catch();
  }
</script>
Пример конфигурации для платежной формы в iframe
<script> 
  const initConfig = {
    terminalKey: 'myTerminalKey', // <-- Значение terminalKey из личного кабинета
    product: 'eacq',
    features: {
       iframe: { // <-- Добавьте, если нужно встроить платежную форму в iframe
          container: document.getElementById('paymentContainer'), // <-- На странице должен существовать элемент с id="paymentContainer"
          paymentStartCallback: async () => {     
            const res = await integration.helpers.init(URL, 'POST', {}); // <-- URL это url вашего backend, который вызовет метод "Инициировать платеж" в интернет-эквайринге
            return res.paymentUrl;
          }        
       }
    }
  }
  function onPaymentIntegrationLoad() {
    PaymentIntegration.init(initConfig).then().catch();
  }
</script>

Модули

Кнопки быстрой оплаты

Поддерживаемые виджеты оплаты (WidgetType):

  • sbp — кнопка оплаты через СБП;
  • tpay — кнопка оплаты через T-Pay;
  • bnpl — кнопка оплаты Долями;
  • sberpay — кнопка оплаты через SberPay. Не отображается в WebView;
  • mirpay — кнопка оплаты через MirPay. Отображается только для устройств на ОС Android.

Есть два способа интеграции виджета:

  • Все доступные методы оплаты — добавляет все включенные в личном кабинете способы оплаты в указанный контейнер (в примере paymentContainer);
  • Ручной — позволяет добавлять разные методы оплаты в разные контейнеры.

Оба способа поддерживают установку и переопределение конфигураций.

Все доступные методы оплаты
Из глобальной конфигурации Используйте скрипт из глобальной конфигурации:
<script> 
  const initConfig = {
    terminalKey: 'myTerminalKey', // <-- Значение terminalKey из личного кабинета
    product: 'eacq',
    features: {
       payment: { // <-- Добавляем, если нужны кнопки оплаты
          container: document.getElementById('paymentContainer'), // <-- На странице должен существовать элемент с id="paymentContainer"
          paymentStartCallback: async (paymentType) => { // <-- paymentType может использоваться для сбора аналитики         
            const res = await integration.helpers.init(URL, 'POST', {}); // <-- URL это url вашего backend, который вызовет метод "Инициировать платеж" в интернет-эквайринге
            return res.paymentUrl;
          },
          config: {} // <-- Возможность переопределить поведение виджета (интерфейс PaymentIntegrationConfig,  описан в разделе "Конфигурация PaymentIntegrationConfig")
       }
    }
  }
</script>
Динамически
  1. Используйте скрипт из глобальной конфигурации:
<script> 
  const initConfig = {
    terminalKey: 'myTerminalKey', // <-- Значение terminalKey из личного кабинета
    product: 'eacq',
    features: {
       payment: {}
    }
  }
</script>
  1. Создайте и соберите скрипт платежной интеграции со всеми возможными способами оплат:
const container = document.getElementById('paymentContainer'); // Получите элемент, в который хотите встроить виджет
const MAIN_INTEGRATION_CONFIG = {}; // Конфигурация описана в разделе "Конфигурация PaymentIntegrationConfig"
const mainPaymentIntegration = await integration.payments.mountAllAvailable(container, MAIN_INTEGRATION_CONFIG); // Создание интеграции
Ручной
  1. Используйте скрипт из глобальной конфигурации:
<script> 
  const initConfig = {
    terminalKey: 'myTerminalKey', // <-- Значение terminalKey из личного кабинета
    product: 'eacq',
    features: {
       payment: {}
    }
  }
</script>
  1. Создайте экземпляр платежной интеграции (блок с кнопками оплаты):
const MAIN_INTEGRATION_NAME = 'main-integration-name'; // Любое название для идентификации конкретной интеграции
const MAIN_INTEGRATION_CONFIG = {}; // Конфигурация описана в разделе "Конфигурация PaymentIntegrationConfig"
const mainPaymentIntegration = await integration.payments.create(MAIN_INTEGRATION_NAME, MAIN_INTEGRATION_CONFIG); // Создание интеграции

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

Получение объекта платежной интеграции после смены контекста выполнения
const mainPaymentIntegration = await integration.payments.get('main-integration-name'); // Получение интеграции
  1. Смонтируйте интеграцию:
const container = document.getElementById('paymentContainer'); // Получите элемент, в который хотите встроить виджет
await mainPaymentIntegration.mount(container); // Монтируем интеграцию в контейнер
  1. Отобразите кнопки платежных методов. На этом этапе определяется, какие методы оплаты будут отображены в контейнере. Предварительно следует включить нужные методы оплаты в личном кабинете:
const widgetTypes = ['tpay']; // Доступные методы оплаты указаны в начале раздела "Кнопки быстрой оплаты"
await mainPaymentIntegration.updateWidgetTypes(widgetTypes); // Передаем нужные методы оплаты в интеграцию

Скрипт определяет, включены ли способы оплаты в личном кабинете:

  • если нужные способы оплаты отключены в личном кабинете — измените updateWidgetTypes;
  • если способ оплаты отключен в личном кабинете, но не выключен в скрипте — способ оплаты будет пропущен.
  1. Установка PaymentStartCallback. Переданная callback-функция срабатывает каждый раз, когда пользователь нажимает кнопку оплаты на платежной форме. При нажатии подразумевается вызов метода Инициировать платеж. Функция требует возврата string с PaymentUrl (например https://securepayments.tinkoff.ru/uuid).
<script>
  const initConfig = { // IntegrationInitConfig интерфейс, описан в разделе "Интерфейс глобальной конфигурации"
    ...
  }
  
  function onPaymentIntegrationLoad() {
     PaymentIntegration.init(initConfig)
       .then(async (integration) => {
  
         /*
           Переданный callback сработает каждый раз при нажатии на кнопку оплаты
         */
         await integration.payments.setPaymentStartCallback(async () => {              
           /**
            * Функция paymentStartCallback должна возвращать Promise который резолвит ссылку PaymentUrl (ссылка платежной формы)
            *
            * В этой функции должен происходить вызов вашего backend-сервиса с передачей туда внутреннего orderId
            * backend-сервис находит необходимые для запроса метода "Инициировать платеж" поля (такие как сумма) внутри вашей системы и отправляет запрос в v2/Init
            * PaymentUrl из v2/Init должен быть возвращен во frontend в paymentStartCallback
            *
            * Например:
            * const res = await new PaymentIntegration.Helpers().request(URL, 'POST', INIT_PARAMS);
            * return res.PaymentURL;
            *
            * Переменная PaymentIntegration содержит класс-помощник Helpers c методом request для отправки запросов на backend
            * В данном примере URL - это url вашего backend-сервиса, который вызовет метод "Инициировать платеж" в интернет-эквайринге и вернет PaymentURL
            *
            * @param {OverlayType} paymentType - способ оплаты выбранный пользователем
            * @returns {Promise<string>}
            */
           const res = await integration.helpers.init(URL, 'POST', {}); // <-- URL это url вашего backend, который вызовет метод "Инициировать платеж" в интернет-эквайринге
   
           return res.paymentUrl;
         });
       }
     ).catch();
  }
</script>

Особенности использования метода Инициировать платеж:

  • Не используйте вызов метода с передачей суммы в теле запроса из frontend-приложения. Всегда используйте свой backend-сервис. Если backend-сервиса нет, рекомендуем использовать наш Конструктор сайтов.
  • Обязательно передавайте connection_type = Widget в объекте DATA. В ином случае корректная работа виджета не гарантирована.

Оба способа поддерживают настройку виджета:

  1. Получите объект платежной интеграции:
const mainPaymentIntegration = await integration.payments.get('main-integration'); // Получение интеграции. При интеграции "Все доступные способы оплаты" присваивается имя "main-integration"
  1. Используйте нужные методы для передачи настроек:
Настройка отображения кнопок платежных методов
const displayParams = {
  gap: 0.375, // Расстояние между кнопками в rem
  hight: 3.5, // Высота кнопки в rem
  radius: 0.75, // Закругление кнопки в rem
  theme: {
    default: 'accent',
  }
}
await mainPaymentIntegration.updateDisplayParams(displayParams); // Передаем нужные методы оплаты в инстанс интеграции
Интерфейс метода displayParams
export interface WidgetDisplayParams {
  gap?: number;
  height?: number;
  radius?: number;
  theme?: {
    default?: ButtonTheme;
    tpay?: ButtonThemeTpay;
    mirpay?: ButtonTheme;
    sbp?: ButtonTheme;
    bnpl?: ButtonTheme;
    sberpay?: ButtonTheme;
  };
}
 
export type ButtonTheme = 'accent' | 'filled' | 'outlined';
export type ButtonThemeTpay = 'accent' | 'accent-black' | 'filled' | 'outlined';
Смена языка
await mainPaymentIntegration.setLang(LANG) // LANG = 'ru' | 'en'
Смена темы

Если метод setTheme не вызван, тема будет изменяться автоматически в соответствии с системной

await mainPaymentIntegration.setTheme(THEME) // THEME = 'dark' | 'light'
Блокировка и разблокировка кнопок

Блокирует кнопки

await mainPaymentIntegration.lock()

Разблокирует кнопки

await mainPaymentIntegration.unlock()
Удаление интеграции
await integration.payment.remove(MAIN_INTEGRATION_NAME)
// или
await mainPaymentIntegration.unmount()

Конфигурация PaymentIntegrationConfig

Интерфейс конфигурации PaymentIntegrationConfig
export interface PaymentIntegrationConfig {
  /**
   * Срабатывает после загрузки кнопок оплаты (перед отображением)
   * Может быть использован для отображения loader в контейнере
   */
  loadedCallback?: () => void;
  /**
   * Возможность переопределить значение z-index оверлея
   */
  zIndex?: number;
  scroll?: {
    /**
     * Основной элемент страницы с включенным overflow
     * Используется для блокировки скролла во время отображения оверлея
     * По умолчанию - document.body
     */
    elementForBlocking?: HTMLElement;
  };
  router?: {
    /**
     * Вызывается в момент получения события на открытие deepLink
     * Стандартное значение: (url) => {window.location.href = url}
     * @param url
     */
    deepLinkRedirectCallback?: (url: string) => Promise<void>;
    /**
     * Вызывается в момент получения события на открытие массива deepLink.
     * Требуется для перебора разных приложений, например, для sberpay
     * Стандартное значение: (links) => {
     *   window.open(
     *       `URL?links=${encodeURIComponent(JSON.stringify(links))}`,
     *       '_blank',
     *     );
     * }
     * URL - url скрипта перебора deepLink
     * @param url
     */
    deepLinksRedirectCallback?: (links: string[]) => Promise<void>;
    /**
     * Вызывается в момент получения события на редирект
     * Стандартное значение: (url) => {window.location.href = url}
     * @param url
     */
    redirectCallback?: (url: string) => Promise<void>;
  };    
 
  dialog?: {
    /**
     * Вызывается в момент получения события exit (оплата отменена пользователем)
     * Например, при нажатии кнопки «Вернуться в магазин» или закрытии модального окна
     * @param url
     */
    closedCallback?: () => Promise<void>;
  };
 
  status?: {
    /**
     * Флаг открытия overlay при смене статуса
     * Если в процессе оплаты диалог оплаты был закрыт, но произошла смена статуса
     * При значении true флага, откроется диалог и отобразится статус платежа
     * Стандартное значение: true
     */
    openOverlay?: boolean;
    /**
     * Вызывается в момент изменения статуса платежа
     * @param status
     */
    changedCallback?: (status: PaymentIntegrationStatus) => Promise<void>;
  };
 
  payment?: {
    /**
     * Вызывается в момент получения ошибки в paymentStartCallback во время инициализации платежа
     */
    failedPaymentStartCallback?: (error: Error) => Promise<void>;
  };
 
  alert?: {
    /**
     * Используется для показа алертов при ошибках
     * При отсутствии используются стандартные алерты
     * @param alert
     */
    showAlertCallback?: (alert: AlertInfo) => Promise<void>;
  };
 }
export type PaymentIntegrationStatus =
  | 'CANCELED'
  | 'EXPIRED'
  | 'NEW'
  | 'PROCESSING_ERROR'
  | 'PROCESSING'
  | 'REFUNDED'
  | 'REJECTED'
  | 'SUCCESS';

Открытие платежной формы в iframe

Есть два способа открытия в iframe:

Из глобальной конфигурации Используйте скрипт из глобальной конфигурации:
<script>    
  const initConfig = {
    /**
     * Значение terminalKey из личного кабинета
     */
    terminalKey: 'myTerminalKey',
    product: 'eacq',
    features: {
      iframe: {
        /**
         * Если используется параметр container, скрипт встроит iframe в этот элемент
         * На странице должен существовать элемент с id="paymentContainer"
         */
        container: document.getElementById('paymentContainer'),         
        /**
         * Функция paymentStartCallback должна возвращать Promise который резолвит ссылку PaymentUrl (ссылка платежной формы)
         *
         * В этой функции должен происходить вызов вашего backend-сервиса с передачей туда внутреннего orderId
         * backend-сервис находит необходимые для запроса метода "Инициировать платеж" поля (такие как сумма) внутри вашей системы и отправляет запрос в v2/Init
         * PaymentUrl из v2/Init должен быть возвращен во frontend в paymentStartCallback
         *
         * Например:
         * const res = await new PaymentIntegration.Helpers().request(URL, 'POST', INIT_PARAMS);
         * return res.PaymentURL;
         *
         * Переменная PaymentIntegration содержит класс-помощник Helpers c методом request для отправки запросов на backend
         * В данном примере URL - это url вашего backend-сервиса, который вызовет метод "Инициировать платеж" в интернет-эквайринге и вернет PaymentURL
         *
         * @param {OverlayType} paymentType - способ оплаты, выбранный пользователем
         * @returns {Promise<string>}
         */
        paymentStartCallback: async () => {
          const res = await new PaymentIntegration.Helpers().request(URL, 'POST', INIT_PARAMS);
          return res.PaymentURL;
        },
      },
    },
  };
  
  function onPaymentIntegrationLoad() {
    PaymentIntegration.init(initConfig).then().catch();
  }
</script>
Динамически
  1. Используйте скрипт из глобальной конфигурации:
<script> 
  const initConfig = {
    terminalKey: 'myTerminalKey', // <-- Значение terminalKey из личного кабинета
    product: 'eacq',
    features: {
       iframe: {}
    }
  }
</script>
  1. Создайте экземпляр iframe интеграции:
const MAIN_INTEGRATION_NAME = 'main-integration-name'; // Любое название для идентификации конкретной интеграции
const iframeConfig = {}; // Конфигурация описана разделе "Конфигурация IframeIntegrationConfig"
const mainPaymentIntegration = await integration.iframe.create(MAIN_INTEGRATION_NAME, iframeConfig); // Создание интеграции

На этом этапе создается объект интеграции iframe, форма оплаты отражена не будет. Интеграция не привязана ни к какому контейнеру. Такой подход позволяет использовать несколько разных интеграций одновременно.

  1. Смонтируйте интеграцию:
const container = document.getElementById('paymentContainer'); // Получаем элемент, в который хотите встроить платежную форму
const res = await integration.helpers.init(URL,'POST', INIT_PARAMS) // Инициируем платеж или получение paymentUrl из вашего backend-сервиса
await mainPaymentIntegration.mount(container, res.paymentUrl); // Монтируем интеграцию в контейнер

Особенности использования метода Инициировать платеж:

  • Не используйте вызов метода с передачей суммы в теле запроса из frontend-приложения. Всегда используйте свой backend-сервис. Если backend-сервиса нет, рекомендуем использовать наш Конструктор сайтов

Оба способа поддерживают настройку платежной формы в iframe:

  1. Получите объект iframe-интеграции:
const mainPaymentIntegration = await integration.iframe.get('main-integration-name'); // Получение интеграции. При использовании метода "Из глобальной конфигурации" присваивается имя "main-integration"
  1. Используйте необходимые методы для передачи настроек:
Смена языка
await mainPaymentIntegration.setLang(LANG) // LANG = 'ru' | 'en'
Смена темы

Если метод setTheme не вызван, тема будет изменяться автоматически в соответствии с системной

await mainPaymentIntegration.setTheme(THEME) // THEME = 'dark' | 'light'
Удаление интеграции
await integration.iframe.remove(MAIN_INTEGRATION_NAME)
// или
await mainPaymentIntegration.unmount()

Конфигурация IframeIntegrationConfig

Интерфейс конфигурации IframeIntegrationConfig
export interface IframeIntegrationConfig {
  router?: {
    /**
     * Вызывается в момент получения события на открытие deepLink
     * Стандартное значение: (url) => {window.location.href = url}
     * @param url
     */
    deepLinkRedirectCallback?: (url: string) => Promise<void>;
    /**
     * Вызывается в момент получения события на открытие массива deepLink.
     * Требуется для перебора разных приложений, например, для sberpay
     * Стандартное значение: (links) => {
     *   window.open(
     *       `URL?links=${encodeURIComponent(JSON.stringify(links))}`,
     *       '_blank',
     *     );
     * }
     * URL - url скрипта перебора deepLink
     * @param url
     */
    deepLinksRedirectCallback?: (links: string[]) => Promise<void>;
    /**
     * Вызывается в момент получения события на редирект
     * Стандартное значение: (url) => {window.location.href = url}
     * @param url
     */
    redirectCallback?: (url: string) => Promise<void>;
  };
  language?: {
    /**
     * Вызывается в момент изменения языка из платежной формы
     * @param status
     */
    changedCallback?: (lang: IntegrationLang) => Promise<void>;
  };
  status?: {
    /**
     * Вызывается в момент изменения статуса платежа
     * @param status
     */
    changedCallback?: (status: PaymentIntegrationStatus) => Promise<void>;
  };
}
export type PaymentIntegrationStatus =
  | 'CANCELED'
  | 'EXPIRED'
  | 'NEW'
  | 'PROCESSING_ERROR'
  | 'PROCESSING'
  | 'REFUNDED'
  | 'REJECTED'
  | 'SUCCESS';

Платежная форма во вложенном iframe

Интеграция платежной формы во вложенном iframe

Бывают случаи, когда приложение используется внутри iframe, который находится внутри другого iframe. Для работы виджета, нужно встроить скрипт и инициализировать его во всех вложенных iframe:

  1. Встройте и инициализируйте скрипт в основную (родительскую страницу):
<iframe id="payment-form-iframe"></iframe
// Загрузка и инициализация скрипта (js код)
await mainPaymentIntegration.connect(document.getElementById('payment-form-iframe'))
  1. Встройте и инициализируйте скрипт во вложенных iframe. В конечном вложенном iframe, подключение виджета аналогично инструкции в разделе "Открытие платежной формы в iframe". Каждый «промежуточный» скрипт будет перенаправлять сообщения в следующий iframe.
<iframe id="payment-form-iframe"></iframe>
// Загрузка и инициализация скрипта (js rjl)
await innerPaymentIntegration.connect(document.getElementById('payment-form-iframe')) // Если iframe создан

Примеры полной конфигурации

Виджет с кнопками оплаты (integration.payments)

Все доступные способы оплаты
<div id="paymentContainer"></div>
<script>
  /**
   * URL - это url вашего backend-сервиса, который вызовет метод "Инициировать платеж" в интернет эквайринге и вернет PaymentURL
   * @type {string}
   */
  const URL = 'https://Init';
  /**
   * INIT_PARAMS - это необходимые параметры тела запроса, которые принимает ваш backend-сервис
   * @type object
   */
  const INIT_PARAMS = {
    get OrderId() {
      return `${Date.now()}${Math.floor(Math.random() * 100)}`; // Случайное число, используется для примера
    }
  };
</script>
<script
  async
  onload="onPaymentIntegrationLoad()"
  src="https://acq-paymentform-integrationjs.t-static.ru/integration.js"
></script>
<script>
  const initConfig = {
    /**
     * Значение terminalKey из личного кабинета
     */
    terminalKey: 'myTerminalKey',
    product: 'eacq',
    features: {
      payment: {
        container: document.getElementById('paymentContainer'),               
        paymentStartCallback: async () => {
          const res = await new PaymentIntegration.Helpers().request(URL, 'POST', INIT_PARAMS);
          return res.PaymentURL;
        },
      },
    },
  };
  
  function onPaymentIntegrationLoad() {
    PaymentIntegration.init(initConfig).then().catch();
  }
</script>
Ручной, с включенными tpay, sbp и mirpay
<div id="paymentContainer"></div>
<script>
  /**
   * URL - это url вашего backend-сервиса, который вызовет метод "Инициировать платеж" в интернет-эквайринге и вернет PaymentURL
   * @type {string}
   */
  const URL = 'https://Init';
  /**
   * INIT_PARAMS - это необходимые параметры тела запроса, которые принимает ваш backend-сервис
   * @type object
   */
  const INIT_PARAMS = {
    get OrderId() {
      return `${Date.now()}${Math.floor(Math.random() * 100)}`; // Случайное число, используется для примера
    }
  };
</script>
<script
  async
  onload="onPaymentIntegrationLoad()"
  src="https://acq-paymentform-integrationjs.t-static.ru/integration.js"
></script>
<script>
  const initConfig = {
    /**
     * Значение terminalKey из личного кабинета
     */
    terminalKey: 'myTerminalKey',
    product: 'eacq',
    features: {
      payment: {},
    },
  };
  
  function onPaymentIntegrationLoad() {
    PaymentIntegration.init(initConfig)
      .then(async (integration) => {
        const MAIN_INTEGRATION_NAME = 'main-integration-name'; // Любое название для идентификации конкретной интеграции
        const MAIN_INTEGRATION_CONFIG = {}; // Конфигурация описана в разделе "Конфигурации PaymentIntegrationConfig"
        const mainPaymentIntegration = await integration.payments.create(
          MAIN_INTEGRATION_NAME,
          MAIN_INTEGRATION_CONFIG,
        ); // Создание интеграции
  
        const container = document.getElementById('paymentContainer'); // Получите элемент, в который хотите встроить виджет
        await mainPaymentIntegration.mount(container); // Монтируем интеграцию в контейнер
  
        await integration.payments.setPaymentStartCallback(async () => {
          const res = await new PaymentIntegration.Helpers().request(URL, 'POST', INIT_PARAMS);
  
          return res.paymentUrl;
        });
  
        const widgetTypes = ['mirpay', 'sbp', 'tpay']; // Доступные методы оплаты
        await mainPaymentIntegration.updateWidgetTypes(widgetTypes); // Передаем нужные методы оплаты в интеграцию
      })
      .catch();
  }
</script>

Платежная форма в iframe

Из глобальной конфигурации
<div id="paymentContainer"></div>
<script>
  /**
   * URL - это url вашего backend-сервиса, который вызовет метод "Инициировать платеж" в интернет-эквайринге и вернет PaymentURL
   * @type {string}
   */
  const URL = 'https://Init';
  /**
   * INIT_PARAMS - это необходимые параметры тела запроса, которые принимает ваш backend-сервис
   * @type object
   */
  const INIT_PARAMS = {
    get OrderId() {
      return `${Date.now()}${Math.floor(Math.random() * 100)}`; // Случайное число, используется для примера
    }
  };
</script>
<script
  async
  onload="onPaymentIntegrationLoad()"
  src="https://acq-paymentform-integrationjs.t-static.ru/integration.js"
></script>
<script>
  const initConfig = {
    /**
     * Значение terminalKey из личного кабинета
     */
    terminalKey: 'myTerminalKey',
    product: 'eacq',
    features: {
      iframe: {
        container: document.getElementById('paymentContainer'),          
        paymentStartCallback: async () => {
          const res = await new PaymentIntegration.Helpers().request(URL, 'POST', INIT_PARAMS);
          return res.PaymentURL;
        },
      },
    },
  };
  
  function onPaymentIntegrationLoad() {
    PaymentIntegration.init(initConfig).then().catch();
  }
</script>
Динамически
<div id="paymentContainer"></div>
<script>
  /**
   * URL - это url вашего backend-сервиса, который вызовет метод "Инициировать платеж" в интернет-эквайринге и вернет PaymentURL
   * @type {string}
   */
  const URL = 'https://Init';
  /**
   * INIT_PARAMS - это необходимые параметры тела запроса, которые принимает ваш backend-сервис
   * @type object
   */
  const INIT_PARAMS = {
    get OrderId() {
      return `${Date.now()}${Math.floor(Math.random() * 100)}`; // Случайное число, используется для примера
    },
    TerminalKey: 'myTerminalKey',
    Amount: 10000,
    Description: 'test payment',
  };
</script>
<script
  async
  onload="onPaymentIntegrationLoad()"
  src="https://acq-paymentform-integrationjs.t-static.ru/integration.js"
></script>
<script>
  const initConfig = {
    /**
     * Значение terminalKey из личного кабинета
     */
    terminalKey: 'myTerminalKey',
    product: 'eacq',
    features: {
      iframe: {}
    },
  };
  
  function onPaymentIntegrationLoad() {
    PaymentIntegration.init(initConfig)
      .then(async (integration) => {
        const MAIN_INTEGRATION_NAME = 'main-integration-name';
        const iframeConfig = {};
        const mainPaymentIntegration = await integration.iframe.create(MAIN_INTEGRATION_NAME, iframeConfig);
  
        const container = document.getElementById('paymentContainer');
  
        const res = await integration.helpers.init(URL, 'POST', INIT_PARAMS);
  
        await mainPaymentIntegration.mount(container, res.PaymentURL);
      })
      .catch();
  }
</script>
Платежная форма во вложенном iframe
  1. Добавьте и инициализируйте скрипт на основном сайте:
<iframe id="first-iframe" src="https://IFRAME_FIRST_URL"></div>
<script
  async
  onload="onPaymentIntegrationLoad()"
  src="https://acq-paymentform-integrationjs.t-static.ru/integration.js"
></script>
<script>
  const initConfig = {
    /**
     * Значение terminalKey из личного кабинета
     */
    terminalKey: 'myTerminalKey',
    product: 'eacq',
    features: {
      iframe: {},
    },
  };
  
  function onPaymentIntegrationLoad() {
    PaymentIntegration.init(initConfig)
      .then(async (integration) => {
        const MAIN_INTEGRATION_NAME = 'main-integration-name';
        const iframeConfig = {};
        const mainPaymentIntegration = await integration.iframe.create(MAIN_INTEGRATION_NAME, iframeConfig);
  
        const iframe = document.getElementById('first-iframe');
  
        await mainPaymentIntegration.connect(iframe);
      })
      .catch();
  }
</script>
  1. Подключите для вложенного iframe скрипт по инструкции в разделе "Открытие платежной формы в iframe".