Section 5 Transmitting IRS ACA Form Data File and Retrieving Acknowledgment via the…

The ISS-A2A Channel allows transmitters to submit a Form Data File to IRS and retrieve the Acknowledgement for that transmission via a Services Oriented Architecture (SOA) interface. The Form Data File is transmitted in the SOAP Message as an MTOM attachment. The response to a request for Acknowledgement may or may not include an Error Data File. If an Error Data File is produced by AIR, it will be returned to the transmitter in the SOAP Response as an MTOM attachment. MTOM is the only method allowed by IRS for transmitters to attach files to a SOAP Message for ACA Information Returns. The purpose of this section is to describe the requirements for submitting an ACA Information Returns Form Data File to IRS using the ISS-A2A Channel.

5.1 | Message Compression

HTTP compression is used to maximize transfer efficiency and is a standard capability within the HTTP protocol. GZIP is a specific compression method defined under HTTP that is required of messages to IRS for ACA. A comprehensive explanation of the GZIP specification is provided by the Internet Engineering Task Force: https://tools.ietf.org/html/rfc1952 .

Depending on what tool the Transmitter is using to submit the message, packaged software like SoapUI allows users to simply enable HTTP transmission compression via a setting while custom solutions would require the appropriate code. GZIP compression is required for sending transmissions via ISS-A2A Channel.

5.2 | Basic SOAP Message Structure

A SOAP message is an XML structure consisting of SOAP Envelope, SOAP Header and SOAP Body which may contain payload data or an MTOM-encoded attachment. A SOAP message starts with an XML declaration . The following section explains various sections and aspects of a SOAP message and IRS A2A web service available to the transmitters. Please be advised that this document is not intended as a tutorial and therefore covers only important aspects of a SOAP message. Please refer to www.w3.org/TR/soap/ and other authoritative websites for more information. This section describes the logical structure of basic messages with a SOAP Header and SOAP Body blocks within a SOAP Message Envelope. A SOAP message contains one SOAP Header and one SOAP Body within one SOAP Envelope. The SOAP Header contains the Web Services (WS) Addressing (WS-Addressing), WS-Security, and ACA-related business header information. The SOAP Body contains the other ACA Business Information and ACA Information Returns as MTOM-encoded attachment.

Guide for ACA Information Returns Submission Composition and Reference Guide 40

Transmitting IRS ACA Form Data File and Retrieving Acknowledgment via the ISS-A2A Channel

An example of the SOAP Message Structure is shown below in Figure 5-1.

Figure 5-1: Basic SOAP Message Structure

5.2.1 | Creating the SOAP Envelope

The SOAP Envelope consist of a SOAP header and a SOAP body. The SOAP header contains information about the transmitter and the transmission and metadata about the payload in the SOAP body. The SOAP body is also referred to as the content file, Form Data File or simply payload. To create the SOAP envelope, the transmitter needs to know the following information:

• UTID (Business Correlation ID)

• TCC

• Form Data File

• The content type for the SOAP Envelop with MTOM encoded attachment must be “application/xop+xml” and the contenttransfer-encoding must be 8-bit. AttachmentByteSizeNum in Manifst should be same as size of the file.

• Right click on Form data file ➜ click on “Properties” ➜ copy the size in bytes (not “Size of disk”)

Injection Concerns

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

Transmitting IRS ACA Form Data File and Retrieving Acknowledgment via the ISS-A2A Channel

5.2.2 | SQL Injection in the SOAP Message

The special characters listed below are treated as SQL (Structured Query Language) injections. SQL injections exploit security vulnerabilities in an application’s software. SQL injections are mostly known as an attack vector for websites or A2A communication between two sources.

SQL Injections may allow attackers to spoof identity, tamper with existing data, cause repudiation issues such as voiding transactions or changing balances, allow the complete disclosure of all data on the system, or destroy the data. Characters that are not allowed due to concerns about SQL Injections are shown in this table. If needed, the escape characters shown in Table 5-1 can be used and are allowed, depending on the efile type.

Table 5-1: Characters not allowed due to SQL Injection Concerns

Note: Allowed escaped characters may be identified as a potential threat (Error Code TPE 1204) when they are used in conjunction with certain words such as “and” and “or”, as in “& or '”. If this occurs troubleshoot by removing the apostrophe.

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

Transmitting IRS ACA Form Data File and Retrieving Acknowledgment via the ISS-A2A Channel

5.3 | SOAP Header

IRS defines what should be in the SOAP header.

Basic steps to consume web service and create client:

• Get the certificate used for A2A message

• Generate and Compile the implementation class

• Deploy the WAR file. The tie classes (which are used to communicate with clients) are generated by the

