Add REST Handler for Payment System sale.paysystem.handler.add

Choose a tool for developing with an AI agent:

  • use Alaio Vibecode to build an app for Bitrix24 from a task description without knowing any programming language. The agent writes the code and deploys the app to a server, with no manual hosting setup
  • use the MCP server to develop a REST API integration in your own project. The agent refers to the official REST documentation

Scope: pay_system

Who can execute the method: CRM administrator (permission "Allow changing settings")

This method adds a REST handler for the payment system.

Method Parameters

Required parameters are marked with *

Name
type

Description

NAME*
string

Name of the REST handler

SORT
integer

Sorting order. Default is 100

CODE*
string

Code of the REST handler. Must be unique among all handlers

SETTINGS*
object

Handler settings (detailed description provided below)

SETTINGS Parameter

Required parameters are marked with *

Depending on the operating mode used, at least one of the following parameters must be present: FORM_DATA, CHECKOUT_DATA, IFRAME_DATA.

Name
type

Description

CODES*
object

List of handler parameters. Keys are parameter codes (string), values are parameter descriptions (detailed description provided below).

Parameter values will be available to the administrator for filling in the settings of the created payment system. They can be specified when adding the payment system in the method sale.paysystem.add in the SETTINGS parameter and modified using the method sale.paysystem.settings.update

FORM_DATA
object

Form settings when using the operating mode in form

CHECKOUT_DATA
object

Settings for the Checkout mode (creating an order on the service side and redirecting the buyer to this page for payment)

IFRAME_DATA
object

Settings for the page displayed in the iframe on the seller's site on the payment page

CLIENT_TYPE
string

Type of buyers that the handler can work with. Available values:

  • b2c — individuals
  • b2b — legal entities

Default value is b2c

CURRENCY
crm_currency.CURRENCY[]

List of currencies supported by the payment system. Default is empty

CODES Parameter

Name
type

Description

NAME
string

Name of the parameter

DESCRIPTION
string

Description of the parameter

SORT
integer

Sorting order

GROUP
string

Code of the group to which the parameter belongs

DEFAULT
object

Description of the default value (detailed description provided below)

INPUT
object

Object describing the input field. The structure of the object contains the TYPE parameter — the type of the field. Supported fields:

  • STRING — string
  • Y/N — checkbox
  • ENUM — list

DEFAULT Parameter

Name
type

Description

PROVIDER_KEY
string

Key of the provider from which the default value will be taken. Possible key values are listed below

PROVIDER_VALUE
string

Code of the value that will be taken from the provider. Possible key values are listed below

Possible Values for PROVIDER_KEY

Name

Description

ORDER

Order

PROPERTY

Invoice properties

PAYMENT

Payment

USER

User

VALUE

Arbitrary string type value

Y\N

Checkbox

Possible Values for PROVIDER_VALUE

Name

Description

ORDER

  • ID — identifier (for invoices corresponds to the ID of the invoice)
  • ACCOUNT_NUMBER — order number (for invoices corresponds to the invoice number)
  • ORDER_TOPIC — topic
  • DATE_INSERT — order date (for invoices corresponds to the invoice date)
  • DATE_INSERT_DATE — order date without time (for invoices corresponds to the invoice date)
  • DATE_BILL — date and time of issuance
  • DATE_BILL_DATE — date of issuance
  • DATE_PAY_BEFORE — payment deadline
  • SHOULD_PAY — invoice amount (for invoices corresponds to the invoice amount)
  • CURRENCY — currency
  • PRICE — order cost (for invoices corresponds to the invoice cost)
  • PRICE_DELIVERY — delivery cost
  • DISCOUNT_VALUE — discount amount
  • USER_ID — buyer code
  • PAY_SYSTEM_ID — payment system code
  • DELIVERY_ID — delivery service code
  • TAX_VALUE — tax
  • USER_DESCRIPTION — comment

