Добавить REST-обработчик платежной системы sale.paysystem.handler.add

Выберите инструмент для разработки с AI-агентом:

  • используйте Битрикс24 Вайбкод, чтобы создать приложение для Битрикс24 по описанию задачи без знания языков программирования. Агент напишет код и разместит приложение на сервере без ручной настройки хостинга
  • используйте MCP-сервер, чтобы разрабатывать интеграцию через REST API в своем проекте. Агент будет обращаться к официальной REST-документации

Scope: pay_system

Кто может выполнять метод: администратор CRM (право «Разрешить изменять настройки»)

Метод добавляет REST-обработчик платежной системы.

Параметры метода

Обязательные параметры отмечены *

Название
тип

Описание

NAME*
string

Название REST-обработчика

SORT
integer

Сортировка. По умолчанию 100

CODE*
string

Код REST-обработчика. Должен быть уникальным среди всех обработчиков

SETTINGS*
object

Настройки обработчика (подробное описание приведено ниже)

Параметр SETTINGS

Обязательные параметры отмечены *

В зависимости от используемого режима работы обязательно наличие одного из следующих параметров: FORM_DATA, CHECKOUT_DATA, IFRAME_DATA.

Название
тип

Описание

CODES*
object

Список параметров обработчика. Ключами являются коды параметров (string), значениями — описания параметров (подробное описание приведено ниже).

Значения параметров будут доступны администратору для заполнения в настройках созданной платежной системы. Их можно задать при добавлении платежной системы в методе sale.paysystem.add в параметре SETTINGS и изменить при помощи метода sale.paysystem.settings.update

FORM_DATA
object

Настройки формы при использовании режима работы в форме

CHECKOUT_DATA
object

Настройки режима Checkout (создание заказа на стороне сервиса и переход покупателя на эту страницу для оплаты)

IFRAME_DATA
object

Настройки страницы, выводимой в iframe на сайте продавца на странице оплаты

CLIENT_TYPE
string

Тип покупателей, с которыми может работать обработчик. Доступные значения:

  • b2c — физические лица
  • b2b — юридические лица

Значение по умолчанию b2c

CURRENCY
crm_currency.CURRENCY[]

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

Параметр CODES

Название
тип

Описание

NAME
string

Название параметра

DESCRIPTION
string

Описание параметра

SORT
integer

Сортировка

GROUP
string

Код группы, к которой относится параметр

DEFAULT
object

Описание значения по умолчанию (подробное описание приведено ниже)

INPUT
object

Объект, описывающий поле ввода. Структура объекта содержит параметр TYPE — тип поля. Поддерживаемые поля:

  • STRING — строка
  • Y/N — флажок
  • ENUM — список

Параметр DEFAULT

Название
тип

Описание

PROVIDER_KEY
string

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

PROVIDER_VALUE
string

Код значения, которое будет взято у провайдера. Возможные значения ключа приведены ниже

Возможные значения ключа PROVIDER_KEY

Название

Описание

ORDER

Заказ

PROPERTY

Свойства счета

PAYMENT

Оплата

USER

Пользователь

VALUE

Произвольное значение типа строка

Y\N

Флажок

Возможные значения ключа PROVIDER_VALUE

Название

Описание

ORDER

  • ID — идентификатор (для счетов соответствует ID счета)
  • ACCOUNT_NUMBER — номер заказа (для счетов соответствует номеру счета)
  • ORDER_TOPIC — тема
  • DATE_INSERT — дата заказа (для счетов соответствует дате счета)
  • DATE_INSERT_DATE — дата заказа без времени (для счетов соответствует дате счета)
  • DATE_BILL — дата и время выставления
  • DATE_BILL_DATE — дата выставления
  • DATE_PAY_BEFORE — срок оплаты
  • SHOULD_PAY — сумма счета (для счетов соответствует сумме счета)
  • CURRENCY — валюта
  • PRICE — стоимость заказа (для счетов соответствует стоимости счета)
  • PRICE_DELIVERY — стоимость доставки
  • DISCOUNT_VALUE — величина скидки
  • USER_ID — код покупателя
  • PAY_SYSTEM_ID — код платежной системы
  • DELIVERY_ID — код службы доставки
  • TAX_VALUE — налог
  • USER_DESCRIPTION — комментарий

PAYMENT

  • ID — идентификатор
  • ACCOUNT_NUMBER — номер оплаты
  • DATE_BILL — дата и время выставления
  • DATE_BILL_DATE — дата выставления без времени
  • SUM — сумма счета
  • CURRENCY — валюта
  • PAID — оплачено
  • DATE_PAID — дата оплаты
  • PAY_SYSTEM_ID — код платежной системы
  • PAY_VOUCHER_NUM — номер ваучера
  • PAY_VOUCHER_DATE — дата ваучера
  • DATE_PAY_BEFORE — оплатить до
  • XML_ID — индентификатор XML
  • PAY_SYSTEM_NAME — название платежной системы
  • COMPANY_ID — код компании
  • PAY_RETURN_NUM — номер возврата
  • PAY_RETURN_DATE — дата возврата
  • PAY_RETURN_COMMENT — коментарий возврата

USER

  • ID — код покупателя,
  • LOGIN — логин
  • NAME — имя
  • SECOND_NAME — отчество
  • LAST_NAME — фамилия
  • EMAIL — EMail
  • PERSONAL_PROFESSION — профессия
  • PERSONAL_WWW — персональный веб-сайт
  • PERSONAL_ICQ — номер ICQ
  • PERSONAL_GENDER — пол
  • PERSONAL_FAX — номер факса
  • PERSONAL_MOBILE — номер телефона
  • PERSONAL_STREET — адрес
  • PERSONAL_MAILBOX — почтовый ящик
  • PERSONAL_CITY — город
  • PERSONAL_STATE — штат
  • PERSONAL_ZIP — индекс
  • PERSONAL_COUNTRY — страна
  • WORK_COMPANY — компания
  • WORK_DEPARTMENT — отдел
  • WORK_POSITION — должность
  • WORK_WWW — сайт компании
  • WORK_PHONE — рабочий телефон
  • WORK_FAX — рабочий факс
  • WORK_STREET — адрес компании
  • WORK_MAILBOX — рабочий почтовый ящик
  • WORK_CITY — город компании
  • WORK_STATE — штат компании
  • WORK_ZIP — индекс компании
  • WORK_COUNTRY — страна компании

Режим работы в форме

При добавлении обработчика в параметре SETTINGS нужно передать параметр FORM_DATA. Способ подходит, если от покупателя ничего не нужно запрашивать либо же нужно запросить небольшой набор данных.

Поля формы автоматически выводятся в соответствии с дизайном страницы оплаты.

Данные формы (значения FIELDS из FORM_DATA) будут отправлены на ACTION_URI. Помимо данных, определенных в FORM_DATA, с формой также будут отправлены два системных ключа:

Название
тип

Описание

BX_PAYSYSTEM_ID
sale_paysystem.ID

Идентификатор платежной системы, через которую совершается оплата. Может быть использован для вызова метода оплаты sale.paysystem.pay.payment

BX_RETURN_URL
string

Адрес сайта магазина, на который будет перенаправлен пользователь

Параметры, передаваемые при добавлении обработчика в массиве FORM_DATA

Обязательные параметры отмечены *

Название
тип

Описание

ACTION_URI*
string

URL, на который отправляется форма

METHOD
string

HTTP-метод, используемый при отправке формы. По умолчанию пусто, при этом используется метод GET

FIELDS
object

Описание полей формы (подробное описание приведено ниже)

PARAMS
object

Описание полей формы. Параметр является устаревшим, рекомендуется использовать параметр FIELDS.

Представляет собой карту соответствия между названиями полей в форме (string) и кодами параметров обработчика (string): [код_поля => код_параметра_обработчика, ...]

Поля добавляются в форму как элементы типа hidden.

Если передавать и FIELDS, и PARAMS, то будет использоваться только FIELDS

Параметр FIELDS

Обязательные параметры отмечены *

Представляет собой массив описаний полей, выводимых в форме и отправляемых на ACTION_URI. Ключом является код поля, используемый в качестве названия поля в форме. В качестве значений используется объект параметров поля.

Название
тип

Описание

CODE*
string|object

Если значение ключа CODE имеет тип string, то это значение будет использоваться для поиска соответствия между полями формы и параметрами обработчика (CODES). Название и значение будут получены из параметров обработчика.

Если в ключе CODE передан object, то в форме оплаты будет добавлено поле согласно описанию в содержимом массива (подробное описание приведено ниже)

VISIBLE
string