Application Server during deployment

• Code the client class

  • Use ws import to generate and compile the stub files

  • Compile the client class

  • Run the client

  • WS-Security – Provides mechanisms for user identification and assertions in SOAP messages

  • ACA AIR Transmission Header Business Elements – Provides elements required for all SOAP messages

on the A2A channel

• •CA AIR Transmission Manifest – Provides manifest elements

5.3.1 | WS-Security

ACA A2A Web Services exposed via IRS Portal comply with Web Services Security (WSSecurity) specification version 1.0 for implementing end to end message security. It is an open standard published by OASIS that defines mechanisms for signing and encrypting SOAP messages and provides transport-neutral mechanisms to enforce integrity and confidentiality on messages and allows the communication of various security token formats.

WS-Security defines SOAP extensions to implement client authentication, message integrity and message confidentiality on the message level. Authentication helps identify the Sender (the transmitter). Message integrity ensures the recipient receives unaltered request. XML Signature specification ensures integrity of the message, which defines a methodology for cryptographically signing XML. Message confidentiality is to make the user sure that the data can’t be read during transit. The XML Encryption specification is the basis to encrypt the parts of SOAP message including headers, body blocks, and substructures, which may be encrypted.

To consume ACA A2A web services, the transmitter must use the X.509 authentication framework with the WS-Security specification. An X.509 certificate specifies a binding between a public key and a set of attributes that includes (at least) a subject name, issuer name, serial number, and validity interval. An X.509 certificate may be used to validate a public key that may be used to verify a SOAP message element or to identify the public key with SOAP message that has been digitally signed.

5.3.1.1 | Creating the XML Signature

The signatures are defined using a element and accompanying sub-elements as part of a security header. Note that the signature must be created after the content of the message is finalized. If changes are made to the message after the signature is created, it may result in a digest mismatch. Below is a quick overview of how to create an XML signature. Note that XML Digital Signature APIs and XML Digital Signature

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

Transmitting IRS ACA Form Data File and Retrieving Acknowledgment via the ISS-A2A Channel

libraries are also publicly available that may simplify development. An overview and tutorial can be found using the following url: https://docs.oracle.com/en/java/javase/24/

1. Determine which resources are to be signed.

2. Calculate the digest of each resource: Each referenced resource is specified through a element and its digest (calculated on the identified resource and not the element itself) is placed in a child element mentioned in the XML snippet below.

<ds:Reference URI=”#TS-E68EBBF1696C5DD4AA143353323390073”> ds:Transforms <ds:Transform Algorithm=”http://www.w3.org/2001/10/xml-exc-c14n#”> <InclusiveNamespaces PrefixList=”wsse wsa soapenv urn urn1 urn2 urn3” xmlns=”http://** **www.w3.org/2001/10/xml-exc-c14n#” /> <ds:DigestMethod Algorithm=”http://www.w3.org/2001/04/xmlenc#sha256” /

> ds:DigestValue?TimestampDigestValue? </ ds:Reference>

The element identifies the algorithm used to calculate the digest.

3. Collect the Reference elements: Collect the elements (with their associated digests) within a element as shown below. Note that InclusiveNamespaces cannot be a child element of the CanonicalizationMethod element.

ds:SignedInfo <ds:CanonicalizationMethod Algorithm=”http://www.w3.org/2001/10/xml-exc-c14n#WithComments” /> <ds:SignatureMethod Algorithm=”http://www.w3.org/2001/04/xmldsig-more#rsa-sha256” /> <ds:Reference URI=”#TS-E68EBBF1696C5DD4AA143353323390073”> ds:Transforms <ds:Transform Algorithm=”http://www.w3.org/2001/10/xml-exc- c14n#WithComments”> <InclusiveNamespaces PrefixList=”wsse wsa soapenv urn urn1 urn2 urn3”** **xmlns=”http://www.w3.org/2001/10/xml-exc-c14n#WithComments” /> </ds:Tr<a/ndssf:oTrrmasn>sform> <ds:DigestMethod Algorithm=”http://www.w3.org/2001/04/xmlenc#sha256” /

> ds:DigestValue?TimestampDigestValue? <ds:Reference URI=”#id-E68EBBF1696C5DD4AA143353323390577”> ds:Transforms <ds:Transform Algorithm=”http://www.w3.org/2001/10/xml-exc-c14n#”> <InclusiveNamespaces PrefixList=”wsa soapenv urn1 urn2 urn3”** **xmlns=”http://www.w3.org/2001/10/xml-exc-c14n#” /> <ds:DigestMethod Algorithm=”http://www.w3.org/2001/04/xmlenc#sha256” /> </ds:DigestVal:DigestValue>?ACATransmitterManifestReqDtlDigestValue? <ds:Reference URI=”#id-E68EBBF1696C5DD4AA143353323390578”>

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