PAYMENT

  • ID — identifier
  • ACCOUNT_NUMBER — payment number
  • DATE_BILL — date and time of issuance
  • DATE_BILL_DATE — date of issuance without time
  • SUM — invoice amount
  • CURRENCY — currency
  • PAID — paid
  • DATE_PAID — payment date
  • PAY_SYSTEM_ID — payment system code
  • PAY_VOUCHER_NUM — voucher number
  • PAY_VOUCHER_DATE — voucher date
  • DATE_PAY_BEFORE — pay by
  • XML_ID — XML identifier
  • PAY_SYSTEM_NAME — name of the payment system
  • COMPANY_ID — company code
  • PAY_RETURN_NUM — return number
  • PAY_RETURN_DATE — return date
  • PAY_RETURN_COMMENT — return comment

USER

  • ID — buyer code,
  • LOGIN — login
  • NAME — first name
  • SECOND_NAME — middle name
  • LAST_NAME — last name
  • EMAIL — EMail
  • PERSONAL_PROFESSION — profession
  • PERSONAL_WWW — personal website
  • PERSONAL_ICQ — ICQ number
  • PERSONAL_GENDER — gender
  • PERSONAL_FAX — fax number
  • PERSONAL_MOBILE — phone number
  • PERSONAL_STREET — address
  • PERSONAL_MAILBOX — mailbox
  • PERSONAL_CITY — city
  • PERSONAL_STATE — state
  • PERSONAL_ZIP — zip code
  • PERSONAL_COUNTRY — country
  • WORK_COMPANY — company
  • WORK_DEPARTMENT — department
  • WORK_POSITION — position
  • WORK_WWW — company website
  • WORK_PHONE — work phone
  • WORK_FAX — work fax
  • WORK_STREET — company address
  • WORK_MAILBOX — work mailbox
  • WORK_CITY — company city
  • WORK_STATE — company state
  • WORK_ZIP — company zip code
  • WORK_COUNTRY — company country

Form Operating Mode

When adding a handler, the FORM_DATA parameter must be passed. This method is suitable if no information needs to be requested from the buyer or if only a small set of data needs to be requested.

Form fields are automatically displayed according to the design of the payment page.

Form data (the FIELDS values from FORM_DATA) will be sent to ACTION_URI. In addition to the data defined in FORM_DATA, two system keys will also be sent with the form:

Name
type

Description

BX_PAYSYSTEM_ID
sale_paysystem.ID

Identifier of the payment system through which the payment is made. Can be used to call the payment method sale.paysystem.pay.payment

BX_RETURN_URL
string

URL of the store site to which the user will be redirected

Parameters Passed When Adding a Handler in the FORM_DATA Array

Required parameters are marked with *

Name
type

Description

ACTION_URI*
string

URL to which the form is sent

METHOD
string

HTTP method used when submitting the form. Default is empty, in which case the GET method is used

FIELDS
object

Description of form fields (detailed description provided below)

PARAMS
object

Description of form fields. This parameter is deprecated; it is recommended to use the FIELDS parameter.

Represents a mapping between field names in the form (string) and handler parameter codes (string): [field_code => handler_parameter_code, ...]

Fields are added to the form as hidden type elements.

If both FIELDS and PARAMS are passed, only FIELDS will be used.

FIELDS Parameter

Required parameters are marked with *

Represents an array of descriptions of fields displayed in the form and sent to ACTION_URI. The key is the field code used as the field name in the form. The values are the field parameter objects.

Name
type

Description

CODE*
string|object

If the value of the CODE key is of type string, this value will be used to find a match between form fields and handler parameters (CODES). The name and value will be obtained from the handler parameters.

If an object is passed in the CODE key, a field will be added to the payment form according to the description in the array content (detailed description provided below)

VISIBLE
string

Whether the field is displayed in the form for input. Available values:

  • Y — yes
  • N — no

Default value is N, the field is displayed in the form as hidden

CODE Parameter

Name
type

Description

NAME
string

Name of the field

INPUT
object

Description of the input field. Contains the TYPE key — the type of the field, which can take values:

  • STRING — string
  • Y/N — checkbox

Code Examples

How to Use Examples in Documentation