Показывается ли поле в форме для ввода. Доступные значения:

  • Y — да
  • N — нет

По умолчанию значение N, поле выводится в форме как hidden

Параметр CODE

Название
тип

Описание

NAME
string

Название поля

INPUT
object

Описание поля ввода. Содержит ключ TYPE — тип поля, который может принимать значения:

  • STRING — строка
  • Y/N — флажок

Примеры кода

Как использовать примеры в документации

curl -X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"NAME":"Обработчик.Rest FORM","CODE":"resthandlerform","SORT":100,"SETTINGS":{"CURRENCY":["RUB"],"CLIENT_TYPE":"b2c","FORM_DATA":{"ACTION_URI":"http://example.com/payment_form.php","METHOD":"POST","FIELDS":{"phone":{"VISIBLE":"Y","CODE":{"NAME":"Номер телефона","TYPE":"STRING"}},"selection":{"VISIBLE":"Y","CODE":{"NAME":"Иллюзия выбора","INPUT":{"TYPE":"Y/N"}}},"paymentId":{"CODE":"PAYMENT_ID","VISIBLE":"Y"},"serviceid":{"CODE":"REST_SERVICE_ID"}}},"CODES":{"REST_SERVICE_ID":{"NAME":"Номер магазина","DESCRIPTION":"Номер магазина","SORT":"100"},"REST_SERVICE_KEY":{"NAME":"Секретный ключ","DESCRIPTION":"Секретный ключ","SORT":"300"},"PAYMENT_ID":{"NAME":"Номер оплаты","SORT":"400","GROUP":"PAYMENT","DEFAULT":{"PROVIDER_KEY":"PAYMENT","PROVIDER_VALUE":"ACCOUNT_NUMBER"}},"PAYMENT_SHOULD_PAY":{"NAME":"Сумма оплаты","SORT":"600","GROUP":"PAYMENT","DEFAULT":{"PROVIDER_KEY":"PAYMENT","PROVIDER_VALUE":"SUM"}},"PS_CHANGE_STATUS_PAY":{"NAME":"Автоматическая смена статуса оплаты","SORT":"700","INPUT":{"TYPE":"Y/N"}},"PAYMENT_BUYER_ID":{"NAME":"Код покупателя","SORT":"1000","GROUP":"PAYMENT","DEFAULT":{"PROVIDER_KEY":"ORDER","PROVIDER_VALUE":"USER_ID"}},"PS_WORK_MODE":{"NAME":"Режим работы платёжной системы","SORT":"1100","INPUT":{"TYPE":"ENUM","OPTIONS":{"TEST":"Тестовый","REGULAR":"Рабочий"}}}}}' \
https://**put_your_bitrix24_address**/rest/**put_your_user_id_here**/**put_your_webhook_here**/sale.paysystem.handler.add
curl -X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"NAME":"Обработчик.Rest FORM","CODE":"resthandlerform","SORT":100,"SETTINGS":{"CURRENCY":["RUB"],"CLIENT_TYPE":"b2c","FORM_DATA":{"ACTION_URI":"http://example.com/payment_form.php","METHOD":"POST","FIELDS":{"phone":{"VISIBLE":"Y","CODE":{"NAME":"Номер телефона","TYPE":"STRING"}},"selection":{"VISIBLE":"Y","CODE":{"NAME":"Иллюзия выбора","INPUT":{"TYPE":"Y/N"}}},"paymentId":{"CODE":"PAYMENT_ID","VISIBLE":"Y"},"serviceid":{"CODE":"REST_SERVICE_ID"}}},"CODES":{"REST_SERVICE_ID":{"NAME":"Номер магазина","DESCRIPTION":"Номер магазина","SORT":"100"},"REST_SERVICE_KEY":{"NAME":"Секретный ключ","DESCRIPTION":"Секретный ключ","SORT":"300"},"PAYMENT_ID":{"NAME":"Номер оплаты","SORT":"400","GROUP":"PAYMENT","DEFAULT":{"PROVIDER_KEY":"PAYMENT","PROVIDER_VALUE":"ACCOUNT_NUMBER"}},"PAYMENT_SHOULD_PAY":{"NAME":"Сумма оплаты","SORT":"600","GROUP":"PAYMENT","DEFAULT":{"PROVIDER_KEY":"PAYMENT","PROVIDER_VALUE":"SUM"}},"PS_CHANGE_STATUS_PAY":{"NAME":"Автоматическая смена статуса оплаты","SORT":"700","INPUT":{"TYPE":"Y/N"}},"PAYMENT_BUYER_ID":{"NAME":"Код покупателя","SORT":"1000","GROUP":"PAYMENT","DEFAULT":{"PROVIDER_KEY":"ORDER","PROVIDER_VALUE":"USER_ID"}},"PS_WORK_MODE":{"NAME":"Режим работы платёжной системы","SORT":"1100","INPUT":{"TYPE":"ENUM","OPTIONS":{"TEST":"Тестовый","REGULAR":"Рабочий"}}}},"auth":"**put_access_token_here**"}' \
https://**put_your_bitrix24_address**/rest/sale.paysystem.handler.add
// This snippet is an ES module: top-level await requires type="module" or a bundler.
// $b24 is an already-initialized SDK instance (see the SDK "Get started" guide).
import { Text } from '@bitrix24/b24jssdk'
import type { B24Frame } from '@bitrix24/b24jssdk'

declare const $b24: B24Frame

try {
  const response = await $b24.actions.v2.call.make<number>({
    method: 'sale.paysystem.handler.add',
    params: {
      NAME: 'Rest handler FORM',
      CODE: 'resthandlerform',
      SORT: 100,
      SETTINGS: {
        CURRENCY: ['RUB'],
        CLIENT_TYPE: 'b2c',
        FORM_DATA: {
          ACTION_URI: 'http://example.com/payment_form.php',
          METHOD: 'POST',
          FIELDS: {
            phone: {
              VISIBLE: 'Y',
              CODE: {
                NAME: 'Phone number',
                TYPE: 'STRING',
              },
            },
            selection: {
              VISIBLE: 'Y',
              CODE: {
                NAME: 'Illusion of choice',
                INPUT: {
                  TYPE: 'Y/N',
                },
              },
            },
            paymentId: {
              CODE: 'PAYMENT_ID',
              VISIBLE: 'Y',
            },
            serviceid: {
              CODE: 'REST_SERVICE_ID',
            },
          },
        },
        CODES: {
          REST_SERVICE_ID: {
            NAME: 'Shop ID',
            DESCRIPTION: 'Shop ID',
            SORT: '100',
          },
          REST_SERVICE_KEY: {
            NAME: 'Secret key',
            DESCRIPTION: 'Secret key',
            SORT: '300',
          },
          PAYMENT_ID: {
            NAME: 'Payment number',
            SORT: '400',
            GROUP: 'PAYMENT',
            DEFAULT: {
              PROVIDER_KEY: 'PAYMENT',
              PROVIDER_VALUE: 'ACCOUNT_NUMBER',
            },
          },
          PAYMENT_SHOULD_PAY: {
            NAME: 'Payment amount',
            SORT: '600',
            GROUP: 'PAYMENT',
            DEFAULT: {
              PROVIDER_KEY: 'PAYMENT',
              PROVIDER_VALUE: 'SUM',
            },
          },
          PS_CHANGE_STATUS_PAY: {
            NAME: 'Automatic payment status change',
            SORT: '700',
            INPUT: {
              TYPE: 'Y/N',
            },
          },
          PAYMENT_BUYER_ID: {
            NAME: 'Buyer ID',
            SORT: '1000',
            GROUP: 'PAYMENT',
            DEFAULT: {
              PROVIDER_KEY: 'ORDER',
              PROVIDER_VALUE: 'USER_ID',
            },
          },
          PS_WORK_MODE: {
            NAME: 'Payment system work mode',
            SORT: '1100',
            INPUT: {
              TYPE: 'ENUM',
              OPTIONS: {
                TEST: 'Test',
                REGULAR: 'Live',
              },
            },
          },
        },
      },
    },
    requestId: Text.getUuidRfc4122()
  })

  // The payload is available only on a successful response
  if (!response.isSuccess) {
    console.error(response.getErrorMessages().join('; '))
  } else {
    const result = response.getData()!.result
    console.info('Handler added with ID:', result)
  }
} catch (error) {
  // Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
  console.error(error)
}
<!-- Load the SDK (UMD build); it is exposed as the global B24Js -->
<script src="https://unpkg.com/@bitrix24/b24jssdk@1/dist/umd/index.min.js"></script>
<script>
  async function addPaySystemHandlerForm() {
    try {
      // Initialize the SDK inside a Bitrix24 frame
      const $b24 = await B24Js.initializeB24Frame()

      const response = await $b24.actions.v2.call.make({
        method: 'sale.paysystem.handler.add',
        params: {
          NAME: 'Rest handler FORM',
          CODE: 'resthandlerform',
          SORT: 100,
          SETTINGS: {
            CURRENCY: ['RUB'],
            CLIENT_TYPE: 'b2c',
            FORM_DATA: {
              ACTION_URI: 'http://example.com/payment_form.php',
              METHOD: 'POST',
              FIELDS: {
                phone: {
                  VISIBLE: 'Y',
                  CODE: {
                    NAME: 'Phone number',
                    TYPE: 'STRING',
                  },
                },
                selection: {
                  VISIBLE: 'Y',
                  CODE: {
                    NAME: 'Illusion of choice',
                    INPUT: {
                      TYPE: 'Y/N',
                    },
                  },
                },
                paymentId: {
                  CODE: 'PAYMENT_ID',
                  VISIBLE: 'Y',
                },
                serviceid: {
                  CODE: 'REST_SERVICE_ID',
                },
              },
            },
            CODES: {
              REST_SERVICE_ID: {
                NAME: 'Shop ID',
                DESCRIPTION: 'Shop ID',
                SORT: '100',
              },
              REST_SERVICE_KEY: {
                NAME: 'Secret key',
                DESCRIPTION: 'Secret key',
                SORT: '300',
              },
              PAYMENT_ID: {
                NAME: 'Payment number',
                SORT: '400',
                GROUP: 'PAYMENT',
                DEFAULT: {
                  PROVIDER_KEY: 'PAYMENT',
                  PROVIDER_VALUE: 'ACCOUNT_NUMBER',
                },
              },
              PAYMENT_SHOULD_PAY: {
                NAME: 'Payment amount',
                SORT: '600',
                GROUP: 'PAYMENT',
                DEFAULT: {
                  PROVIDER_KEY: 'PAYMENT',
                  PROVIDER_VALUE: 'SUM',
                },
              },
              PS_CHANGE_STATUS_PAY: {
                NAME: 'Automatic payment status change',
                SORT: '700',
                INPUT: {
                  TYPE: 'Y/N',
                },
              },
              PAYMENT_BUYER_ID: {
                NAME: 'Buyer ID',
                SORT: '1000',
                GROUP: 'PAYMENT',
                DEFAULT: {
                  PROVIDER_KEY: 'ORDER',
                  PROVIDER_VALUE: 'USER_ID',
                },
              },
              PS_WORK_MODE: {
                NAME: 'Payment system work mode',
                SORT: '1100',
                INPUT: {
                  TYPE: 'ENUM',
                  OPTIONS: {
                    TEST: 'Test',
                    REGULAR: 'Live',
                  },
                },
              },
            },
          },
        },
        requestId: B24Js.Text.getUuidRfc4122()
      })

      // The payload is available only on a successful response
      if (!response.isSuccess) {
        console.error(response.getErrorMessages().join('; '))
        return
      }

      const result = response.getData().result
      console.info('Handler added with ID:', result)
    } catch (error) {
      // Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
      console.error(error)
    }
  }

  document.addEventListener('DOMContentLoaded', addPaySystemHandlerForm)
