Создание списочного платежа
Создаёт платёж по реестру сотрудников. Передайте paymentProductType=SEPARATE_PAYMENT и один из типов MedicalContribution, PensionContribution, SocialContribution, InsuranceContribution, SingleContribution.
| Endpoint | POST /domestic-payment-service/api/v1/external-payment |
| Content-Type | application/json |
| Авторизация | OAuth2 / JWT (Bearer token) |
Тело запроса
| Поле | Тип | Обязательность | Описание |
|---|---|---|---|
id | Long | Нет | Идентификатор платежа. При создании не передаётся, используется при обновлении |
domesticTransferType | enum (DomesticTransferType) | Да | Одно из: "MedicalContribution", "PensionContribution", "SocialContribution", "InsuranceContribution", "SingleContribution" |
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 | Да | Код назначения платежа (КНП) |
purpose.label | String | Да | Текст назначения платежа |
priority | boolean | Нет | Признак срочности |
info | String | Нет | Доп. информация по назначению |
employeeTransferCategory | String | Условно | Категория периода, заданная индивидуально для конкретного сотрудника |
employeeTransferPeriod | LocalDate (yyyy-MM-dd) | Условно | Период если общий для всех сотрудников |
account.currency | String | Да | Валюта счёта списания |
account.number | String | Да | IBAN счёта списания |
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 | Нет | Страна получателя (название): передавать для каждого сотрудника не требуется |
employees | List<EmployeeRequest> | Да | Список сотрудников; не может быть пустым, см. таблицу ниже и раздел «Правила валидации» |
subsidiary.subsidiaryOrganizationId | Long | Нет | ID дочерней организации |
paymentProductType | enum (PaymentProductType) | Да | для списочных платежей всегда SEPARATE_PAYMENT |
taxCommittee | PaymentTaxCommitteeRequest | Не используется | Унаследовано от AbstractPaymentRequest; для списочных платежей не заполняется |
Поля элемента списка employees (EmployeeRequest)
Поля fullAmount и paymentPurposes относятся к единому платежу (SingleContribution); согласно описанию метода, при обработке запроса не используются.
| Поле | Тип | Обязательность | Описание |
|---|---|---|---|
id | Long | Нет | Идентификатор сотрудника (при обновлении существующей записи) |
firstName | String | Да | Имя сотрудника |
lastName | String | Да | Фамилия сотрудника |
middleName | String | Нет | Отчество сотрудника |
amount | BigDecimal | Да | Сумма выплаты сотруднику |
account | String | Да | Лицевой счёт сотрудника |
taxCode | String | Да | ИИН сотрудника |
period | LocalDate (yyyy-MM-dd) | Условно | Период отчисления |
birthDate | LocalDate (yyyy-MM-dd) | Нет | Дата рождения |
residencyCountryCode | String | Нет | Код резидентства страны сотрудника |
fullAmount | BigDecimal | Нет | Полная сумма с учётом всех отчислений (модель «Единого платежа»; не читается бэкендом) |
paymentPurposes | List<String> | Нет | Список кодов КНП (модель «Единого платежа»; не читается бэкендом) |
modified | boolean | Нет | Признак, что запись сотрудника должна быть обновлена в справочнике employee |
externalId | Long | Нет | Внутренний 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 не проходят | Общие проверки, аналогичные другим типам платежей |
Тело ответа
| Поле | Тип | Описание |
|---|---|---|
paymentId | Long | Идентификатор созданного платежа |
Коды ошибок
| Код | Условие |
|---|---|
| 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 и настроек банка.
Следующие действия
Инициализация подписания → подписание с синхронной отправкой в АБС. Результат доступен через получение платежа.