curl -X POST \
        -H "Content-Type: application/json" \
        -H "Accept: application/json" \
        -d '{"NAME":"Handler.Rest FORM","CODE":"resthandlerform","SORT":100,"SETTINGS":{"CURRENCY":["USD"],"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":"Store Number","DESCRIPTION":"Store Number","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 Code","SORT":"1000","GROUP":"PAYMENT","DEFAULT":{"PROVIDER_KEY":"ORDER","PROVIDER_VALUE":"USER_ID"}},"PS_WORK_MODE":{"NAME":"Payment System Operating Mode","SORT":"1100","INPUT":{"TYPE":"ENUM","OPTIONS":{"TEST":"Test","REGULAR":"Live"}}}}}' \
        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":"Handler.Rest FORM","CODE":"resthandlerform","SORT":100,"SETTINGS":{"CURRENCY":["USD"],"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":"Store Number","DESCRIPTION":"Store Number","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 Code","SORT":"1000","GROUP":"PAYMENT","DEFAULT":{"PROVIDER_KEY":"ORDER","PROVIDER_VALUE":"USER_ID"}},"PS_WORK_MODE":{"NAME":"Payment System Operating Mode","SORT":"1100","INPUT":{"TYPE":"ENUM","OPTIONS":{"TEST":"Test","REGULAR":"Live"}}}},"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: ['USD'],
                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: ['USD'],
                    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": [
                "USD",
            ],
            "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 error",
                f"error: {error.error}",
                f"error_description: {error.error_description}",
                sep="\n",
            )
        except BitrixSDKException as error:
            print(f"Bitrix SDK error: {error.message}")
        except Exception as error:
            print(f"Unexpected error: {error}")
        
try {
            $response = $b24Service
                ->core
                ->call(
                    'sale.paysystem.handler.add',
                    [
                        'NAME'     => 'Handler.Rest FORM',
                        'CODE'     => 'resthandlerform',
                        'SORT'     => 100,
                        'SETTINGS' => [
                            'CURRENCY'    => ['USD'],
                            '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'        => 'Store Number',
                                    'DESCRIPTION' => 'Store Number',
                                    '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 Code',
                                    'SORT'    => '1000',
                                    'GROUP'   => 'PAYMENT',
                                    'DEFAULT' => [
                                        'PROVIDER_KEY'   => 'ORDER',
                                        'PROVIDER_VALUE' => 'USER_ID',
                                    ],
                                ],
                                'PS_WORK_MODE'        => [
                                    'NAME'  => 'Payment System Operating Mode',
                                    'SORT'  => '1100',
                                    'INPUT' => [
                                        'TYPE'    => 'ENUM',
                                        'OPTIONS' => [
                                            'TEST'    => 'Test',
                                            'REGULAR' => 'Live',
                                        ],
                                    ],
                                ],
                            ],
                        ],
                    ]
                );
        
            $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": "Handler.Rest FORM",
                "CODE": "resthandlerform",
                "SORT": 100,
                "SETTINGS": {
                    "CURRENCY": [
                        "USD"
                    ],
                    "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": "Store Number",
                            "DESCRIPTION": "Store Number",
                            "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 Code",
                            "SORT": "1000",
                            "GROUP": "PAYMENT",
                            "DEFAULT": {
                                "PROVIDER_KEY": "ORDER",
                                "PROVIDER_VALUE": "USER_ID"
                            }
                        },
                        "PS_WORK_MODE": {
                            "NAME": "Payment System Operating Mode",
                            "SORT": "1100",
                            "INPUT": {
                                "TYPE": "ENUM",
                                "OPTIONS": {
                                    "TEST": "Test",
                                    "REGULAR": "Live"
                                }
                            }
                        }
                    }
                }
            }
            ,
            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' => 'Handler.Rest FORM',
                'CODE' => 'resthandlerform',
                'SORT' => 100,
                'SETTINGS' => [
                    'CURRENCY' => ['USD'],
                    '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' => 'Store Number',
                            'DESCRIPTION' => 'Store Number',
                            '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 Code',
                            'SORT' => '1000',
                            'GROUP' => 'PAYMENT',
                            'DEFAULT' => [
                                'PROVIDER_KEY' => 'ORDER',
                                'PROVIDER_VALUE' => 'USER_ID'
                            ]
                        ],
                        'PS_WORK_MODE' => [
                            'NAME' => 'Payment System Operating Mode',
                            'SORT' => '1100',
                            'INPUT' => [
                                'TYPE' => 'ENUM',
                                'OPTIONS' => [
                                    'TEST' => 'Test',
                                    'REGULAR' => 'Live'
                                ]
                            ]
                        ]
                    ]
                ]
            ]
        );
        
        echo '<PRE>';
        print_r($result);
        echo '</PRE>';