Transmitting IRS ACA Form Data File and Retrieving Acknowledgment via the ISS-A2A Channel

ds:Transforms <ds:Transform Algorithm=”http://www.w3.org/2001/10/xml-exc-** **c14n#”> <InclusiveNamespaces PrefixList=”wsa soapenv urn urn1** **urn3”** **xmlns=”http://www.w3.org/2001/10/xml-exc-c14n#” /> </** **ds:Transform> <ds:DigestMethod Algorithm=”http://www.w3.org/2001/04/xmlenc#sha256” / ds:DigestValue>?ACABusinessHeaderDigestValue?

The element indicates the algorithm was used to canonize the element. Different data streams with the same XML information set may have different textual representations, e.g. differing as to whitespace. The element identifies the algorithm used to produce the signature value.

4. Signing: Calculate the digest of the element, sign that digest and put the signature value in a element.

ds:SignatureValueSignatureValue

5. Add key information: If keying information is to be included, place it in a element. Here the keying information contains the X.509 certificate for the transmitter, which would include the public key needed for signature verification.

<ds:KeyInfo Id=”KI-E68EBBF1696C5DD4AA143353323390475”> <wsse:SecurityTokenReference wsu:Id=”STR-E68EBBF1696C5DD4AA143353323390476”> <wsse:KeyIdentifier EncodingType=”http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soapmessage- secu-** **rity- 1.0#Base64Binary”** **ValueType=”http://docs.oasis-open.org/wss/2004/01/oasis-** **200401-wss-x509-token-profile-1.0#X509v3”>?CertificateValue?

6. Enclose in a Signature element

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

Transmitting IRS ACA Form Data File and Retrieving Acknowledgment via the ISS-A2A Channel

Place the , , and elements into a element. The element comprises the XML signature.

<ds:Signature Id=”SIG-E68EBBF1696C5DD4AA143353323390579”** **xmlns:ds=”http://www.w3.org/2000/09/xmldsig#”> ds:SignedInfo <ds:CanonicalizationMethod …/

> <ds:SignatureMethod …/> <ds:Reference …/> <ds:Reference …/> <ds:Reference …/> ds:SignatureValue?SignatureValue? <ds:KeyInfo Id=”KI-E68EBBF1696C5DD4AA143353323390475”…/>

5.3.1.2 | ACA SOAP Header Elements to be Digitally Signed

The Header Elements in the Request SOAP Message to be digitally signed:

• Message Type - ACAGetTransmitterBulkRequestService -ACABusinessHeader -ACATransmitterManifestReqDtl -Timestamp

• Message Type – ACAGetTransmitterBulkRequestStatus -CABusinessHeader -ACABulkRequestTransmitterStatusDetailRequest -Timestamp

5.3.1.3 | Message Timeout

WS-Security provides the header that can be used to record creation and expiration time of a request message. Note that the WS Timestamp must be used within 10 minutes of creation time based on GMT.

<wsu:Timestamp wsu:Id=”TS-E68EBBF1696C5DD4AA143353323390073”> wsu:Created2015-06-05T19:40:33.900Z wsu:Expires2015-06-05T19:50:33.900Z

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

Transmitting IRS ACA Form Data File and Retrieving Acknowledgment via the ISS-A2A Channel

5.3.1.4 | SOAP Header Examples showing Security Header and related elements

A sample of ACAGetTransmitterBulkRequestService:

NOTE: For processing year 2022, use xmlns:urn=”urn:us:gov:treasury:irs:ext:aca:air:ty21” as shown in the sample on the next page.

<soapenv:Envelope** **xmlns:soapenv=”http://schemas.xmlsoap.org/soap/envelope/”** **xmlns:urn=”urn:us:gov:treasury:irs:ext:aca:air:tyYY”** **xmlns:urn1=”urn:us:gov:treasury:irs:common”** **xmlns:urn2=”urn:us:gov:treasury:irs:msg:acabusinessheader”** **xmlns:urn3=”urn:us:gov:treasury:irs:msg:acasecurityheader”** **xmlns:urn4=”urn:us:gov:treasury:irs:msg:irsacabulkrequesttransmitter”** **xmlns:wsse=”http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd”** **xmlns:wsu=”http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd”> soapenv:Header wsse:Security <Signature Id=”SIG-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx” xmlns=”http://www.** **w3.org/2000/09/xmldsig#”> <CanonicalizationMethod Algorithm=”http://www.w3.org/2001/10/xml-exc-** **c14n#WithComments” /> <SignatureMethod Algorithm=”http://www.w3.org/2001/04/xmldsig-** **more#rsa-sha256” /> <Transform Algorithm=”http://www.w3.org/2001/10/xml-exc-** **c14n#”> <InclusiveNamespaces PrefixList=”wsse wsa oas1 soapenv urn urn1** **urn2 urn3 urn4” xmlns=”http://www.w3.org/2001/10/xml-exc-** **c14n#” /> <DigestMethod Algorithm=”http://www.w3.org/2001/04/** **xmlenc#sha256” /> xxxxxxxxxxxxxxxxxxxxxxxxxxxx <Transform Algorithm=”http://www.w3.org/2001/10/xml-exc-** **c14n#”> <InclusiveNamespaces PrefixList=”wsa oas1 soapenv urn urn1** **urn3 urn4” xmlns=”http://www.w3.org/2001/10/xml-exc-c14n#”** **/>

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

