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:
Parse intent: The user wants to send 10,000 UAH to the specified IBAN.
Validate IBAN format: Check that it matches UA + 27 digits = 29 characters total. This IBAN is valid.
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.
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)
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.
Call the payment tool only after user confirms.
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
- 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.
- 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.
- Verify the amount format for the target bank before sending. A kopiykas/decimal mixup causes 100x errors.
- Mask IBANs in output: show only last 4 digits (
UA...****0001) to protect account information.
- Log external references for tracking — these are safe to display and useful for follow-up.
1---2name: payments3description: 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.4---56# Payments via Bank MCP78Prepare and track payments through bank MCP tools. This covers corporate payment operations for Monobank and PrivatBank.910## Practical Example1112**User says:** "відправ 10000 грн на цей IBAN UA293220010000026000000000001"1314**Step-by-step workflow:**15161. **Parse intent:** The user wants to send 10,000 UAH to the specified IBAN.17182. **Validate IBAN format:** Check that it matches `UA` + 27 digits = 29 characters total. This IBAN is valid.19203. **Convert amount to the correct format:**21 - For Monobank: convert to kopiykas. 10000 UAH = `1000000` kopiykas (multiply by 100).22 - For PrivatBank: use decimal string `"10000.00"`.23 Getting this wrong causes a 100x error — sending 100 kopiykas instead of 100 UAH, or 1,000,000 UAH instead of 10,000 UAH.24254. **Collect missing info:** Ask the user for:26 - Recipient name and EDRPOU (required by bank API)27 - Payment purpose/destination (6-420 characters)28 - Which sender account to use (if multiple)29305. **Confirm before sending:** Display a summary and ask for explicit confirmation:31 ```32 Підтвердіть платіж:33 Відправник: UA29322001... (ваш рахунок)34 Отримувач: ТОВ "Компанія" (ЄДРПОУ: 12345678)35 IBAN: UA29322001...000136 Сума: ₴10 000,0037 Призначення: "Оплата за послуги згідно рахунку №123"3839 Підтверджуєте? (так/ні)40 ```4142 **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.43446. **Call the payment tool** only after user confirms.45467. **Report result:** Show payment ID, status (CREATED = awaiting mobile signature), and next steps.4748**Output:**49```50Платіж створено:51 ID: pay_abc12352 Статус: CREATED (очікує підпису в мобільному додатку)5354Відкрийте додаток банку для підписання.55```5657## Tool Discovery5859Search for payment-related MCP tools using keywords: `payment`, `prepare`, `pay`, `платіж`.6061Typical tools:62- **Prepare/create payment** — creates a payment and sends it for mobile signing63- **Get payment status by ID** — check state after preparation64- **Get payment status by external reference** — track by your own reference ID6566## Amount Formats: Kopiykas vs. Decimal6768Monobank 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.6970| Bank | Format | Example for ₴10 000,00 | Why |71|------|--------|------------------------|-----|72| Monobank | Integer in **kopiykas** | `1000000` | API works with smallest currency unit, like cents |73| PrivatBank | **Decimal string** | `"10000.00"` | API works with human-readable amounts |7475Conversion examples:76```77₴1 000,00 → Monobank: 100000 PrivatBank: "1000.00"78₴15 432,50 → Monobank: 1543250 PrivatBank: "15432.50"79₴0,01 → Monobank: 1 PrivatBank: "0.01"80```8182Maximum amount: ₴100 000 000,00 (Monobank: `10000000000`).8384Always double-check: if the user says "10 тисяч гривень", that is 10,000 UAH = 1,000,000 kopiykas. Do not confuse the two.8586## Monobank Payment Parameters8788### Required8990| Parameter | Description | Format |91|-----------|------------|--------|92| senderIban | Sending account IBAN | UA + 27 digits |93| receiver.iban | Recipient IBAN | UA + 27 digits |94| receiver.edrpou | Recipient ЄДРПОУ | 8 digits |95| receiver.name | Recipient legal name | String |96| destination | Payment purpose | 6-420 characters |97| amount | Amount in kopiykas | Integer, 1-10,000,000,000 |98| currency | ISO 4217 numeric code | "980" for UAH |99100### Optional101102| Parameter | Description | When needed |103|-----------|------------|-------------|104| externalReference | Your tracking ID | 3-256 chars, for idempotency and tracking |105| payCode | Budget classification code | 3 chars, for government/tax payments |106| additionalInfo | Budget payment extra info | 6-130 chars, required when payCode is set |107108## PrivatBank Payment Parameters109110### Required111112| Parameter | Description | Format |113|-----------|------------|--------|114| document_number | Unique document number | String |115| payer_account | Sender IBAN | UA + 27 digits |116| recipient_account | Recipient IBAN | UA + 27 digits (or use recipient_card) |117| recipient_nceo | Recipient ЄДРПОУ | String ("0000000000" for individuals) |118| payment_naming | Recipient name | String |119| payment_amount | Amount as decimal | e.g., "1000.50" |120| payment_destination | Purpose | 5-420 chars |121122### Optional123124| Parameter | Description |125|-----------|------------|126| payment_ccy | Currency, default "UAH" |127| payment_date | Execution date DD.MM.YYYY |128| recipient_card | Card number (alternative to IBAN) |129| externalReference | Your tracking ID |130| struct_type | Budget classification code |131| struct_code | Tax payment code |132| struct_category | Tax notice info (1-140 chars) |133134## IBAN Validation135136Ukrainian IBAN format: `UA` + 2 check digits + 6 bank code digits + 19 account digits = 29 characters total.137138```139UA 29 322001 0000026000000000001140│ │ │ └── Account number (19 digits)141│ │ └── Bank code (MFO, 6 digits)142│ └── Check digits143└── Country code144```145146Validate before calling the API — an invalid IBAN will be rejected and wastes a round-trip.147148## Payment States149150| State | Meaning |151|-------|---------|152| CREATED | Prepared, awaiting signature in mobile app |153| PROCESSING | Signed, being processed by bank |154| SUCCESS | Payment completed |155| FAILURE | Payment failed |156| EXPIRED | Not signed in time |157158## Budget Payments159160For government/tax payments, provide additional fields:161162- **payCode** — 3-character classification code (e.g., "058")163- **additionalInfo** — description required by budget rules (6-130 chars)164165```166Example:167 destination: "Сплата ПДВ за березень 2026"168 payCode: "058"169 additionalInfo: "30968899; ПДВ; березень 2026"170```171172## PrivatBank-Specific Features173174**Payment lifecycle:**175```1761. createPayment → returns ref1772. getPayment(ref) → check status1783. addPaymentSign(ref, sign) → add digital signature (multi-level signing supported)1794. deletePayment(ref) → cancel unsigned payment180```181182**Key differences from Monobank:**183- PrivatBank supports payment deletion before signing.184- Multi-level signing — multiple signatures may be required.185- `createPaymentWithForecast` — same as create but includes balance prediction.186- Card payments — use `recipient_card` instead of `recipient_account`.187188## Bank-Specific Comparison189190| Feature | Monobank | PrivatBank |191|---------|----------|------------|192| Amount format | Kopiykas (integer) | Decimal string |193| Currency | ISO 4217 code ("980") | Text ("UAH") |194| Signing | Mobile app | Digital signature (Base64) |195| Deletion | Not supported | Before signing only |196| Card payments | Not available | recipient_card field |197198## Safety Rules1992001. **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.2012. **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.2023. **Verify the amount format** for the target bank before sending. A kopiykas/decimal mixup causes 100x errors.2034. **Mask IBANs** in output: show only last 4 digits (`UA...****0001`) to protect account information.2045. **Log external references** for tracking — these are safe to display and useful for follow-up.
agents-store