Checkout Operating Mode

When adding a handler, the CHECKOUT_DATA must be passed in the SETTINGS parameter.

A script that will process the received data, create the payment, and return the identifier of the created payment and the URL of the payment page must be located at the address specified in ACTION_URI.

Data for payment will be sent to ACTION_URI in the form of an array. It contains an array of system parameters under the key BX_SYSTEM_PARAMS and the values of FIELDS from CHECKOUT_DATA, each as a separate key at the top level of the array.

Structure of the BX_SYSTEM_PARAMS array:

Name
type

Description

RETURN_URL
string

Current page

PAYSYSTEM_ID
sale_paysystem.ID

Identifier of the payment system

PAYMENT_ID
sale_order_payment.id

Identifier of the payment

SUM
double

Payment amount

CURRENCY
string

Currency

EXTERNAL_PAYMENT_ID
string

Identifier of the payment in the payment system (if any). For example, if a request for the current payment has already been sent to ACTION_URI

In response to a request to ACTION_URI, the script must return the identifier of the created payment and the URL of the payment page.

Name
type

Description

PAYMENT_URL
string

URL of the payment page

PAYMENT_ID
string

Identifier of the payment in the payment system

The buyer will be redirected to the link from PAYMENT_URL automatically or by clicking the "Buy" button. If fields intended for filling through the form are passed among others in FIELDS, a form will be displayed to the buyer.

As a result, an array of errors can be returned under the key PAYMENT_ERRORS. The manager will see the errors in the timeline or on the payment page (depending on the template used).

Name
type

Description

PAYMENT_ERRORS
string[]

List of errors that occurred during payment creation

If nothing is returned, the default error Error registering order in payment system will be used.

Parameters Passed When Adding a Handler in the CHECKOUT_DATA Array

Required parameters are marked with *

Name
type

Description

ACTION_URI*
string

URL to which the request for payment creation is sent

FIELDS
object

Description of fields sent to ACTION_URI. The format is similar to the FIELDS field in the form operating mode (FORM_DATA)

Code Examples

How to Use Examples in Documentation

curl -X POST \
        -H "Content-Type: application/json" \
        -H "Accept: application/json" \
        -d '{"NAME":"Handler.Rest CHECKOUT","CODE":"resthandlercheckout","SORT":100,"SETTINGS":{"CURRENCY":["USD"],"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":"Store Number","DESCRIPTION":"Store Number","SORT":"100"},"REST_SERVICE_KEY_CHECKOUT":{"NAME":"Secret Key","DESCRIPTION":"Secret Key","SORT":"300"},"PS_WORK_MODE_CHECKOUT":{"NAME":"Payment System Operating Mode","SORT":"1100","INPUT":{"TYPE":"ENUM","OPTIONS":{"TEST":"Test","REGULAR":"Live"}}}}}' \
        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":"Handler.Rest CHECKOUT","CODE":"resthandlercheckout","SORT":100,"SETTINGS":{"CURRENCY":["USD"],"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":"Store Number","DESCRIPTION":"Store Number","SORT":"100"},"REST_SERVICE_KEY_CHECKOUT":{"NAME":"Secret Key","DESCRIPTION":"Secret Key","SORT":"300"},"PS_WORK_MODE_CHECKOUT":{"NAME":"Payment System Operating Mode","SORT":"1100","INPUT":{"TYPE":"ENUM","OPTIONS":{"TEST":"Test","REGULAR":"Live"}}}},"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: ['USD'],
                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: ['USD'],
                    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='Handler.Rest CHECKOUT',
                code='resthandlercheckout',
                settings={
                    "CURRENCY": [
                        "USD",
                    ],
                    "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": "Service key",
                            "DESCRIPTION": "Service key",
                            "SORT": "100",
                        },
                        'REST_SERVICE_KEY_CHECKOUT': {
                            "NAME": "Identifier",
                            "DESCRIPTION": "Identifier",
                            "SORT": "300",
                        },
                        'PS_WORK_MODE_CHECKOUT': {
                            "NAME": "Payment system operating mode",
                            "SORT": "1100",
                            "INPUT": {
                                "TYPE": "ENUM",
                                "OPTIONS": {
                                    "TEST": "Test",
                                    "REGULAR": "Live",
                                },
                            },
                        },
                    },
                },
                sort=100,
            ).response
            result = bitrix_response.result
            print(result)
        except BitrixAPIError as error:
            print(
                "Bitrix API error",
                f"error: {error.error}",
                f"error_description: {error.error_description}",
                sep="\n",
            )
        except BitrixSDKException as error:
            print(f"Bitrix SDK error: {error.message}")
        except Exception as error:
            print(f"Unexpected error: {error}")
        
