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

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

Создаёт платёж по реестру сотрудников. Передайте paymentProductType=SEPARATE_PAYMENT и один из типов MedicalContribution, PensionContribution, SocialContribution, InsuranceContribution, SingleContribution.

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

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

ПолеТипОбязательностьОписание
idLongНетИдентификатор платежа. При создании не передаётся, используется при обновлении
domesticTransferTypeenum (DomesticTransferType)ДаОдно из: "MedicalContribution", "PensionContribution", "SocialContribution", "InsuranceContribution", "SingleContribution"
numberStringДаНомер документа
amountBigDecimalДаСумма пакета целиком; сверяется с суммой по сотрудникам
senderResidencyCountry.twoLetterCodeStringДаКод страны отправителя
senderResidencyCountry.nameStringНетНаименование страны отправителя
actualSender.taxCodeStringНетБИН/ИИН фактического отправителя
actualSender.nameStringНетИмя фактического отправителя
actualSender.typeenum (ActualSenderType)НетТип (DEBTOR)
paymentSourceenum (PaymentSource)—Вычисляется сервером, клиентом не передаётся
valueDateLocalDate (yyyy-MM-dd)ДаДата валютирования
purpose.codeStringДаКод назначения платежа (КНП)
purpose.labelStringДаТекст назначения платежа
prioritybooleanНетПризнак срочности
infoStringНетДоп. информация по назначению
employeeTransferCategoryStringУсловноКатегория периода, заданная индивидуально для конкретного сотрудника
employeeTransferPeriodLocalDate (yyyy-MM-dd)УсловноПериод если общий для всех сотрудников
account.currencyStringДаВалюта счёта списания
account.numberStringДаIBAN счёта списания
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НетСтрана получателя (название): передавать для каждого сотрудника не требуется
employeesList<EmployeeRequest>ДаСписок сотрудников; не может быть пустым, см. таблицу ниже и раздел «Правила валидации»
subsidiary.subsidiaryOrganizationIdLongНетID дочерней организации
paymentProductTypeenum (PaymentProductType)Дадля списочных платежей всегда SEPARATE_PAYMENT
taxCommitteePaymentTaxCommitteeRequestНе используетсяУнаследовано от AbstractPaymentRequest; для списочных платежей не заполняется

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

Поля fullAmount и paymentPurposes относятся к единому платежу (SingleContribution); согласно описанию метода, при обработке запроса не используются.

ПолеТипОбязательностьОписание
idLongНетИдентификатор сотрудника (при обновлении существующей записи)
firstNameStringДаИмя сотрудника
lastNameStringДаФамилия сотрудника
middleNameStringНетОтчество сотрудника
amountBigDecimalДаСумма выплаты сотруднику
accountStringДаЛицевой счёт сотрудника
taxCodeStringДаИИН сотрудника
periodLocalDate (yyyy-MM-dd)УсловноПериод отчисления
birthDateLocalDate (yyyy-MM-dd)НетДата рождения
residencyCountryCodeStringНетКод резидентства страны сотрудника
fullAmountBigDecimalНетПолная сумма с учётом всех отчислений (модель «Единого платежа»; не читается бэкендом)
paymentPurposesList<String>НетСписок кодов КНП (модель «Единого платежа»; не читается бэкендом)
modifiedbooleanНетПризнак, что запись сотрудника должна быть обновлена в справочнике employee
externalIdLongНетВнутренний id сотрудника, используется в личном кабинете сотрудников

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

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

Пример для MedicalContribution. Для других типов используйте соответствующие значения domesticTransferType, КНП и реквизитов получателя.

