Salary Management

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:

1. 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.

2. Get registry types — call the types endpoint to discover available options (e.g., "Заробітна плата", "Аванс", "Премія"). The user said "зарплатна відомість", so select the salary type.

3. Prepare recipient list — for each employee:

   • Full name in format "Прізвище Ім'я По батькові"
   • IBAN from salary contacts
   • Amount in kopiykas (Monobank) or decimal (PrivatBank)

4. 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  |
     ...
   
   Підтверджуєте створення? (так/ні)
   

5. Create the registry after confirmation. Return the registry ID.

6. 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:

1. Salary Contacts — employee registry (CRUD, search)
2. Salary Registries — payment batches (create, check status)
3. Payslips — pay stubs (upload, send, PDF generation)

Salary Contacts

Contact Fields

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

Recipient Fields

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:

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:

For the complete Maspay workflow (groups, receivers, packets, validation), read references/privatbank-maspay.md.

Safety Rules

1. Mask ІПН in output — show only last 4 digits (******1234). Tax IDs are sensitive personal data.
2. Mask IBAN and card numbers — show only last 4 digits. Protects account information.
3. Confirm before batch operations — especially delete and registry creation. These affect real money.
4. Double-check recipient list before creating registries. Show total count and total amount for verification.
5. 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.