try {
            $response = $b24Service
                ->core
                ->call(
                    'sale.paysystem.handler.add',
                    [
                        'NAME'     => 'Handler.Rest CHECKOUT',
                        'CODE'     => 'resthandlercheckout',
                        'SORT'     => 100,
                        'SETTINGS' => [
                            'CURRENCY'    => ['USD'],
                            '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'        => 'Store Number',
                                    'DESCRIPTION' => 'Store Number',
                                    'SORT'        => '100'
                                ],
                                'REST_SERVICE_KEY_CHECKOUT' => [
                                    'NAME'        => 'Secret Key',
                                    'DESCRIPTION' => 'Secret Key',
                                    'SORT'        => '300'
                                ],
                                'PS_WORK_MODE_CHECKOUT'     => [
                                    'NAME'  => 'Payment System Operating Mode',
                                    'SORT'  => '1100',
                                    'INPUT' => [
                                        'TYPE'    => 'ENUM',
                                        'OPTIONS' => [
                                            'TEST'    => 'Test',
                                            'REGULAR' => 'Live'
                                        ]
                                    ]
                                ]
                            ]
                        ]
                    ]
                );
        
            $result = $response
                ->getResponseData()
                ->getResult();
        
            echo 'Handler added with ID ' . $result;
        
        } catch (Throwable $e) {
            error_log($e->getMessage());
            echo 'Error adding payment system handler: ' . $e->getMessage();
        }
        
BX24.callMethod(
            "sale.paysystem.handler.add",
            {
                "NAME": "Handler.Rest CHECKOUT",
                "CODE": "resthandlercheckout",
                "SORT": 100,
                "SETTINGS": {
                    "CURRENCY": [
                        "USD"
                    ],
                    "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": "Store Number",
                            "DESCRIPTION": "Store Number",
                            "SORT": "100"
                        },
                        "REST_SERVICE_KEY_CHECKOUT": {
                            "NAME": "Secret Key",
                            "DESCRIPTION": "Secret Key",
                            "SORT": "300"
                        },
                        "PS_WORK_MODE_CHECKOUT": {
                            "NAME": "Payment System Operating Mode",
                            "SORT": "1100",
                            "INPUT": {
                                "TYPE": "ENUM",
                                "OPTIONS": {
                                    "TEST": "Test",
                                    "REGULAR": "Live"
                                }
                            }
                        }
                    }
                }
            }
            ,
            function (result) {
                if (result.error())
                {
                    console.error(result.error());
                }
                else
                {
                    console.info("Handler added with ID " + result.data());
                }
            }
        );
        