</script>
from b24pysdk.errors import BitrixAPIError, BitrixSDKException

settings = {
    "CURRENCY": [
        "RUB",
    ],
    "CLIENT_TYPE": "b2c",
    "FORM_DATA": {
        "ACTION_URI": "http://example.com/payment_form.php",
        "METHOD": "POST",
        "FIELDS": {
            "phone": {
                "VISIBLE": "Y",
                "CODE": {
                    "NAME": "Phone number",
                    "TYPE": "STRING",
                },
            },
            "selection": {
                "VISIBLE": "Y",
                "CODE": {
                    "NAME": "Illusion of choice",
                    "INPUT": {
                        "TYPE": "Y/N",
                    },
                },
            },
            "paymentId": {
                "CODE": "PAYMENT_ID",
                "VISIBLE": "Y",
            },
            "serviceid": {
                "CODE": "REST_SERVICE_ID",
            },
        },
    },
    "CODES": {
        "REST_SERVICE_ID": {
            "NAME": "Shop ID",
            "DESCRIPTION": "Shop ID",
            "SORT": "100",
        },
        "REST_SERVICE_KEY": {
            "NAME": "Secret key",
            "DESCRIPTION": "Secret key",
            "SORT": "300",
        },
        "PAYMENT_ID": {
            "NAME": "Payment number",
            "SORT": "400",
            "GROUP": "PAYMENT",
            "DEFAULT": {
                "PROVIDER_KEY": "PAYMENT",
                "PROVIDER_VALUE": "ACCOUNT_NUMBER",
            },
        },
    },
}

try:
    bitrix_response = client.sale.paysystem.handler.add(
        name="Rest handler FORM",
        code="resthandlerform",
        sort=100,
        settings=settings,
    ).response
    result = bitrix_response.result
    print(result)
except BitrixAPIError as error:
    print(
        "Ошибка Bitrix API",
        f"error: {error.error}",
        f"error_description: {error.error_description}",
        sep="\n",
    )
except BitrixSDKException as error:
    print(f"Ошибка Bitrix SDK: {error.message}")
except Exception as error:
    print(f"Непредвиденная ошибка: {error}")
