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

If you are developing integrations for Bitrix24 using AI tools (Codex, Claude Code, Cursor), connect to the MCP server so the assistant can use 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 `int`	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](../data-types.md)

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 (Webhook)

cURL (OAuth)

PHP

BX24.js

PHP CRest

curl -X POST \
        -H "Content-Type: application/json" \
        -H "Accept: application/json" \
        -d '{"NAME":"Handler.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":"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":["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":"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

try
        {
            const response = await $b24.callMethod(
                "sale.paysystem.handler.add",
                {
                    "NAME": "Handler.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": "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"
                                    }
                                }
                            }
                        }
                    }
                }
            );
            
            const result = response.getData().result;
            console.info(result);
        }
        catch(error)
        {
            console.error(error);
        }

try {
            $response = $b24Service
                ->core
                ->call(
                    'sale.paysystem.handler.add',
                    [
                        'NAME'     => 'Handler.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' => '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": [
                        "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": "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' => ['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' => '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 (Webhook)

cURL (OAuth)

PHP

BX24.js

PHP CRest

curl -X POST \
        -H "Content-Type: application/json" \
        -H "Accept: application/json" \
        -d '{"NAME":"Handler.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":"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":["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":"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

try
        {
            const response = await $b24.callMethod(
                "sale.paysystem.handler.add",
                {
                    "NAME": "Handler.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": "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"
                                    }
                                }
                            }
                        }
                    }
                }
            );
            
            const result = response.getData().result;
            console.info("Handler added with ID " + result);
        }
        catch( error )
        {
            console.error(error);
        }

try {
            $response = $b24Service
                ->core
                ->call(
                    'sale.paysystem.handler.add',
                    [
                        'NAME'     => 'Handler.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'        => '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": [
                        "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": "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'    => ['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' => '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 (Webhook)

cURL (OAuth)

PHP

BX24.js

PHP CRest

curl -X POST \
        -H "Content-Type: application/json" \
        -H "Accept: application/json" \
        -d '{"NAME":"Handler.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":"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":["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":"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

try
        {
            const response = await $b24.callMethod(
                "sale.paysystem.handler.add",
                {
                    "NAME": "Handler.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": "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"
                                    }
                                }
                            }
                        }
                    }
                }
            );
            
            const result = response.getData().result;
            console.info(result);
        }
        catch( error )
        {
            console.error(error);
        }

try {
            $response = $b24Service
                ->core
                ->call(
                    'sale.paysystem.handler.add',
                    [
                        'NAME'     => 'Handler.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'        => '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": [
                        "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": "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' => ['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' => '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 may consist of digits, Latin letters, and underscores
error_description `error_description`	Textual description of the error. The description is not intended to be shown to the end user in its raw form

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: 20x, 40x, 50x

The errors described below may occur when calling any method.

Status	Code Error Message	Description
`500`	`INTERNAL_SERVER_ERROR` Internal server error	An internal server error has occurred. Please contact the server administrator or Bitrix24 technical support
`500`	`ERROR_UNEXPECTED_ANSWER` Server returned an unexpected response	An internal server error has occurred. Please contact the server administrator or Bitrix24 technical support
`503`	`QUERY_LIMIT_EXCEEDED` Too many requests	The request intensity limit has been exceeded
`405`	`ERROR_BATCH_METHOD_NOT_ALLOWED` Method is not allowed for batch usage	The current method is not permitted for calls using batch
`400`	`ERROR_BATCH_LENGTH_EXCEEDED` Max batch length exceeded	The maximum length of parameters passed to the batch method has been exceeded
`401`	`NO_AUTH_FOUND` Wrong authorization data	Invalid access token or webhook code
`400`	`INVALID_REQUEST` Https required	The HTTPS protocol is required for method calls
`503`	`OVERLOAD_LIMIT` REST API is blocked due to overload	The REST API is blocked due to overload. This is a manual individual block; please contact Bitrix24 technical support to lift it
`403`	`ACCESS_DENIED` REST API is available only on commercial plans	The REST API is only available on commercial plans
`403`	`INVALID_CREDENTIALS` Invalid request credentials	The user associated with the access token or webhook used to call the method lacks the necessary permissions
`404`	`ERROR_MANIFEST_IS_NOT_AVAILABLE` Manifest is not available	The manifest is not available
`403`	`insufficient_scope` The request requires higher privileges than provided by the webhook token	The request requires higher privileges than those provided by the webhook token
`401`	`expired_token` The access token provided has expired	The provided access token has expired
`403`	`user_access_error` The user does not have access to the application	The user does not have access to the application. This means that the application is installed, but the portal administrator has restricted access to this application to specific users only
`500`	`PORTAL_DELETED` Portal was deleted	The public part of the site is closed. To open the public part of the site 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

Overview of Methods

Update Payment System REST Handler

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

Method ParametersMethod Parameters

SETTINGS ParameterSETTINGS Parameter

CODES ParameterCODES Parameter

DEFAULT ParameterDEFAULT Parameter

Possible Values for PROVIDER_KEYPossible Values for PROVIDER_KEY

Possible Values for PROVIDER_VALUEPossible Values for PROVIDER_VALUE

Form Operating ModeForm Operating Mode

Parameters Passed When Adding a Handler in the FORM_DATA ArrayParameters Passed When Adding a Handler in the FORM_DATA Array

FIELDS ParameterFIELDS Parameter

CODE ParameterCODE Parameter

Code ExamplesCode Examples

Checkout Operating ModeCheckout Operating Mode

Parameters Passed When Adding a Handler in the CHECKOUT_DATA ArrayParameters Passed When Adding a Handler in the CHECKOUT_DATA Array

Code ExamplesCode Examples

IFrame Operating ModeIFrame Operating Mode

Parameters Passed When Adding a Handler in the IFRAME_DATA ArrayParameters Passed When Adding a Handler in the IFRAME_DATA Array

Code ExamplesCode Examples

Response HandlingResponse Handling

Returned DataReturned Data

Error HandlingError Handling

Possible Error CodesPossible Error Codes

Statuses and System Error CodesStatuses and System Error Codes

Continue LearningContinue Learning

Method Parameters

SETTINGS Parameter

CODES Parameter

DEFAULT Parameter

Possible Values for PROVIDER_KEY

Possible Values for PROVIDER_VALUE

Form Operating Mode

Parameters Passed When Adding a Handler in the FORM_DATA Array

FIELDS Parameter

CODE Parameter

Code Examples

Checkout Operating Mode

Parameters Passed When Adding a Handler in the CHECKOUT_DATA Array

Code Examples

IFrame Operating Mode

Parameters Passed When Adding a Handler in the IFRAME_DATA Array

Code Examples

Response Handling

Returned Data

Error Handling

Possible Error Codes

Statuses and System Error Codes

Continue Learning