Transmitting IRS ACA Form Data File and Retrieving Acknowledgment via the ISS-A2A Channel

<DigestMethod Algorithm=”http://www.w3.org/2001/04/** **xmlenc#sha256” /> xxxxxxxxxxxxxxxxxxxxxxxxxxxx <Transform Algorithm=”http://www.w3.org/2001/10/xml-exc-** **c14n#”> <InclusiveNamespaces PrefixList=”wsa oas1 soapenv urn1 urn2** **urn3 urn4” xmlns=”http://www.w3.org/2001/10/xml-exc-c14n#”** **/> <DigestMethod Algorithm=”http://www.w3.org/2001/04/** **xmlenc#sha256” /> xxxxxxxxxxxxxxxxxxxxxxxxxxxx xxxxxxxxxx xxxxxxxxxx <wsu:Timestamp wsu:Id=”reference-URI-1”> wsu:Created2021-02-10T06:10:19.744Z wsu:Expires2021-02-12T06:10:19.744Z <urn:ACATransmitterManifestReqDtl wsu:Id=”reference-URI-2”> urn:PaymentYryyyy urn:PriorYearDataInd0 urn1:EINxxxxxxxxx urn:TransmissionTypeCdO urn:TestFileCdT urn:TransmitterNameGrp

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

Transmitting IRS ACA Form Data File and Retrieving Acknowledgment via the ISS-A2A Channel

urn:BusinessNameLine1Txtbusiness name1 urn:BusinessNameLine2Txtbusiness name2 urn:CompanyInformationGrp urn:CompanyNmcompany name urn:MailingAddressGrp urn:USAddressGrp urn:AddressLine1Txtaddress line1 urn:AddressLine2Txtaddress line2 urn1:CityNmcity name urn:USStateCdXX urn1:USZIPCd##### urn:ContactNameGrp urn:PersonFirstNmFirstname urn:PersonLastNmLastname urn:ContactPhoneNumxxxxxxxxxx urn:VendorInformationGrp urn:VendorCdX urn:ContactNameGrp urn:PersonFirstNmFirstname urn:PersonLastNmLastname urn:ContactPhoneNumxxxxxxxxxx urn:TotalPayeeRecordCnt# urn:TotalPayerRecordCnt# urn:SoftwareIdxxxxxxxxxx urn:FormTypeCd1094/1095C urn1:BinaryFormatCdapplication/xml urn1:ChecksumAugmentationNumxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx xxxxxxxxxxxxxxxxxxxx urn:AttachmentByteSizeNumxxxxx urn:DocumentSystemFileNmxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.xml</** **urn:DocumentSystemFileNm> <urn2:ACABusinessHeader wsu:Id=”reference-URI-3”> urn:UniqueTransmissionIdxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx:SYS12:BBttt::T</** **urn:UniqueTransmissionId> urn1:Timestamp2021-02-10T06:10:19Z

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

Transmitting IRS ACA Form Data File and Retrieving Acknowledgment via the ISS-A2A Channel

urn3:ACASecurityHeader urn1:UserId1BBtttxx

soapenv:Body <urn4:ACABulkRequestTransmitter version=”1.0”> urn1:BulkExchangeFile <inc:Include href=”cid:attachment-filename.xml” xmlns:inc=”http://www.w3.org/2004/08/** **xop/include” />

A sample of ACAGetTransmitterBulkRequestStatus (check status of a transmission):

< Accept-Encoding: gzip,deflate Content- Type: text/xml;charset=UTF-8 SOAPAction: “RequestSubmissionStatusDetail”

