International Compliance Management Model (ICMM) Notification XML Schema User Guide Publication 5216 (3-2018) Catalog Number 67683B Department of the Treasury Internal Revenue Service www.irs.gov
| International Compliance Management Model (ICMM) Notification XML Schema User Guide Publication 5216 (3-2018) Catalog Number 67683B Department of the Treasury Internal Revenue Service www.irs.gov |
| Publication 5216 Table of Contents WHAT’S NEW ..................................................................................................................................................................... 5 1. Introduction ...................................................................................................................................................... 2 1.1. Purpose of This Document .................................................................................................................................... 2 1.2. FATCA Notification Overview ................................................................................................................................ 2 1.3. Notification Schema Files Covered in this Document ........................................................................................... 3 1.4. Schema Element Descriptions ............................................................................................................................... 4 1.5. How to Use this Guide .......................................................................................................................................... 4 1.6. Restrictions on Text in FATCA String Characters ................................................................................................... 5 1.7. Compatibility with FATCA Notification Schema V2.2 ............................................................................................ 5 1.8. Comments ............................................................................................................................................................. 5 2. FATCAFileErrorNotification ............................................................................................................................... 6 2.1. FATCANotificationHeaderGrp ............................................................................................................................ 7 2.1.1. FATCANotificationCreateTs ................................................................................................................................... 8 2.1.2. FATCANotificationRefId ........................................................................................................................................ 8 2.1.3. FATCANotificationCd ............................................................................................................................................. 8 2.1.4. FATCAEntitySenderId .......................................................................................................................................... 10 2.1.5. FATCAEntityReceiverId ........................................................................................................................................ 10 2.1.6. CopiedToFATCAEntityId ...................................................................................................................................... 11 2.1.7. ContactInformationTxt ........................................................................................................................................ 11 2.2. OriginalFileMetadataGrp .................................................................................................................................... 12 2.2.1. IDESTransmissionId ............................................................................................................................................. 13 2.2.2. IDESSendingTs ..................................................................................................................................................... 13 2.2.3. SenderFileId ........................................................................................................................................................ 14 2.2.4. UncompressedFileSizeKBQty .............................................................................................................................. 14 2.3. NotificationContentTxt ....................................................................................................................................... 14 2.4. ActionRequestedGrp ........................................................................................................................................... 15 2.4.1. ActionRequestedTxt ............................................................................................................................................ 15 2.4.2. ActionRequestedDueDateTxt .............................................................................................................................. 16 2.5. HCTATreatyStampTxT ......................................................................................................................................... 16 3. FATCAValidFileNotification ............................................................................................................................. 17 3.1. FATCANotificationHeaderGrp ............................................................................................................................. 18 3.2. OriginalFileMetadataGrp .................................................................................................................................... 20 3.3. OriginalFileMessageSpecGrp .............................................................................................................................. 21 3.3.1. MessageRefId ...................................................................................................................................................... 22 3.3.2. CorrMessageRefId ............................................................................................................................................... 22 3.3.3. SendingCompanyGIIN ......................................................................................................................................... 22 |
| Publication 5216 3.3.4. TransmittingCountryCd ....................................................................................................................................... 23 3.3.5. ReceivingCountryCd ............................................................................................................................................ 23 3.3.6. MessageTypeCd .................................................................................................................................................. 23 3.3.7. ReportingPeriodDt .............................................................................................................................................. 23 3.4. NotificationContentTxt ....................................................................................................................................... 24 3.5. OriginalFileProcessingDataGrp ........................................................................................................................... 24 3.5.1. FileTypeCd ........................................................................................................................................................... 24 3.5.2. FinancialInstitutionCnt ........................................................................................................................................ 24 3.5.3. RecordCnt ............................................................................................................................................................ 26 3.5.4. DupAccountReportRecordCnt and Non DupAccountReportRecordCnt ............................................................. 26 3.5.5. PooledReportRecordCnt ..................................................................................................................................... 26 3.6. HCTATreatyStampTxt .......................................................................................................................................... 26 3.7. FATCARecordErrorGrp ........................................................................................................................................ 26 3.7.1. FATCARecordInfoHeaderTxt ............................................................................................................................ 28 3.7.2. FATCARecordErrorFIGrp .................................................................................................................................. 28 3.7.2.1. SponsorGIIN ....................................................................................................................................................... 29 3.7.2.2. SponsorNm ......................................................................................................................................................... 29 3.7.2.3. ReportingFIGIIN ................................................................................................................................................ 29 3.7.2.4. ReportingFINm .................................................................................................................................................. 30 3.7.2.5. FATCARecordErrorDetailGrp ........................................................................................................................... 30 3.7.2.5.1.FATCAReportTypeCd ........................................................................................................................................ 30 3.7.2.5.2.DocTypeIndicCd ................................................................................................................................................ 30 3.7.2.5.3.DocRefId ............................................................................................................................................................. 31 3.7.2.5.4.CorrMessageRefId ............................................................................................................................................. 31 3.7.2.5.5.CorrDocRefId ..................................................................................................................................................... 33 3.7.2.5.6.RecordLevelErrorCd ......................................................................................................................................... 33 3.7.2.5.7.FieldErrorGrp .................................................................................................................................................... 33 3.7.2.5.7.1. FieldPartNum ............................................................................................................................................. 34 3.7.2.5.7.2. FieldLineNum ............................................................................................................................................ 34 3.7.2.5.7.3. FieldNm ...................................................................................................................................................... 35 3.7.2.5.7.4. FieldErrorCd .............................................................................................................................................. 35 3.7.2.5.7.5. FieldErrorTxt ............................................................................................................................................. 36 3.7.2.5.8.ActionRequestedGrp ......................................................................................................................................... 36 3.7.3. PotentialEffectTxt .............................................................................................................................................. 36 Appendix A: Glossary ........................................................................................................................................................... 37 Appendix B: Example: Incorrect AES Key Size Notification (NKS) ....................................................................................... 38 Appendix C: Example Valid–File Notification (NVF) without Record Level Errors ............................................................ 39 |
| Publication 5216 Appendix D: Example Valid–File Notification (NVF) with Record Level Error .................................................................... 40 |
|
Publication 5216
WHAT’S NEW
This section summarizes updates since the last publication of the XML Schema Guide (March 2017):
Section Description
Section 2.1.3 Updated the File Error Notifications to reflect new
notifications (NCF – Certificate Failure, NDF – Failed
Decoding, and NIF – Invalid File Format).
Removed Notification (NDR – File Contains Invalid
DocRefID). The IRS no longer validates DocRefID at the
file-level. If your file contains an invalid or duplicate
DocRefID, then you will receive a record-level error (NVF).
Section 3.7.2.5.6 Added Record Level Error Codes 8019, 8020, and 8021
(Unspecified Report, Duplicate DocRefID, and Invalid
DocRefID respectively).
|
|
Publication 5216
1. Introduction
1.1. Purpose of This Document
The purpose of this document is to provide a general description of the FATCA Notification Schema V2.3 that
will be the basis for all electronic notifications from the Internal Revenue Service (IRS) to FATCA filers –
Foreign Financial Institutions (FFIs), direct reporting non-financial foreign entities (direct reporting NFFEs),
sponsoring entities, trustees of trustee-documented trusts, non-GIIN filers1, and Host Country Tax Authorities
(HCTAs) -- using the International Data Exchange Service (IDES). Throughout this user guide, the term “FFI”
is used to refer to FFIs, sponsoring entities, trustees of trustee-documented trusts, and non-GIIN filers. FATCA
XML files based on the FATCA Notification Schema V2.3 will only be generated by the IRS; FFIs, direct
reporting NFFEs, and HCTAs can use this guide to interpret notifications received from the IRS, and to
program their systems to receive and manage these files. [Note: HCTAs receiving reciprocal data from the IRS
are free to use the FATCA Notification Schema to format their notifications. However, this guide only
addresses the use of the notification schema from the IRS’s perspective.]
1.2. FATCA Notification Overview
A FATCA Notification is a message from the IRS to a sender of a FATCA Report file concerning the outcome
of processing the file as received by the IRS. A FATCA Notification is contained in a “transmission” file archive
through IDES to an international partner, either an FFI, direct reporting NFFE, or HCTA, in response to the
transmission and processing of a FATCA Report from that partner.
Transmissions containing notifications are prepared using the same process and components used to prepare
the FATCA Report transmission. When the IRS sends a notification, IDES will send an email to the FFI, direct
reporting NFFE, or HCTA that a file is ready for download. The email correspondence will reference the
“TransmissionID” of the original transmission from the FFI, direct reporting NFFE, or HCTA and the recipient
must access IDES to download the notification package. The FATCA IDES User Guide, Publication 5190,
provides detailed instructions on how to download notifications.
There are two types of notifications that the IRS will send in response to FATCA Report transmissions:
• File Error Notification – If there is an error encountered in attempting to access file contents, the
notification email provides a summary of the transmission, the error code, and the instructions to correct
the error and resubmit the file.
• Valid File Notification – This notification confirms that your file was received and processed successfully
and will document any record-level errors identified within the file.
File-level error conditions prevent the IRS from accessing and prpocessing the XML data within the FATCA
Report submission, and will trigger FATCA File Error Notifications. File level errors include the following:
• Failed download, due to a file transfer interruption or other fault condition preventing file access on
IDES;
• Decryption failure involving the encrypted payload file;
• Decryption failure involving the sender’s encrypted AES key;
• Failed decompression of decrypted payload files;
• Invalid digital signature;
• Invalid sender digital certificate;
• Detection of one or more virus or non-virus security threats at any stage of processing of received
1 A non-GIIN filer is an entity that is required to file Form 8966 but is not required to get a GIIN. A non-GIIN filer,
such as a withholding agent, territory financial institution, third party preparer, or commercial software vendor,
will be issued a FATCA Identification Number (FIN) to enroll in IDES and submit FATCA reports.
2
|
|
Publication 5216
transmission from IDES in which a file’s state is changed (initial download, unzipping the transmission
archive, decryption of AES key and payload files, payload decompression);
• Detection of restricted characters or character combinations
(https://www.irs.gov/businesses/corporations/fatca-xml-schema-best-practices-for-form-8966) ;
• FATCA Report payload file that cannot be validated against the FATCA XML Schema;
• MessageRefId value consisting solely of one or more blank characters;
• DocRefId value consisting solely of one or more blank characters;
• Duplicate MessageRefId value (MessageRefId value received on a prior valid file).
Error Notifications will provide the FATCA Filer a 3-character code for the type of error; pre-defined text
describing the error, recovery actions, and due dates; and a hyperlink the sender can use to find additional
information and resources to resolve the error.
A Valid File Notification informs the filer of the following:
• The specified FATCA Report file has been received;
• No file errors were found;
• Individual account, pooled, and nil reports contained with the specified file have been processed;
• The number of total account, pooled, and nil reports received, and the number of FFIs including reports
(as Reporting FIs) in the file;
• Error codes and descriptions of record-level errors detected in the file, including data elements and error
descriptions for field-level errors.
Additional information around interpretation of FATCA notification contents can be found on the FATCA Report
Notifications website at http://www.irs.gov/Businesses/Corporations/IRS-FATCA-Report-Notifications.
1.3. Notification Schema Files Covered in this Document
The FATCA Error and Valid File Notification types each have their own schema structure and data elements,
which are described in this guide. All schema files used for FATCA data exchange are available at
http://www.irs.gov/Businesses/Corporations/FATCA-XML-Schemas-and-Business-Rules-for-Form-8966.
The FATCA Notification Schema consists of three schema (.xsd) files:
• BASE-FATCA-NOTIFICATION-2.3 – Base schema for common data elements and data types related to
FATCA notifications. Referenced by all main notifications schemas.
• FATCA-FILE-ERROR-NOTIFICATION-2.3 (4 KB) – Main schema describing file level error notifications.
• FATCA -VALID-FILE-NOTIFICATION-2.3 (4 KB) – Main schema for the valid file notifications.
The structure and data elements for FATCA Filer Error and Valid File Notification schemas are discussed in
this document.
3
|
|
Publication 5216
1.4. Schema Element Descriptions
Each schema element is presented in terms of the characteristics in Table 1 below.
Table 1: Element Description
Characteristic Description
Element • The name of the schema element. Elements not described in
the guide are not supported.
Size • The minimum and/or maximum size in characters of the
element value.
Cardinality • The number of times an element occurs in an XML file.
• If cardinality is not defined, then one and only one instance
should be included (minOccurs=1 and maxOccurs=1).
• Where a data element is not used, then the associated
attribute(s) are not used.
Data type • The data type for a data element value, such as numeric, string,
Boolean, date, time, etc.
• XML supports custom data types and inheritance.
Requirement • The requirement field for each data element and its attribute
indicates whether the element must be included in the XML
document.
Required: The data element is required for schema
validation and must be included in the Notification.
Optional: The data element is not always needed in the
Notification. Refer to the user guide to determine when it
should be included.
Description • This contains the business definition for the element.
1.5. How to Use this Guide
The notification schema files define how valid FATCA Notification XML files will be structured. This guide
contains additional information on how the IRS will use the notiification schema to generate FATCA
notifications. This guide explains how the IRS will augment valid XML notification files to convey error and
valid file processing outcomes.
Each data element described in the FATCA XML Schema supports metadata, notifications and the FATCA
Report (Form 8966). The schema definition files provide the framework for discussion of data elements
presented within the guide. The FATCA XML schema definition files or .xsd files may be downloaded from the
IDES site on IRS.gov.
The diagrams included in this document illustrate the message structure and hierarchy relationship of
notification schema elements. These diagrams were developed using XMLSpy®, but the schema and sample
files can be viewed with other XML tools, such as XML Notepad. The table in Figure 1 describes the XMLSpy®
legend to interpret the diagrams in the text. If you are using a different XML tool, the icons and images may
vary.
Other organizations, such as HCTAs, receiving data from the IRS through IDES using the FATCA XML
Schema are free to use the FATCA Notification Schema to format their notifications to the IRS. However, the
perspective within this guide is restricted to IRS usage of this notification schema when responding to FATCA
XML files received through IDES.
4
|
|
Publication 5216
Figure 1: Schema Legend
Schema Icon Description
Box with full-line is a required report element.
Box with dotted line is an optional report element.
The child elements must appear in the sequence mentioned.
Only one of the possible child elements may be present.
Element descriptions are annotated with graphics generated using XML Spy ® which is provided by Altova
(www.altova.com). A tutorial for XMLSpy can be found here.
1.6. Restrictions on Text in FATCA String Characters
The UTF-8 encoding standard must be used in all FATCA XML reports. In addition, there are important
restrictions on the use of certain characters and character combinations in FATCA Report files to which filers
should adhere to in order to avoid a File-Level Error.
1.7. Compatibility with FATCA Notification Schema V2.2
The changes from FATCA Notification Schema V2.2 to 2.3 include:
• New enumeration code "NIL_REPORT" for FATCAReportTypeCdType;
• New enumeration codes (8013-8018) for nil report record level errors in RecordLevelErrorCdType; and
• Updated enumerations in ISO3166Alpha2CountryCodeType according to CountryCode_Type in
isofatcatypes_v1.1.xsd in FATCA XML 2.0.
In addition, the “version” attribute on the “FATCAFileErrorNotification” schema element is now set to “2.3”.
1.8. Comments
We appreciate your comments on the quality and usefulness of this publication. If you find any errors or have
suggestions, please indicate the chapter, section and page. Send your comments to the following email
address: lbi.fatca.ides@irs.gov.
5
|
|
Publication 5216
2. FATCAFileErrorNotification
This section discusses the data elements of FATCA-FILE-ERROR-NOTIFICATION-2.3.xsd schema file, which
will be used to transmit error notifications when the conditions outlined in Section 1.2 above are detected by
the IRS on FATCA Report files received through IDES. The structure of a FATCA error notification is shown in
Figure 2 below.
Figure 2: FATCAFileErrorNotification Type Layout
An example FATCA File Error Notification in XML format for the “NDC” (failed decryption) case is shown in
Appendix B.
“FATCAFileErrorNotification” Attribute: The “FATCAFileErrorNotification” element is currently the only
element in the FATCA-FILE-ERROR-NOTIFICATION-2.3.xsd schema with an attribute. The Attribute name
is “version”, the type is “string”, and the value is fixed at “2.3”.
6
|
|
Publication 5216
Each of the sub-elements for the FATCAFileErrorNotification data elements are discussed in more detail in
the following sections, per the table below.
Ref Element Datatype Cardinality Requirement
2.1 FATCANotificationHeaderGrp Complex Type 1 Required
2.2 OriginalFileMetadataGrp Complex Type 1 Required
2.3 NotificationContentTxt String 1 Required
2.4 ActionRequestedGrp Complex Type 1 Required
2.5 HCTATreatyStampTxt String 0..1 Optional
2.1. FATCANotificationHeaderGrp
The FATCANotificationHeaderGrp is a required complex data element which contains information about the
sender, receiver, and identity of the notification, time and date of notification creation, and the type of error
triggering the notification. The FATCANotificationHeaderGrp type and sub-elements are depicted in Figure
3 below.
Figure 3: FATCANotificationHeaderGrp Type Layout
The sub-elements of FATCANotificationHeaderGrp are described below.
7
|
|
Publication 5216
2.1.1. FATCANotificationCreateTs
The “FATCANotificationCreateTs” data element provides the date and time at which the FATCA error
notification was created by the IRS.
Size/Pattern • String type
• ISO-8601 format
• Typically 22 characters (fractional seconds are not used)
Datatype TimestampWithMillisecondsType
Requirement Required
Description: • FATCA Notification Create Timestamp.
• Element identifies the timestamp for the notification payload that is
created by the IRS. The element will be automatically populated by
the IRS.
• The ISO-8601 compatible format is YYYY-MM-DD’T’hh:mm:ss, with
time zone indicator. Fractions of seconds are not used.
• Example: 2016-03-15T09:45:30Z+04.
2.1.2. FATCANotificationRefId
The “FATCANotificationRefId” sub-element contains the unique reference number created by the IRS for
the error notification. The notification identity in this sub-element must be used by the sending FFI, NFFE,
and/or HCTA in communications with the IRS about this notification.
Size/Pattern String type
Maximum length 200 characters
Datatype String
Requirement Required
Description: • Free text field to capture the IRS’s unique identification number for
each generated notification. The identifier allows both the IRS and
receiving entity to identify the specific message.
2.1.3. FATCANotificationCd
The “FATCANotificationCd” sub-element will be a 3 character string on the form “Nxx”, where “xx” will
depend on the type of error triggering the notification. The notification codes and related error conditions
are outlined in Table 2 below.
8
|
|
Publication 5216
Table 2: FATCA Error Notification Codes and Triggers
Code Notifications Error Conditions Triggering Notifications
NDW Failed Download • Failed download, due to a file transfer interruption or other
Notification fault condition preventing file access on IDES
NDC Failed Decryption • Decryption failure involving the encrypted payload file
Notification
• Decryption failure involving the sender’s encrypted AES
key file other than incorrect size
NDP Failed Decompression • Failed decompression of decrypted payload files
Notification
NSC Failed Signature Check • Invalid digital signature
Notification
• Invalid sender digital certificate
NKS Incorrect AES Key Size • Decryption failure due to the sender’s encrypted AES key
Notification having an incorrect size
• Intended to alert filer of possible use of EBC versus CBC
ciphering for AES encryption
NTD Failed Threat Detection • Detection of restricted characters, including apostrophe ('),
Notification double dash (--), and hash key (#)
• Detection of one or more non-virus security threats at any
stage of processing of received transmission from IDES in
which a file’s state is changed (initial download, unzipping
the transmission archive, decryption of AES key and
payload files, payload decompression)
NVS Failed Virus Scan • Detection of one or more viruses at any stage of
Notification processing of received transmission from IDES in which a
file’s state is changed (initial download, unzipping the
transmission archive, decryption of AES key and payload
files, payload decompression)
NSV Failed Schema Check • FATCA Report payload file cannot be validated against
Notification the FATCA XML Schema
NMR Invalid MessageRefId • MessageRefId value consisting solely of one or more
Notification blank characters
NDM Duplicate • Duplicate MessageRefId value (MessageRefId value
MessageRefId received on a prior valid file).
Notification
NTP Test data has been • Records with DocTypeIndic values for test data were
submitted into present in the file submitted to the IRS live filing
production environment
NPT Production data has • Records with DocTypeIndic values for production data
been submitted into test were present in the file submitted to an IRS test
environment
NCF Certificate Failure • Invalid certificate
9
|
|
Publication 5216
NDF Failed Decoding • File could not be decoded because file type and decoding
type were inconsistent
NIF Invalid File Format • File format type and actual file contents were inconsistent
The aspects of the “FATCANotificationCd” sub-element are given below:
Size/Pattern 3 characters
Datatype FATCANotificationCdType
Requirement Required
Description: • Three character code indicates the type of error encountered in file
processing (see Table 2).
2.1.4. FATCAEntitySenderId
The “FATCAEntitySenderId” sub-element identifies the IRS as the sender of the notification by providing the
IRS HCTA GIIN, which will be 000000.00000.TA.840. FFIs, direct reporting NFFEs, and HCTAs should not
be receiving notifications from any other sender (though HCTAs are free to use the notification schema to
send notifications to the IRS for reciprocal reporting issues).
Size/Pattern String containing 19 characters in GIIN format
Datatype FATCAEntityIdType
Requirement Required
Description: • Element contains the IRS HCTA Global Intermediary Identifying
Number (GIIN).
• Value will be 000000.00000.TA.840.
2.1.5. FATCAEntityReceiverId
The “FATCAEntityReceiverId” is the GIIN of the HCTA, FFI, or direct reporting NFFE receiving the
notification. If a non-GIIN filer is receiving the notification, the “FATCAEntityReceiverID” will be the FIN of
the non-GIIN filer. This field will be in the FATCA GIIN or FIN format.
Size/Pattern String containing 19 characters in GIIN format
Datatype FATCAEntityIdType
Requirement Required
Description: • Element contains the receiver FATCA entity identification in the GIIN-
or FIN format with punctuation (period or decimal) and will match a
valid GIIN or FIN in the Registration database.
• If the direct recipient is an HCTA, HCTA GIIN is used (example:
000000.00000.TA.101).
10
|
|
Publication 5216
2.1.6. CopiedToFATCAEntityId
The “CopiedToFATCAEntityId” contains the HCTA GIIN for an HCTA receiving a copy of a notification. In
2016 certain HCTAs may receive copies of notifications from the IRS to FFIs in their jurisdiction under terms
of Competent Authority Agreements between the US and the jurisdiction country.
Size/Pattern String containing 19 characters in GIIN format
Datatype FATCAEntityIdType
Requirement Optional
Description: • Element contains the unique entity identifier for the HCTA or FFI that
receives a copy of the notification. The identifier is in the GIIN-format
with punctuation (period or decimal) and must match a valid GIIN in
the Registration database.
• If the direct recipient is the HCTA, use the IRS issued HCTA GIIN.
Example: 000000.00000.TA.101.
• If the direct recipient is a FFI, use the IRS issued FFI GIIN
Example: 12A34B.00000.LE.102.
2.1.7. ContactInformationTxt
The “ContactInformationTxt” sub-element provides the contact information for the recipient to use in
reaching to the IRS about a received error notification.
Size/Pattern Maximum length of 200 characters
Datatype StringMax200Type
Requirement Optional
Description: • Contains a URL to an irs.gov site with additional resources to assist in
resolving errors creating notifications
• Always included in FATCA error notifications from the IRS.
11
|
|
Publication 5216
2.2. OriginalFileMetadataGrp
The OriginalFileMetadataGrp is a required complex data element which contains information about the
original transmission from IDES that contained the FATCA Report file. This data includes the IDES ID for
the original transmission as sent by the FFI, direct reporting NFFE, or HCTA and as received by the IRS,
the date and time the transmission was sent to the IRS, the sender of the original transmission, and the size
of the decrypted, uncompressed FATCA Report payload file. The OriginalFileMetadataGrp type and sub-
elements are depicted in Figure 4 below.
Figure 4: OriginalFileMetadatGrp Type Layout
12
|
|
Publication 5216
The sub-elements of OriginalFileMetadataGrp are described in the subsections below.
2.2.1. IDESTransmissionId
The “IDESTransmissionId” sub-element provides the IDES ID assigned to the original transmission by IDES
when it was initially received from the sender FFI, direct reporting NFFE, or HCTA.
Size/Pattern 32 character-length string in IDES ID format
Datatype String32Type
Requirement Required
Description: • Free text field to reference the original FFI, direct reporting NFFE, or
HCTA sender unique transmission identification number automatically
generated by IDES.
• Including this identifier will help the sender correlate the notification to
the original transmission and payload (FATCA Report file).
2.2.2. IDESSendingTs
The “IDESSendingTs” sub-element provides the date and time the original transmission was initially
delivered to the IRS by IDES.
Size/Pattern • String type
• ISO-8601 format
• Typically 22 characters (fractional seconds are not used)
Datatype TimestampWithMillisecondsType
Requirement Required
Description: • FATCA Notification Create Timestamp
• Element identifies the timestamp for the notification payload that is created by the
IRS. The element will be automatically populated by the IRS.
• The ISO-8601 compatible format is YYYY-MM-DD’T’hh:mm:ss, with time zone
indicator. Fractions of seconds are not used.
• Example: 2016-03-15T09:45:30Z+04
13
|
|
Publication 5216
2.2.3. SenderFileId
The “SenderFileId” sub-element provides the file identifier (MessageRefId) assigned to the notification
transmission by the IRS. This data can be used by the notification recipient in communications with the IRS
concerning the notification.
Size/Pattern Maximum length of 200 characters
Datatype StringMax200Type
Requirement Required
Description: • Free text field containing the IRS-assigned unique file identifier
number or filename for the notification payload file.
• The value can be a unique file name or an identification number.
2.2.4. UncompressedFileSizeKBQty
The “UncompressedFileSizeKBQty” provides the size of the payload file, after decryption and
decompression, in which the IRS identified the error condition triggering the error notification. This data will
be provided to the FFI, direct reporting NFFE, or HCTA, if available. Note that the IRS will not be able to
provide this information for error conditions which prevent the IRS from decompressing the payload file (for
example, decryption, digital signature, or file download failures).
Size/Pattern N/A
Datatype Integer
Requirement Optional
Description • Provides the uncompressed payload file size in kilobytes (KB).
• Not applicable if errors preventing the IRS from decompressing the
payload file take place.
2.3. NotificationContentTxt
The “NotificationContentTxt” is a required sub-element of the main FATCAFileErrorNotification element
which provides information about the nature of the error encountered while the IRS was processing the
FATCA Report file received from the FFI, direct reporting NFFE, or HCTA. The relationship between
NotificationContextTxt and FATCAFileErrorNotification elements is depicted in Figure 2. This is a required
sub element for this error notification schema, and there are no lower level sub-elements.
Size/Pattern Maximum length of 4000 characters
Datatype StringMax4000Type
Requirement Required
Description: • Element is a free text field to explain the file error notification.
14
|
|
Publication 5216
2.4. ActionRequestedGrp
The “ActionRequestedGrp” is a required sub-element of the main FATCAFileErrorNotification element which
provides information about how the FFI, direct reporting NFFE, or HCTA should respond to the error
notification, and when a response is expected. There are two required sub elements for this data element.
The ActionRequestedGrp and its sub-elements are depicted in Figure 5.
Figure 5: ActionRequestedGrp Type Layout
The sub-elements of ActionRequestedGrp are described below.
2.4.1. ActionRequestedTxt
The “ActionRequestedTxt” sub-element provides information to the FFI, direct reporting NFFE, and/or HCTA
on how to resolve the error condition that was detected by the IRS on the transmission. This text message
will be targeted to the specific error condition reflected in the error notification.
15
|
|
Publication 5216
Size/Pattern Maximum length of 4000 characters
Datatype StringMax 4000Type
Requirement Required
Description: • Text field to explain the process or actions required to clear the error
notification.
• Specific details will depend on the type of error notification.
• The text message will also reiterate the contact information in the
“ContactInformationTxt” data element (see Section 2.1.7).
2.4.2. ActionRequestedDueDateTxt
The “ActionRequestedDueDateTxt” sub-element provides the due date for the FFI, direct reporting NFFE,
and/or HCTA to resolve the error condition that was detected by the IRS on the transmission.
Size/Pattern Maximum length of 200 characters
Datatype StringMax200Type
Requirement Required
Description: • Due date for the action requested to clear the error notification. Note
that the due date may not be a specific date. Instead, it could have a
text value such as “Your organization’s due date for filing Form 8966.”
• Typically the due date will be that relevant filing date for FATCA
Reports (Forms 8966) per IRS regulations and instructions.
2.5. HCTATreatyStampTxT
The “HCTATreatyStampTxT” sub-element is optional and will only be applied to notifications transmitted in
response to FATCA Report files received from an HCTA under a tax treaty, tax information exchange
agreement (TIEA) or other bilateral agreement for the exchange of information. The treaty stamp is clearly
applicable and required for information received or sent from a HCTA. The treaty stamp is a required
statement, and is necessary to ensure that the data exchanged with a foreign government, including data
regarding an original FATCA Report file received from an HCTA, is properly protected and that the use or
disclosure of such data is in accordance with the applicable tax treaty, TIEA, or other bilateral agreement
relating to the exchange of tax information with the United States.
Size/Pattern Maximum length of 4000 characters
Datatype String
Requirement Optional
Description • The “HCTATreatyStampTxT” element contains a required statement
necessary to ensure that data furnished to the IRS under the provisions
of an income tax treaty, TIEA, or other bilateral agreement relating to
the exchange of information (for example, IGA) with a foreign
government is kept confidential, and that the use and disclosure of
such data must be governed by the provisions of that treaty, TIEA, or
other agreement.
• Example: “This information is furnished under the provisions of an
income tax treaty, tax information exchange agreement (TIEA), or other
agreement for the exchange of information with a foreign government,
and its use and disclosure must be governed by the provisions of that
treaty, TIEA, or other agreement.”
16
|
|
Publication 5216
3. FATCAValidFileNotification
This section discusses the data elements of FATCA-VALID-FILE-NOTIFICATION -2.3.xsd schema file, which
will be used to transmit notifications when FATCA Report files received by the IRS have passed all file
processing checks. The structure of a FATCA valid file notification is shown in Figure 6.
Figure 6: FATCAValidFileNotification Type Layout
17
|
|
Publication 5216
“FATCAValidFileNotification” Attribute: The “FATCAValidFileNotification” element is currently the only
element in the FATCA-VALID-FILE-NOTIFICATION-2.3.xsd schema with an attribute. The Attribute name
is “version”, the type is “string”, and the value is fixed at “2.3”.
Each of the sub-elements for the FATCAValidFileNotification data elements are discussed in more detail in
the following sections, per the table below.
Ref Element Datatype Cardinality Requirement
3.1 FATCANotificationHeaderGrp Complex Type 1 Required
3.2 OriginalFileMetadataGrp Complex Type 1 Required
3.3 OriginalFileMessageSpecGrp Complex Type 0..1 Optional
3.4 ActionRequestedGrp Complex Type 1 Required
3.5 NotificationContentTxt String 1 Required
3.6 OriginalFileProcessingData Complex Type 0..1 Optional
3.7 FATCARecordErrorDetailGrp Complex Type 0..1 Optional
3.7 HCTATreatyStampTxt String 0..1 Optional
Many of the sub-elements of the FATCAValidFileNotification element have considerable overlap with their
counterparts in the FATCAFileErrorNotification element documented in Section 2. The following
FATCAValidFileNotification subsections will build out the differences with the FATCAFileErrorNotification
and make reference to the corresponding subsections of Section 2 where needed.
An example Valid File Notification in XML format for the “NVF” case is shown in Appendix C.
3.1. FATCANotificationHeaderGrp
The valid file schema “FATCANotificationHeaderGrp” data element is similar in purpose and structure to its
counterpart in the error notification schema. All seven sub-elements for the FATCANotificationHeaderGrp
are documented in Sections 2.1.1 through 2.1.7. The only difference with the sub-elements here versus the
discussion for the FATCAFileErrorNotification occurrences is that the “FATCANotificationCd” sub-element
takes on only one value “NVF” for valid file notifications:
The FATCANotificationHeaderGrp is depicted in Figure 7.
18
|
|
Publication 5216
Figure 7: FATCANotificationHeaderGrp Type Layout
19
|
|
Publication 5216
3.2. OriginalFileMetadataGrp
The valid file schema “OriginalFileMetadataGrp” data element is similar in purpose and structure to its
counterpart in the error notification schema. All five sub-elements for the OriginalFileMetadataGrp are
documented in Sections 2.2.1 through 2.2.5. The OriginalFileMetadataGrp is depicted in Figure 8.
Figure 8: FATCANotificationHeaderGrp Type Layout
20
|
|
Publication 5216
3.3. OriginalFileMessageSpecGrp
The “OriginalFileMessageSpecGrp” sub-element provides the FFI, direct reporting NFFE, or HCTA sender
of the original FATCA Report file with information from the message header data element (“MessageSpec”,
see IRS Publication 5124) from the FATCA Report file generating the valid notification. The
OriginalFileMessageSpecGrp is depicted in Figure 9 below.
Figure 9: OriginalFileMessageSpecGrp Type Layout
21
|
|
Publication 5216
The seven sub-elements in the OriginalFileMessageSpecGrp are described in the following subsections.
3.3.1. MessageRefId
The “MessageRefId” sub-element provides the MessageRefId for the processed file that the FFI, direct
reporting NFFE, or HCTA sender assigned to the original FATCA Report file. This will allow the recipient to
correlate the valid file notification to the original FATCA Report file.
Size/Pattern Maximum length of 200 characters
Datatype String
Requirement Required
Description: • Free text field to capture the identifying number of the FATCA Report
file created by the originating FFI/NFFE/HCTA to track a transmission
• This identifier will help both the IRS and file originator to identify the
specific transmission.
• Refer to the originally defined MessageRefId in stffatcatypes_v2.0
XSD of FACTA XML 2.0.
3.3.2. CorrMessageRefId
The “CorrMessageRefId” sub-element provides the CorrMessageRefId for the processed file that the FFI,
direct reporting NFFE, or HCTA sender assigned to the original FATCA Report file, where applicable. This
will allow the recipient to correlate the valid file notification to the original FATCA Report file.
Size/Pattern Maximum length of 200 characters
Datatype String
Requirement Optional
Description: • Element contains the MessageRefId for a transmission (report) that is
being corrected when the original file itself is a revised file.
• This identifier will help both the IRS and file originator to identify the
specific transmission.
• Refer to the originally defined CorrMessageRefId in
stffatcatypes_v2.0 XSD of FACTA XML 2.0.
3.3.3. SendingCompanyGIIN
The “SendingCompanyGIIN” sub-element provides the GIIN of the FFI or direct reporting NFFE, or FIN of
the non-GIIN filer, submitting the reports in the processed FATCA Report file.
Size/Pattern 19-digit GIIN format
Datatype String
Requirement Optional
Description: • Element contains the sender entity GIIN or FIN for the original
transmission.
• Refer to the originally defined SendingCompanyIN in
stffatcatypes_v2.0XSD of FACTA XML 2.0.
22
|
|
Publication 5216
3.3.4. TransmittingCountryCd
The “TransmittingCountryCd” sub-element provides the country code of the FFI or direct reporting NFFE
submitting the reports in reports from the processed FATCA Report file.
Size/Pattern 2-digit alphabetic country code specified in the ISO 3166-1 Alpha 2
standard. Examples: GB (Great Britain) or DE (Germany)
Datatype String
Requirement Required
Description: • Element contains the jurisdiction of the sender entity for the original
transmission.
• Originally defined as TransmittingCountry in stffatcatypes_v2.0 XSD
of FACTA XML 2.0.
3.3.5. ReceivingCountryCd
The “ReceivingCountryCd” sub-element provides the country code of the recipient of the processed FATCA
Report file. This should be “US” in all valid file notifications from the IRS in 2016.
Size/Pattern 2-digit alphabetic country code specified in the ISO 3166-1 Alpha 2
standard.
Example: US (United States)
Datatype String
Requirement Required
Description: • Element identifies the jurisdiction of the receiving entity (“US” for IRS
in 2017).
• Originally defined as ReceivingCountry in stffatcatypes_v2.0XSD of
FACTA XML 2.0.
3.3.6. MessageTypeCd
The “MessageTypeCd” sub-element provides contents of the “MessageType” field from the processed
FATCA Report file. Its value will always be “FATCA” in 2016.
Size/Pattern 5 character (currently, the only allowable entry is“FATCA”)
Datatype String
Requirement Required
Description: • Element specifies the type of report transmitted from “MessageType”
in the original FATCA Report file.
• Will always be “FATCA” for 2017.
• Originally defined as MessageType in stffatcatypes_v2.0 XSD of
FATCA XML 2.0 Message type defines the type of reporting.
3.3.7. ReportingPeriodDt
The “ReportingPeriodDt” sub-element provides period covered by the FATCA account, pooled, or nil reports
enclosed in the processed FATCA Report file. This element is shown “date” format as “YYYY-MM-DD”, and
is taken from the “ReportingPeriod” data element in the processed FATCA Report file. This data element
should read “2016-12-31” for 2017.
23
|
|
Publication 5216
Size/Pattern YYYY-MM-DD format
Datatype xsd:date
Requirement Required
Description: • Element identifies the reporting yearof the transmitted message
• Originally defined as ReportingPeriod in stffatcatypes_v2.0 XSD of
FATCA XML 2.0.
3.4. NotificationContentTxt
The “NotificationContentTxt” sub-element is documented in Section 2.3 above.
3.5. OriginalFileProcessingDataGrp
The “OriginalFileProcessingDataGrp” sub-element provides the FATCA Filer with information derived by the
IRS from data elements from the FATCA Report file generating the valid notification. The
OriginalFileProcessingDataGrp is depicted in Figure 10. The six sub-elements in the
OriginalFileProcessingDataGrp are described in the following subsections.
3.5.1. FileTypeCd
The “FileTypeCd” sub-element is generated by the IRS to indicate the type of file to the originator of the
FATCA Report file. The type of files include: new file; a revision of a previous file (corrected or amended
file); a duplicate of a previous file; or an unknown file type. This is an enumerated data element, with only
four valid values shown in the table below.
Size/Pattern Enumeration codes
Datatype String
Requirement Required
Description: • Element identities the type of FATCA report filed.
• The valid type codes to be sent by the IRS are:
NEW: New File
REV: Revised File
DUP: Duplicate File
UNK: Unknown File Type
3.5.2. FinancialInstitutionCnt
The “FinancialInstitutionCnt” sub-element is generated by the IRS as the total number of FFIs reporting
account or pooled reports in the FATCA Report file generating the valid file notification.
Size/Pattern N/A
Datatype Integer
Requirement Optional
Description: • Indicates the number of financial institutions reporting in the file, as
calculated by the IRS.
• May not always be provided (for example, will not be provided for
“DUP” files).
24
|
|
Publication 5216
Figure 10: OriginalFileProcessingDataGrp Type Layout
25
|
|
Publication 5216
3.5.3. RecordCnt
The “RecordCnt” sub-element is generated by the IRS as the total number of account and pooled reports in
the FATCA Report file generating the valid file notification.
Size/Pattern N/A
Datatype Integer
Requirement Optional
Description: • Indicates the total number of account and pooled report records in the
file, as calculated by the IRS.
• May not always be provided (for example for example, will not be
provided for “DUP” files).
3.5.4. DupAccountReportRecordCnt and Non DupAccountReportRecordCnt
The “DupAccountReportRecordCnt” and “NonDupAccountReportRecordCnt” sub-elements are generated
by the IRS as the total number of duplicated and non-duplicated account report records, respectively, in the
FATCA Report file generating the valid file notification.
Size/Pattern N/A
Datatype Integer
Requirement Optional
Description: • Combined total indicates the total number of account report records in
the file, as calculated by the IRS.
• May not always be provided (for example, will not be provided for
“DUP” files).
3.5.5. PooledReportRecordCnt
The “PooledReportRecordCnt” sub-element is generated by the IRS as the total number of pooled reports in
the FATCA Report file generating the valid file notification.
Size/Pattern N/A
Datatype Integer
Requirement Optional
Description:
• Indicates the total number of pooled report records in the file, as
calculated by the IRS.
• May not always be provided (for example, will not be provided for
“DUP” files).
3.6. HCTATreatyStampTxt
The “HCTATreatyStampTxt” sub-element is documented in Section 2.5.
3.7. FATCARecordErrorGrp
The “FATCARecordErrorGrp” data elements provide full information on any record-level errors present in
the file. These are optional elements and only included if there are record errors to be reported to the
26
|
|
Publication 5216
FATCA Filer, with one FATCARecordErrorGrp provided per file, as needed. There are 3 sub-elements The
FATCARecordErrorGrp is depicted in Figure 11.
Figure 11: FATCARecordErrorGrp Type Layout
27
|
|
Publication 5216
3.7.1. FATCARecordInfoHeaderTxt
The “FATCARecordHeaderTxt” data element advises the filer that errors were detected and provides error
details organized by FI.
Size/Pattern 4000 characters
Datatype StringMax4000Type
Requirement Required
Description: • Provides a message advising the filer of record errors, and that record
error descriptions will be organized by FI.
• Example: “Record level error details from the file submitted are
provided and are organized by financial institution.”
3.7.2. FATCARecordErrorFIGrp
The “FATCARecordErrorFIGrp” data element, illustrated in Figure 12, provides a description of record errors
and the names and GIINs of the Sponsor and Reporting FIs linked to the identified errors; these FIs are
reporting the accounts and may be responsible for error resolution. There are five sub-elements described
below.
Figure 12: FATCARecordErrorFIGrp Type Layout
28
|
|
Publication 5216
3.7.2.1. SponsorGIIN
The “SponsorGIIN” sub-element provides the Sponsor GIIN, if available, for the record in error. This is an
optional data element, and will not be provided if there is a field-level error involving the Sponsor GIIN.
Size/Pattern 19 character GIIN format
Datatype FATCAEntityIdType
Requirement Optional
Description: • Provides the Sponsor GIIN in valid GIIN format.
• Will be taken from the FATCA/ReportingGroup/Sponsor/TIN data
element from the record in question.
• Will not be provided if there is a field-level error involving the Sponsor
GIIN (such as invalid format).
3.7.2.2. SponsorNm
The “SponsorNm” sub-element provides the name of the Sponsor, if available, for the record in error. This
is an optional data element, and will not be provided if there is a field-level error involving the Sponsor
name.
Size/Pattern 200 characters
Datatype StringMax200Type
Requirement Optional
Description: • Provides the Sponsor name.
• Will be taken from the FATCA/ReportingGroup/Sponsor/Name data
element from the record in question.
• Will not be provided if there is a field-level error involving the Sponsor
name.
3.7.2.3. ReportingFIGIIN
The “ReportingFIGIIN” sub-element provides the Reporting FI GIIN or EIN for the record in error. This is an
optional data element, and will not be provided if there is a field-level error involving the Reporting FI GIIN or
EIN.
Size/Pattern 19 character GIIN format (for GIIN) or 9-numeric characters (for EIN)
Datatype FATCAEntityIdType
Requirement Optional
Description: • Provides the Reporting FI GIIN or EIN in valid format
• Will be taken from the FATCA/ReportingFI/TIN data element from the
record in question.
• Will not be provided if there is a field-level error involving the
Reporting FI GIIN or EIN (for example, invalid format).
29
|
|
Publication 5216
3.7.2.4. ReportingFINm
The “ReportingFINm” sub-element provides the name of the Reporting FI, if available, for the record in error.
This is an optional data element, and will not be provided if there is a field-level error involving the Reporting
FI name.
Size/Pattern 200 characters
Datatype StringMax200Type
Requirement Optional
Description: • Provides the Reporting FI name.
• Will be taken from the FATCA/ReportingFI/Name data element from
the record in question.
• Will not be provided if there is a field-level error involving the
Reporting FI name.
3.7.2.5. FATCARecordErrorDetailGrp
The “FATCARecordErrorDetailGrp” sub-element provides basic descriptive and identifying information on
the record in which errors were detected, the type of record level error detected, details on any field level
errors within the record that require correction, and corrective action needed to address the errors identified.
There are 8 sub-elements The FATCARecordErrorDetailGrp is depicted in Figure 13. The eight sub-
elements in the FATCARecordErrorDetailGrp are described in the following subsections.
3.7.2.5.1. FATCAReportTypeCd
The “FATCAReportTypeCode” sub-element is generated by the IRS to indicate the type of record, account
report, pooled, or nil report, in the FATCA Report file in which the IRS has detected a record error. This is
an enumerated data element, with only three valid values shown in the table.
Size/Pattern Character Enumeration codes
Datatype String
Requirement Required
Description: • Element identities the type of FATCA report filed.
• The valid type codes to be sent by the IRS are:
ACCOUNT_REPORT: Account Report
POOL_REPORT: Pooled Report
NIL_REPORT: Nil Report
3.7.2.5.2. DocTypeIndicCd
The “DocTypeIndicCd” sub-element is generated by the IRS to provide the DocTypeIndic value from the
erroneous record (whether the record is NEW, CORRECTED, AMENDED, or VOID filing or test data). This
data element has type “FatcaDocTypeIndicType” and is an enumerated data element with eight values.
Size/Pattern Enumeration codes
Datatype String
Requirement Required
30
|
|
Publication 5216
Description: • Element identities the type of FATCA report filed.
• The valid type codes to be sent by the IRS are:
FATCA1: New Record
FATCA2: Corrected Record
FATCA3: Void Record
FATCA4: Amended Record
FATCA11: New Test Record
FATCA12: Corrected Test Record
FATCA13: Void Test Record
FATCA14: Amended Test Record
3.7.2.5.3. DocRefId
The “DocRefId” sub-element is generated by the IRS to provide the DocRefId value from the erroneous
record being presorted on.
Size/Pattern 200 character string maximum
Datatype StringMax200Type
Requirement Required
Description: • Element identities the erroneous FATCA record within a file.
• Naming conventions for DocRefId values are recommended.
3.7.2.5.4. CorrMessageRefId
The “CorrMessageRefId” sub-element is an optional element containing the MessageRefId of the original,
corrected, or amended file, in which the erroneous record was identified, that is being replaced. This is an
optional element and will be included if and only if the record was submitted as part of a corrected or
amended file.
Size/Pattern 200 character string maximum
Datatype StringMax200Type
Requirement Optional
Description: • Element identities the original, corrected, or amended file containing
the erroneous FATCA record that is being replaced.
31
|
|
Publication 5216
Figure 13: FATCARecordErrorDetailGrp Type Layout
32
|
|
Publication 5216
3.7.2.5.5. CorrDocRefId
The “CorrDocRefId” sub-element is an optional element identifying the DocRefId of the original record
intended to be replaced by the erroneous record within the corrected or amended file. This is an optional
element and will be included if and only if the record was submitted as part of a corrected or amended file.
Size/Pattern 200 character string maximum
Datatype StringMax200Type
Requirement Optional
Description: • Element identities the erroneous FATCA record within a file.
• Content must exactly match the character string of the DocRefId
impacted by this record.
3.7.2.5.6. RecordLevelErrorCd
The “RecordLevelErrorCd” sub-element provides information on the type of record level error identified.
This is an enumerated data element, with valid values shown in the table below.
Size/Pattern Enumeration codes
Datatype String (4 characters)
Requirement Required
Description: • Element identities the type of FATCA report filed.
• The valid Record Error codes to be sent by the IRS are:
8001 Pooled Reporting Error
8002 Duplicate Pooled Report Record
8003 Pooled Report Correction with Error
8004 Pooled Report Correction without Matching Original
8005 Void Pooled Report without Matching Original
8006 Amended Pooled Report without Matching Original
8007 Account Reporting Error
8008 Duplicate Account Report Record
8009 Account Report Correction with Error
8010 Account Report Correction without Matching Original
8011 Void Account Report without Matching Original
8012 Amended Account Report without Matching Original
8013 Nil Reporting Error
8014 Duplicate Nil Report Record
8015 Nil Report Correction with Error
8016 Nil Report Correction without Matching
8017 Void Nil Report without Matching Original
8018 Amended Nil Report without Matching
8019 Unspecified Report
8020 Duplicate DocRefID
8021 Invalid DocRefID
3.7.2.5.7. FieldErrorGrp
The “FieldErrorGrp” sub-element is an optional complex element which provides specific information on the
type and location of Field-Level Errors detected within a record. This data element is included only for
33
|
|
Publication 5216
record-level errors involving Field-Level Errors with data. The Record-Level Errors which will be triggered
by Field-Level Errors are those for original account, pooled and nil reports with errors:
8001 Pooled Reporting Error
8007 Account Reporting Error
8013 Nil Reporting Error
FieldErrorGrp elements will only be included in the “FATCARecordErrorDetailGrp” element for these three
record-level errors. The sub-elements within each FieldErrorGrp are listed in the table below and described
in the following sections.
Ref Element Datatype Cardinality Requirement
3.7.2.5.7.1 FieldPartNum Integer 0..1 Optional
3.7.2.5.7.2 FieldLineNum Integer 0..1 Optional
3.7.2.5.7.3 FieldNm StringMax200Type 1 Required
3.7.2.5.7.4 FieldErrorCd StringMax200Type 0..1 Optional
3.7.2.5.7.5 FieldErrorTxt StringMax4000Type 1 Required
3.7.2.5.7.1. FieldPartNum
The “FieldPartNum” sub-element is an optional element which provides the part number of the Form 8966 in
which the Field-Level Error was detected. This element only has meaning in the context of Field-Level
Errors identified on paper Forms 8966, and will not be included in any of the Valid File Notifications to be
sent by ICMM during 2016 (which are in response to electronically filed FATCA Reports in XML form).
Size/Pattern N/A
Datatype Integer
Requirement Optional
Description: • Will provide the Form 8966 Part number (1 through 5)
• Intended for electronic error notifications in response to paper filings
(not provided in 2016).
• Has no direct application to Field-Level Errors in the XML version of
Form 8966 (FATCA reports in XML).
3.7.2.5.7.2. FieldLineNum
The “FieldLineNum” sub-element is an optional element which provides the line number, within the part of
the Form 8966 provided in “FieldPartNum”, in which the Field-Level Error was detected. This element only
has meaning in the context of Field-Level Errors identified on paper Forms 8966, and will not be included in
any of the Valid File Notifications to be sent by ICMM during 2016 (which are in response to electronically
filed FATCA Reports in XML form).
34
|
|
Publication 5216
Size/Pattern N/A
Datatype Integer
Requirement Optional
Description: • Will provide the Form 8966 line number (1 through 10 maximum for
Part 1).
• Intended for electronic error notifications in response to paper filings
(not provided in 2016).
• Has no direct application to Field-Level Errors in the XML version of
Form 8966 (FATCA reports in XML).
3.7.2.5.7.3. FieldNm
The “FieldNm” sub-element is a required element which provides the name of the FATCA XML data
element or paper Form 8966 entry which is in error. For Field-Level Errors in records from FATCA XML
files, the FieldNm value will be the complete path to the data element requiring correction, in the following
form:
“/element1/sub-element1.1/ sub-element1.1.1/…/finalsubelement”
This element must be included for Field-Level Errors identified on XML FATCA Reports.
Size/Pattern 200 characters maximum
Datatype StringMax200Type
Requirement Required
Description: • Provides the name or label of the Form 8966 or FATCA XML file in
which the error was detected.
• For field-level errors found in electronic records the path for the data
element will be provided (provided in 2016 Valid File Notifications).
3.7.2.5.7.4. FieldErrorCd
The “FieldErrorCd” subelement is an optional data element containing a four-digit code for the type of field
error detected in the record. This code is currently not being included on Valid File Notifications.
35
|
|
Publication 5216
Size/Pattern 4 numeric characters
Datatype StringMax200Type
Requirement Optional (not used in Valid File Notifications for FATCA Report XML files)
Description: • Provides a 4-digit error code for the specific field-level error detected.
• This will NOT be provided in XML valid file notifications transmitted in
2016.
3.7.2.5.7.5. FieldErrorTxt
The “FieldErrorTxt” subelement is a required data element containing a text description of the field error
detected in the record. (Note: specific error messages included in the “FieldErrorTxt” sub-element are
provided in Publication 5189.)
Size/Pattern 4000 characters
Datatype StringMax4000Type
Requirement Required
Description: • Provides a descriptive message and possibly resolution actions
concerning the Field-Level Error reported in this group.
• This will be provided in XML Valid File Notifications transmitted in
2016.
3.7.2.5.8. ActionRequestedGrp
The “ActionRequestedGrp” sub-element is a required data element containing a high level text description
of the resolution action requested from the filer. This data element is also provided in File Error Notification
and is documented in Section 2.4.
3.7.3. PotentialEffectTxt
The “PotentialEffectTxt” data element informs the FATCA Filer of the potential implications of not correcting
the errors documented in the notification.
Size/Pattern 4000 characters
Datatype StringMax4000Type
Requirement Required
Description: • Provides a message advising the filer of the potential consequences
of not resolving the errors documented in the notification.
36
|
|
Publication 5216
Appendix A: Glossary
Terms Description
Record A record is a subset of a file that is specific to an account, pooled, or nil
report. A single account report or pool report is equivalent to one paper
Form 8966. A record may contain only one account report or pooled
report.
Report A group of records assembled into a single XML instance. A FATCA
report may contain zero, one, or many records from one of more FATCA
Filers.
File Records sent to the receiving tax jurisdiction. A file may contain one
FATCA report that may consist of zero, one, or many reports.
Transmission A set or group of files moved through IDES. All transmissions will share a
similar structure consisting of multiple files with specific purposes. These
files will be zipped into an uncompressed archive using common tools
available with common user operating systems (Windows, MacOS, and
Linux/Unix). The specific files within the transmission archive structure
and their filename conventions sent to IDES are described below:
1. Encrypted FATCA Report (from FFI/NFFE/HCTA) or Notification
(from IRS): filename has the form [SenderGIIN]_Payload, where
SenderGIIN is the IRS-issued GIIN of the sender in full GIIN
format.
2. Encrypted AES Key: AES key used to encrypt payload in
[SenderGIIN]_Payload: filename has the form
[ReceiverGIIN]_Key, where ReceiverGIIN is the GIIN of the
recipient whose public key was used to encrypt the HCTA key.
3. Sender Metadata: contains the unencrypted metadata used by
IDES to identify the sender and route to the recipient; the filename
has the form [SenderGIIN]_Metadata.xml, where SenderGIIN is
the GIIN of the sender in full GIIN format.
Payload The electronic files that are packaged / encrypted / compressed in the
format required by IDES and are transmitted to the receiving party by
IDES.
Sender Metadata Sender metadata is the information provided to identify the Sender and to
ensure that the recipient can correctly process FATCA Reports or
Notifications.
Notification A Notification is a message sent from the United States Internal Revenue
Service (IRS) to an FFI, direct reporting non-financial foreign entity
(NFFE), or Host Country Tax Authority (HCTA) in response to the
transmission of a FATCA Report from that partner.
37
|
|
Publication 5216
Appendix B: Example: Incorrect AES Key Size Notification (NKS)
<?xml version="1.0" encoding="UTF-8"?>
<n1:FATCAFileErrorNotification xmlns="urn:fatca:fatcanotificationbase" xmlns:n1="urn:fatca:fatcafileerrornotification"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="2.3 ">
<FATCANotificationHeaderGrp>
<FATCANotificationCreateTs>2016-06-10T00:10:00Z</FATCANotificationCreateTs>
<FATCANotificationRefId>125</FATCANotificationRefId>
<FATCANotificationCd>NKS</FATCANotificationCd>
<FATCAEntitySenderId> 000000.00000.TA.840</FATCAEntitySenderId >
<FATCAEntityReceiverId>000000.00000.TA.124</FATCAEntityReceiverId>
<ContactInformationTxt>http://www.irs.gov/Businesses/Corporations/FATCA-Error-Notifications</ContactInformationTxt>
</FATCANotificationHeaderGrp>
<OriginalFileMetadataGrp>
<IDESTransmissionId>a7c6363de36f4c2192856b4d3283747c</IDESTransmissionId >
<IDESSendingTs >2016-06-10T00:00:00Z</IDESSendingTs >
<SenderFileId>20160609T004725848Z_000000.00000.TA.124.zip</SenderFileId>
<UncompressedFileSizeKBQty>100000</UncompressedFileSizeKBQty>
</OriginalFileMetadataGrp>
<NotificationContentTxt>The IRS could not decrypt the referenced file following download from IDES because the AES-256 key file was either blank,
missing or could not be decrypted, or because the decryption process failed to complete. Please do not submit a request to correct, amend or void any of the
records in this file until you receive a notification that this file has been received as valid. For more information on this notification, including the classification of a
failed file decryption under an intergovernmental agreement (IGA), please see: http://www.irs.gov/Businesses/Corporations/FATCA-Error-
Notifications</NotificationContentTxt>
<ActionRequestedGrp>
<ActionRequestedTxt>Please ensure the key/initialization vector file is encrypted using the valid IRS certificate on IDES, and the encrypted file is
included in the IDES transmission packet. Please repost the file to IDES.</ActionRequestedTxt>
<ActionRequestedDueDateTxt>Your FATCA reporting due date for the prior tax year.</ActionRequestedDueDateTxt>
</ActionRequestedGrp>
<HCTATreatyStampTxt>This information is furnished under the provisions of an income tax treaty, tax information exchange agreement (TIEA), or other
agreement for the exchange of information with a foreign government, and its use and disclosure must be governed by the provisions of that treaty, TIEA, or other
agreement.</ HCTATreatyStampTxt>
</n1:FATCAFileErrorNotification>
38
|
|
Publication 5216
Appendix C: Example – Valid File Notification (NVF) without Record Level Errors
The following is an example of the xml text for a “Valid File” Notification with record-level errors. The “FATCARecordErrorGrp” data element and
related sub-elements identifying record-level and field-level errors are indicated in the boxed area below. These elements will not be included in
the valid file notification for a file that contains no record-level errors. That is, the “FATCARecordErrorGrp” data element is only included in a
Valid File Notification if there are record-level errors present in the file.
<?xml version="1.0" encoding="UTF-8" standalone="true"?>
-<ns2:FATCAValidFileNotification version="2.3" xmlns:ns4="urn:fatca:fatcafileerrornotification" xmlns:ns3="urn:fatca:fatcapaperrecorderrornotification"
xmlns:ns2="urn:fatca:fatcavalidfilenotification "xmlns= urn:fatca:fatcanotificationbase" ">
- <FATCANotificationHeaderGrp >
<FATCANotificationCreateTs>2016-01-31T11:28:21Z</FATCANotificationCreateTs >
<FATCANotificationRefId>372</FATCANotificationRefId >
<FATCANotificationCd>NVF</FATCANotificationCd >
<FATCAEntitySenderId> 000000.00000.TA.840</FATCAEntitySenderId >
<FATCAEntityReceiverId>ABEBBA.99999.SL.756</FATCAEntityReceiverId >
<ContactInformationTxt>http://www.irs.gov/Businesses/Corporations/FATCA-Error-Notifications </ContactInformationTxt>
</FATCANotificationHeaderGrp >
- <OriginalFileMetadataGrp >
<IDESTransmissionId>7a627fec4aec4a2d8397ec836eea783c </IDESTransmissionId >
<IDESSendingTs >2017-01-31T11:21:17.017Z</IDESSendingTs >
<SenderFileId>20170131T004725848Z_ABEBBA.99999.SL.756.zip</SenderFileId >
</OriginalFileMetadataGrp >
- <OriginalFileMessageSpecGrp >
<MessageRefId>5PLDCARJune10AP2DB</MessageRefId >
<SendingCompanyGIIN>ABEBBA.99999.SL.756 </SendingCompanyGIIN >
<TransmittingCountryCd>CH</TransmittingCountryCd >
<ReceivingCountryCd>US</ReceivingCountryCd >
<MessageTypeCd>FATCA</MessageTypeCd >
<ReportingPeriodDt >2016-12-31Z</ReportingPeriodDt >
</OriginalFileMessageSpecGrp >
<NotificationContentTxt>The IRS has determined that the referenced file is in a valid format. Individual records submitted within the file have been
processed and any errors detected during processing are provided in the Error Details included. For more information about record level errors,
including their classification under an intergovernmental agreement (IGA), see: http://www.irs.gov/Businesses/Corporations/FATCA-Error-
Notifications</NotificationContentTxt >
- <OriginalFileProcessingDataGrp >
<FileTypeCd>NEW </FileTypeCd >
<FinancialInstitutionCnt>1< /FinancialInstitutionCnt >
39
|
|
Publication 5216
<RecordCnt>1</RecordCnt >
<DupAccountReportRecordCnt>0< /DupAccountReportRecordCnt >
<NonDupAccountReportRecordCnt>0</NonDupAccountReportRecordCnt >
<PooledReportRecordCnt>1< /PooledReportRecordCnt >
</OriginalFileProcessingDataGrp >
<HCTATreatyStampTxt>This information is furnished under the provisions of an income tax treaty, tax information exchange agreement (TIEA), or
other agreement for the exchange of information with a foreign government, and its use and disclosure must be governed by the provisions of that
treaty, TIEA, or other agreement.</HCTATreatyStampTxt >
</ns2:FATCAValidFileNotification >
Appendix D: Example – Valid File Notification (NVF) with Record Level Error
<?xml version="1.0" encoding="UTF-8"?>
-<ns2:FATCAValidFileNotification xmlns="urn:fatca:fatcanotificationbase" xmlns:ns2="urn:fatca:fatcavalidfilenotification"
xmlns:ns3="urn:fatca:fatcapaperrecorderrornotification" xmlns:ns4="urn:fatca:fatcafileerrornotification" version="2.3">
- <FATCANotificationHeaderGrp >
<FATCANotificationCreateTs>2017-01-22T11:44:17Z</FATCANotificationCreateTs >
<FATCANotificationRefId>247</FATCANotificationRefId >
<FATCANotificationCd>NVF</FATCANotificationCd >
<FATCAEntitySenderId>000000.00000.TA.840</FATCAEntitySenderId >
<FATCAEntityReceiverId>ABEBBA.99999.SL.756</FATCAEntityReceiverId >
<ContactInformationTxt>http://www.irs.gov/Businesses/Corporations/FATCA- Error-Notifications</ContactInformationTxt >
</FATCANotificationHeaderGrp >
- <OriginalFileMetadataGrp >
<IDESTransmissionId>060FZp24O6EdhuqtB1k66sCcx0kM56EX</IDESTransmissionId >
<IDESSendingTs>2017-01-22T11:38:18.018Z</IDESSendingTs >
<SenderFileId >20170122T004725848Z_ABEBBA.99999.SL.756.zip /SenderFileId < >
</OriginalFileMetadataGrp >
- <OriginalFileMessageSpecGrp >
<MessageRefId>1PLDzAM1zzWDRLJuly13</MessageRefId >
<SendingCompanyGIIN >ABEBBA.99999.SL.756</SendingCompanyGIIN >
<TransmittingCountryCd >CH</TransmittingCountryCd >
<ReceivingCountryCd>US</ReceivingCountryCd >
<MessageTypeCd>FATCA</MessageTypeCd >
<ReportingPeriodDt>2016-12-31Z</ReportingPeriodDt >
40
|
|
Publication 5216
</OriginalFileMessageSpecGrp >
<NotificationContentTxt>The IRS has determined that the referenced file is in a valid format. Individual records submitted within the
file have been processed and any errors detected during processing are provided in the Error Details included. For more information
about record level errors, including their classification under an intergovernmental agreement (IGA), see:
http://www.irs.gov/Businesses/Corporations/FATCA-Error-Notifications /NotificationContentTxt < >
- <OriginalFileProcessingDataGrp >
<FileTypeCd >NEW</FileTypeCd >
<FinancialInstitutionCnt>1< /FinancialInstitutionCnt>
<RecordCnt>5</RecordCnt >
<DupAccountReportRecordCnt>0< /DupAccountReportRecordCnt >
<NonDupAccountReportRecordCnt>0< /NonDupAccountReportRecordCnt >
<PooledReportRecordCnt>5< /PooledReportRecordCnt >
</OriginalFileProcessingDataGrp >
<HCTATreatyStampTxt>This information is furnished under the provisions of an income tax treaty, tax information exchange agreement
(TIEA), or other agreement for the exchange of information with a foreign government, and its use and disclosure must be governed by the
provisions of that treaty, TIEA, or other agreement.</HCTATreatyStampTxt >
- <ns2:FATCARecordErrorGrp >
<RecordErrorInfoHeaderTxt>Record level error details from the file submitted are provided and are organized by financial
institution.</RecordErrorInfoHeaderTxt >
- <ns2:FATCARecordErrorFIGrp >
<ReportingFIGIIN>ABEBBA.99999.SL.756</ReportingFIGIIN >
<ReportingFINm>Union Asset Management Incorporated</ReportingFINm >
- <ns2:FATCARecordErrorDetailGrp >
<FATCAReportTypeCd>ACCOUNT_REPORT </FATCAReportTypeCd >
<DocTypeIndicCd >FATCA1</DocTypeIndicCd >
<DocRefId>ABEBBA.99999.SL.756.1PLDAM3WsRDLDsocJuly1301
</DocRefId >
<RecordLevelErrorCd>8007</RecordLevelErrorCd >
- <FieldErrorGrp >
<FieldNm>ReportingGroup/AccountReport/AccountHolder/Organisation/Name;ReportingGroup/AccountReport/Acco
untHolder/Individual/Name</FieldNm>
<FieldErrorTxt>Name of Account Holder or Recipient Not Provided</FieldErrorTxt >
</FieldErrorGrp >
- <ActionRequestedGrp >
41
|
|
Publication 5216
<ActionRequestedTxt>Please correct all records with errors. Ensure the corrected record has a CorrDocRefID
that matches the DocRefId and a CorrMessageRefID that matches the MessageRefID for the original(s) record
submitted for which the IRS is requesting a correction and post the file with corrected records to IDES. If the record
has an error in the Reporting FI GIIN, the original record must be voided and a new record submitted to correct the
GIIN.</ActionRequestedTxt >
<ActionRequestedDueDateTxt>Correct the errors within 120 days of the date of this
notice.</ActionRequestedDueDateTxt >
</ActionRequestedGrp >
</ns2:FATCARecordErrorDetailGrp >
</ns2:FATCARecordErrorFIGrp >
<PotentialEffectTxt>Failure to correct errors by the date required may result in a determination by the IRS that the Financial
Institution has defaulted under its FFI Agreement and/or is in Significant Non-Compliance with the terms of the
IGA.</PotentialEffectTxt >
</ns2:FATCARecordErrorGrp >
</ns2:FATCAValidFileNotification>
42
|