# Payments

> This skill should be used when preparing or sending payments, checking payment status, validating IBAN numbers, making tax or budget payments, or tracking payments by reference. Relevant for queries like "send a payment to this IBAN", "check payment status", "make a tax payment", "is my payment processed yet", or "prepare a payment of 10000 UAH". Use this skill whenever the user mentions sending money, paying someone, IBAN, payment status, or any transfer operation.

- Skill: `agents-store/payments` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add agents-store/payments`
- Raw SKILL.md: https://api.skillmd.com/api/skills/agents-store/payments/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Finance & Business
- Author: agents-store (https://skillmd.com/u/agents-store)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/agents-store/payments

---


# Payments via Bank MCP

Prepare and track payments through bank MCP tools. This covers corporate payment operations for Monobank and PrivatBank.

## Practical Example

**User says:** "відправ 10000 грн на цей IBAN UA293220010000026000000000001"

**Step-by-step workflow:**

1. **Parse intent:** The user wants to send 10,000 UAH to the specified IBAN.

2. **Validate IBAN format:** Check that it matches `UA` + 27 digits = 29 characters total. This IBAN is valid.

3. **Convert amount to the correct format:**
   - For Monobank: convert to kopiykas. 10000 UAH = `1000000` kopiykas (multiply by 100).
   - For PrivatBank: use decimal string `"10000.00"`.
   Getting this wrong causes a 100x error — sending 100 kopiykas instead of 100 UAH, or 1,000,000 UAH instead of 10,000 UAH.

4. **Collect missing info:** Ask the user for:
   - Recipient name and EDRPOU (required by bank API)
   - Payment purpose/destination (6-420 characters)
   - Which sender account to use (if multiple)

5. **Confirm before sending:** Display a summary and ask for explicit confirmation:
   ```
   Підтвердіть платіж:
     Відправник: UA29322001... (ваш рахунок)
     Отримувач: ТОВ "Компанія" (ЄДРПОУ: 12345678)
     IBAN: UA29322001...0001
     Сума: ₴10 000,00
     Призначення: "Оплата за послуги згідно рахунку №123"

   Підтверджуєте? (так/ні)
   ```

   **Why confirm?** Once a payment is signed in the mobile app, it cannot be cancelled or reversed. A wrong amount, wrong IBAN, or wrong recipient means the money is gone. This is the last safety checkpoint.

6. **Call the payment tool** only after user confirms.

7. **Report result:** Show payment ID, status (CREATED = awaiting mobile signature), and next steps.

**Output:**
```
Платіж створено:
  ID: pay_abc123
  Статус: CREATED (очікує підпису в мобільному додатку)