require_once('crest.php');
        
        $result = CRest::call(
            'sale.paysystem.handler.add',
            [
                'NAME' => 'Handler.Rest CHECKOUT',
                'CODE' => 'resthandlercheckout',
                'SORT' => 100,
                'SETTINGS' => [
                    'CURRENCY'    => ['USD'],
                    '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' => 'Store Number',
                            'DESCRIPTION' => 'Store Number',
                            'SORT' => '100'
                        ],
                        'REST_SERVICE_KEY_CHECKOUT' => [
                            'NAME' => 'Secret Key',
                            'DESCRIPTION' => 'Secret Key',
                            'SORT' => '300'
                        ],
                        'PS_WORK_MODE_CHECKOUT' => [
                            'NAME' => 'Payment System Operating Mode',
                            'SORT' => '1100',
                            'INPUT' => [
                                'TYPE' => 'ENUM',
                                'OPTIONS' => [
                                    'TEST' => 'Test',
                                    'REGULAR' => 'Live'
                                ]
                            ]
                        ]
                    ]
                ]
            ]
        );
        
        echo '<PRE>';
        print_r($result);
        echo '</PRE>';

IFrame Operating Mode

When adding a handler, the IFRAME_DATA must be passed in the SETTINGS parameter.

A page that will be loaded in an iframe on the seller's site must be located at the address specified in ACTION_URI.

When loading the iframe via the Window.postMessage() method, the values of FIELDS from IFRAME_DATA will be sent to ACTION_URI (each as a separate key at the top level of the array), as well as the following data:

Name
type

Description

BX_SYSTEM_PARAMS
object

System parameters

BX_COMPUTED_STYLE
object

Styles of the parent iframe element obtained via the window.getComputedStyle() method

Data sent in BX_SYSTEM_PARAMS:

Name
type

Description

RETURN_URL
string

Current page

PAYSYSTEM_ID
sale_paysystem.ID

Identifier of the payment system

PAYMENT_ID
sale_order_payment.id

Identifier of the payment

SUM
string

Payment amount

CURRENCY
string

Currency

You can get values in the iframe through the message event handler, for example:

document.addEventListener("DOMContentLoaded", function() {
            window.addEventListener("message", function (event) {
                // receiving data from the site (from the payment system)
                var paymentData = event.data;
                // working with BX_SYSTEM_PARAMS
                if (paymentData.BX_SYSTEM_PARAMS)
                {
                    // ...
                }
                // using site styles
                if (paymentData.BX_COMPUTED_STYLE)
                {
                    document.body.style.background = paymentData.BX_COMPUTED_STYLE.background;
                    document.body.style.color = paymentData.BX_COMPUTED_STYLE.color;
                }
            }, false);
        });

By default, the width of the iframe is 100% of the parent element, and the height is 350px.

The dimensions of the iframe can be changed. To do this, the height and/or width must be sent from the iframe to the seller's site. For example:

document.addEventListener("DOMContentLoaded", function() {
            var size = {
                width: document.body.scrollWidth,
                height: document.body.scrollHeight
            };
            // sending data to the seller's site
            parent.postMessage(size, "*");
        });

width and height are reserved variable names, and only they are processed on the seller's site.

Parameters Passed When Adding a Handler in the IFRAME_DATA Array

Required parameters are marked with *

Name
type

Description

ACTION_URI*
string

URL of the page that will be displayed in the iframe

FIELDS
object

Description of fields sent to the iframe. The format is similar to the FIELDS field in the form operating mode (FORM_DATA)

Code Examples

How to Use Examples in Documentation