<soapenv:Envelope xmlns:oas1=”http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss- wssecurity-secext-** **1.0.xsd”** **xmlns:soapenv=”http://schemas.xmlsoap.org/soap/envelope/” xmlns:urn=”urn:us:gov:treasury:irs:msg:irst** **ransmitterstatusrequest”** **xmlns:urn1=”urn:us:gov:treasury:irs:ext:aca:air:tyYY” xmlns:urn2=”urn:us:gov:treasury:irs:common”** **xmlns:urn3=”urn:us:gov:treasury:irs:msg:acasecurityheader”> <soapenv:Header xmlns:wsa=”http://www.w3.org/2005/08/addressing”> <wsse:Security** **xmlns:wsse=”http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-** **1.0.xsd”** **xmlns:wsu=”http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-** **utility-1.0.xsd”> <ds:Signature Id=”SIG-82E7E6716E615C14D6144736030986660”** **xmlns:ds=”http://www.w3.org/2000/09/** **xmldsig#”> ds:SignedInfo <ds:CanonicalizationMethod Algorithm=”http://www.w3.org/TR/2001/REC-xml-c14n-** **20010315#WithComments” /> <ds:SignatureMethod Algorithm=”http://www.w3.org/2001/04/xmldsig- more#rsa-sha256” /

> <ds:Reference URI=”#TS-82E7E6716E615C14D6144736030985954”> ds:Transforms <ds:Transform Algorithm=”http://www.w3.org/2001/10/xml-exc-** **c14n#WithComments”> <InclusiveNamespaces PrefixList=”wsse wsa oas1 soapenv urn urn1 urn2 urn3”** **xmlns=”http://www.w3.org/2001/10/xml-exc-c14n#WithComments” /> <ds:DigestMethod Algorithm=”http://www.w3.org/2001/04/xmlenc#sha256” /> ds:DigestValueTimestamp

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

Transmitting IRS ACA Form Data File and Retrieving Acknowledgment via the ISS-A2A Channel

<ds:Reference URI=”#id-82E7E6716E615C14D6144736030986558”> ds:Transforms <ds:Transform Algorithm=”http://www.w3.org/2001/10/xml-exc-c14n#”> <InclusiveNamespaces PrefixList=”wsa oas1 soapenv urn1 urn2

xmlns=”http://www.w3.org/2001/10/xml-exc-c14n#” /> <ds:DigestMethod Algorithm=”http://www.w3.org/2001/04/xmlenc#sha256” /> ds:DigestValueACABusinessHeader <ds:Reference URI=”#id-82E7E6716E615C14D6144736030986559”> ds:Transforms <ds:Transform Algorithm=”http://www.w3.org/2001/10/xml-exc-c14n#”> <InclusiveNamespaces PrefixList=”oas1 soapenv urn1 urn2 urn3”** **xmlns=”http://www.w3.org/2001/10/xml-exc-c14n#” /> <ds:DigestMethod Algorithm=”http://www.w3.org/2001/04/xmlenc#sha256” /> ds:DigestValueACABulkRequestTransmitterStatusDetailRequest ds:SignatureValueSignatureValue <ds:KeyInfo Id=”KI-82E7E6716E615C14D6144736030986456”> <wsse:SecurityTokenReference wsu:Id=”STR-82E7E6716E615C14D6144736030986457”> <wsse:KeyIdentifier EncodingType=”http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-** **soap-message-security-1.0#Base64Binary”** **ValueType=”http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token- profile1.0#X5** **09v3”>CertificateValue <wsu:Timestamp wsu:Id=”TS-82E7E6716E615C14D6144736030985954”> wsu:Created2015-11-12T20:31:49.859Z wsu:Expires2015-11-12T23:01:49.859Z <urn:ACABusinessHeader wsu:Id=”id-82E7E6716E615C14D6144736030986558”** **xmlns:wsu=”http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd”> urn1:UniqueTransmissionIdUNITTEST-c023-4c48-a01a-000000000000:SYS12:XXXXX::T

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

Transmitting IRS ACA Form Data File and Retrieving Acknowledgment via the ISS-A2A Channel

urn2:Timestamp2015-11-12T15:31:49Z <urn3:ACASecurityHeader /> wsa:ActionRequestSubmissionStatusDetail soapenv:Body <urn:ACABulkRequestTransmitterStatusDetailRequest version=”1.0” wsu:Id=”id82E7E6716E615C14D6144736030986559” xmlns:wsu=”http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity- urn1:ACABulkReqTrnsmtStsReqGrpDtlutility-1.0.xsd”> urn2:ReceiptId1095C-15-00000787

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

Transmitting IRS ACA Form Data File and Retrieving Acknowledgment via the ISS-A2A Channel

5.3.1.5 | Digital Certificates