try {
    $response = $b24Service
        ->core
        ->call(
            'sale.paysystem.handler.add',
            [
                'NAME'     => 'Обработчик.Rest FORM',
                'CODE'     => 'resthandlerform',
                'SORT'     => 100,
                'SETTINGS' => [
                    'CURRENCY'    => ['RUB'],
                    'CLIENT_TYPE' => 'b2c',
                    'FORM_DATA'   => [
                        'ACTION_URI' => 'http://example.com/payment_form.php',
                        'METHOD'     => 'POST',
                        'FIELDS'     => [
                            'phone'     => [
                                'VISIBLE' => 'Y',
                                'CODE'    => [
                                    'NAME' => 'Номер телефона',
                                    'TYPE' => 'STRING',
                                ],
                            ],
                            'selection' => [
                                'VISIBLE' => 'Y',
                                'CODE'    => [
                                    'NAME' => 'Иллюзия выбора',
                                    'INPUT' => [
                                        'TYPE' => 'Y/N',
                                    ],
                                ],
                            ],
                            'paymentId' => [
                                'CODE'    => 'PAYMENT_ID',
                                'VISIBLE' => 'Y',
                            ],
                            'serviceid' => [
                                'CODE' => 'REST_SERVICE_ID',
                            ],
                        ],
                    ],
                    'CODES'      => [
                        'REST_SERVICE_ID'    => [
                            'NAME'        => 'Номер магазина',
                            'DESCRIPTION' => 'Номер магазина',
                            'SORT'        => '100',
                        ],
                        'REST_SERVICE_KEY'   => [
                            'NAME'        => 'Секретный ключ',
                            'DESCRIPTION' => 'Секретный ключ',
                            'SORT'        => '300',
                        ],
                        'PAYMENT_ID'         => [
                            'NAME'    => 'Номер оплаты',
                            'SORT'    => '400',
                            'GROUP'   => 'PAYMENT',
                            'DEFAULT' => [
                                'PROVIDER_KEY'   => 'PAYMENT',
                                'PROVIDER_VALUE' => 'ACCOUNT_NUMBER',
                            ],
                        ],
                        'PAYMENT_SHOULD_PAY' => [
                            'NAME'    => 'Сумма оплаты',
                            'SORT'    => '600',
                            'GROUP'   => 'PAYMENT',
                            'DEFAULT' => [
                                'PROVIDER_KEY'   => 'PAYMENT',
                                'PROVIDER_VALUE' => 'SUM',
                            ],
                        ],
                        'PS_CHANGE_STATUS_PAY' => [
                            'NAME'  => 'Автоматическая смена статуса оплаты',
                            'SORT'  => '700',
                            'INPUT' => [
                                'TYPE' => 'Y/N',
                            ],
                        ],
                        'PAYMENT_BUYER_ID'     => [
                            'NAME'    => 'Код покупателя',
                            'SORT'    => '1000',
                            'GROUP'   => 'PAYMENT',
                            'DEFAULT' => [
                                'PROVIDER_KEY'   => 'ORDER',
                                'PROVIDER_VALUE' => 'USER_ID',
                            ],
                        ],
                        'PS_WORK_MODE'        => [
                            'NAME'  => 'Режим работы платёжной системы',
                            'SORT'  => '1100',
                            'INPUT' => [
                                'TYPE'    => 'ENUM',
                                'OPTIONS' => [
                                    'TEST'    => 'Тестовый',
                                    'REGULAR' => 'Рабочий',
                                ],
                            ],
                        ],
                    ],
                ],
            ]
        );

    $result = $response
        ->getResponseData()
        ->getResult();

    echo 'Success: ' . print_r($result, true);

} catch (Throwable $e) {
    error_log($e->getMessage());
    echo 'Error adding payment system handler: ' . $e->getMessage();
}
BX24.callMethod(
    "sale.paysystem.handler.add",
    {
        "NAME": "Обработчик.Rest FORM",
        "CODE": "resthandlerform",
        "SORT": 100,
        "SETTINGS": {
            "CURRENCY": [
                "RUB"
            ],
            "CLIENT_TYPE": "b2c",
            "FORM_DATA": {
                "ACTION_URI": "http://example.com/payment_form.php",
                "METHOD": "POST",
                "FIELDS": {
                    "phone": {
                        "VISIBLE": "Y",
                        "CODE": {
                            "NAME": "Номер телефона",
                            "TYPE": "STRING"
                        }
                    },
                    "selection": {
                        "VISIBLE": "Y",
                        "CODE": {
                            "NAME": "Иллюзия выбора",
                            "INPUT": {
                                "TYPE": "Y/N"
                            }
                        }
                    },
                    "paymentId": {
                        "CODE": "PAYMENT_ID",
                        "VISIBLE": "Y"
                    },
                    "serviceid": {
                        "CODE": "REST_SERVICE_ID"
                    }
                }
            },
            "CODES": {
                "REST_SERVICE_ID": {
                    "NAME": "Номер магазина",
                    "DESCRIPTION": "Номер магазина",
                    "SORT": "100"
                },
                "REST_SERVICE_KEY": {
                    "NAME": "Секретный ключ",
                    "DESCRIPTION": "Секретный ключ",
                    "SORT": "300"
                },
                "PAYMENT_ID": {
                    "NAME": "Номер оплаты",
                    "SORT": "400",
                    "GROUP": "PAYMENT",
                    "DEFAULT": {
                        "PROVIDER_KEY": "PAYMENT",
                        "PROVIDER_VALUE": "ACCOUNT_NUMBER"
                    }
                },
                "PAYMENT_SHOULD_PAY": {
                    "NAME": "Сумма оплаты",
                    "SORT": "600",
                    "GROUP": "PAYMENT",
                    "DEFAULT": {
                        "PROVIDER_KEY": "PAYMENT",
                        "PROVIDER_VALUE": "SUM"
                    }
                },
                "PS_CHANGE_STATUS_PAY": {
                    "NAME": "Автоматическая смена статуса оплаты",
                    "SORT": "700",
                    "INPUT": {
                        "TYPE": "Y/N"
                    }
                },
                "PAYMENT_BUYER_ID": {
                    "NAME": "Код покупателя",
                    "SORT": "1000",
                    "GROUP": "PAYMENT",
                    "DEFAULT": {
                        "PROVIDER_KEY": "ORDER",
                        "PROVIDER_VALUE": "USER_ID"
                    }
                },
                "PS_WORK_MODE": {
                    "NAME": "Режим работы платёжной системы",
                    "SORT": "1100",
                    "INPUT": {
                        "TYPE": "ENUM",
                        "OPTIONS": {
                            "TEST": "Тестовый",
                            "REGULAR": "Рабочий"
                        }
                    }
                }
            }
        }
    }
    ,
    function (result) {
        if (result.error())
        {
            console.error(result.error());
        }
        else
        {
            console.info(result.data());
        }
    }
);
require_once('crest.php');

$result = CRest::call(
    'sale.paysystem.handler.add',
    [
        'NAME' => 'Обработчик.Rest FORM',
        'CODE' => 'resthandlerform',
        'SORT' => 100,
        'SETTINGS' => [
            'CURRENCY' => ['RUB'],
            'CLIENT_TYPE' => 'b2c',
            'FORM_DATA' => [
                'ACTION_URI' => 'http://example.com/payment_form.php',
                'METHOD' => 'POST',
                'FIELDS' => [
                    'phone' => [
                        'VISIBLE' => 'Y',
                        'CODE' => [
                            'NAME' => 'Номер телефона',
                            'TYPE' => 'STRING'
                        ]
                    ],
                    'selection' => [
                        'VISIBLE' => 'Y',
                        'CODE' => [
                            'NAME' => 'Иллюзия выбора',
                            'INPUT' => [
                                'TYPE' => 'Y/N'
                            ]
                        ]
                    ],
                    'paymentId' => [
                        'CODE' => 'PAYMENT_ID',
                        'VISIBLE' => 'Y'
                    ],
                    'serviceid' => [
                        'CODE' => 'REST_SERVICE_ID'
                    ]
                ]
            ],
            'CODES' => [
                'REST_SERVICE_ID' => [
                    'NAME' => 'Номер магазина',
                    'DESCRIPTION' => 'Номер магазина',
                    'SORT' => '100'
                ],
                'REST_SERVICE_KEY' => [
                    'NAME' => 'Секретный ключ',
                    'DESCRIPTION' => 'Секретный ключ',
                    'SORT' => '300'
                ],
                'PAYMENT_ID' => [
                    'NAME' => 'Номер оплаты',
                    'SORT' => '400',
                    'GROUP' => 'PAYMENT',
                    'DEFAULT' => [
                        'PROVIDER_KEY' => 'PAYMENT',
                        'PROVIDER_VALUE' => 'ACCOUNT_NUMBER'
                    ]
                ],
                'PAYMENT_SHOULD_PAY' => [
                    'NAME' => 'Сумма оплаты',
                    'SORT' => '600',
                    'GROUP' => 'PAYMENT',
                    'DEFAULT' => [
                        'PROVIDER_KEY' => 'PAYMENT',
                        'PROVIDER_VALUE' => 'SUM'
                    ]
                ],
                'PS_CHANGE_STATUS_PAY' => [
                    'NAME' => 'Автоматическая смена статуса оплаты',
                    'SORT' => '700',
                    'INPUT' => [
                        'TYPE' => 'Y/N'
                    ]
                ],
                'PAYMENT_BUYER_ID' => [
                    'NAME' => 'Код покупателя',
                    'SORT' => '1000',
                    'GROUP' => 'PAYMENT',
                    'DEFAULT' => [
                        'PROVIDER_KEY' => 'ORDER',
                        'PROVIDER_VALUE' => 'USER_ID'
                    ]
                ],
                'PS_WORK_MODE' => [
                    'NAME' => 'Режим работы платёжной системы',
                    'SORT' => '1100',
                    'INPUT' => [
                        'TYPE' => 'ENUM',
                        'OPTIONS' => [
                            'TEST' => 'Тестовый',
                            'REGULAR' => 'Рабочий'
                        ]
                    ]
                ]
            ]
        ]
    ]
);

echo '<PRE>';
print_r($result);
echo '</PRE>';

Режим работы Checkout

При добавлении обработчика в параметр SETTINGS нужно передать CHECKOUT_DATA.

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

На ACTION_URI будут передаваться данные для оплаты в виде массива. Он содержит массив системных параметров в ключе BX_SYSTEM_PARAMS и значения FIELDS из CHECKOUT_DATA, каждое отдельным ключом на верхнем уровне массива.

Структура массива BX_SYSTEM_PARAMS:

Название
тип

Описание

RETURN_URL
string

Текущая страница

PAYSYSTEM_ID
sale_paysystem.ID

Идентификатор платежной системы

PAYMENT_ID
sale_order_payment.id

Идентификатор оплаты

SUM
double

Сумма платежа

CURRENCY
string

Валюта

EXTERNAL_PAYMENT_ID
string

Идентификатор платежа в платежной системе (если он есть). Например, если для текущей оплаты уже отправлялся запрос на ACTION_URI

В ответ на запрос к ACTION_URI скрипт должен вернуть идентификатор созданной оплаты и URL страницы оплаты.

Название
тип

Описание

PAYMENT_URL
string

URL страницы оплаты

PAYMENT_ID
string

Идентификатор платежа в платежной системе

Покупатель перейдет по ссылке из PAYMENT_URL автоматически или по клику на кнопку «Купить». Если в FIELDS среди прочих переданы поля, предназначенные для заполнения через форму, то покупателю будет выведена форма.

В результате можно вернуть массив ошибок в ключе PAYMENT_ERRORS. Менеджер увидит ошибки в таймлайне или на странице оплаты (зависит от используемого шаблона).

Название
тип

