ISO 20022 Wire Transactions¶

GIB exposes the ability to transmit wires using the modern ISO 20022 standard. While traditional wire formats are often labor-intensive and prone to manual exceptions due to unstructured data, ISO 20022 offers a structured, data-rich format that reduces ambiguity and streamlines processing.

Our goal is to get you as close to the metal as possible. Experts can submit a perfectly formatted ISO 20022 (pacs.008.001.08) Customer Credit Transfer message, while leveraging our rigorous validations and effective error handling to ensure that when you initiate a wire, it goes through seamlessly.

The guide below defines the requirements for constructing these files. Unlike legacy formats, a specific address structure is required.

For domestic (US) wires you can skip constructing the file yourself: the Create a Wire Transfer from Subledger guide shows how the bank composes the message from your stored Subclients and Subclient Accounts.

The order of XML Tags is not important. Our endpoints will ensure the XML Tag order is corrected.

Message Structure¶

For direct submission to GIB, the file must use the Document element as the root. Do not include outer envelopes (such as AppHdr or FedwireFundsIncoming).

High-Level Hierarchy¶

<?xml version="1.0" encoding="UTF-8"?>
<Document xmlns="urn:iso:std:iso:20022:tech:xsd:pacs.008.001.08">
    <FIToFICstmrCdtTrf>
        <GrpHdr> ... </GrpHdr>

        <CdtTrfTxInf> ... </CdtTrfTxInf>
    </FIToFICstmrCdtTrf>
</Document>

Critical Validation Rules¶

ISO 20022 schemas are far stricter than legacy formats. You must adhere to the following rules to prevent immediate rejection.

1. Address Formatting¶

Three address formats exist within PstlAdr elements. Which of them Fedwire accepts depends on the party and, for some parties, on the next Fedwire Funds Service release:

Release rescheduled to November 2027. The Fedwire Funds Service release previously scheduled for November 16, 2026 has been rescheduled by Federal Reserve Financial Services to November 2027. The Federal Reserve will share more detail on the scope of the November 2027 release. The "From the next release" column below shows the changes announced for the original date. Until the release, the "Today" column applies. We will update this guide when the Federal Reserve confirms the date and scope.

Until the release, an address for Dbtr, Cdtr or an agent must be either fully structured or fully unstructured — the two must never be mixed within one party. Mixing them is rejected today (confirmed by our correspondent bank and FRB after production rejections in December 2025). Only the three parties above use the hybrid format before the release date.

A PstlAdr block may only be used when the party's Nm element is present.

Structured (recommended)¶

Use individual fields for each address component. This is the preferred format — it enables the cleanest processing and fewest rejections downstream.

<PstlAdr>
  <StrtNm>Main St</StrtNm>
  <BldgNb>101</BldgNb>
  <PstCd>56051</PstCd>
  <TwnNm>Kiester</TwnNm>
  <CtrySubDvsn>MN</CtrySubDvsn>
  <Ctry>US</Ctry>
</PstlAdr>

Fields:

1. StrtNm (Street)
2. BldgNb (Building Number)
3. PstCd (Zip/Postal Code)
4. TwnNm (City/Town)
5. CtrySubDvsn (State/Province)
6. Ctry (Country)

Hybrid (not recommended but supported, max 2 lines)¶

Who may use it, and when: today only UltmtDbtr, UltmtCdtr and InitgPty — for those parties it is the required format. For Dbtr, Cdtr and the agents the hybrid format becomes available with the next release (now November 2027); sending it for them before then is rejected (see the table above).

When a fully structured address is not available, you may use up to two <AdrLine> elements (max 35 characters each — our bank enforces a stricter limit than the ISO 20022 base standard of 70). TwnNm and Ctry are always required — <AdrLine> must never stand on its own.

<PstlAdr>
  <AdrLine>101 Main St</AdrLine>
  <AdrLine>MN 56051</AdrLine>
  <TwnNm>Kiester</TwnNm>
  <Ctry>US</Ctry>
</PstlAdr>

Exceeding two <AdrLine> elements, or omitting <TwnNm>/<Ctry>, will be rejected.