Digital certificates bind digital information to physical identities and provide non-repudiation and data integrity. Before you begin the enrollment process, each entity should obtain one valid digital certificate issued by an approved certificate authority (CA). Automated Enrollment only recognizes and accepts digital certificates issued by IRS approved certificate authorities, listed below. The ISS-A2A channel requires the full certificate chain including the root certificate and all CA certificates used for signing. Certificates' Key Usage attribute should list both of the values "digital signature" and "key encipherment," and no other values. A certificate can be associated with more than one TCC/ Role, and it can be used by any ACA service.

Table 5-2: IRS Authorized Certificate Issuing Authorities

5.3.2 | ACA Transmitter Business Header Elements

Table 5-3: Transmitter Business Header Elements

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

Transmitting IRS ACA Form Data File and Retrieving Acknowledgment via the ISS-A2A Channel

5.3.3 | ACA AIR Transmission Manifest

The Manifest provides information about the submission and must pass validation checks before submission can be accepted. It consist of details about the transmitter and about the file transmitted.

5.4 | SOAP Body

The SOAP Body contains the request message and the Form Data File as an MTOM attachment submitted by the transmitter application. When retrieving acknowledgments, the SOAP body contains the response message, and optionally the Error Data File as an MTOM attachment, which informs the transmitter of any errors in the submissions.

5.4.1 | Message Attachment File Format

Only one Form Data File will be accepted as an attachment sent by a transmitter and, in the event errors are found during processing, only one Error Data File will be returned as an attachment by IRS to the transmitter. The Form Data File and the Error Data File will be in XML format and will be attached to the message using the W3C MTOM specification.

The Form Data File must be encoded in UTF-8 without BOM file format prior to MTOM encoding during submission. Please refer to the fault messages below.

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

Transmitting IRS ACA Form Data File and Retrieving Acknowledgment via the ISS-A2A Channel

5.4.2 | Message Attachment Content Type

ISS-A2A AIR web services require transmitters to use SOAP-over-HTTP messaging with MTOM to send XML data files. The file that is encoded in the MTOM attachment must be uncompressed native XML. The content type for the MTOM encoded binary object identified in the Manifest header must be “text/xml”. If the contenttransfer-encoding of the Form Data File is 7-bit, “Pretty Print” formatting must be used.

5.5 | ISS-A2A Web Services Summary

Transmitters that take advantage of the A2A channel to submit their transmissions will have to program their systems to generate and transmit information returns via SOAP Messages (Request/Response). The transmitter will implement a Web Service Client on their host systems and will configure their SOAP Messages so that they are delivered to the Web Service endpoint exposed by IRS.

The SOAP Message is made up of a HTTP Header and a SOAP Envelope. The SOAP Envelope contains a SOAP Header and a SOAP Body. The XML elements in the SOAP Header facilitate transporting the information returns between the end points representing applications (Application to Application or A2A). The SOAP Header contains the URL for the Web Service endpoint exposed at IRS as well as security mechanisms for authenticating the transmitter.

The SOAP Body contains the XML elements that make up the Information Return transmission. ACA Information Return XML Schema will ensure that all required information pertaining to the transmitter and transmission is captured in corresponding XML elements. The normal processing for a transmission is as follows:

• Transmitter sends a transmission to IRS via SOAP Request message

• Transmitter receives a SOAP Response message which includes the Receipt ID assigned and the status (i.e. Pro- cessing or Rejected) to the transmission by IRS

• IRS processes the transmission

• Transmitter sends a request for Acknowledgment via SOAP Request message to IRS with the Receipt ID corre- sponding to the transmission for which they are requesting status

• Transmitter receives a SOAP Response message which provides the status of the transmission (i.e., Accepted, Accepted with Errors, Rejected, Processing, Not Found, and Partially Accepted) and any errors in the Error Data File attached to the SOAP Response message.

The exception path covers the following error processing:

• Manifest errors (errors relating to transmitter information and/or transmission details)

• Duplicate transmissions

• Business Rule errors

• System errors

Transmitters transmitting ACA Information Returns have two channels with which they can submit transmissions containing the information returns. IRS has directed that ACA Information Returns will be transmitted as XML documents.

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

Transmitting IRS ACA Form Data File and Retrieving Acknowledgment via the ISS-A2A Channel

Following services (service names) are available to the transmitters through ISS-A2A Channel:

• IRS-ACASubmitService (ACAGetTransmitterBulkRequestService.wsdl) - 1095BC_Transmission

• IRS-ACAAckngService (ACAGetTransmitterBulkRequestStatus.wsdl) - 1095BC_Status_Request

5.5.1 | Overview of Transmission and Submission

A transmission must consist of specific information pertaining to the transmitter and the transmission and at least one transmittal and the corresponding detail records. The transmittal information equates to the Form 1094 and the corresponding detail records equate to Form 1095.

