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")