From the next release (now November 2027) Fedwire also permits further structured elements (StrtNm, BldgNb, PstCd, CtrySubDvsn, …) next to <AdrLine>, on the condition that information present in a structured element is never repeated in an <AdrLine>. Before then this applies to UltmtDbtr, UltmtCdtr and InitgPty only. We recommend not mixing at all: either stay with AdrLine + TwnNm + Ctry, or go fully structured.

Unstructured (deprecated)¶

<AdrLine>-only addresses (without TwnNm and Ctry) are accepted during the current transition period for Dbtr, Cdtr and the agents, but will be rejected by Fedwire from the next release (now November 2027) onward. Migrate before then, either to the structured format, which is accepted both before and after the release, or to the hybrid format, which those parties may only send from the release on.

For UltmtDbtr, UltmtCdtr and InitgPty the unstructured format is already invalid today — those parties must use the structured or the hybrid format.

2. Financial Constraints¶

• Currency: Must be USD.
• Decimals: Strictly 2 decimal places (e.g., 5.55 is valid; 5.555 is invalid).

Amount Fields¶

Two amount fields appear in every CdtTrfTxInf block:

Why both? They diverge when a currency conversion is involved. For example, if a customer instructs their bank to send €3,800 EUR to a European beneficiary, the US bank settles the wire in USD:

<IntrBkSttlmAmt Ccy="USD">4300.00</IntrBkSttlmAmt>  <!-- what moved between banks -->
<InstdAmt Ccy="EUR">3800.00</InstdAmt>               <!-- what the customer asked for -->

For straight USD wires (no FX), both fields carry the same value and currency:

<IntrBkSttlmAmt Ccy="USD">1000.00</IntrBkSttlmAmt>
<InstdAmt Ccy="USD">1000.00</InstdAmt>

InstdAmt must always appear before ChrgBr in the XML sequence.

3. Remittance Information (RmtInf)¶

Unstructured remittance information is limited to a single <Ustrd> line of at most 140 characters. Multiple <Ustrd> elements within one RmtInf block will be rejected.

<!-- Valid: one line, ≤ 140 characters -->
<RmtInf>
  <Ustrd>Supplier invoice payment ABCDEF IMP EX INV: E001223</Ustrd>
</RmtInf>

<!-- Invalid: more than one Ustrd line -->
<RmtInf>
  <Ustrd>Supplier invoice payment ABCDEF IMP</Ustrd>
  <Ustrd>EX INV: E001223</Ustrd>
</RmtInf>

If your remittance text exceeds 140 characters, abbreviate or truncate it to fit the single line — do not split it across multiple <Ustrd> elements.

4. Party Identification (Id)¶

Parties (Dbtr, Cdtr, UltmtDbtr, UltmtCdtr) may carry an optional <Id> block that identifies them as an organisation (OrgId) or as a private person (PrvtId), in addition to Nm and PstlAdr.

When you identify a party with the generic <Othr> element, a <SchmeNm> is required — it says what kind of identifier <Othr><Id> holds. An <Othr> block carrying only <Id> passes today's Fedwire schema, but the next Fedwire release (now November 2027) is set to reject it with:

The content of element 'Othr' is not complete. One of the following elements is expected: 'SchmeNm'

Use the scheme name code that matches the party type:

<!-- Company: account / relationship number assigned by the bank -->
<Id>
  <OrgId>
    <Othr>
      <Id>1234567890</Id>
      <SchmeNm>
        <Cd>BANK</Cd>
      </SchmeNm>
    </Othr>
  </OrgId>
</Id>

<!-- Private person: customer number -->
<Id>
  <PrvtId>
    <Othr>
      <Id>1234567890</Id>
      <SchmeNm>
        <Cd>CUST</Cd>
      </SchmeNm>
    </Othr>
  </PrvtId>
</Id>

Other standard ISO 20022 codes may be used where they fit the identifier better (for example TXID for a tax identification number). If no standard code applies, use <SchmeNm><Prtry>...</Prtry></SchmeNm> with your own scheme name instead of <Cd>.

<SchmeNm> only applies to <Othr>. Identifying an organisation by <AnyBIC> or <LEI> instead needs no scheme name:

<Id>
  <OrgId>
    <AnyBIC>SMBCJPJT</AnyBIC>
  </OrgId>
