Build the FATCA Form 8966 Report into IDES XML

Skill: Convert account-holder data into the FATCA Form 8966 XML for IDES

Region: United States Category: FATCA — Form 8966 (FATCA XML for IDES) Does: Takes reportable-account data and produces the FATCA Report (Form 8966) XML in the IRS FATCA XML v2.0 schema for transmission through the International Data Exchange Service (IDES). Schema version: IRS FATCA XML v2.0 — urn:oecd:ties:fatca:v2

The AI builds the report payload only. IDES requires the file to be signed, compressed, and AES/RSA-encrypted with the IRS public key and packaged per the IDES User Guide — those steps happen in your transmission tooling, not here. Validate against the FATCA XML v2.0 XSD before packaging. Reporting is annual; a Reporting Period of YYYY-12-31.

This skill assists with authorized, legitimate tax-reporting compliance only.

When this applies

• A Foreign Financial Institution (FFI), a Model 2 IGA FFI, or a withholding agent reports U.S. accounts (or pooled/aggregate reporting) directly to the IRS via IDES.
• Model 1 IGA filers usually send to their host tax authority in the same schema; the wrapper/transmission differs but the FATCA_OECD payload is the same.
• Use for new reports (FATCA1), nil reports (FATCA3), and corrections/amendments/voids (FATCA2/FATCA4) via DocTypeIndic.

Conversion procedure

1. Read the source. Accept CSV/JSON of accounts plus the FFI's identity (GIIN, name, address, country). Identify the reporting period and message type.
2. Extract fields. For each account: account number, holder (individual or organisation), U.S. TIN, address, account balance, and payments (dividends, interest, gross proceeds, other). If a GIIN, U.S. TIN, AccountNumber, or AccountBalance is missing, stop and ask.
3. Normalize. Dates YYYY-MM-DD. Currency codes ISO-4217 (USD). Country codes ISO-3166 alpha-2. Generate a unique MessageRefId and, for each DocSpec, a unique DocRefId (convention: GIIN + period + sequence).
4. Assemble MessageSpec once, then ReportingFI, ReportingGroup, and one AccountReport per account (or a PoolReport/NilReport).
5. Emit the XML per the structure and worked example.
6. Validate against the XSD and the checklist.

Source → FATCA XML field map

Document structure

FATCA_OECD (version 2.0)
├── MessageSpec
│   ├── SendingCompanyIN            (GIIN)
│   ├── TransmittingCountry         (ISO-2)
│   ├── ReceivingCountry            (US)
│   ├── MessageType                 (FATCA)
│   ├── MessageRefId                (unique)
│   ├── MessageTypeIndic            (FATCA1 new / FATCA2 corrected / FATCA3 void / FATCA4 amended)
│   └── ReportingPeriod             (YYYY-12-31)
└── FATCA
    ├── ReportingFI
    │   ├── ResCountryCode / TIN (GIIN) / Name / Address
    │   └── DocSpec (DocTypeIndic, DocRefId)
    ├── ReportingGroup
    │   └── AccountReport ...        (one per account)
    │       ├── DocSpec (DocTypeIndic, DocRefId[, CorrDocRefId])
    │       ├── AccountNumber
    │       ├── AccountHolder (Individual | Organisation + TIN)
    │       ├── AccountBalance
    │       └── Payment ...
    └── (PoolReport | NilReport as alternatives)

Code tables

MessageTypeIndic / DocTypeIndic

Payment/Type (selected)

AcctHolderType (Organisation accounts)

Calculation rules

• AccountBalance is the period-end balance/value in the account currency; report 0 only for a closed account flagged accordingly.
• Payment amounts are aggregate gross amounts paid/credited during the period, per type, to the cent.
• DocRefId must be globally unique and begin with the reporting GIIN; a correction sets CorrDocRefId to the prior DocRefId and DocTypeIndic to the corrected/void/amended code.
• Recompute payment totals from source rows; flag mismatches.

Worked example (end-to-end)

Input — one reportable individual account

Reporting FI: Example Bank Ltd, Germany, GIIN S519K4.99999.SL.276
Reporting period: 2025
Account: CH9300762011623852957, holder Maria Schmidt, US TIN 123-45-6789
Balance: 250000 USD ; Dividends paid: 1200 USD

After normalization (intermediate)

MessageRefId  S519K4.99999.SL.276-2025-001
DocRefId(FI)  S519K4.99999.SL.276-2025-FI
DocRefId(acct) S519K4.99999.SL.276-2025-A001
US TIN 123456789 ; ReportingPeriod 2025-12-31