Описание

PAYMENT_ERRORS
string[]

Список ошибок, возникших при создании оплаты

Если ничего не возвращать, то будет использоваться ошибка по умолчанию Ошибка регистрации заказа в платёжной системе (Error registering order in payment system).

Параметры, передаваемые при добавлении обработчика в массиве CHECKOUT_DATA

Обязательные параметры отмечены *

Название
тип

Описание

ACTION_URI*
string

URL, на который отправляется запрос на создание оплаты

FIELDS
object

Описание полей, передаваемых на ACTION_URI. Формат аналогичен полю FIELDS в режиме работы в форме (FORM_DATA)

Примеры кода

Как использовать примеры в документации

curl -X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"NAME":"Обработчик.Rest CHECKOUT","CODE":"resthandlercheckout","SORT":100,"SETTINGS":{"CURRENCY":["RUB"],"CLIENT_TYPE":"b2c","CHECKOUT_DATA":{"ACTION_URI":"http://example.com/payment_checkout.php","FIELDS":{"serviceKey":{"CODE":"REST_SERVICE_KEY_CHECKOUT"},"serviceid":{"CODE":"REST_SERVICE_ID_CHECKOUT"}}},"CODES":{"REST_SERVICE_ID_CHECKOUT":{"NAME":"Номер магазина","DESCRIPTION":"Номер магазина","SORT":"100"},"REST_SERVICE_KEY_CHECKOUT":{"NAME":"Секретный ключ","DESCRIPTION":"Секретный ключ","SORT":"300"},"PS_WORK_MODE_CHECKOUT":{"NAME":"Режим работы платёжной системы","SORT":"1100","INPUT":{"TYPE":"ENUM","OPTIONS":{"TEST":"Тестовый","REGULAR":"Рабочий"}}}}}' \
https://**put_your_bitrix24_address**/rest/**put_your_user_id_here**/**put_your_webhook_here**/sale.paysystem.handler.add
curl -X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"NAME":"Обработчик.Rest CHECKOUT","CODE":"resthandlercheckout","SORT":100,"SETTINGS":{"CURRENCY":["RUB"],"CLIENT_TYPE":"b2c","CHECKOUT_DATA":{"ACTION_URI":"http://example.com/payment_checkout.php","FIELDS":{"serviceKey":{"CODE":"REST_SERVICE_KEY_CHECKOUT"},"serviceid":{"CODE":"REST_SERVICE_ID_CHECKOUT"}}},"CODES":{"REST_SERVICE_ID_CHECKOUT":{"NAME":"Номер магазина","DESCRIPTION":"Номер магазина","SORT":"100"},"REST_SERVICE_KEY_CHECKOUT":{"NAME":"Секретный ключ","DESCRIPTION":"Секретный ключ","SORT":"300"},"PS_WORK_MODE_CHECKOUT":{"NAME":"Режим работы платёжной системы","SORT":"1100","INPUT":{"TYPE":"ENUM","OPTIONS":{"TEST":"Тестовый","REGULAR":"Рабочий"}}}},"auth":"**put_access_token_here**"}' \
https://**put_your_bitrix24_address**/rest/sale.paysystem.handler.add
// This snippet is an ES module: top-level await requires type="module" or a bundler.
// $b24 is an already-initialized SDK instance (see the SDK "Get started" guide).
import { Text } from '@bitrix24/b24jssdk'
import type { B24Frame } from '@bitrix24/b24jssdk'

declare const $b24: B24Frame

try {
  const response = await $b24.actions.v2.call.make<number>({
    method: 'sale.paysystem.handler.add',
    params: {
      NAME: 'Rest handler CHECKOUT',
      CODE: 'resthandlercheckout',
      SORT: 100,
      SETTINGS: {
        CURRENCY: ['RUB'],
        CLIENT_TYPE: 'b2c',
        CHECKOUT_DATA: {
          ACTION_URI: 'http://example.com/payment_checkout.php',
          FIELDS: {
            serviceKey: {
              CODE: 'REST_SERVICE_KEY_CHECKOUT',
            },
            serviceid: {
              CODE: 'REST_SERVICE_ID_CHECKOUT',
            },
          },
        },
        CODES: {
          REST_SERVICE_ID_CHECKOUT: {
            NAME: 'Shop ID',
            DESCRIPTION: 'Shop ID',
            SORT: '100',
          },
          REST_SERVICE_KEY_CHECKOUT: {
            NAME: 'Secret key',
            DESCRIPTION: 'Secret key',
            SORT: '300',
          },
          PS_WORK_MODE_CHECKOUT: {
            NAME: 'Payment system work mode',
            SORT: '1100',
            INPUT: {
              TYPE: 'ENUM',
              OPTIONS: {
                TEST: 'Test',
                REGULAR: 'Live',
              },
            },
          },
        },
      },
    },
    requestId: Text.getUuidRfc4122()
  })

  // The payload is available only on a successful response
  if (!response.isSuccess) {
    console.error(response.getErrorMessages().join('; '))
  } else {
    const result = response.getData()!.result
    console.info('Handler added with ID:', result)
  }
} catch (error) {
  // Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
  console.error(error)
}
<!-- Load the SDK (UMD build); it is exposed as the global B24Js -->
<script src="https://unpkg.com/@bitrix24/b24jssdk@1/dist/umd/index.min.js"></script>
<script>
  async function addPaySystemHandlerCheckout() {
    try {
      // Initialize the SDK inside a Bitrix24 frame
      const $b24 = await B24Js.initializeB24Frame()

      const response = await $b24.actions.v2.call.make({
        method: 'sale.paysystem.handler.add',
        params: {
          NAME: 'Rest handler CHECKOUT',
          CODE: 'resthandlercheckout',
          SORT: 100,
          SETTINGS: {
            CURRENCY: ['RUB'],
            CLIENT_TYPE: 'b2c',
            CHECKOUT_DATA: {
              ACTION_URI: 'http://example.com/payment_checkout.php',
              FIELDS: {
                serviceKey: {
                  CODE: 'REST_SERVICE_KEY_CHECKOUT',
                },
                serviceid: {
                  CODE: 'REST_SERVICE_ID_CHECKOUT',
                },
              },
            },
            CODES: {
              REST_SERVICE_ID_CHECKOUT: {
                NAME: 'Shop ID',
                DESCRIPTION: 'Shop ID',
                SORT: '100',
              },
              REST_SERVICE_KEY_CHECKOUT: {
                NAME: 'Secret key',
                DESCRIPTION: 'Secret key',
                SORT: '300',
              },
              PS_WORK_MODE_CHECKOUT: {
                NAME: 'Payment system work mode',
                SORT: '1100',
                INPUT: {
                  TYPE: 'ENUM',
                  OPTIONS: {
                    TEST: 'Test',
                    REGULAR: 'Live',
                  },
                },
              },
            },
          },
        },
        requestId: B24Js.Text.getUuidRfc4122()
      })

      // The payload is available only on a successful response
      if (!response.isSuccess) {
        console.error(response.getErrorMessages().join('; '))
        return
      }

      const result = response.getData().result
      console.info('Handler added with ID:', result)
    } catch (error) {
      // Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
      console.error(error)
    }
  }

  document.addEventListener('DOMContentLoaded', addPaySystemHandlerCheckout)
</script>
from b24pysdk.errors import BitrixAPIError, BitrixSDKException

try:
    bitrix_response = client.sale.paysystem.handler.add(
        name='Обработчик.Rest CHECKOUT',
        code='resthandlercheckout',
        settings={
            "CURRENCY": [
                "RUB",
            ],
            "CLIENT_TYPE": "b2c",
            "CHECKOUT_DATA": {
                "ACTION_URI": 'http://example.com/payment_checkout.php',
                "FIELDS": {
                    "serviceKey": {
                        "CODE": 'REST_SERVICE_KEY_CHECKOUT',
                    },
                    "serviceid": {
                        "CODE": 'REST_SERVICE_ID_CHECKOUT',
                    },
                },
            },
            "CODES": {
                'REST_SERVICE_ID_CHECKOUT': {
                    "NAME": "Ключ сервиса",
                    "DESCRIPTION": "Ключ сервиса",
                    "SORT": "100",
                },
                'REST_SERVICE_KEY_CHECKOUT': {
                    "NAME": "Идентификатор",
                    "DESCRIPTION": "Идентификатор",
                    "SORT": "300",
                },
                'PS_WORK_MODE_CHECKOUT': {
                    "NAME": "Режим работы платежной системы",
                    "SORT": "1100",
                    "INPUT": {
                        "TYPE": "ENUM",
                        "OPTIONS": {
                            "TEST": "Тестовый",
                            "REGULAR": "Реальный",
                        },
                    },
                },
            },
        },
        sort=100,
    ).response
    result = bitrix_response.result
    print(result)