curl -X POST \
        -H "Content-Type: application/json" \
        -H "Accept: application/json" \
        -d '{"NAME":"Handler.Rest IFrame","CODE":"resthandleriframe","SORT":100,"SETTINGS":{"CURRENCY":["USD"],"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":"Store Number","DESCRIPTION":"Store Number","SORT":"100"},"REST_SERVICE_KEY_IFRAME":{"NAME":"Secret Key","DESCRIPTION":"Secret Key","SORT":"300"},"PS_WORK_MODE_IFRAME":{"NAME":"Payment System Operating Mode","SORT":"1100","INPUT":{"TYPE":"ENUM","OPTIONS":{"TEST":"Test","REGULAR":"Live"}}}}}' \
        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":"Handler.Rest IFrame","CODE":"resthandleriframe","SORT":100,"SETTINGS":{"CURRENCY":["USD"],"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":"Store Number","DESCRIPTION":"Store Number","SORT":"100"},"REST_SERVICE_KEY_IFRAME":{"NAME":"Secret Key","DESCRIPTION":"Secret Key","SORT":"300"},"PS_WORK_MODE_IFRAME":{"NAME":"Payment System Operating Mode","SORT":"1100","INPUT":{"TYPE":"ENUM","OPTIONS":{"TEST":"Test","REGULAR":"Live"}}}},"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: ['USD'],
                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: ['USD'],
                    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='Handler.Rest IFrame',
                code='resthandleriframe',
                settings={
                    "CURRENCY": [
                        "USD",
                    ],
                    "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": "Service key",
                            "DESCRIPTION": "Service key",
                            "SORT": "100",
                        },
                        'REST_SERVICE_KEY_IFRAME': {
                            "NAME": "Identifier",
                            "DESCRIPTION": "Identifier",
                            "SORT": "300",
                        },
                        'PS_WORK_MODE_IFRAME': {
                            "NAME": "Payment system operating mode",
                            "SORT": "1100",
                            "INPUT": {
                                "TYPE": "ENUM",
                                "OPTIONS": {
                                    "TEST": "Test",
                                    "REGULAR": "Live",
                                },
                            },
                        },
                    },
                },
                sort=100,
            ).response
            result = bitrix_response.result
            print(result)
        except BitrixAPIError as error:
            print(
                "Bitrix API error",
                f"error: {error.error}",
                f"error_description: {error.error_description}",
                sep="\n",
            )
        except BitrixSDKException as error:
            print(f"Bitrix SDK error: {error.message}")
        except Exception as error:
            print(f"Unexpected error: {error}")
        
try {
            $response = $b24Service
                ->core
                ->call(
                    'sale.paysystem.handler.add',
                    [
                        'NAME'     => 'Handler.Rest IFrame',
                        'CODE'     => 'resthandleriframe',
                        'SORT'     => 100,
                        'SETTINGS' => [
                            'CURRENCY'    => ['USD'],
                            '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'        => 'Store Number',
                                    'DESCRIPTION' => 'Store Number',
                                    'SORT'        => '100'
                                ],
                                'REST_SERVICE_KEY_IFRAME' => [
                                    'NAME'        => 'Secret Key',
                                    'DESCRIPTION' => 'Secret Key',
                                    'SORT'        => '300'
                                ],
                                'PS_WORK_MODE_IFRAME'     => [
                                    'NAME'  => 'Payment System Operating Mode',
                                    'SORT'  => '1100',
                                    'INPUT' => [
                                        'TYPE'    => 'ENUM',
                                        'OPTIONS' => [
                                            'TEST'    => 'Test',
                                            'REGULAR' => 'Live'
                                        ]
                                    ]
                                ]
                            ]
                        ]
                    ]
                );
        
            $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": "Handler.Rest IFrame",
                "CODE": "resthandleriframe",
                "SORT": 100,
                "SETTINGS": {
                    "CURRENCY": [
                        "USD"
                    ],
                    "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": "Store Number",
                            "DESCRIPTION": "Store Number",
                            "SORT": "100"
                        },
                        "REST_SERVICE_KEY_IFRAME": {
                            "NAME": "Secret Key",
                            "DESCRIPTION": "Secret Key",
                            "SORT": "300"
                        },
                        "PS_WORK_MODE_IFRAME": {
                            "NAME": "Payment System Operating Mode",
                            "SORT": "1100",
                            "INPUT": {
                                "TYPE": "ENUM",
                                "OPTIONS": {
                                    "TEST": "Test",
                                    "REGULAR": "Live"
                                }
                            }
                        }
                    }
                }
            }
            ,
            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' => 'Handler.Rest IFrame',
                'CODE' => 'resthandleriframe',
                'SORT' => 100,
                'SETTINGS' => [
                    'CURRENCY' => ['USD'],
                    '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' => 'Store Number',
                            'DESCRIPTION' => 'Store Number',
                            'SORT' => '100'
                        ],
                        'REST_SERVICE_KEY_IFRAME' => [
                            'NAME' => 'Secret Key',
                            'DESCRIPTION' => 'Secret Key',
                            'SORT' => '300'
                        ],
                        'PS_WORK_MODE_IFRAME' => [
                            'NAME' => 'Payment System Operating Mode',
                            'SORT' => '1100',
                            'INPUT' => [
                                'TYPE' => 'ENUM',
                                'OPTIONS' => [
                                    'TEST' => 'Test',
                                    'REGULAR' => 'Live'
                                ]
                            ]
                        ]
                    ]
                ]
            ]
        );
        
        echo '<PRE>';
        print_r($result);
        echo '</PRE>';