{
"number": "123",
"valueDate": "2026-07-28",
"paymentProductType": "SEPARATE_PAYMENT",
"domesticTransferType": "MedicalContribution",
"purpose": {
"code": "121",
"label": "Отчисления на обязательное социальное медицинское страхование"
},
"beneficiary": {
"account": "KZ11111MEDS111111111",
"name": "НАО “Государственная корпорация “Правительство для граждан”",
"bankCode": "009",
"bankBIC": "GCVPKZ2A",
"bankName": "НАО «Государственная корпорация «Правительство для граждан»",
"taxCode": "111111111111",
"residencyAndEconomicCode": "11",
"residencyCountryCode": {
"twoLetterCode": "KZ",
"name": "КАЗАХСТАН"
},
"actualBeneficiary": null
},
"priority": true,
"amount": 2,
"account": {
"status": "ACTIVE",
"currency": "KZT",
"number": "KZ1111111111KZ11111",
"type": "Current"
},
"info": "Test info",
"employees": [
{
"firstName": "TestName",
"lastName": "TestSurname",
"middleName": "Test",
"amount": 2,
"taxCode": "111111111111",
"birthDate": "1999-10-26",
"period": "2026-06-01",
"account": "KZ000000000000000003"
}
],
"actualSender": {
"name": "Independant comp",
"taxCode": "111111111111"
},
"senderResidencyCountry": {
"twoLetterCode": "KZ",
"name": "КАЗАХСТАН"
}
}

Правила валидации​

Правила применяются ко всем пяти списочным типам.

ПравилоУсловие срабатыванияПримечание
Согласованность периода отчисленияПериод указан и в employeeTransferPeriod, и хотя бы у одного employees[].period одновременно — ошибка «указан в обоих полях»; либо не указан нигде — ошибка «период не указан»EMPLOYEE_TRANSFER_PERIOD_SPECIFIED_IN_BOTH_FIELDS / EMPLOYEE_TRANSFER_PERIOD_NOT_SPECIFIED
КНП соответствует счёту/бенефициару (validatePaymentPurposeCode)purpose.code не согласуется со связкой account/beneficiaryОбщая проверка
Проверка счетов (validateAccounts)account/beneficiary не проходят базовые проверки существования/валютыОбщая проверка
Лимит транзакции (validateTransactionLimit)Сумма превышает лимит транзакции для типа платежаОбщая проверка
Список сотрудников не пустemployees пуст или отсутствуетFIELD_IS_EMPTY на поле employees
Сумма по сотрудникам = amountСумма employees[].amount не равна amount (проверка выполняется, если employees не пуст)Тот же механизм, что и у Payroll — validation.v1.employee_sum_not_equal_to_total_sum
Пер-полевые constraint'ы по сотрудникамЗначения полей employees[] не соответствуют ограничениям типа платежаДополнительные ограничения зависят от настроек типа платежа
Актуальный отправитель/ISO-поля/дочерняя организацияvalidateActualSubjectFields / validateIsoFields / validateSubsidiaryOrganization не проходятОбщие проверки, аналогичные другим типам платежей

Тело ответа​

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

Коды ошибок​

КодУсловие
400 Bad RequestНевалидный JSON / неизвестный domesticTransferType / нарушение constraint полей
401 UnauthorizedОтсутствует/невалиден JWT
403 ForbiddenНет привилегии payments_budget_create
400 / бизнес-ошибки валидацииВозвращаются как ValidationExceptionResponse (список ошибок по полям, см. раздел «Правила валидации»)

Пример ошибки валидации — пустой список сотрудников:

{
"validationExceptions": [
{
"fieldName": "employees",
"translationKey": "validation.v1.field_is_empty",
"message": "Field is empty",
"translatedMessage": "Поле не может быть пустым"
}
]
}

Пример ошибки валидации — период отчисления указан в обоих местах:

{
"validationExceptions": [
{
"fieldName": "employeeTransferPeriod",
"translationKey": "validation.v1.employee_transfer_period_specified_in_both_fields",
"message": "Employee transfer period specified in both fields",
"translatedMessage": "Период отчисления указан одновременно в двух местах"
}
]
}

Необходимые привилегии​

  • payments_budget_create

Для создания всех пяти списочных типов требуется payments_budget_create. Доступность SingleContribution в справочнике типов дополнительно зависит от права single_contribution_view и настроек банка.

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

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