| name | salary-management |
| description | This skill should be used when managing employee salary contacts, creating salary payment registries, uploading or distributing payslips, generating payslip PDFs, or working with Maspay salary batches. Relevant for queries like "add an employee to salary project", "create a salary registry for March", "send payslips to employees", or "list salary contacts". Use this skill whenever the user mentions salary, payroll, employees, payslips, or any HR-related banking operation. |
Salary Project Management via Bank MCP
Manage salary project operations: employee contacts, salary registries (batch payments), and payslip distribution.
Why Monobank and PrivatBank Differ
Monobank and PrivatBank have fundamentally different corporate banking architectures, which affects salary operations:
- Monobank uses a modern REST API with contacts, registries, and payslips as separate entities. Amounts are in kopiykas (smallest currency unit). Pagination uses limit/offset.
- PrivatBank uses a legacy packet-based system called Maspay with salary groups, receivers, and packets. Amounts are decimal strings. Pagination is page-based.
This means you cannot use the same API calls for both banks. Always check which bank the user's salary project is connected to before proceeding. For PrivatBank Maspay specifics, refer to references/privatbank-maspay.md.
Practical Example
User says: "створи зарплатну відомість за березень"
Workflow:
-
Clarify details: The user wants to create a salary registry for March 2026. Ask:
- Which sender account (IBAN) to use?
- Which employees to include? (All contacts, or a subset?)
- What amounts per employee?
If the user has a prepared list (spreadsheet, previous registry), ask for it.
-
Get registry types — call the types endpoint to discover available options (e.g., "Заробітна плата", "Аванс", "Премія"). The user said "зарплатна відомість", so select the salary type.
-
Prepare recipient list — for each employee:
- Full name in format "Прізвище Ім'я По батькові"
- IBAN from salary contacts
- Amount in kopiykas (Monobank) or decimal (PrivatBank)
-
Show summary before creating:
Зарплатна відомість за березень 2026:
Тип: Заробітна плата
Рахунок: UA29322001...
Період: 01.03.2026 – 31.03.2026
Працівників: 15
Загальна сума: ₴450 000,00
Перші 5 записів:
| # | ПІБ | Сума |
|---|---------------------------|-------------|
| 1 | Петренко Петро Петрович | ₴35 000,00 |
| 2 | Іваненко Іван Іванович | ₴32 000,00 |
| 3 | Сидоренко Олена Василівна | ₴28 500,00 |
...
Підтверджуєте створення? (так/ні)
-
Create the registry after confirmation. Return the registry ID.
-
Poll status until processing completes. Report results.
Output:
Відомість створено:
ID: reg_xyz789
Статус: Processing
Очікуйте завершення обробки...
Tool Discovery
Search for salary-related MCP tools using keywords: salary, contact, registry, payslip, зарплат, контакт, відомість, розрахунковий.
Three sub-domains:
- Salary Contacts — employee registry (CRUD, search)
- Salary Registries — payment batches (create, check status)
- Payslips — pay stubs (upload, send, PDF generation)
Salary Contacts
Contact Fields
| Field | Required | Description | Example |
|---|
| firstName | Yes | First name | Петро |
| lastName | Yes | Last name | Петренко |
| middleName | No | Patronymic | Петрович |
| iban | Yes | Employee bank IBAN | UA29322001... |
| inn | Yes | ІПН (tax ID, РНОКПП) | 10 digits |
| pan | No | Card number | 16 digits |
| documentType | No | ID document type | OLD_PASSPORT, ID_CARD, FOREIGN_PASSPORT |
| documentSeries | No | Document series | 2 chars (e.g., АБ) |
| documentNumber | No | Document number | Up to 9 digits |
Contact Operations
- List contacts — paginated list. Params:
limit (1-500, default 100), offset (default 0).
- Search contacts — by name, INN, or IBAN. Params:
query (min 3 chars), limit, offset.
- Get contact by ID — full details. Param:
id (UUID).
- Create contact — add employee to salary project. Param:
body with contact fields.
- Delete contact — remove one. Param:
id (UUID).
- Batch delete — remove multiple. Param:
ids (array of UUIDs).
Salary Registries
A registry is a batch payment instruction for distributing salary to multiple employees at once.
Registry Fields
| Field | Required | Description | Format |
|---|
| registryName | Yes | Descriptive name | "Заробітна плата за березень 2026" |
| senderIban | Yes | Company source IBAN | UA + 27 digits |
| salaryRegistryType | Yes | Type code | Get from types endpoint |
| from | Yes | Period start | YYYY-MM-DD |
| to | Yes | Period end | YYYY-MM-DD |
| recipients | Yes | Payment recipients | See below |
Recipient Fields
| Field | Required | Description |
|---|
| fullName | Yes | "Прізвище Ім'я По батькові" |
| iban | Yes | Recipient IBAN |
| amount | Yes | Amount in kopiykas (Monobank) |
| inn | No | ІПН (tax ID) |
| documentType | No | OLD_PASSPORT / ID_CARD / FOREIGN_PASSPORT |
Registry Workflow
1. Get available registry types (call types endpoint)
2. Prepare recipient list with amounts (kopiykas for Monobank)
3. Create registry with name, IBAN, type, period, recipients
4. Receive registry ID
5. Poll status until processing completes
6. Report results to user
Registry Status
Track by ID after creation. Typical states: Created / Processing / Completed / Partially completed / Failed.
Payslips (Розрахункові листки)
Payslips are detailed salary breakdowns sent to employees via their mobile banking app. They help employees understand their pay composition — base salary, bonuses, deductions, net pay.
Payslip Structure
Each payslip is tied to a period (YYYY-MM) and an employee (ІПН).
Payslip attributes are key-value pairs:
| Field | Description | Example |
|---|
| attributeName | Component name | "Базова зарплата" |
| value | Component value | "50000" |
| attributeSuffix | Unit/suffix | "грн" |
| sortOrder | Display order | 1, 2, 3... |
Example:
1. Базова зарплата — 50000 грн
2. Премія — 5000 грн
3. Відпускні — 0 грн
4. ПДФО (18%) — -9900 грн
5. Військовий збір (5%) — -2750 грн
6. ЄСВ — -12100 грн
7. До виплати — 30250 грн
Payslip Operations
- Batch upload — upload payslips for a period. Max 1000 employees per batch. Params:
period (YYYY-MM), employees array.
- Get import status — check upload progress. Param:
period.
- Send to mobile — distribute to employees' banking apps. Param:
period.
- Generate PDF — create PDF for one employee. Params:
identification (ІПН), period.
- Delete payslips — remove specific employees'. Params:
period, identifications (array of ІПН).
- Delete entire import — remove all payslips for a period. Param:
period.
Payslip Distribution Workflow
1. Prepare payslip data (attributes per employee)
2. Upload batch: batchUploadPayslips(period, employees)
3. Check status: getImportStatus(period)
4. When ready, send: sendToMobile(period)
5. Optionally generate individual PDFs for records
PrivatBank Salary Project (Maspay)
PrivatBank uses a packet-based model called Maspay. Key differences from Monobank:
| Aspect | Monobank | PrivatBank (Maspay) |
|---|
| Structure | Contacts + Registries | Groups + Receivers + Packets |
| Amounts | Kopiykas (integer) | Decimal strings |
| Pagination | limit/offset | Page-based |
| Workflow | Create registry directly | Create packet, validate, then process |
For the complete Maspay workflow (groups, receivers, packets, validation), read references/privatbank-maspay.md.
Safety Rules
- Mask ІПН in output — show only last 4 digits (
******1234). Tax IDs are sensitive personal data.
- Mask IBAN and card numbers — show only last 4 digits. Protects account information.
- Confirm before batch operations — especially delete and registry creation. These affect real money.
- Double-check recipient list before creating registries. Show total count and total amount for verification.
- Verify amount format — kopiykas (Monobank) vs. decimal strings (PrivatBank). A mixup means employees get 100x too much or too little. See the payments skill for detailed conversion rules.