except BitrixAPIError as error:
    print(
        "Ошибка Bitrix API",
        f"error: {error.error}",
        f"error_description: {error.error_description}",
        sep="\n",
    )
except BitrixSDKException as error:
    print(f"Ошибка Bitrix SDK: {error.message}")
except Exception as error:
    print(f"Непредвиденная ошибка: {error}")
try {
    $response = $b24Service
        ->core
        ->call(
            'sale.paysystem.handler.add',
            [
                'NAME'     => 'Обработчик.Rest CHECKOUT',
                'CODE'     => 'resthandlercheckout',
                'SORT'     => 100,
                'SETTINGS' => [
                    'CURRENCY'    => ['RUB'],
                    'CLIENT_TYPE' => 'b2c',
                    'CHECKOUT_DATA' => [
                        'ACTION_URI' => 'http://example.com/payment_checkout.php',
                        'FIELDS'     => [
                            'serviceKey' => [
                                'CODE' => 'REST_SERVICE_KEY_CHECKOUT',
                            ],
                            'serviceid'  => [
                                'CODE' => 'REST_SERVICE_ID_CHECKOUT'
                            ]
                        ]
                    ],
                    'CODES' => [
                        'REST_SERVICE_ID_CHECKOUT' => [
                            'NAME'        => 'Номер магазина',
                            'DESCRIPTION' => 'Номер магазина',
                            'SORT'        => '100'
                        ],
                        'REST_SERVICE_KEY_CHECKOUT' => [
                            'NAME'        => 'Секретный ключ',
                            'DESCRIPTION' => 'Секретный ключ',
                            'SORT'        => '300'
                        ],
                        'PS_WORK_MODE_CHECKOUT'     => [
                            'NAME'  => 'Режим работы платёжной системы',
                            'SORT'  => '1100',
                            'INPUT' => [
                                'TYPE'    => 'ENUM',
                                'OPTIONS' => [
                                    'TEST'    => 'Тестовый',
                                    'REGULAR' => 'Рабочий'
                                ]
                            ]
                        ]
                    ]
                ]
            ]
        );

    $result = $response
        ->getResponseData()
        ->getResult();

    echo 'Обработчик добавлен с ID ' . $result;

} catch (Throwable $e) {
    error_log($e->getMessage());
    echo 'Error adding paysystem handler: ' . $e->getMessage();
}
BX24.callMethod(
    "sale.paysystem.handler.add",
    {
        "NAME": "Обработчик.Rest CHECKOUT",
        "CODE": "resthandlercheckout",
        "SORT": 100,
        "SETTINGS": {
            "CURRENCY": [
                "RUB"
            ],
            "CLIENT_TYPE": "b2c",
            "CHECKOUT_DATA": {
                "ACTION_URI": "http://example.com/payment_checkout.php",
                "FIELDS": {
                    "serviceKey": {
                        "CODE": "REST_SERVICE_KEY_CHECKOUT",
                    },
                    "serviceid": {
                        "CODE": "REST_SERVICE_ID_CHECKOUT"
                    }
                }
            },
            "CODES": {
                "REST_SERVICE_ID_CHECKOUT": {
                    "NAME": "Номер магазина",
                    "DESCRIPTION": "Номер магазина",
                    "SORT": "100"
                },
                "REST_SERVICE_KEY_CHECKOUT": {
                    "NAME": "Секретный ключ",
                    "DESCRIPTION": "Секретный ключ",
                    "SORT": "300"
                },
                "PS_WORK_MODE_CHECKOUT": {
                    "NAME": "Режим работы платёжной системы",
                    "SORT": "1100",
                    "INPUT": {
                        "TYPE": "ENUM",
                        "OPTIONS": {
                            "TEST": "Тестовый",
                            "REGULAR": "Рабочий"
                        }
                    }
                }
            }
        }
    }
    ,
    function (result) {
        if (result.error())
        {
            console.error(result.error());
        }
        else
        {
            console.info("Обработчик добавлен с ID " + result.data());
        }
    }
);
require_once('crest.php');

$result = CRest::call(
    'sale.paysystem.handler.add',
    [
        'NAME' => 'Обработчик.Rest CHECKOUT',
        'CODE' => 'resthandlercheckout',
        'SORT' => 100,
        'SETTINGS' => [
            'CURRENCY' => ['RUB'],
            'CLIENT_TYPE' => 'b2c',
            'CHECKOUT_DATA' => [
                'ACTION_URI' => 'http://example.com/payment_checkout.php',
                'FIELDS' => [
                    'serviceKey' => [
                        'CODE' => 'REST_SERVICE_KEY_CHECKOUT',
                    ],
                    'serviceid' => [
                        'CODE' => 'REST_SERVICE_ID_CHECKOUT'
                    ]
                ]
            ],
            'CODES' => [
                'REST_SERVICE_ID_CHECKOUT' => [
                    'NAME' => 'Номер магазина',
                    'DESCRIPTION' => 'Номер магазина',
                    'SORT' => '100'
                ],
                'REST_SERVICE_KEY_CHECKOUT' => [
                    'NAME' => 'Секретный ключ',
                    'DESCRIPTION' => 'Секретный ключ',
                    'SORT' => '300'
                ],
                'PS_WORK_MODE_CHECKOUT' => [
                    'NAME' => 'Режим работы платёжной системы',
                    'SORT' => '1100',
                    'INPUT' => [
                        'TYPE' => 'ENUM',
                        'OPTIONS' => [
                            'TEST' => 'Тестовый',
                            'REGULAR' => 'Рабочий'
                        ]
                    ]
                ]
            ]
        ]
    ]
);

echo '<PRE>';
print_r($result);
echo '</PRE>';

Режим работы IFrame

При добавлении обработчика в параметр SETTINGS нужно передать IFRAME_DATA.

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

При загрузке iframe через метод Window.postMessage() на ACTION_URI будут переданы значения FIELDS из IFRAME_DATA (каждое отдельным ключом на верхнем уровне массива), а также следующие данные:

Название
тип

Описание

BX_SYSTEM_PARAMS
object

Системные параметры

BX_COMPUTED_STYLE
object

Cтили родительского элемента iframe, полученные методом window.getComputedStyle()

Данные, передаваемые в BX_SYSTEM_PARAMS:

Название
тип

Описание

RETURN_URL
string

Текущая страница

PAYSYSTEM_ID
sale_paysystem.ID

Идентификатор платежной системы

PAYMENT_ID
sale_order_payment.id

Идентификатор оплаты

SUM
string

Сумма платежа

CURRENCY
string

Валюта

Получить значения в iframe можно через обработчик события message, например:

document.addEventListener("DOMContentLoaded", function() {
	window.addEventListener("message", function (event) {
		// получение данных от сайта (от платёжной системы)
		var paymentData = event.data;
		// работа с BX_SYSTEM_PARAMS
		if (paymentData.BX_SYSTEM_PARAMS)
		{
			// ...
		}
		// использование стилей сайта
		if (paymentData.BX_COMPUTED_STYLE)
		{
			document.body.style.background = paymentData.BX_COMPUTED_STYLE.background;
			document.body.style.color = paymentData.BX_COMPUTED_STYLE.color;
		}
	}, false);
});

По умолчанию ширина iframe — 100% родительского элемента, а высота — 350px.

Размеры iframe можно изменить. Для этого нужно из iframe передать высоту и/или ширину на сайт продавца. Например:

document.addEventListener("DOMContentLoaded", function() {
	var size = {
		width: document.body.scrollWidth,
		height: document.body.scrollHeight
	};
	// отправка данных на сайт продавца
	parent.postMessage(size, "*");
});

width и height — зарезервированные названия переменных, и на сайте продавца обрабатываются только они.

Параметры, передаваемые при добавлении обработчика в массиве IFRAME_DATA

Обязательные параметры отмечены *

Название
тип

Описание

ACTION_URI*
string

URL страницы, которая будет выведена в элементе iframe

FIELDS
object

Описание полей, передаваемых в iframe. Формат аналогичен полю FIELDS в режиме работы в форме (FORM_DATA)

Примеры кода

Как использовать примеры в документации