</Id>

Dynamic Fields & Identifiers¶

Clients must dynamically generate specific IDs for every transaction to ensure uniqueness and traceability. Do not hardcode these fields.

• MsgId (Message ID): Must follow the Fedwire IMAD format (22 characters total):
• 8 digits (Date YYYYMMDD)
• 8 alphanumeric characters (Source/Cycle)
• 6 digits (Sequence Number)
• Example: 20260123ABC12345000001
• EndToEndId (End-to-End ID): Unique reference assigned by the initiating party.
• UETR (Unique End-to-End Transaction Reference): Must be a valid UUIDv4.

Possible MsgId implementation in python 3:

from datetime import datetime
import random
import string
import time


def generate_input_source():
    # Generate a random 8-character string of uppercase letters and digits
    return "".join(random.choices(string.ascii_uppercase + string.digits, k=8))

def generate_input_sequence_number():
    # Generate a random 6-character number
    timestamp = int(time.time() * 1000)  # Current time in milliseconds
    random_part = random.randint(0, 999)  # 0-999; mixed into the low 3 digits of the 6-digit sequence
    unique_number = (timestamp * 1000 + random_part) % 1000000  # Ensure 6 digits
    return f"{unique_number:06d}"

# Generate the inputCycleDate (Current date in YYYYMMDD format) (8 characters)
# We serialize OUR business date
input_cycle_date = datetime.now(BUSINESS_TIMEZONE).strftime("%Y%m%d")

# Generate a random inputSource (8 characters)
input_source = generate_input_source()

# Generate a random input sequence number (6 characters)
input_sequence_number = generate_input_sequence_number()

msg_id = f"""{input_cycle_date}{input_source}{input_sequence_number}"""

Fixed / Hardcoded Values¶

Certain fields reflect fixed Fedwire or GIB operational requirements and should be set as follows:

• SttlmMtd: Set to CLRG (Clearing).
• ClrSys/Cd: Set to FDW (Fedwire).
• LclInstrm/Prtry: Set to CTRC (Customer Credit Transfer).
• ChrgBr: Set to SLEV (Service Level) or SHAR (Shared).

Auto-Populated Fields¶

GIB will automatically fill in IntrBkSttlmDt (Interbank Settlement Date) if you omit it, using the same cut-off logic as ACH:

You may still supply IntrBkSttlmDt explicitly — GIB will leave your value untouched. If you do, use today's or a future banking date; past dates will be rejected by Fedwire.