Response Handling

HTTP Status: 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
            }
        }

Returned Data

Name
type

Description

result
sale_paysystem_handler.ID

Identifier of the created handler, used later for updating and deleting it

time
time

Information about the request execution time

Error Handling

HTTP Status: 400, 403

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

Name
type

Description

error
string

String error code. It consists of digits, Latin letters, and underscores. It may arrive empty — in that case only error_description shows the reason

error_description
string

Error message for the developer. Do not show it to the end user without processing

Possible Error Codes

Code

Description

Status

ACCESS_DENIED

Insufficient permissions to add the handler

403

ERROR_CHECK_FAILURE

Required field value is not specified or one of the field values is incorrect

400

ERROR_HANDLER_ALREADY_EXIST

A handler with the code specified in the CODE parameter already exists in the system

400

ERROR_HANDLER_ADD

Other errors. For detailed information about the error, see error_description

400

Statuses and System Error Codes

HTTP Status: 4xx, 5xx

The errors described below are returned by the REST API itself, not by the logic of a specific method. They can arrive in response to any method.

Status

Code
Error Message

Description

500

INTERNAL_SERVER_ERROR
Internal server error

An internal server error has occurred. Retry the call, and if the error persists, contact the server administrator or Bitrix24 technical support

500

ERROR_UNEXPECTED_ANSWER
Server returned an unexpected response

The server returned an unexpected response. Retry the call, and if the error persists, contact the server administrator or Bitrix24 technical support

503

QUERY_LIMIT_EXCEEDED
Too many requests

The request intensity limit has been exceeded

429

OPERATION_TIME_LIMIT
Method is blocked due to operation time limit

The method is blocked because the request resource intensity limit has been exceeded. The block is lifted automatically once the accumulated execution time of the method no longer exceeds the limit

401

NO_AUTH_FOUND
Wrong authorization data

The request contains no authorization data: neither an access token nor a webhook code was passed

401

INVALID_REQUEST
Https required

Methods are called over the HTTPS protocol only

401

OVERLOAD_LIMIT
REST API is blocked due to overload

The REST API is blocked due to overload. This is a manual individual block. To have it lifted, contact Bitrix24 technical support

401

ACCESS_DENIED
REST is available only on commercial plans

REST API access is not active for this account. In Bitrix24 Cloud, check the current plan or trial status: Vibe+ plans include REST API access, while Essentials plans do not. A webhook receives a different error message — REST is available only by subscription

401

INVALID_CREDENTIALS
Invalid request credentials

No active webhook with the specified user identifier and secret code was found

404

ERROR_METHOD_NOT_FOUND
Method not found!

No method with this name was found. The name is misspelled, the method does not exist in the REST API, or it is unavailable without the required scope

401

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

The request requires broader permissions than the token has: for a webhook these are the permissions granted to it, for an application it is the scope. For an application, the error message ends with provided by the access token

401

expired_token
The access token provided has expired

The access token has expired

401

user_access_error
The user does not have access to the application

The application is installed, but the Bitrix24 administrator has granted access to it only to specific users

403

PORTAL_DELETED
Portal was deleted

The public part of the site is closed. To open it on an on-premise installation, disable the "Temporary closure of the public part of the site" option. Path to the setting: Desktop > Settings > Product Settings > Module Settings > Main Module > Temporary closure of the public part of the site

Continue Learning

Previous
Overview of Methods
Next
Update Payment System REST Handler