Ensure your outbound SWIFT wire includes a UETR (Unique End-to-End Transaction Reference, a UUID v4) in field 121 of the MT103 or in the pacs.008 GrpHdr; the UETR is the key for all gpi tracking calls
Authenticate against the SWIFT gpi API using OAuth 2.0 with your SWIFT credentials; access is scoped to your BIC and requires your institution to be enrolled in SWIFT gpi
Call GET /v4/payments/{uetr} to retrieve the payment status; parse the transaction_status (ACCC = credit confirmed, ACSP = processing, RJCT = rejected) and the payment_tracking[] array showing each correspondent bank hop
For each entry in payment_tracking, inspect the from_bic, to_bic, instructed_amount, exchange_rate (if FX was applied), and deduction_amount (correspondent fees deducted from principal)
If status is RJCT, read the cancellation_reason_information for the structured reason code and surface it to the payment initiator with guidance on next steps (e.g., incorrect beneficiary IBAN)
Implement a polling interval appropriate to the payment corridor (e.g., every 15–30 minutes for major corridors, hourly for exotic ones) and set a final timeout at which point you escalate to manual investigation
Known gotchas
Not all correspondent banks on a payment chain are gpi members; for non-gpi hops, the tracker shows the payment entering the non-gpi bank but cannot report what happens inside it — status may stall at a non-gpi correspondent
Exchange rates and deductions visible in the tracker are reported by each bank and may arrive with a lag; the amounts shown are informational — the final credited amount at the beneficiary is the authoritative figure
UETR must be generated by the payment originator and included from the start; you cannot retroactively add a UETR to track a payment that was sent without one
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp