4

Transmitting Information Returns

Section 4 Transmitting Information Returns

This section provides an overview of transmission methodology, transmission composition, as well as data structure needed to successfully transmit ACA Information Returns to IRS. The data exchanged between the Transmitters and the ACA Information Return (AIR) System via XML files or messages conforms to the Simple Object Access Protocol (SOAP). There are two data communication channels between external clients and the AIR System: Both channels require the submissions to be self-contained in a single uncompressed XML formatted file. AIR will allow the Transmitter to transmit submissions to IRS and retrieve acknowledgements for those transmissions from IRS.

• The ISS-User Interface (UI) Channel (Web Browser) – The XML forms are created using the published

XML schemas located on the Affordable Care Act Information Returns (AIR) page and then uploaded to the AIR System via the UI Channel. This data is exchanged using the Hyper Text Transfer Protocol Secure (HTTPS) protocol over a Transport Layer Security (TLS) connection and then converted to SOAP. Transport Layer Security (TLS) versions 1.0 and 1.1 have been deprecated by the industry. According to NIST SP 800-52r2 guidelines, all government agencies, including IRS, should move off these versions and preferably move to TLS version 1.3 (TLS version 1.2 is also acceptable).

• The ISS-Application to Application (A2A) Channel – The data is exchanged in SOAP messages using

the Web Application request-response model transport mechanism over an HTTPS connection.

All information returns transmitted to IRS undergo a series of checks in the Portal. If any of these checks fail, the Transmitter will receive a fault response (an error prefixed with “TPE”), and a Receipt ID is not provided. The list of “TPE” errors is shown in Table 4-4 If every validation passes, the transmission continues to be processed in AIR, where additional validations are performed, (i.e., Schema and Manifest TCC) and a Receipt ID is generated.

Generally, the Receipt ID is returned to the Transmitter almost immediately after a successful transmission. For ISS-UI, the Receipt ID will be displayed via web browser upon successful transmission. For ISS-A2A, the Receipt ID will be part of the system-to-system response. The Receipt ID does not provide proof that the ACA Information Returns in the transmission were either accepted or rejected. The Receipt ID does provide proof that IRS received the file. The Transmitter must retrieve their Acknowledgement to obtain proof of acceptance or rejection. The Correction and Replacement process also utilize the Receipt ID in combination with the Submission and Record Identifiers as described later in Section 7.

For more information on how to compose submission and transmission files sent to IRS for processing using the AIR System, refer to Publication 5258, AIR Submission Composition and Reference Guide, located on the Affordable Care Act Information Returns (AIR) page.

4.1 | Transmitting via the User Interface (UI) Channel

Transmitters must have registered with ID.me to access the e-Services suite of online applications, must have an ACA Transmitter Control Code (TCC), and must be using IRS approved software to submit returns and retrieve acknowledgments. See Section 2 above for information on creating an e-Services account and applying for an ACA TCC. The Transmitter will be required to log in to the IEP using the links found on the Affordable Care Act Information Returns (AIR) Program page:

• AIR UI Channel Login AATS (Testing)

• AIR UI Channel Login Production

Guide for Electronically Filing ACA Information Returns for Software Developers and Transmitters 18

Transmitting Information Returns

The Transmitter is required to upload two uncompressed native XML files to the AIR System: A Manifest File, which includes all the Transmitter’s information and the Form Data File, which includes the Forms 1094/1095-B or Forms 1094/1095-C data.

IRS Portal will perform authentication and authorization, threat mitigation, and initial validation on the transmission. IRS Portal will return a fault response (an error prefixed with “TPE”), if a transmission contains a threat, or if a transmission fails initial validation. The list of “TPE” errors is shown in Table 4-4.

If threats are detected or XML Schema validation fails, IRS will reject the transmission and inform the Transmitter of the rejection. If no security threats are detected, AIR returns a Receipt ID, UTID and a Timestamp to the Transmitter in the web browser as part of the synchronous session.

The AIR System validates the Manifest and Form Data File and performs additional security checks and XML Schema validation on the inbound transmission. The Receipt ID and UTID are the key information required for a Transmitter to retrieve the acknowledgement for the respective transmission. See sample in Figure 4-1.

Note: The Receipt ID returned to the Transmitter should be kept with the transmission and protected from loss or deletion. If the Transmitter does not receive the Receipt ID for some reason (e.g., the session times out or is terminated) or it is accidentally lost or deleted, request the Acknowledgement File using the UTID before calling the AIR Help Desk, toll-free, at 1-866-937-4130, for domestic calls, or 470-769-5100 (not toll-free) for international calls to request the Receipt ID for the transmission. The AIR Help Desk assistor will require the user to identify themselves and the UTID for the transmission in question to provide the respective Receipt ID.

Figure 4-1: Sample of a Receipt ID via UI Channel

For more specific information on creating transmission files for the UI channel, refer to Publication 5258, AIR Submission Composition and Reference Guide, located on the Affordable Care Act Information Returns (AIR) page.

Guide for Electronically Filing ACA Information Returns for Software Developers and Transmitters 19

Transmitting Information Returns

4.2 | Transmitting via the Application to Application (A2A) Channel

To invoke the A2A channel, Transmitters must have an active IRS e-Services account and an ACA Transmitter Control Code (TCC). In addition, they must have completed the Automated Enrollment application and be using IRS approved Software to submit returns and retrieve acknowledgements in Production. See Section 2 for information about obtaining an account and applying for an ACA TCC.

The TCC in the UTID must be the same as the TCC in the UserId. The UserId must match the ASID in the A2A Client Application.

IRS uses SOAP with HyperText Transfer Protocol (HTTP) binding for the transmission file, which are SOAP messages transported over a HTTPS connection (HTTP over TLS – Transport Layer Security) protocol. A comprehensive understanding of Web Service SOAP messaging and Web Services Standards is necessary in order to create software capable of transmitting data to IRS.

The Transmitter will be required to include their digital certificate and a digitally signed hash of certain message structures in the WS-Security Header of the SOAP Message and invoke the appropriate URL for the Web Service endpoint that exposes the IRS-ACASubmitService within the ACAGetTransmitterBulkRequestService.wsdl. The Transmitter is required to transmit a SOAP Message in a SOAP Envelope that consists of the SOAP Header, and the SOAP Body. The SOAP Header includes the Transmitter information. The SOAP Body consists of Forms 1094/1095-B or Forms 1094/1095-C data in an uncompressed native XML file that is attached to the SOAP Message as an MTOM encoded attachment.

SOAP messages are exchanged with IRS using the Web Services request-response model transport mechanism using the HTTPS protocol. For specific information on creating A2A Messages, please refer to Publication 5258, AIR Submission Composition and Reference Guide is located on the Affordable Care Act Information Returns (AIR) page.

IRS Portal will perform authentication and authorization, threat mitigation, and initial validation on the transmission. IRS Portal will return a fault response (an error prefixed with “TPE”), if a transmission contains a threat, if a transmission fails initial validation, or if a connection with the endpoint cannot be established. The list of “TPE” errors is shown in Table 4-4.

The AIR System validates the SOAP message and performs additional security checks and Manifest Schema validation on the inbound transmission. If threats are detected or Manifest Schema validation fails, IRS will reject the transmission and inform the Transmitter of the rejection. If no security threats or Manifest schema validation failure are detected, AIR returns a Receipt ID, the UTID, and a Timestamp to the Transmitter in the SOAP Response message as part of the synchronous session. The Receipt ID or the UTID is the key information required for a Transmitter to retrieve the acknowledgement for the respective transmission.

Note: The Receipt ID returned to the Transmitter should be kept with the transmission and protected from loss or deletion.

If the Transmitter does not receive the Receipt ID for some reason (e.g., the session times out or is terminated) or it is accidentally lost or deleted, request the Acknowledgement File using the UTID before calling the AIR Help Desk, toll-free, at 1-866-937-4130, for domestic calls, or 470-769-5100 (not toll-free) for international calls to request the Receipt ID for the transmission. The AIR Help Desk assistor will require the user to identify themselves and the UTID for the transmission in question to provide the respective Receipt ID.

Guide for Electronically Filing ACA Information Returns for Software Developers and Transmitters 20

Transmitting Information Returns

Figure 4-2: Sample XML of Receipt ID through A2A Channel (footnote ¹ in screenshot above, see reference below)

For more specific information on creating transmission files for the A2A channel, refer to Publication 5258, AIR Submission Composition and Reference Guide, located on the Affordable Care Act Information Returns (AIR) page.

4.2.1 | Transmission File and Soap Message via A2A

The AIR transmission file is a MIME (Multipurpose Internet Mail Extensions) multipart document that contains two parts that conforms to “SOAP message with attachments” standard as given below:

• The first part of the multi-part document is the SOAP envelope that contains transmission level

information