curl -X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"NAME":"Обработчик.Rest IFrame","CODE":"resthandleriframe","SORT":100,"SETTINGS":{"CURRENCY":["RUB"],"CLIENT_TYPE":"b2c","IFRAME_DATA":{"ACTION_URI":"http://example.com/payment_iframe.php","FIELDS":{"serviceKey":{"CODE":"REST_SERVICE_KEY_IFRAME"},"serviceid":{"CODE":"REST_SERVICE_ID_IFRAME"}}},"CODES":{"REST_SERVICE_ID_IFRAME":{"NAME":"Номер магазина","DESCRIPTION":"Номер магазина","SORT":"100"},"REST_SERVICE_KEY_IFRAME":{"NAME":"Секретный ключ","DESCRIPTION":"Секретный ключ","SORT":"300"},"PS_WORK_MODE_IFRAME":{"NAME":"Режим работы платёжной системы","SORT":"1100","INPUT":{"TYPE":"ENUM","OPTIONS":{"TEST":"Тестовый","REGULAR":"Рабочий"}}}}}' \
https://**put_your_bitrix24_address**/rest/**put_your_user_id_here**/**put_your_webhook_here**/sale.paysystem.handler.add
curl -X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"NAME":"Обработчик.Rest IFrame","CODE":"resthandleriframe","SORT":100,"SETTINGS":{"CURRENCY":["RUB"],"CLIENT_TYPE":"b2c","IFRAME_DATA":{"ACTION_URI":"http://example.com/payment_iframe.php","FIELDS":{"serviceKey":{"CODE":"REST_SERVICE_KEY_IFRAME"},"serviceid":{"CODE":"REST_SERVICE_ID_IFRAME"}}},"CODES":{"REST_SERVICE_ID_IFRAME":{"NAME":"Номер магазина","DESCRIPTION":"Номер магазина","SORT":"100"},"REST_SERVICE_KEY_IFRAME":{"NAME":"Секретный ключ","DESCRIPTION":"Секретный ключ","SORT":"300"},"PS_WORK_MODE_IFRAME":{"NAME":"Режим работы платёжной системы","SORT":"1100","INPUT":{"TYPE":"ENUM","OPTIONS":{"TEST":"Тестовый","REGULAR":"Рабочий"}}}},"auth":"**put_access_token_here**"}' \
https://**put_your_bitrix24_address**/rest/sale.paysystem.handler.add
// This snippet is an ES module: top-level await requires type="module" or a bundler.
// $b24 is an already-initialized SDK instance (see the SDK "Get started" guide).
import { Text } from '@bitrix24/b24jssdk'
import type { B24Frame } from '@bitrix24/b24jssdk'

declare const $b24: B24Frame

try {
  const response = await $b24.actions.v2.call.make<number>({
    method: 'sale.paysystem.handler.add',
    params: {
      NAME: 'Rest handler IFrame',
      CODE: 'resthandleriframe',
      SORT: 100,
      SETTINGS: {
        CURRENCY: ['RUB'],
        CLIENT_TYPE: 'b2c',
        IFRAME_DATA: {
          ACTION_URI: 'http://example.com/payment_iframe.php',
          FIELDS: {
            serviceKey: {
              CODE: 'REST_SERVICE_KEY_IFRAME',
            },
            serviceid: {
              CODE: 'REST_SERVICE_ID_IFRAME',
            },
          },
        },
        CODES: {
          REST_SERVICE_ID_IFRAME: {
            NAME: 'Shop ID',
            DESCRIPTION: 'Shop ID',
            SORT: '100',
          },
          REST_SERVICE_KEY_IFRAME: {
            NAME: 'Secret key',
            DESCRIPTION: 'Secret key',
            SORT: '300',
          },
          PS_WORK_MODE_IFRAME: {
            NAME: 'Payment system work mode',
            SORT: '1100',
            INPUT: {
              TYPE: 'ENUM',
              OPTIONS: {
                TEST: 'Test',
                REGULAR: 'Live',
              },
            },
          },
        },
      },
    },
    requestId: Text.getUuidRfc4122()
  })

  // The payload is available only on a successful response
  if (!response.isSuccess) {
    console.error(response.getErrorMessages().join('; '))
  } else {
    const result = response.getData()!.result
    console.info('Handler added with ID:', result)
  }
} catch (error) {
  // Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
  console.error(error)
}
<!-- Load the SDK (UMD build); it is exposed as the global B24Js -->
<script src="https://unpkg.com/@bitrix24/b24jssdk@1/dist/umd/index.min.js"></script>
<script>
  async function addPaySystemHandlerIframe() {
    try {
      // Initialize the SDK inside a Bitrix24 frame
      const $b24 = await B24Js.initializeB24Frame()

      const response = await $b24.actions.v2.call.make({
        method: 'sale.paysystem.handler.add',
        params: {
          NAME: 'Rest handler IFrame',
          CODE: 'resthandleriframe',
          SORT: 100,
          SETTINGS: {
            CURRENCY: ['RUB'],
            CLIENT_TYPE: 'b2c',
            IFRAME_DATA: {
              ACTION_URI: 'http://example.com/payment_iframe.php',
              FIELDS: {
                serviceKey: {
                  CODE: 'REST_SERVICE_KEY_IFRAME',
                },
                serviceid: {
                  CODE: 'REST_SERVICE_ID_IFRAME',
                },
              },
            },
            CODES: {
              REST_SERVICE_ID_IFRAME: {
                NAME: 'Shop ID',
                DESCRIPTION: 'Shop ID',
                SORT: '100',
              },
              REST_SERVICE_KEY_IFRAME: {
                NAME: 'Secret key',
                DESCRIPTION: 'Secret key',
                SORT: '300',
              },
              PS_WORK_MODE_IFRAME: {
                NAME: 'Payment system work mode',
                SORT: '1100',
                INPUT: {
                  TYPE: 'ENUM',
                  OPTIONS: {
                    TEST: 'Test',
                    REGULAR: 'Live',
                  },
                },
              },
            },
          },
        },
        requestId: B24Js.Text.getUuidRfc4122()
      })

      // The payload is available only on a successful response
      if (!response.isSuccess) {
        console.error(response.getErrorMessages().join('; '))
        return
      }

      const result = response.getData().result
      console.info('Handler added with ID:', result)
    } catch (error) {
      // Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
      console.error(error)
    }
  }

  document.addEventListener('DOMContentLoaded', addPaySystemHandlerIframe)
</script>
from b24pysdk.errors import BitrixAPIError, BitrixSDKException

try:
    bitrix_response = client.sale.paysystem.handler.add(
        name='Обработчик.Rest IFrame',
        code='resthandleriframe',
        settings={
            "CURRENCY": [
                "RUB",
            ],
            "CLIENT_TYPE": "b2c",
            "IFRAME_DATA": {
                "ACTION_URI": 'http://example.com/payment_iframe.php',
                "FIELDS": {
                    "serviceKey": {
                        "CODE": 'REST_SERVICE_KEY_IFRAME',
                    },
                    "serviceid": {
                        "CODE": 'REST_SERVICE_ID_IFRAME',
                    },
                },
            },
            "CODES": {
                'REST_SERVICE_ID_IFRAME': {
                    "NAME": "Ключ сервиса",
                    "DESCRIPTION": "Ключ сервиса",
                    "SORT": "100",
                },
                'REST_SERVICE_KEY_IFRAME': {
                    "NAME": "Идентификатор",
                    "DESCRIPTION": "Идентификатор",
                    "SORT": "300",
                },
                'PS_WORK_MODE_IFRAME': {
                    "NAME": "Режим работы платежной системы",
                    "SORT": "1100",
                    "INPUT": {
                        "TYPE": "ENUM",
                        "OPTIONS": {
                            "TEST": "Тестовый",
                            "REGULAR": "Реальный",
                        },
                    },
                },
            },
        },
        sort=100,
    ).response
    result = bitrix_response.result
    print(result)
except BitrixAPIError as error:
    print(
        "Ошибка Bitrix API",
        f"error: {error.error}",
        f"error_description: {error.error_description}",
        sep="\n",
    )
except BitrixSDKException as error:
    print(f"Ошибка Bitrix SDK: {error.message}")
except Exception as error:
    print(f"Непредвиденная ошибка: {error}")