Creditor Agent postal address. When CdtrAgt/FinInstnId carries a BICFI and a Nm but no PstlAdr at all, GIB adds the two elements the wire needs: Ctry taken from the BIC itself (characters 5–6 are the bank's ISO country code) and TwnNm set to the placeholder NOTPROVIDED. Nothing else is added. Supplying the bank's real address is still preferred: if you provide any PstlAdr element, GIB leaves the whole address untouched (and TwnNm and Ctry are then required, see the address formats above).

<CdtrAgt>
  <FinInstnId>
    <BICFI>KREDBEBB</BICFI>
    <Nm>KBC Bank NV</Nm>
    <!-- Added by GIB when omitted -->
    <PstlAdr>
      <TwnNm>NOTPROVIDED</TwnNm>
      <Ctry>BE</Ctry>
    </PstlAdr>
  </FinInstnId>
</CdtrAgt>

Outbound Wire Construction¶

When constructing the pacs.008 message, you act as the initiator. However, because GIB is the bank executing the wire on your behalf, the Sender (Instructing Agent) and Debtor Agent fields must always identify GIB.

Fixed Sender Details (GIB)¶

Two different agents identify us, and they are not interchangeable: they carry different routing numbers and follow opposite rules about Nm and PstlAdr. Hardcode both blocks exactly as below.

Instructing Agent (InstgAgt) — United Bankers Bank (UBB), our correspondent. Nm and PstlAdr are not allowed here.

<InstgAgt>
  <FinInstnId>
    <ClrSysMmbId>
      <ClrSysId>
        <Cd>USABA</Cd>
      </ClrSysId>
      <MmbId>091001322</MmbId>
    </ClrSysMmbId>
  </FinInstnId>
</InstgAgt>

Debtor Agent (DbtrAgt) — GIB (Global Innovations Bank), the bank holding your account. Nm and PstlAdr are required here.

<DbtrAgt>
  <FinInstnId>
    <ClrSysMmbId>
      <ClrSysId>
        <Cd>USABA</Cd>
      </ClrSysId>
      <MmbId>091208154</MmbId>
    </ClrSysMmbId>
    <Nm>Global Innovations Bank</Nm>
    <PstlAdr>
      <StrtNm>N Main St</StrtNm>
      <BldgNb>101</BldgNb>
      <PstCd>56051</PstCd>
      <TwnNm>Kiester</TwnNm>
      <CtrySubDvsn>MN</CtrySubDvsn>
      <Ctry>US</Ctry>
    </PstlAdr>
  </FinInstnId>
</DbtrAgt>

Both blocks belong inside CdtTrfTxInf, not inside GrpHdr. An InstgAgt placed in the group header is not read by our Fedwire enveloping step, and the wire is rejected with "The Instructing Agent (Sender) is missing or does not have a valid US ABA Routing Number" — regardless of which routing number it contains.

The base ISO 20022 schema does allow InstgAgt and InstdAgt at group-header level, so a message that puts them there is not malformed — it is simply the placement we do not support. Do not populate the group-header ones at all: the ISO cross-element rules InstructingAgentRule and InstructedAgentRule state that if GroupHeader/InstructingAgent is present then CreditTransferTransactionInformation/InstructingAgent is not allowed, so a message carrying both breaks the standard and can be rejected downstream even though we accept it.

POBO (Payments On Behalf Of)¶

For Fintechs, Aggregators, or Treasury Centers sending funds on behalf of Subclients, you must utilize the Ultimate Debtor (UltmtDbtr) element. This ensures compliance with Travel Rule regulations and transparency for correspondent banks.

• Dbtr (Debtor): This is YOU and YOUR ADDRESS (The GIB Account Holder/Fintech).
• UltmtDbtr (Ultimate Debtor): This is your Subclient (The true originator of the funds).

Placement: The UltmtDbtr block should be placed at the same level as DbtrAgt/CdtrAgt.

Validation: The UltmtDbtr must adhere to the same Structured Address rules as other parties. Note that the unstructured (AdrLine-only) format is not allowed for this party — Fedwire requires structured or hybrid here already today (see Address Formatting).

If you identify the Subclient with an <Id> block, the <Othr> element requires a <SchmeNm> (see Party Identification) — this is the most common cause of rejection on POBO wires under the next release.

<UltmtDbtr>
    <Nm>Originating Customer Name</Nm>
    <PstlAdr>
        <StrtNm>Originator St</StrtNm>
        <BldgNb>55</BldgNb>
        <PstCd>10001</PstCd>
        <TwnNm>New York</TwnNm>
        <CtrySubDvsn>NY</CtrySubDvsn>
        <Ctry>US</Ctry>
    </PstlAdr>
    <!-- Optional. When present, SchmeNm is required -->
    <Id>
        <OrgId>
            <Othr>
                <Id>1234567890</Id>
                <SchmeNm>
                    <Cd>BANK</Cd>
                </SchmeNm>
            </Othr>
        </OrgId>
    </Id>
</UltmtDbtr>

Receiver & Agent Requirements (Domestic vs. International)¶

The structure of the receiving agents changes depending on whether the final beneficiary is domestic (US) or international.

1. Domestic Wires (US to US)¶

For domestic wires, the "Instructed Agent" and the "Creditor Agent" are usually the same US institution.

• InstdAgt (Instructed Agent): The Beneficiary's Bank. Must be identified by a US Routing Number (ABA). Note: Nm and PstlAdr are not allowed here!
• CdtrAgt (Creditor Agent): Same as InstdAgt.

2. International Wires (US to Foreign)¶

Fedwire cannot route directly to a SWIFT BIC. You must route the wire through GIB's US Correspondent, United Bankers Bank (UBB), which acts as the gateway to the SWIFT network.

• InstdAgt (Instructed Agent): MUST be UBBs (details below).
• CdtrAgt (Creditor Agent): The Final Foreign Bank, identified by SWIFT BIC (BICFI).

Required InstdAgt Block for International Wires:

<InstdAgt>
  <FinInstnId>
    <ClrSysMmbId>
      <ClrSysId>
        <Cd>USABA</Cd>
      </ClrSysId>
      <MmbId>091001322</MmbId>
    </ClrSysMmbId>
  </FinInstnId>
</InstdAgt>

Note: Nm and PstlAdr are not allowed here!

Beneficiary Account (CdtrAcct)¶

• Domestic: Use Account Number (Othr/Id).
• International: Use IBAN (if applicable for the country, see Account Numbers and Addresses) or Account Number.

Purpose Codes (Purp)¶

For international wires, transfer purposes are highly recommended to avoid payment delays or rejections by the beneficiary bank, and they are strictly mandatory for certain countries (e.g., China, UAE, India).

When constructing your ISO 20022 XML, specify the purpose code within the <Purp> element inside <CdtTrfTxInf>.

Depending on the destination country's requirements, you will use either a standard ISO code (Cd) or a proprietary/local code (Prtry).

Standard ISO Code Example (e.g., Goods and Services):

<Purp>
  <Cd>GDSV</Cd>
</Purp>

Proprietary Code Example:

<Purp>
  <Prtry>CAP</Prtry>
</Purp>

Note: For the full list of standard ISO 20022 purpose codes, see the Purpose Code Reference. For mandatory and recommended codes by destination country, see the Country-specific guides or the International Wire Transactions guide.

Full Sample File (International Example)¶

Below is a valid pacs.008.001.08 payload for an International Wire (e.g., to Japan). Note the use of GIB as the Sender, UBB as the Instructed Agent (Intermediary), and SMBC as the Creditor Agent (Final Destination).

<?xml version="1.0" encoding="UTF-8"?>
<Document xmlns="urn:iso:std:iso:20022:tech:xsd:pacs.008.001.08"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="urn:iso:std:iso:20022:tech:xsd:pacs.008.001.08 CustomerCreditTransfer_pacs_008_001_08.xsd">
  <FIToFICstmrCdtTrf>
    <!-- Header -->
    <GrpHdr>
      <MsgId>20260123ABCDEFGH000001</MsgId>
      <CreDtTm>2026-01-23T12:58:28</CreDtTm>
      <NbOfTxs>1</NbOfTxs>
      <SttlmInf>
        <SttlmMtd>CLRG</SttlmMtd>
        <ClrSys>
          <Cd>FDW</Cd>
        </ClrSys>
      </SttlmInf>
    </GrpHdr>

    <!-- Transaction -->
    <CdtTrfTxInf>
      <!-- General Information -->
      <PmtId>
        <EndToEndId>f8826d7607e349e596f486b04b5a3a0f</EndToEndId>
        <UETR>a5a58c6f-38ca-4b35-ac6f-9136540ff832</UETR>
      </PmtId>
      <PmtTpInf>
        <InstrPrty>NORM</InstrPrty>
        <LclInstrm>
          <Prtry>CTRC</Prtry>
        </LclInstrm>
      </PmtTpInf>
      <IntrBkSttlmAmt Ccy="USD">1.00</IntrBkSttlmAmt>
      <IntrBkSttlmDt>2026-01-23</IntrBkSttlmDt>
      <InstdAmt Ccy="USD">1.00</InstdAmt>
      <ChrgBr>SLEV</ChrgBr>

      <Purp>
        <Cd>GDSV</Cd>
      </Purp>

      <!-- Instructing Agent -->
      <InstgAgt>
        <FinInstnId>
          <ClrSysMmbId>
            <ClrSysId><Cd>USABA</Cd></ClrSysId>
            <MmbId>091001322</MmbId>
          </ClrSysMmbId>
        </FinInstnId>
      </InstgAgt>

      <!-- Instructed Agent -->
      <InstdAgt>
        <FinInstnId>
          <ClrSysMmbId>
             <ClrSysId><Cd>USABA</Cd></ClrSysId>
             <MmbId>091001322</MmbId>
          </ClrSysMmbId>
        </FinInstnId>
      </InstdAgt>

      <!-- Debtor -->
      <DbtrAgt>
        <FinInstnId>
          <ClrSysMmbId>
            <ClrSysId><Cd>USABA</Cd></ClrSysId>
            <MmbId>091208154</MmbId>
          </ClrSysMmbId>
          <Nm>Global Innovations Bank</Nm>
          <PstlAdr>
            <StrtNm>N Main St</StrtNm>
            <BldgNb>101</BldgNb>
            <PstCd>56051</PstCd>
            <TwnNm>Kiester</TwnNm>
            <CtrySubDvsn>MN</CtrySubDvsn>
            <Ctry>US</Ctry>
          </PstlAdr>
        </FinInstnId>
      </DbtrAgt>
      <Dbtr>
        <Nm>Debtor Name</Nm>
        <PstlAdr>
          <StrtNm>Def Street</StrtNm>
          <BldgNb>100</BldgNb>
          <PstCd>94105</PstCd>
          <TwnNm>San Francisco</TwnNm>
          <CtrySubDvsn>CA</CtrySubDvsn>
          <Ctry>US</Ctry>
        </PstlAdr>
      </Dbtr>
      <DbtrAcct>
        <Id>
          <Othr>
            <Id>900001</Id>
          </Othr>
        </Id>
      </DbtrAcct>

      <!-- Optional Ultimate Debtor for POBO -->
      <!--UltmtDbtr-->
        <!--Nm>John Doe Enterprises</Nm-->
        <!--PstlAdr-->
          <!--StrtNm>Market Street</StrtNm-->
          <!--BldgNb>550</BldgNb-->
          <!--PstCd>10001</PstCd-->
          <!--TwnNm>New York</TwnNm-->
          <!--CtrySubDvsn>NY</CtrySubDvsn-->
          <!--Ctry>US</Ctry-->
        <!--/PstlAdr-->
        <!-- Optional Id. When present, SchmeNm is required -->
        <!--Id-->
          <!--OrgId-->
            <!--Othr-->
              <!--Id>1234567890</Id-->
              <!--SchmeNm><Cd>BANK</Cd></SchmeNm-->
            <!--/Othr-->
          <!--/OrgId-->
        <!--/Id-->
      <!--/UltmtDbtr-->

      <!-- Creditor -->
      <CdtrAgt>
        <FinInstnId>
          <BICFI>SMBCJPJT</BICFI>
          <!--ClrSysMmbId-->
            <!--ClrSysId><Cd>USABA</Cd></ClrSysId-->
            <!--MmbId>021000021</MmbId-->
          <!--/ClrSysMmbId-->
          <Nm>Sumitomo Mitsui Banking Corporation</Nm>
          <PstlAdr>
            <StrtNm>Marunouchi</StrtNm>
            <BldgNb>1-1-2</BldgNb>
            <PstCd>100-10005</PstCd>
            <TwnNm>Chiyoda-ku</TwnNm>
            <CtrySubDvsn>Tokyo</CtrySubDvsn>
            <Ctry>JP</Ctry>
          </PstlAdr>
        </FinInstnId>
      </CdtrAgt>
      <Cdtr>
        <Nm>Creditor Name</Nm>
        <PstlAdr>
          <StrtNm>Def Street</StrtNm>
          <BldgNb>200</BldgNb>
          <PstCd>94105</PstCd>
          <TwnNm>San Francisco</TwnNm>
          <CtrySubDvsn>CA</CtrySubDvsn>
          <Ctry>US</Ctry>
        </PstlAdr>
      </Cdtr>
      <CdtrAcct>
        <Id>
          <!-- The destination country in this sample (US) does not use IBAN; use the local account number under Othr/Id. -->
          <Othr>
            <Id>1234567</Id>
          </Othr>
          <!-- For IBAN countries, use the IBAN element instead, e.g.: -->
          <!--IBAN>{VALID_IBAN_FOR_DESTINATION_COUNTRY}</IBAN-->
        </Id>
      </CdtrAcct>

      <!-- Remittance Info -->
      <RmtInf>
        <Ustrd>INVOICES</Ustrd>
      </RmtInf>
    </CdtTrfTxInf>
  </FIToFICstmrCdtTrf>
</Document>

International Wires¶

See International Wire Transactions