track_payment

ai.ohmyfin/banking-intelligence · Verify this server

Track a SWIFT payment by UETR or reference number. Basic SWIFT payment tracking enriched by data from certain banks in the correspondent chain. Returns the overall payment status and, when available, per-bank details showing which banks reported information about this payment. IMPORTANT — every trace needs four things: amount, currency, date, and an identifier (uetr, or reference when there is no UETR). amount, currency and date are required parameters, on the UETR path too: there is no UETR-only lookup, so never tell the user the UETR alone is enough to run one. Ask for whatever is missing before calling, and never guess a value. IMPORTANT — UETR vs Reference: The UETR (Unique End-to-End Transaction Reference) is a UUID assigned to every SWIFT gpi payment. Tracking by UETR succeeds ~80% of the time. Tracking by reference number alone succeeds less than 1% of the time because most banks only index by UETR. → Always provide the UETR if available. → The reference number is Field 20 of the MT103 (or the equivalent <InstrId>/<EndToEndId> in pacs.008). It is the sender's transaction reference. Still valuable — provide it alongside the UETR when you have both. WHEN THE USER HAS ONLY A REFERENCE AND NO UETR ("how do I find / trace my payment?", "I have a reference number but no UETR, where is it?"): This is exactly the scenario this tool can attempt — do NOT answer from general knowledge. A reference-based trace cannot be run from the reference alone; you MUST first collect three things from the user: 1. amount — the exact amount as sent 2. currency — ISO 4217 (e.g. "USD") 3. date — the send date (within the last 90 days) Then call track_payment(reference=..., amount=..., currency=..., date=...). State the expectation up front: reference-only tracing succeeds less than 1% of the time. In parallel, tell the user how to recover the UETR for a reliable (~80%) trace: ask the SENDING bank for the MT103 confirmation — the UETR is in Block 3, tag {121:} (a UUID v4), stored by every gpi-enabled bank against the payment. Re-run with uetr= once they have it. (swift_message_reference("MT103") returns the full field/UETR-recovery reference if you need to cite specifics.) IMPORTANT — Interpreting bank details: Each entry in the 'details' array represents a bank that reported data about this payment. The bank could be the SENDER, the BENEFICIARY, or ANY INTERMEDIARY/CORRESPONDENT in the chain. Do NOT assume a bank is an intermediary just because it appears in the list — we only know the payment passed through that bank. The bank's role is only known when it self-reports via push API (indicated by a non-null 'role' field). Requires an API key with an active FI subscription. To get started: call mcp_register → mcp_verify → subscribe to an FI plan at https://ohmyfin.ai/subscription. Args: uetr: UETR (UUID v4 format, e.g. "eb6305c8-0710-4e41-84ad-f58db3083e82"). Strongly recommended — tracking without UETR rarely returns results. This is the Unique End-to-End Transaction Reference assigned to every SWIFT gpi payment. reference: Sender's bank reference number (MT103 Field 20 / pacs.008 InstrId). Useful alongside UETR for cross-referencing, but alone it rarely produces results. Required only if uetr is not provided. amount: REQUIRED. Transaction amount as sent (e.g. 15000.00). Must match the original payment amount — even small differences may prevent tracking from finding the payment, so ask the user for the exact figure rather than estimating or rounding one. currency: REQUIRED. ISO 4217 code of the currency the payment was SENT in (e.g. "USD", "EUR", "GBP"). Ask if you do not know it; do not assume the sender's or the beneficiary's home currency. date: REQUIRED. Transaction date. Preferred format: YYYY-MM-DD (ISO 8601). Also accepted: DD.MM.YYYY or DD-MM-YYYY (European format). Must be within the last 90 days. api_key: Your Ohmyfin API key (prod-...). Can also be passed via KEY header or Authorization: Bearer header. Returns a dict with: status: Overall payment status — one of: "success" — payment delivered to beneficiary (final) "in progress" — payment is being processed (may update) "returned" — payment was canceled/returned after processing (final) "rejected" — payment was refused (final) "on hold" — temporarily held, e.g. compliance review "future" — scheduled for a future value date "unknown" — no tracking data available yet status_raw: ISO 20022 status code (ACCC/ACSP/RJCT/PDNG) or null status_reason: ISO 20022 reason code if available, or null lastupdate: Date of last status change (YYYY-MM-DD) or null details: Array of bank-level tracking entries (see role_explanation in each entry for how to interpret the bank's role) not_found_guidance: Present only when nothing was found — concrete next steps (UETR recovery, exact-match checks). Relay these to the user instead of improvising; a miss on a reference-only trace is the expected outcome and does NOT mean the payment failed. Examples: track_payment(uetr="eb6305c8-0710-4e41-84ad-f58db3083e82", amount=15000, currency="USD", date="2026-03-10") track_payment(uetr="eb6305c8-0710-4e41-84ad-f58db3083e82", reference="FT2603100123", amount=15000, currency="USD", date="2026-03-10") track_payment(reference="FT2603100123", amount=5000, currency="EUR", date="12.03.2026")