• The second part of the document is a SOAP attachment that contains the ACA Information Return

Submissions

1 Author replaced ty21 with tyYY - Use of generic namespace text to minimize need for Current Tax Year updates and continued

document maintenance.

Guide for Electronically Filing ACA Information Returns for Software Developers and Transmitters 21

Transmitting Information Returns

SOAP is an XML based protocol used to encode the information in Web Service request and response messages before transmitting them over a network. A SOAP message is a simple XML document that consists of a SOAP Envelope with the following elements:

• A SOAP Header element that contains header information (ACA Header, WS-Addressing and Manifest)

• A SOAP Body element that contains request and response information and the reference to the MTOM

(Message Transmission Optimization Mechanism) attachment

• A SOAP Fault element containing errors and status information

The second part of the message, MIME (Multipurpose Internet Mail Extension), is the SOAP attachment which contains the ACA Information Return Submission(s) as an MTOM encoded attachment. See example below.

Figure 4-3: SOAP Message Structure

Guide for Electronically Filing ACA Information Returns for Software Developers and Transmitters 22

Transmitting Information Returns

4.2.2 | Strong Authentication

All external partner communication will need to support encryption using TLS 1.2 or 1.3 Federal Information Processing Standards (FIPS) Publication 140-2. Compliant cryptography will be used for strong and secure communication between Transmitters and IRS.

The A2A registration and enrollment process for Transmitters and their application system is an automated process. The authorized user can perform the following functions relative to their A2A Client System ID (ASID) for their organization:

• Enroll, Update, and Un-enroll ASID

• View a deleted ASID

• Inactivate, Activate ASID

• Replace the certificate for ASID

Publication 5308, The Automated Enrollment for ACA Providers External Guide describes the automated enrollment process and can be found on the Affordable Care Act Information Returns (AIR) page.

IRS requires strong authentication when transmitting via the A2A channel, which will affect authentication techniques for all A2A Web services. The strong authentication certificate/credential will replace the password and the ACA Information Returns Web Service Endpoint, Web Services Description Language (WSDL) will accommodate this credential. Each Transmitter will be required to register their certificate with AIR through the Automated Enrollment (AE) application. Software Developers must use the set of WSDL files provided by IRS to build their application so that they can use strong authentication. The WSDL files are not automatically sent upon download of the certificate/credential.

Note: A Responsible Official, or an official identified as a Contact on the ACA Application for TCC, should call AIR Help Desk - 1-866-937-4130 to request the WSDLs.

Publication 5258, AIR Submission Composition and Reference Guide, explains the integration and uses of this IRS- provided client code sample to support certificate-based authentication for AIR A2A Web services. In addition to the code itself, this guide provides necessary information for developers to use when integrating the new feature into client software that communicates with A2A Web services.

4.2.3 | Certificate Management

IRS requires the use of client digital (X.509) certificates issued by IRS-designated certificate authorities (see listing of approved Certificate Authorities (CA) in Section 4.2.4) to provide enhanced authentication of external partner application systems for A2A Web service processing. This capability is intended to mitigate threats defined in Treasury Department Publication 85-01, Department of the Treasury Information Technology (IT) Security Program, Vol. II, Handbook, Part 1, Section 5.4.4 Sensitive Systems.

To meet the requirements stated in the Treasury directive, the system will:

1. Provide verification of a digital signature of appropriate message parts produced using the private key for the X.509 certificate submitted with the authentication request and shall prevent (fail) authentication if this verification fails.

2. Verify that a submitted X.509 certificate is properly formatted and is verified by appropriate CA signature and shall prevent (fail) authentication if this verification fails.

3. Provide checks to ascertain that a submitted X.509 certificate has not been revoked, using most

Guide for Electronically Filing ACA Information Returns for Software Developers and Transmitters 23

Transmitting Information Returns

current Certificate Revocation List (CRL) resources from IRS-designated CAs, and shall prevent (fail) authentication if the certificate has been revoked. CRLs will be retrieved from each IRS-designated CA based on the schedule of available updates for that CA, so that the most up-to-date CRL will be made available for A2A authentication.

4. KeyInfo should use the KeyIdentifier tag which has the Base64 encoded certificate as its value. The Base64 encoded certificate should include the entire certificate chain including the root certificate and all the authorized CA certificates to pass the authentication process.

5. Provide checks to ensure that a submitted X.509 certificate has not expired and shall prevent (fail) authentication if the certificate has expired.