Output — FATCA Form 8966 XML

<?xml version="1.0" encoding="UTF-8"?>
<ftc:FATCA_OECD xmlns:ftc="urn:oecd:ties:fatca:v2"
                xmlns:sfa="urn:oecd:ties:stffatcatypes:v2"
                xmlns:iso="urn:oecd:ties:isofatcatypes:v1" version="2.0">
  <ftc:MessageSpec>
    <sfa:SendingCompanyIN>S519K4.99999.SL.276</sfa:SendingCompanyIN>
    <sfa:TransmittingCountry>DE</sfa:TransmittingCountry>
    <sfa:ReceivingCountry>US</sfa:ReceivingCountry>
    <sfa:MessageType>FATCA</sfa:MessageType>
    <sfa:MessageRefId>S519K4.99999.SL.276-2025-001</sfa:MessageRefId>
    <sfa:MessageTypeIndic>FATCA1</sfa:MessageTypeIndic>
    <sfa:ReportingPeriod>2025-12-31</sfa:ReportingPeriod>
  </ftc:MessageSpec>
  <ftc:FATCA>
    <ftc:ReportingFI>
      <sfa:ResCountryCode>DE</sfa:ResCountryCode>
      <sfa:TIN issuedBy="US">S519K4.99999.SL.276</sfa:TIN>
      <sfa:Name>Example Bank Ltd</sfa:Name>
      <sfa:Address>
        <iso:CountryCode>DE</iso:CountryCode>
        <sfa:AddressFree>Hauptstrasse 1, 60311 Frankfurt</sfa:AddressFree>
      </sfa:Address>
      <ftc:DocSpec>
        <sfa:DocTypeIndic>FATCA11</sfa:DocTypeIndic>
        <sfa:DocRefId>S519K4.99999.SL.276-2025-FI</sfa:DocRefId>
      </ftc:DocSpec>
    </ftc:ReportingFI>
    <ftc:ReportingGroup>
      <ftc:AccountReport>
        <ftc:DocSpec>
          <sfa:DocTypeIndic>FATCA11</sfa:DocTypeIndic>
          <sfa:DocRefId>S519K4.99999.SL.276-2025-A001</sfa:DocRefId>
        </ftc:DocSpec>
        <ftc:AccountNumber>CH9300762011623852957</ftc:AccountNumber>
        <ftc:AccountHolder>
          <ftc:Individual>
            <sfa:TIN issuedBy="US">123456789</sfa:TIN>
            <sfa:Name>
              <sfa:FirstName>Maria</sfa:FirstName>
              <sfa:LastName>Schmidt</sfa:LastName>
            </sfa:Name>
            <sfa:Address>
              <iso:CountryCode>DE</iso:CountryCode>
              <sfa:AddressFree>Hauptstrasse 1, 60311 Frankfurt</sfa:AddressFree>
            </sfa:Address>
          </ftc:Individual>
        </ftc:AccountHolder>
        <ftc:AccountBalance currCode="USD">250000</ftc:AccountBalance>
        <ftc:Payment>
          <ftc:Type>FATCA501</ftc:Type>
          <ftc:PaymentAmnt currCode="USD">1200</ftc:PaymentAmnt>
        </ftc:Payment>
      </ftc:AccountReport>
    </ftc:ReportingGroup>
  </ftc:FATCA>
</ftc:FATCA_OECD>

Normalisations shown: U.S. TIN 123-45-6789 → 123456789; reporting year 2025 → ReportingPeriod 2025-12-31; DocRefIds prefixed with the GIIN; dividends mapped to FATCA501.

Validation checklist

• All required fields extracted; AI asked about any missing GIIN, U.S. TIN, account number, or balance (nothing invented)
• MessageRefId unique; every DocRefId globally unique and GIIN-prefixed
• MessageTypeIndic correct (FATCA1 new vs FATCA2/3/4) and DocTypeIndic consistent
• Corrections set CorrDocRefId to the prior DocRefId
• ReportingPeriod = YYYY-12-31; country codes ISO-3166-2; currency ISO-4217
• U.S. TIN present (9 digits, no hyphens) or the documented missing-TIN handling applied
• Payment types/amounts reconcile to source; balances at period end
• XML validates against FATCA XML v2.0 XSD before IDES packaging (sign/compress/encrypt)

Last updated: 2026-06-13 — verify the active FATCA XML schema version, DocTypeIndic/MessageTypeIndic code lists, and IDES packaging requirements before use.