Перейти к основному содержимому
Версия: 2026.09.1

Создание зарплатного платежа

Создаёт зарплатный платёж со списком сотрудников employees и транзитным счётом beneficiary. Передайте domesticTransferType=Payroll.

EndpointPOST /domestic-payment-service/api/v1/external-payment
Content-Typeapplication/json
АвторизацияOAuth2 / JWT (Bearer token)

Тело запроса​

ПолеТипОбязательностьОписание
idLongНетИдентификатор платежа. При создании не передаётся, используется при обновлении
domesticTransferTypeenum (DomesticTransferType)ДаТип платежа: Payroll
numberStringДаНомер документа; проверяется, что не пусто
amountBigDecimalДаСумма пакета целиком; сверяется с суммой по сотрудникам (см. раздел «Правила валидации»)
senderResidencyCountry.twoLetterCodeStringДаКод страны отправителя
senderResidencyCountry.nameStringНетНаименование страны отправителя
actualSender.taxCodeStringНетБИН/ИИН фактического отправителя
actualSender.nameStringНетИмя фактического отправителя
actualSender.typeenum (ActualSenderType)НетТип (DEBTOR)
paymentSourceenum (PaymentSource)—Вычисляется сервером, клиентом не передаётся
valueDateLocalDate (yyyy-MM-dd)ДаДата валютирования
purpose.codeStringДаКод назначения платежа (КНП). Для Payroll код должен существовать в справочнике КНП и (если настроен) входить в allow-list TRANSFER_FROM_PAYROLL_KNP
purpose.labelStringДаТекст назначения платежа
prioritybooleanНетПризнак срочности
infoStringНетДоп. информация по назначению; максимум 700 символов
account.currencyStringДаВалюта счёта списания
account.numberStringДаIBAN счёта списания; счёт должен существовать и быть в KZT
account.aliasStringНетПсевдоним
account.balanceBigDecimalНетБаланс
account.typeenum AccountTypeДаТип счёта
beneficiary.accountStringДаТранзитный счёт, через который выплата разводится по сотрудникам (не «контрагент»); должен резолвиться в банк через справочник транзитных счетов
beneficiary.nameStringДаНаименование получателя (банка)
beneficiary.bankCodeStringДаКод банка получателя
beneficiary.taxCodeStringДаБИН/ИИН получателя
beneficiary.bankNameStringДаБанк получателя
beneficiary.bankBICStringДаBIC банка получателя
beneficiary.residencyAndEconomicCodeStringДаКБе
beneficiary.counterpartyIdLongНетID контрагента
beneficiary.residencyCountryCode.twoLetterCodeStringДаСтрана получателя (код)
beneficiary.residencyCountryCode.nameStringНетСтрана получателя (название)
kvo.codeStringУсловноКод валютной операции
kvo.labelStringУсловноНаименование КВО
employeesList<EmployeeRequest>ДаСписок сотрудников; см. таблицу полей EmployeeRequest ниже. Сумма по сотрудникам должна совпадать с amount
subsidiary.subsidiaryOrganizationIdLongНетID дочерней организации

Поля элемента списка employees (EmployeeRequest)​

ПолеТипОбязательностьОписание
idLongНетИдентификатор сотрудника (при ссылке на сохранённого сотрудника)
firstNameStringДаИмя сотрудника
lastNameStringДаФамилия сотрудника
middleNameStringНетОтчество сотрудника
amountBigDecimalДаСумма выплаты сотруднику
accountStringДаЛицевой счёт сотрудника
taxCodeStringДаИИН сотрудника
residencyCountryCodeStringНе уточненоКод резидентства страны сотрудника

Пример тела запроса​

Реквизиты и суммы в примере условные. Замените их актуальными значениями.

{
"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)
КНП разрешён для Payrollpurpose.code не входит в allow-list TRANSFER_FROM_PAYROLL_KNP (если allow-list не пуст)Errors.FORBIDDEN_PURPOSE_CODE
Счёт списания в KZTaccount.number не найден или его валюта не KZTУчетная запись не найдена в базе данных / Валюта должна быть KZT
Транзитный счёт существуетbeneficiary.account не резолвится в банк через справочник транзитных счетовБанк по этому счёту не найден (error.payroll.transit_account)
Отправитель ≠ бенефициарaccount.number == beneficiary.accountСчет отправителя и получателя совпадают (validation.v1.sender_and_beneficiary_account_number_same)
info — максимум 700 символовдлина info > 700MAX_LENGTH_700
number не пустоnumber пусто/отсутствуетПоле не может быть пустым (validation.v1.field_is_empty)

Тело ответа​

ПолеТипОписание
paymentIdLongИдентификатор созданного платежа

Коды ошибок​

КодУсловие
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 включает сверку общей суммы с суммой по сотрудникам; сама по себе она не даёт право создать платёж.

Следующие действия​

Инициализация подписания → подписание с синхронной отправкой в АБС. Результат доступен через получение платежа.