try {
    $response = $b24Service
        ->core
        ->call(
            'sale.paysystem.handler.add',
            [
                'NAME'     => 'Обработчик.Rest IFrame',
                'CODE'     => 'resthandleriframe',
                'SORT'     => 100,
                'SETTINGS' => [
                    'CURRENCY'    => ['RUB'],
                    'CLIENT_TYPE' => 'b2c',
                    'IFRAME_DATA' => [
                        'ACTION_URI' => 'http://example.com/payment_iframe.php',
                        'FIELDS'     => [
                            'serviceKey' => [
                                'CODE' => 'REST_SERVICE_KEY_IFRAME',
                            ],
                            'serviceid'  => [
                                'CODE' => 'REST_SERVICE_ID_IFRAME'
                            ]
                        ]
                    ],
                    'CODES'      => [
                        'REST_SERVICE_ID_IFRAME' => [
                            'NAME'        => 'Номер магазина',
                            'DESCRIPTION' => 'Номер магазина',
                            'SORT'        => '100'
                        ],
                        'REST_SERVICE_KEY_IFRAME' => [
                            'NAME'        => 'Секретный ключ',
                            'DESCRIPTION' => 'Секретный ключ',
                            'SORT'        => '300'
                        ],
                        'PS_WORK_MODE_IFRAME'     => [
                            'NAME'  => 'Режим работы платёжной системы',
                            'SORT'  => '1100',
                            'INPUT' => [
                                'TYPE'    => 'ENUM',
                                'OPTIONS' => [
                                    'TEST'    => 'Тестовый',
                                    'REGULAR' => 'Рабочий'
                                ]
                            ]
                        ]
                    ]
                ]
            ]
        );

    $result = $response
        ->getResponseData()
        ->getResult();

    echo 'Success: ' . print_r($result, true);

} catch (Throwable $e) {
    error_log($e->getMessage());
    echo 'Error adding payment system handler: ' . $e->getMessage();
}
BX24.callMethod(
    "sale.paysystem.handler.add",
    {
        "NAME": "Обработчик.Rest IFrame",
        "CODE": "resthandleriframe",
        "SORT": 100,
        "SETTINGS": {
            "CURRENCY": [
                "RUB"
            ],
            "CLIENT_TYPE": "b2c",
            "IFRAME_DATA": {
                "ACTION_URI": "http://example.com/payment_iframe.php",
                "FIELDS": {
                    "serviceKey": {
                        "CODE": "REST_SERVICE_KEY_IFRAME",
                    },
                    "serviceid": {
                        "CODE": "REST_SERVICE_ID_IFRAME"
                    }
                }
            },
            "CODES": {
                "REST_SERVICE_ID_IFRAME": {
                    "NAME": "Номер магазина",
                    "DESCRIPTION": "Номер магазина",
                    "SORT": "100"
                },
                "REST_SERVICE_KEY_IFRAME": {
                    "NAME": "Секретный ключ",
                    "DESCRIPTION": "Секретный ключ",
                    "SORT": "300"
                },
                "PS_WORK_MODE_IFRAME": {
                    "NAME": "Режим работы платёжной системы",
                    "SORT": "1100",
                    "INPUT": {
                        "TYPE": "ENUM",
                        "OPTIONS": {
                            "TEST": "Тестовый",
                            "REGULAR": "Рабочий"
                        }
                    }
                }
            }
        }
    }
    ,
    function (result) {
        if (result.error())
        {
            console.error(result.error());
        }
        else
        {
            console.info(result.data());
        }
    }
);
require_once('crest.php');

$result = CRest::call(
    'sale.paysystem.handler.add',
    [
        'NAME' => 'Обработчик.Rest IFrame',
        'CODE' => 'resthandleriframe',
        'SORT' => 100,
        'SETTINGS' => [
            'CURRENCY' => ['RUB'],
            'CLIENT_TYPE' => 'b2c',
            'IFRAME_DATA' => [
                'ACTION_URI' => 'http://example.com/payment_iframe.php',
                'FIELDS' => [
                    'serviceKey' => [
                        'CODE' => 'REST_SERVICE_KEY_IFRAME',
                    ],
                    'serviceid' => [
                        'CODE' => 'REST_SERVICE_ID_IFRAME'
                    ]
                ]
            ],
            'CODES' => [
                'REST_SERVICE_ID_IFRAME' => [
                    'NAME' => 'Номер магазина',
                    'DESCRIPTION' => 'Номер магазина',
                    'SORT' => '100'
                ],
                'REST_SERVICE_KEY_IFRAME' => [
                    'NAME' => 'Секретный ключ',
                    'DESCRIPTION' => 'Секретный ключ',
                    'SORT' => '300'
                ],
                'PS_WORK_MODE_IFRAME' => [
                    'NAME' => 'Режим работы платёжной системы',
                    'SORT' => '1100',
                    'INPUT' => [
                        'TYPE' => 'ENUM',
                        'OPTIONS' => [
                            'TEST' => 'Тестовый',
                            'REGULAR' => 'Рабочий'
                        ]
                    ]
                ]
            ]
        ]
    ]
);

echo '<PRE>';
print_r($result);
echo '</PRE>';

Обработка ответа

HTTP-статус: 200

{
    "result": 5,
    "time": {
        "start": 1712132792.910734,
        "finish": 1712132793.530359,
        "duration": 0.6196250915527344,
        "processing": 0.032338857650756836,
        "date_start": "2024-04-03T10:26:32+02:00",
        "date_finish": "2024-04-03T10:26:33+02:00",
        "operating_reset_at": 1705765533,
        "operating": 3.3076241016387939
    }
}

Возвращаемые данные

Название
тип

Описание

result
sale_paysystem_handler.ID

Идентификатор созданного обработчика, используемый в дальнейшем для его обновления и удаления

time
time

Информация о времени выполнения запроса

Обработка ошибок

HTTP-статус: 400, 403

{
    "error": "ERROR_HANDLER_ALREADY_EXIST",
    "error_description": "Handler already exists!"
}

Название
тип

Описание

error
string

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

error_description
string

Текст ошибки для разработчика. Не показывайте его конечному пользователю без обработки

Возможные коды ошибок

Код

Описание

Статус

ACCESS_DENIED

Недостаточно прав для добавления обработчика

403

ERROR_CHECK_FAILURE

Не указано значение обязательного поля либо значение одного из полей указано неверно

400

ERROR_HANDLER_ALREADY_EXIST

Обработчик с кодом, указанным в параметре CODE, уже существует в системе

400

ERROR_HANDLER_ADD

Прочие ошибки. Подробную информацию об ошибке смотрите в error_description

400

Статусы и коды системных ошибок

HTTP-статус: 4xx, 5xx

Описанные ниже ошибки возвращает сам REST API, а не логика конкретного метода. Они могут прийти в ответ на любой метод.

Статус

Код
Текст ошибки

Описание

500

INTERNAL_SERVER_ERROR
Internal server error

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

500

ERROR_UNEXPECTED_ANSWER
Server returned an unexpected response

Сервер вернул неожиданный ответ. Повторите вызов, а если ошибка сохраняется, обратитесь к администратору сервера или в техническую поддержку Битрикс24

503

QUERY_LIMIT_EXCEEDED
Too many requests

Превышен лимит на интенсивность запросов

429

OPERATION_TIME_LIMIT
Method is blocked due to operation time limit

Метод заблокирован из-за превышения лимита на ресурсоемкость запросов. Блокировка снимается автоматически, когда накопленное время выполнения метода перестает превышать лимит

401

NO_AUTH_FOUND
Wrong authorization data

В запросе нет авторизационных данных: не передан ни access-токен, ни код вебхука

401

INVALID_REQUEST
Https required

Методы вызываются только по протоколу HTTPS

401

OVERLOAD_LIMIT
REST API is blocked due to overload

REST API заблокирован из-за перегрузки. Это ручная индивидуальная блокировка. Чтобы ее снять, обратитесь в техническую поддержку Битрикс24

401

ACCESS_DENIED
REST is available only on commercial plans

REST API доступен только на коммерческих тарифах. У вебхука текст ошибки другой — REST is available only by subscription

401

INVALID_CREDENTIALS
Invalid request credentials

Не найден активный вебхук с указанным идентификатором пользователя и секретным кодом

404

ERROR_METHOD_NOT_FOUND
Method not found!

Метод с таким именем не найден. Имя написано с ошибкой, метода нет в REST API или он недоступен без нужного скоупа

401

insufficient_scope
The request requires higher privileges than provided by the webhook token

Запрос требует более широких прав, чем есть у токена: у вебхука это выданные ему права, у приложения — скоуп. У приложения текст ошибки заканчивается на provided by the access token

401

expired_token
The access token provided has expired

Срок действия access-токена истек

401

user_access_error
The user does not have access to the application

Приложение установлено, но администратор Битрикс24 открыл доступ к нему только конкретным пользователям

403

PORTAL_DELETED
Portal was deleted

Публичная часть сайта закрыта. Чтобы открыть ее на коробочной установке, отключите опцию «Временное закрытие публичной части сайта». Путь к настройке: Рабочий стол > Настройки > Настройки продукта > Настройки модулей > Главный модуль > Временное закрытие публичной части сайта

Продолжите изучение