Создание зарплатного платежа
Создаёт зарплатный платёж со списком сотрудников employees и транзитным счётом beneficiary. Передайте domesticTransferType=Payroll.
| Endpoint | POST /domestic-payment-service/api/v1/external-payment |
| Content-Type | application/json |
| Авторизация | OAuth2 / JWT (Bearer token) |
Тело запроса
| Поле | Тип | Обязательность | Описание |
|---|---|---|---|
id | Long | Нет | Идентификатор платежа. При создании не передаётся, используется при обновлении |
domesticTransferType | enum (DomesticTransferType) | Да | Тип платежа: Payroll |
number | String | Да | Номер документа; проверяется, что не пусто |
amount | BigDecimal | Да | Сумма пакета целиком; сверяется с суммой по сотрудникам (см. раздел «Правила валидации») |
senderResidencyCountry.twoLetterCode | String | Да | Код страны отправителя |
senderResidencyCountry.name | String | Нет | Наименование страны отправителя |
actualSender.taxCode | String | Нет | БИН/ИИН фактического отправителя |
actualSender.name | String | Нет | Имя фактического отправителя |
actualSender.type | enum (ActualSenderType) | Нет | Тип (DEBTOR) |
paymentSource | enum (PaymentSource) | — | Вычисляется сервером, клиентом не передаётся |
valueDate | LocalDate (yyyy-MM-dd) | Да | Дата валютирования |
purpose.code | String | Да | Код назначения платежа (КНП). Для Payroll код должен существовать в справочнике КНП и (если настроен) входить в allow-list TRANSFER_FROM_PAYROLL_KNP |
purpose.label | String | Да | Текст назначения платежа |
priority | boolean | Нет | Признак срочности |
info | String | Нет | Доп. информация по назначению; максимум 700 символов |
account.currency | String | Да | Валюта счёта списания |
account.number | String | Да | IBAN счёта списания; счёт должен существовать и быть в KZT |
account.alias | String | Нет | Псевдоним |
account.balance | BigDecimal | Нет | Баланс |
account.type | enum AccountType | Да | Тип счёта |
beneficiary.account | String | Да | Транзитный счёт, через который выплата разводится по сотрудникам (не «контрагент»); должен резолвиться в банк через справочник транзитных счетов |
beneficiary.name | String | Да | Наименование получателя (банка) |
beneficiary.bankCode | String | Да | Код банка получателя |
beneficiary.taxCode | String | Да | БИН/ИИН получателя |
beneficiary.bankName | String | Да | Банк получателя |
beneficiary.bankBIC | String | Да | BIC банка получателя |
beneficiary.residencyAndEconomicCode | String | Да | КБе |
beneficiary.counterpartyId | Long | Нет | ID контрагента |
beneficiary.residencyCountryCode.twoLetterCode | String | Да | Страна получателя (код) |
beneficiary.residencyCountryCode.name | String | Нет | Страна получателя (название) |
kvo.code | String | Условно | Код валютной операции |
kvo.label | String | Условно | Наименование КВО |
employees | List<EmployeeRequest> | Да | Список сотрудников; см. таблицу полей EmployeeRequest ниже. Сумма по сотрудникам должна совпадать с amount |
subsidiary.subsidiaryOrganizationId | Long | Нет | ID дочерней организации |
Поля элемента списка employees (EmployeeRequest)
| Поле | Тип | Обязательность | Описание |
|---|---|---|---|
id | Long | Нет | Идентификатор сотрудника (при ссылке на сохранённого сотрудника) |
firstName | String | Да | Имя сотрудника |
lastName | String | Да | Фамилия сотрудника |
middleName | String | Нет | Отчество сотрудника |
amount | BigDecimal | Да | Сумма выплаты сотруднику |
account | String | Да | Лицевой счёт сотрудника |
taxCode | String | Да | ИИН сотрудника |
residencyCountryCode | String | Не уточнено | Код резидентства страны сотрудника |
Пример тела запроса
Реквизиты и суммы в примере условные. Замените их актуальными значениями.
{
"domesticTransferType": "Payroll",
"account": {
"status": "ACTIVE",
"currency": "KZT",
"number": "KZ11111111111KZ11111",
"type": "Current"
},
"beneficiary": {
"account": "KZ11111111111KZ11111",
"name": "АО BANK",
"bankCode": "914",
"taxCode": "111111111111",
"bankBIC": "BBBBBBBBB",
"residencyAndEconomicCode": "14"
},
"amount": 111111,
"valueDate": "2026-07-16",
"employees": [
{
"lastName": "Тест",
"firstName": "Тест",
"middleName": "Тест",
"taxCode": "111111111111",
"amount": 111111,
"account": "KZ111111111111111111",
"residencyCountryCode": "KZ"
},
{
"lastName": "Test",
"firstName": "Test",
"middleName": "Test",
"taxCode": "111111111111",
"amount": 11111,
"account": "KZ11111C1111111111",
"residencyCountryCode": "KZ"
}
],
"purpose": {
"code": "332",
"label": "Перечисление юридическим лицом в банк заработной платы, оплаты трудового отпуска для последующего зачисления на банковские счета работников данного юридического лица"
},
"kvo": null,
"info": "Тест назначение свободное поле",
"number": "1",
"priority": false,
"actualSender": null,
"subsidiary": null
}
В примере из описания метода общая сумма 111111 отличается от суммы сотрудников 122222, а счета списания и получателя совпадают. Также отсутствуют поля senderResidencyCountry.twoLetterCode, beneficiary.bankName и beneficiary.residencyCountryCode.twoLetterCode, отмеченные в таблице как обязательные. Перед отправкой заполните обязательные поля и приведите данные к правилам валидации ниже.
Правила валидации
| Правило | Условие срабатывания | Сообщение (RU) |
|---|---|---|
| Сумма по сотрудникам = amount | Только если у пользователя есть привилегия dompay_list_employee_amount; иначе проверка молча пропускается | Сумма по сотрудникам не совпадает с общей суммой (validation.v1.employee_sum_not_equal_to_total_sum) |
| КНП существует | purpose.code не найден в справочнике КНП | КНП с таким кодом не найден (validation.v1.knp_not_found) |
| КНП разрешён для Payroll | purpose.code не входит в allow-list TRANSFER_FROM_PAYROLL_KNP (если allow-list не пуст) | Errors.FORBIDDEN_PURPOSE_CODE |
| Счёт списания в KZT | account.number не найден или его валюта не KZT | Учетная запись не найдена в базе данных / Валюта должна быть KZT |
| Транзитный счёт существует | beneficiary.account не резолвится в банк через справочник транзитных счетов | Банк по этому счёту не найден (error.payroll.transit_account) |
| Отправитель ≠ бенефициар | account.number == beneficiary.account | Счет отправителя и получателя совпадают (validation.v1.sender_and_beneficiary_account_number_same) |
| info — максимум 700 символов | длина info > 700 | MAX_LENGTH_700 |
| number не пусто | number пусто/отсутствует | Поле не может быть пустым (validation.v1.field_is_empty) |
Тело ответа
| Поле | Тип | Описание |
|---|---|---|
paymentId | Long | Идентификатор созданного платежа |
Коды ошибок
| Код | Условие |
|---|---|
| 400 Bad Request | Невалидный JSON / неизвестный domesticTransferType / нарушение constraint полей |
| 401 Unauthorized | Отсутствует/невалиден JWT |
| 403 Forbidden | Нет привилегии cp_new_payroll |
| 400 / бизнес-ошибки валидации | Возвращаются как ValidationExceptionResponse (список ошибок по полям, см. раздел «Правила валидации») |
Пример ошибки валидации — транзитный счёт не найден:
{
"validationExceptions": [
{
"fieldName": "beneficiary.account",
"translationKey": "error.payroll.transit_account",
"message": "Bank for this account not found",
"translatedMessage": "Банк по этому счёту не найден"
}
]
}
Пример ошибки валидации — сумма по сотрудникам не совпадает с общей суммой:
{
"validationExceptions": [
{
"fieldName": "amount",
"translationKey": "validation.v1.employee_sum_not_equal_to_total_sum",
"message": "Employee amount sum not equal to total sum",
"translatedMessage": "Сумма по сотрудникам не совпадает с общей суммой"
}
]
}
Необходимые привилегии
cp_new_payroll
Для создания требуется cp_new_payroll. Привилегия dompay_list_employee_amount включает сверку общей суммы с суммой по сотрудникам; сама по себе она не даёт право создать платёж.
Следующие действия
Инициализация подписания → подписание с синхронной отправкой в АБС. Результат доступен через получение платежа.