Note that a transmission consists of the following:

• Transmitter, transmission, and transmission summary information

• All of the Form 1094/1095 forms and summary information

A submission consists of one Form 1094 and its associated Form 1095 forms and the submission summary information. A submission may also consist of one Form 1094-C and zero Form 1095-Cs, whenever the Form 1094-C is marked as a correction to an Authoritative Transmittal (for a previously accepted Form 1094-C). A transmission must contain at least one submission. A transmission can contain more than one submission. A transmission cannot comingle Forms 1094/1095-B and Forms 1094/1095-C.

In the example below, the text in brown/orange is required for A2A SOAP Transactions between two exposed Web Service endpoints and do not contain any information pertinent to the transmission. The text in blue are comments and have no effect on the processing of the transmission.

SOAP-ENV:Envelope SOAP-ENV:Header Example of 1094B and 1095B schema Example of 1094C and 1095C schema

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

Transmitting IRS ACA Form Data File and Retrieving Acknowledgment via the ISS-A2A Channel

</SOAP-ENV:Body

Figure 5-2: High Level Form schema structure

The information contained within the open element tag and the close element tag or and the closing element tag

are the “as-is” transmission submitted by the transmitter. This XML will be retained in the Information Return Repository as received from the transmitter without alteration, while ensuring appropriate access controls are in place to protect the integrity of the transmission.

The information required for the transmittal and transmission is contained within the element tags and for Form 1094-B and Form 1095-B. The tags and are for Form 1094-C and Form 1095-C.

Transmitter meta-data information goes in the Manifest File and Transmittal information is in the Form Data File.

This is the information that equates to the “T” Record documented in Publication 1220, Specifications for Electronic Filing of Forms 1097, 1098, 1099, 3921, 3922, 5498, and W-2G.

The information required for the detail information (1095X) associated with each transmittal (1094X) is contained within the variable number of element tags and . This is the information that equates to the “B” Record documented in Publication 1220.

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

Transmitting IRS ACA Form Data File and Retrieving Acknowledgment via the ISS-A2A Channel

5.5.2 | IRS-ACA Submit Transmission Request Message

The ACAGetTransmitterBulkRequestService operation allows the transmitter to send transmissions to the web service endpoint exposed at IRS. The service name within the WSDL file is 1095BC_Transmission. The binding for the exposed web service is as follows:

Figure 5-3: ACA Binding – ACAGetTransmitterBulkRequestService.wsdl

The SOAP Message Header in the SOAP Request message, ACATransmitterStatusReqBody, requires the following elements (see wsdl:input in Figure 5-3 above):

Table 5-4: Transmission SOAP Message Binding – SOAP Request Message Header

SOAP Binding – Input Header Element SOAP Binding – Header Element Description

ACASecurityHeader

For A2A transmissions the ASID associated with the certificate must be provided in the UserID element.

Requires Signature (Signed Info, Signature Value, WSSESecurity KeyInfo) and a Timestamp

Requires the Unique Transmission ID (UTID) and a ACABusinessHeader Timestamp

Requires the metadata (information) pertaining to the ACATransmitterManifestReqDtl transmitter and the transmission

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

Transmitting IRS ACA Form Data File and Retrieving Acknowledgment via the ISS-A2A Channel

The SOAP Message Body in the SOAP Request message requires the following elements:

Table 5-5: Transmission SOAP Message Binding – SOAP Request Message Body

SOAP Binding – Input Header Element SOAP Binding – Header Element Description

BulkRequestTransmitter

Requires the BulkExchangeFile is the base64Binary MTOM encoded attachment containing the Form Data File

The SOAP Message Header in the SOAP Response message includes the following elements:

Table 5-6: Transmission SOAP Message Binding – SOAP Response Message Header

SOAP Binding – Output Header Element SOAP Binding – Header Element Description

Includes the Unique Transmission ID (UTID) and a ACABusinessHeader Timestamp

ACASecurityHeader IRS Credentials for identification and authentication

Securing the message according to OASIS WSSESecurity Standards

The SOAP Message Body in the SOAP Response message includes the following elements:

Table 5-7: Transmission SOAP Message Binding – Soap Response Message Body

SOAP Binding – Output BodyElement SOAP Binding – Body Element Description

Includes “TransmissionStatusCd”, “ReceiptId”,“irs:Err ACATransmitterStatusRespBody orMessageDetail”

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

Transmitting IRS ACA Form Data File and Retrieving Acknowledgment via the ISS-A2A Channel

5.5.3 | IRS-ACA Retrieve Acknowledgement Request Message