Відкрийте додаток банку для підписання.
```

## Tool Discovery

Search for payment-related MCP tools using keywords: `payment`, `prepare`, `pay`, `платіж`.

Typical tools:
- **Prepare/create payment** — creates a payment and sends it for mobile signing
- **Get payment status by ID** — check state after preparation
- **Get payment status by external reference** — track by your own reference ID

## Amount Formats: Kopiykas vs. Decimal

Monobank and PrivatBank use different amount formats. Getting this wrong is the single most common payment error — it causes amounts to be 100x too large or 100x too small.

| Bank | Format | Example for ₴10 000,00 | Why |
|------|--------|------------------------|-----|
| Monobank | Integer in **kopiykas** | `1000000` | API works with smallest currency unit, like cents |
| PrivatBank | **Decimal string** | `"10000.00"` | API works with human-readable amounts |

Conversion examples:
```
₴1 000,00  → Monobank: 100000    PrivatBank: "1000.00"
₴15 432,50 → Monobank: 1543250   PrivatBank: "15432.50"
₴0,01      → Monobank: 1         PrivatBank: "0.01"
```

Maximum amount: ₴100 000 000,00 (Monobank: `10000000000`).

Always double-check: if the user says "10 тисяч гривень", that is 10,000 UAH = 1,000,000 kopiykas. Do not confuse the two.

## Monobank Payment Parameters

### Required

| Parameter | Description | Format |
|-----------|------------|--------|
| senderIban | Sending account IBAN | UA + 27 digits |
| receiver.iban | Recipient IBAN | UA + 27 digits |
| receiver.edrpou | Recipient ЄДРПОУ | 8 digits |
| receiver.name | Recipient legal name | String |
| destination | Payment purpose | 6-420 characters |
| amount | Amount in kopiykas | Integer, 1-10,000,000,000 |
| currency | ISO 4217 numeric code | "980" for UAH |

### Optional

| Parameter | Description | When needed |
|-----------|------------|-------------|
| externalReference | Your tracking ID | 3-256 chars, for idempotency and tracking |
| payCode | Budget classification code | 3 chars, for government/tax payments |
| additionalInfo | Budget payment extra info | 6-130 chars, required when payCode is set |

## PrivatBank Payment Parameters

### Required

| Parameter | Description | Format |
|-----------|------------|--------|
| document_number | Unique document number | String |
| payer_account | Sender IBAN | UA + 27 digits |
| recipient_account | Recipient IBAN | UA + 27 digits (or use recipient_card) |
| recipient_nceo | Recipient ЄДРПОУ | String ("0000000000" for individuals) |
| payment_naming | Recipient name | String |
| payment_amount | Amount as decimal | e.g., "1000.50" |
| payment_destination | Purpose | 5-420 chars |

### Optional

| Parameter | Description |
|-----------|------------|
| payment_ccy | Currency, default "UAH" |
| payment_date | Execution date DD.MM.YYYY |
| recipient_card | Card number (alternative to IBAN) |
| externalReference | Your tracking ID |
| struct_type | Budget classification code |
| struct_code | Tax payment code |
| struct_category | Tax notice info (1-140 chars) |

## IBAN Validation

Ukrainian IBAN format: `UA` + 2 check digits + 6 bank code digits + 19 account digits = 29 characters total.

```
UA 29 322001 0000026000000000001
│  │  │       └── Account number (19 digits)
│  │  └── Bank code (MFO, 6 digits)
│  └── Check digits
└── Country code
```

Validate before calling the API — an invalid IBAN will be rejected and wastes a round-trip.

## Payment States

| State | Meaning |
|-------|---------|
| CREATED | Prepared, awaiting signature in mobile app |
| PROCESSING | Signed, being processed by bank |
| SUCCESS | Payment completed |
| FAILURE | Payment failed |
| EXPIRED | Not signed in time |

## Budget Payments

For government/tax payments, provide additional fields:

- **payCode** — 3-character classification code (e.g., "058")
- **additionalInfo** — description required by budget rules (6-130 chars)

```
Example:
  destination: "Сплата ПДВ за березень 2026"
  payCode: "058"
  additionalInfo: "30968899; ПДВ; березень 2026"
```

## PrivatBank-Specific Features

**Payment lifecycle:**
```
1. createPayment → returns ref
2. getPayment(ref) → check status
3. addPaymentSign(ref, sign) → add digital signature (multi-level signing supported)
4. deletePayment(ref) → cancel unsigned payment
```

**Key differences from Monobank:**
- PrivatBank supports payment deletion before signing.
- Multi-level signing — multiple signatures may be required.
- `createPaymentWithForecast` — same as create but includes balance prediction.
- Card payments — use `recipient_card` instead of `recipient_account`.

## Bank-Specific Comparison

| Feature | Monobank | PrivatBank |
|---------|----------|------------|
| Amount format | Kopiykas (integer) | Decimal string |
| Currency | ISO 4217 code ("980") | Text ("UAH") |
| Signing | Mobile app | Digital signature (Base64) |
| Deletion | Not supported | Before signing only |
| Card payments | Not available | recipient_card field |

## Safety Rules

1. **Confirm payment details before calling the API** — display amount, recipient, IBAN, and purpose. Ask for explicit "yes". Payments are irreversible after signing, so this confirmation is the last chance to catch errors.
2. **Display amounts in human-readable UAH** — always convert kopiykas back to UAH for display. A user seeing "1000000" cannot easily verify that is ₴10,000.
3. **Verify the amount format** for the target bank before sending. A kopiykas/decimal mixup causes 100x errors.
4. **Mask IBANs** in output: show only last 4 digits (`UA...****0001`) to protect account information.
5. **Log external references** for tracking — these are safe to display and useful for follow-up.