Swift GPI tracking
Track cross-border payments using Swift GPI in Mambu Payments (formerly Numeral)
Track cross-border Swift payments end-to-end using UETRs and GPI tracker messages. Mambu Payments supports outbound GPI trackers for incoming payments and inbound GPI trackers for payment orders.
UETRs
A UETR (unique end-to-end transaction reference) is included on payment orders, incoming payments, and transactions when the payment flows through the Swift GPI network.
The uetr field appears on each object:
{
"object": "payment_order",
"uetr": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}
//
{
"object": "incoming_payment",
"uetr": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}
//
{
"object": "transaction",
"uetr": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}Outbound GPI trackers
When you confirm or reject a Swift incoming payment, Mambu Payments generates and sends a trck.001 (Universal Confirmation) tracker message to the Swift GPI network.
Two methods are available:
API. Call the update GPI tracker endpoint to choose which tracking status to send for a specific incoming payment.
Payment validation rules. Configure payment validation rules to send GPI trackers automatically based on the validation outcome (successful, failed, or pending_investigation).
Tracker statuses
Each trck.001 message contains a status code indicating the payment outcome:
| Status code | Meaning | When Mambu Payments sends it |
|---|---|---|
ACCC | Accepted, credited | Payment confirmed and funds credited to the beneficiary |
ACSP with reason G003 | Pending | Payment received, processing in progress |
ACSP with reason G001 | Transferred | Payment forwarded to the next institution in the chain |
RJCT | Rejected | Payment rejected, with a reason code (for example, AC04 for closed account) |
Example: confirmed payment (ACCC)
ACCC)The trck.001 message for a confirmed incoming payment:
<?xml version="1.0" encoding="UTF-8"?>
<DataPDU xmlns="urn:swift:saa:xsd:saa.2.0">
<Revision>2.0.14</Revision>
<Header>
<Message>
<SenderReference>251028367329Yhej</SenderReference>
<MessageIdentifier>trck.001.001.03</MessageIdentifier>
<Format>MX</Format>
<Sender>
<DN>ou=xxx,o=somebic0,o=swift</DN>
</Sender>
<Receiver>
<DN>ou=xxx,o=trckchz0,o=swift</DN>
</Receiver>
<NetworkInfo>
<Service>swift.finplus!pf</Service>
</NetworkInfo>
</Message>
</Header>
<Body>
<AppHdr xmlns="urn:iso:std:iso:20022:tech:xsd:head.001.001.02">
<Fr>
<FIId>
<FinInstnId>
<BICFI>SOMEBIC0XXX</BICFI>
</FinInstnId>
</FIId>
</Fr>
<To>
<FIId>
<FinInstnId>
<BICFI>TRCKCHZ0XXX</BICFI>
</FinInstnId>
</FIId>
</To>
<BizMsgIdr>251028367329Yhej</BizMsgIdr>
<MsgDefIdr>trck.001.001.03</MsgDefIdr>
<BizSvc>swift.uc.01</BizSvc>
<CreDt>2025-10-28T08:32:38.811Z</CreDt>
</AppHdr>
<Document xmlns="urn:swift:xsd:trck.001.001.03">
<PmtStsTrckrUpd>
<GrpHdr>
<MsgId>251028367329Yhej</MsgId>
</GrpHdr>
<TrckrStsAndTx>
<TxSts>
<Sts>ACCC</Sts>
</TxSts>
<Tx>
<TrckrInfrmgPty>
<Id>
<FinInstnId>
<BICFI>SOMEBIC0XXX</BICFI>
</FinInstnId>
</Id>
</TrckrInfrmgPty>
<PmtId>
<InstrId>34FMAF2FPV83U8ZL</InstrId>
<UETR>4a4b2178-17c4-4e5b-92fb-41f30ea9bc11</UETR>
</PmtId>
<PmtScnro>CCTR</PmtScnro>
<SttlmInf>
<SttlmMtd>INDA</SttlmMtd>
</SttlmInf>
<TrckrData>
<ConfdDt>
<DtTm>2025-10-28T08:32:38.811Z</DtTm>
</ConfdDt>
<ConfdAmt Ccy="EUR">11.56</ConfdAmt>
</TrckrData>
</Tx>
</TrckrStsAndTx>
</PmtStsTrckrUpd>
</Document>
</Body>
</DataPDU>See the update GPI tracker API reference for all supported statuses and parameters.
Inbound GPI trackers
Track the progress of outbound Swift payment orders through the correspondent banking chain. Mambu Payments retrieves tracking updates and adds them to the swift_gpi object on the payment order.
How tracking updates are retrieved
| Method | How it works | Availability |
|---|---|---|
| Partner bank GPI reports | Mambu Payments processes GPI tracking reports provided by your partner bank | Available |
| Swift Business Connect polling | Mambu Payments polls the Swift GPI network directly for tracking updates until a final status (received or rejected) is reached | Planned 2026 |
Payment order with GPI tracking
Each tracking update appears in the tracking_progress array. The swift_gpi.status field reflects the latest status.
Payment received by the beneficiary:
{
"object": "payment_order",
"uetr": "2362836f-b4b0-46e5-ade2-4f92bb3fdbd4",
"swift_gpi": {
"tracking_id": "e9d24fd8-7c7c-491d-a873-20f8fbae3940",
"confirmed_date": "2025-05-06T10:23:12Z",
"confirmed_amount": 14505,
"confirmed_currency": "EUR",
"status": "received",
"tracking_progress": [
{
"id": "01",
"processed_at": "2025-05-05T09:15:34Z",
"status": "executed",
"status_details": "G001",
"bank_code": "CITI0100000",
"fee_amount": 1125,
"fee_currency": "USD"
},
{
"id": "02",
"processed_at": "2025-05-06T10:23:12Z",
"status": "received",
"status_details": "ACCC",
"bank_code": "SOMEBIC0XXX",
"fee_amount": 1099,
"fee_currency": "EUR"
}
]
}
}Payment rejected by a bank in the chain:
{
"object": "payment_order",
"uetr": "f8b3f81e-6935-4183-9653-c64d1bed0586",
"swift_gpi": {
"tracking_id": "3432047a-e7cf-4734-919a-2f754c78e278",
"confirmed_date": "2025-05-06T08:45:11Z",
"confirmed_amount": 14505,
"confirmed_currency": "EUR",
"status": "rejected",
"tracking_progress": [
{
"id": "01",
"processed_at": "2025-05-06T06:23:12Z",
"status": "executed",
"status_details": "G005",
"bank_code": "CITI0100000",
"fee_amount": null,
"fee_currency": null
},
{
"id": "02",
"processed_at": "2025-05-06T08:45:11Z",
"status": "rejected",
"status_details": "G006",
"bank_code": "SOMEBIC0XXX",
"fee_amount": null,
"fee_currency": null
}
]
}
}Events
When a new tracking update is received, Mambu Payments updates the swift_gpi object on the payment order and triggers an event with topic = payment_order and type = swift_gpi_tracking_updated.
Subscribe to this event via webhooks to react to tracking updates in real time.
Related
Updated 4 days ago