The ACAGetTransmitterBulkRequestStatus operation allows the transmitter to send a request for processing status and detail for transmissions they previously sent to IRS. The service name within the WSDL file is 1095BC_Status_Request. The binding for the exposed web service is as follows:

Figure 5-4: ACA Binding – ACAGetTransmitterBulkRequestStatus.wsdl

The SOAP Message Header in the SOAP Request message requires the following elements (see wsdl:input in Figure 5-4 above):

Table 5-8: Status Request SOAP Message Binding – SOAP Request Message Header

SOAP Binding – InputHeader Element SOAP Binding – Header ElementDescription

For A2A transmissions the ASID associated with the ACASecurityHeader certificate must be provided in the UserID element.

Requires Signature (Signed Info, Signature Value, WSSESecurity KeyInfo) and a Timestamp

Requires the Unique Transmission ID (UTID) and a ACABusinessHeader Timestamp

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

Transmitting IRS ACA Form Data File and Retrieving Acknowledgment via the ISS-A2A Channel

The SOAP Message Body in the SOAP Request message requires the following elements:

Table 5-9: Status Request SOAP Message Binding – SOAP Request Message Body

SOAP Binding – InputBody Element SOAP Binding – Body ElementDescription

ACATransmitterStatusReqBody Includes Receipt ID

The SOAP Message Header in the SOAP Request message includes the following elements:

Table 5-10: Status SOAP Message Binding – SOAP Request Message Header

SOAP Binding – Output Header Element SOAP Binding – Header Element Description

For A2A transmissions the ASID associated with the ACASecurityHeader certificate must be provided in the UserID element.

Requires Signature (Signed Info, Signature Value, WSSESecurity KeyInfo) and a Timestamp

Requires the Unique Transmission ID (UTID) and a ACABusinessHeader Timestamp

The SOAP Message Body in the SOAP Response message includes an MTOM attachment containing the following elements for each error identified during processing:

Table 5-11: Transmission SOAP Message Binding – Soap Response Message Body

SOAP Binding – Output Body Element SOAP Binding – Body ElementDescription

BulkRequestTransmitterResponse

Includes the Unique Record Identifier, ErrorMessageCd, ErrorMessageTxt, and XpathContent

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

Transmitting IRS ACA Form Data File and Retrieving Acknowledgment via the ISS-A2A Channel

5.5.4 | A2A Channel TY2017, TY2018, TY2019, TY2020, TY2021, TY2022, TY2023, TY2024, TY2025 and TY2026 Schema/WSDL Guidance

Transmitters sending returns through A2A Channel (AATS and Production):

• AIR will accept Tax Years 2017, 2018, 2019, 2020, 2021, 2022, 2023, 2024, 2025, 2026 for Processing

Year 2027

• Transmitters should use the latest TY2026 schema version to generate Forms 1094/1095-B or

Forms 1094/1095-C Form Data (payload) for TY2026 returns

• For prior year returns 2017, 2018, 2019, 2020, 2021, 2022, 2023, 2024, 2025 use the latest year

schema for that tax year.

• Example: Transmitters should use the latest TY2019 schema version to generate Forms

1094/1095-B or Forms 1094/1095-C Form Data (payload) for TY2019 returns

• Transmitters should use TY2026 schema package and deploy at their end

• Transmitters should use TY2026 WSDL’s: ACAGetTransmitterBulkRequestService.wsdl to transmit

TY2017, TY2018, TY2019, TY2020, TY2021, TY2022, TY2023, TY2024, TY2025 and TY2026 transmissions ACAGetTransmitterBulkRequestStatus.wsdl to check the status of TY2017, TY2018, TY2019, TY2020, TY2021, TY2022, TY2023, TY2024, TY2025 and TY2026 transmissions

• TY2026 WSDL capable to generate SOAP envelope for TY2017, TY2018, TY2019, TY2020, TY2021,

TY2022, TY2023, TY2024, TY2025 and TY2026 transmissions

• SOAP envelope generated by TY2026 WSDL’s contained: ACA Header, WS-Security, ACA Business

header and Manifest information which are same for TY2017, TY2018, TY2019, TY2020, TY2021, TY2022, TY2023, TY2024, TY2025 and TY2026 transmission (namespaces are different in payload)

• Forms 1094/1095-B and Forms 1094/1095-C: Manifest element:

• Transmitter should use Manifest schema from current tax year (TY2026) schema package to generate

TY2017, TY2018, TY2019, TY2020, TY2021, TY2022, TY2023, TY2024,TY2025 and TY2026 Manifest file. Manifest will be validated against the 2026 schema.

• Example: 2015 Manifest will be checked and validated against TY2025

manifest schema and business rules

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

Transmitting IRS ACA Form Data File and Retrieving Acknowledgment via the ISS-A2A Channel