6. Ensure that a submitted X.509 certificate matches a certificate previously registered for the application system using data stored in IRS directory by an enrollment process and shall prevent (fail) authentication if the match cannot be made.

7. Mitigate replay attacks for authentication.

8. Provide error handling by which any external failing strong authentication for any reason will receive a SOAP fault response message stating that “Authentication Failed.”

9. Provide adequate capacity for A2A certificate-based authentication.

10. Ensure that authentication attempts and results are audited and incorporated into log files for audit and forensic purposes.

11. Accommodate external users that have one or more sites (and client certificates) associated with a single Public Key Infrastructure (PKI) sponsor.

12. Register valid certificates for each enrolled external application system using an automated enrollment process. The authentication credentials structure shall be changed for all A2A Web service requests to accommodate session-less requests.

A2A Transmitters must use digital certificates (X.509) versus passwords upon proper enrollment and registration of the certificate. The registered certificate’s Key Usage attribute should ONLY list BOTH of the values “digital signature” and “key encipherment.” Any additional values for this attribute will result in submission rejection due to the strict Key Usage Enforcement policy at the IRS portal. Encryption of the signing key is important on your system. Do not store an unencrypted copy of the signing key on your system. The signing key should be stored in a standard encrypted key store.

4.2.4 | Authorized Certificate Authorities

Digital certificates bind digital information to physical identities and provide non-repudiation and data integrity. Before you begin the Automated Enrollment (AE) process, each entity should obtain one valid digital certificate issued by an approved Certificate Authority (CA). Automated Enrollment (AE) only recognizes and accepts digital certificates issued by IRS approved certificate authorities, listed below.

Guide for Electronically Filing ACA Information Returns for Software Developers and Transmitters 24

Transmitting Information Returns

Table 4-1: List of Authorized Certificate Authorities

4.3 | XML Overview for AIR

IRS uses XML, a language that specifies the structure and content of electronic documents and files to define the electronic format of ACA Information Returns. This section explains some of the elements of an XML document. For detailed information regarding the IRS Submission File structure, including the XML Schema containing the required Tag Names/Element Names and Namespaces, refer to Publication 5258, AIR Submission Composition and Reference Guide .

4.3.1 | AIR XML Schema Package Structure

This section describes the AIR XML Schema file structure and how the schemas will be packaged as of the date this publication was issued.

Schemas for a given ACA Information Return are developed by the respective projects and submitted to the IRS Data Engineering (DE) Group. The DE Group integrates the project XML Schemas into a standard ACA XML Common Library. The ACA XML Common Library consists of several common XML Schema building blocks as follows:

• IRS-CAC.xsd – contains common aggregate components

• IRS-CBC.xsd – contains common basic components

• IRS-SDT.xsd – contains specialized data types

Guide for Electronically Filing ACA Information Returns for Software Developers and Transmitters 25

Transmitting Information Returns

The ACA XML Common Library is built following IRS Enterprise Standards, Naming, and Design Rules.

The common XML Schema building blocks are packaged into a COMMON folder within the XML Library structure as follows:

XML Library n.n

COMMON

The ACA XML Library for AIR includes the following folders:

EXT

IRS-EXT-ACA-AIR-1094BC.xsd

MSG

Various .xsd and .xml – contains the Message, Form Data File, Manifest File, and Error Data File

SRV

ACAGetTransmitterBulkRequestService - the WSDL for the transmission endpoint

ACAGetTransmitterBulkRequestStatus - the WSDL for the retrieve acknowledgements endpoint

In addition to the schema files, there are six business rule files, one for each Form 1094-B, Form 1095-B, Form 1094-C, Form 1095-C, one for the Shared rules, and one for the Manifest/Header.

The schema and business rule files can be found on the Affordable Care Act Information Returns (AIR) page.

4.3.2 | AIR XML Structure

When entering character data into an XML document, it is important to ensure that the specified encoding supports the characters provided. By design, AIR uses Unicode Transformation Format-8 (UTF-8), without Byte Order Mark (BOM). AIR does not support any other encoding scheme (for example, UTF-16 and UTF-32).

4.3.3 | Prohibited and Constrained Special Characters

Software Developers and Transmitters must not include certain special characters in any character data included in the XML of the SOAP message or the XML file attached to the SOAP message. The following special characters must not be included in any of the data fields for either Forms 1094/1095-B or Forms 1094/1095-C transmissions:

Table 4-2: Special Characters Not to Be Included in Any Data

Character Character Description

-- Double Dash