Developers

Request (This is for NA server, for UK server please use link above)

Response

Overview of Request Parameters

Here is an overview of the request parameters for the North American version of “GetACHEFTApprovedDateRangeCSV”.

Parameters in red are mandatory.

REPORTS FOR REJECTED BANK DEBIT TRANSACTIONS

Rejected Debit Transactions for a Specific Single Date

This section will explain how to use the Web service calls to request a report of rejected Bank Debit style transactions on a specific date, depending on your desired format. These types of transaction may be referred to as ACH/EFT, Direct Debit, and SEPA Debit depending on the currency.

Please note that rejected (processing issue) debit transactions are not the same as Returns (donor or bank initiated refund) debit transactions.

• GetACHEFTRejectSpecificDateCSV
• GetACHEFTRejectSpecificDateXML

These calls are available on either our NA or UK system.

SOAP Request and Response Server Addresses

Depending on which service you require, you can find the SOAP request and response structures at the following URLs:

• North America XML
• North America CSV
• UK/International XML
• UK/International CSV

SOAP Request and Response Structure

The code below shows the SOAP request and response structure for the North American version of “GetACHEFTRejectSpecificDateCSV”.

Notes:

• This code corresponds to SOAP 1.2 shown at the NA CSV server address above.
• The addresses above also contain the code for SOAP 1.1 if you require it.
• The request parameter placeholders shown (e.g., “string”, “dateTime,” etc.) need to be replaced with actual values.

Request (This is for NA server, for UK server please use link above)

Response

Overview of Request Parameters

Here is an overview of the request parameters for the North American version of “GetACHEFTRejectSpecificDateCSV”.

Parameters in red are mandatory.

Rejected Debit Transactions plus Details for a Date Range

This section will explain how to use the Web service calls to request a report of rejected Bank Debit style transactions over a date rage, including additional fields captured from the donor. These types of transaction may be referred to as ACH/EFT, Direct Debit, and SEPA Debit depending on the currency. This report is only available in .CSV format.

Please note that rejected (processing issue) debit transactions are not the same as Returns (donor or bank initiated refund) debit transactions.

• GetACHEFTRejectDateRangeCSV

This call is available on either our NA or UK system.

SOAP Request and Response Server Addresses

Depending on which service you require, you can find the SOAP request and response structures at the following URLs:

• North America CSV
• UK/International CSV

SOAP Request and Response Structure

The code below shows the SOAP request and response structure for the North American version of “GetACHEFTRejectDateRangeCSV”.

Notes:

• This code corresponds to SOAP 1.2 shown at the NA CSV server address above.
• The addresses above also contain the code for SOAP 1.1 if you require it.
• The request parameter placeholders shown (e.g., “string”, “dateTime,” etc.) need to be replaced with actual values.

Request (This is for NA server, for UK server please use link above)

Response

Here is an overview of the request parameters for the North American version of “GetACHEFTRejectDateRangeCSV”.

Parameters in red are mandatory.

REPORTS FOR RETURNED DEBIT TRANSACTIONS–NAACH & EURO SEPA ONLY

Returned Debit Transactions (NA ACH & Euro SEPA) for a Specific Single Date

This section will explain how to use the Web service calls to request a report of returned Bank Debit style transactions for a specific date, for North American ACH and Euro SEPA only. These types of transactions may be referred to as ACH/EFT and SEPA Debit depending on the currency.

Please note that Returns (donor or bank initiated refund) debit transactions are not the same as rejected (processing issue) debit transactions.

• GetACHEFTReturnSpecificDateCSV
• GetACHEFTReturnSpecificDateXML

This call is available on either our NA or UK system, but should not be used for UK Direct Debit BACS report returns.

SOAP Request and Response Server Addresses

Depending on which service you require, you can find the SOAP request and response structures at the following URLs:

• North America XML
• North America CSV
• UK/International XML
• UK/International CSV

SOAP Request and Response Structure

The code below shows the SOAP request and response structure for the North American version of “GetACHEFTReturnSpecificDateCSV”.

Notes:

• This code corresponds to SOAP 1.2 shown at the NA CSV server address, above.
• The addresses above also contain the code for SOAP 1.1 if you require it.
• The request parameter placeholders shown (e.g., “string”, “dateTime,” etc.) need to be replaced with actual values.

Request (This is for NA server, for UK server please use link above)

Response

Here is an overview of the request parameters for “GetACHEFTReturnSpecificDateCSV” above.

Parameters in red are mandatory.

Returned Debit Transactions (NA ACH & Euro SEPA) plus Details for a Date Range

This section will explain how to use the Web service calls to request a report of returned Bank Debit style transactions, plus donor details over a date range for North American ACH and Euro SEPA only. These types of transaction may be referred to as ACH/EFT and SEPA Debit depending on the currency. This report is only available in .CSV format.

Please note that Returns (donor or bank initiated refund) debit transactions are not the same as rejected (processing issue) debit transactions.

• GetACHEFTReturnDateRangeCSV

SOAP Request and Response Server Addresses

Depending on which service you require, you can find the SOAP request and response structures at the following URLs:

• North America CSV
• UK/International CSV

SOAP Request and Response Structure

The code below shows the SOAP request and response structure for the North American version of “GetACHEFTReturnDateRangeCSV”.

Notes:

• This code corresponds to SOAP 1.2 shown at the NA CSV server address, above.
• The addresses above also contain the code for SOAP 1.1 if you require it.
• The request parameter placeholders shown (e.g., “string”, “dateTime,” etc.) need to be replaced with actual values.

Request (This is for NA server, for UK server please use link above)

Response

Here is an overview of the request parameters for “GetACHEFTReturnDateRangeCSV” above.

Parameters in red are mandatory.

REPORTS FOR UK BACS REPORTS AND RETURNED UK DIRECT DEBIT – UK ONLY

Details on BACS Report Types (UK Direct Debit Use Only)

In Direct Debit, all communications with the banking system go through the Bacs clearing service. Submitting and receiving messages from Bacs is therefore essential to collecting payments by Direct Debit.

This section details how to download the ARUDD, AUDDIS, ADDACS, and the DDICA from our UK Direct Debit acquirer Smart Debit directly, enabling you to receive updates from BACS in the form of XML reports. Updates on the reports could include a notification about payment failures, Direct Debit indemnity claims, or changes made by the donor or their bank.

Each report is for a separate notification type, and contains a line for each event of that type. For examples of each response result, please see Section 3 of this document.

The different reports and their reason codes are described below:

• GetDirectDebitAUDDIS
• GetDirectDebitADDACS
• GetDirectDebitARUDD
• GetDirectDebitDDICA

AUDDIS/ADDACS

Notifications about the Direct Debit Instructions are received as AUDDIS (Automated Direct Debit Instruction Service) or ADDACS (Automated Direct Debit Amendment and Cancellation Service) messages.

1. AUDDISmessages

AUDDIS messages relate to the DDI setup process, and cancellations initiated by the merchant. If there have been any problems with the setup or cancellation you'll receive an AUDDIS message.

Generally, AUDDIS messages are generated by the donor’s bank, and are received three working days after a DDI is submitted. In some cases, however, Bacs will identify problems with your submission before passing it to the donor’s bank, and trigger an AUDDIS message immediately.

AUDDIS messages can be received for a number of reasons. These can be grouped into the below.

a. Errors in the bank account details you provided:

c. Direct Debit Instructions cannot be set up on the requested account:

d. Errors cancelling a DDI:

2. ADDACSmessages

ADDACS messages relate to amendments or cancellations of DDIs that are made by the donor. They are not avoidable, as all ADDACS reports are triggered by the donor, but some require you to take specific action.

An example ADDACS report is available here. For reference purposes only; please see our code samples below.

ADDACS messages can be grouped into those relating to cancellations, and those relating to amendments, as below.

a. The DDI has been cancelled:

b. The DDI has been amended:

ARUDD/DDIC:

Notifications about payment requests you've submitted are received as ARUDD (Automated Return of Unpaid Direct Debit) or DDICA (Direct Debit Indemnity Claim Advice) messages.

3. ARUDDmessages

For successful payment requests you won't receive any notification from Bacs at all. If, on the other hand, your payment fails, you'll receive an ARUDD message with a reason code describing the failure.

You can view an example ARUDD message here. For reference purposes only; please see our code samples below.

Many of the reasons for payment failure can be easily avoided. Below is a comprehensive list of all failure reasons, with details of how to avoid them.

a. Insufficient funds:

This type will generally be 90% of the ARUDD messages you receive.

b. Mandate no longer up-to-date: 

These failures are largely avoidable by regularly processing ADDACS reports. They can not be entirely eliminated, however due  to the time lag between payment submission and collection: 

The reasons for indemnity claims can be grouped into three distinct areas.

• Problems with a specific payment collection
• Payments collected after a mandate has been cancelled
• Payer disputes having set up a mandate

Request for UK Direct Debit BACS ARUDD Report

This section will explain how to use the Web service calls to request a report of the UK Direct Debit BACS ARUDD report for a specific date. For more information on this report and the other BACS report types, please see section 7.1 of this guide. This report is available in XML only.

• GetDirectDebitARUDD

This call is available on our UK system only.

SOAP Request and Response Server Addresses

Depending on which service you require, you can find the SOAP request and response structures at the following URL:

• UK/International XML

SOAP Request and Response Server Addresses

The code below shows the SOAP request and response structure for “GetDirectDebitARUDD”.

Notes:

• This code corresponds to SOAP 1.2 shown at the UK XML server address above.
• The addresses above also contain the code for SOAP 1.1 if you require it.
• The request parameter placeholders shown (e.g., “string”, “dateTime,” etc.) need to be replaced with actual values.

Request (This request is for UK server only)

Response:

Examples of the XML message can be found in the Testing section of this document, Section 9.

Overview of Request Parameters

Here is an overview of the request parameters for “GetDirectDebitARUDD” above.

Parameters in red are mandatory.

Request for UK Direct Debit BACS AUDDIS Report

This section will explain how to use the Web service calls to request a report of the UK Direct Debit BACS AUDDIS report for a specific date. For more information on this report and the other BACS report types, please see section 7.1 of this guide. This report is available in XML only.

• GetDirectDebitAUDDIS

This call is available on our UK system only.

SOAP Request and Response Server Addresses

Depending on which service you require, you can find the SOAP request and response structures at the following URL:

• UK/International XML

SOAP Request and Response Server Addresses

The code below shows the SOAP request and response structure for “GetDirectDebitAUDDIS”. Notes:

• This code corresponds to SOAP 1.2 shown at the UK XML server address above.
• The addresses above also contain the code for SOAP 1.1 if you require it.
• The request parameter placeholders shown (e.g., “string”, “dateTime,” etc.) need to be replaced with actual values.

Request (This request is for UK server only)

Response:

Examples of the XML message can be found in the Testing section of this document, Section 9.

Overview of Request Parameters

Here is an overview of the request parameters for “GetDirectDebitAUDDIS” above.

Parameters in red are mandatory.

Request for UK Direct Debit BACS ADDACS Report

This section will explain how to use the Web service calls to request a report of the UK Direct Debit BACS ADDACS report for a specific date. For more information on this report and the other BACS report types, please see section 7.1 of this guide. This report is available in XML only.

• GetDirectDebitADDACS

This call is available on our UK system only.

SOAP Request and Response Server Addresses

Depending on which service you require, you can find the SOAP request and response structures at the following URL:

• UK/International XML

SOAP Request and Response Server Addresses

The code below shows the SOAP request and response structure for “GetDirectDebitADDACS”. Notes:

• This code corresponds to SOAP 1.2 shown at the UK XML server address above.
• The addresses above also contain the code for SOAP 1.1 if you require it.
• The request parameter placeholders shown (e.g., “string”, “dateTime,” etc.) need to be replaced with actual values.

Request (This request is for UK server only)

Response:

Examples of the XML message can be found in the Testing section of this document, Section 9.

Overview of Request Parameters

Here is an overview of the request parameters for “GetDirectDebitADDACS” above.

Parameters in red are mandatory.

Request for UK Direct Debit BACS DDICA Report

This section will explain how to use the Web service calls to request a report of the UK Direct Debit BACS DDICA report for a specific date. For more information on this report and the other BACS report types, please see section 7.1 of this guide. This report is available in XML only.

• GetDirectDebitDDICA

This call is available on our UK system only.

SOAP Request and Response Server Addresses

Depending on which service you require, you can find the SOAP request and response structures at the following URL:

• UK/International XML

SOAP Request and Response Server Addresses

The code below shows the SOAP request and response structure for “GetDirectDebitDDICA”. Notes:

• This code corresponds to SOAP 1.2 shown at the UK XML server address above.
• The addresses above also contain the code for SOAP 1.1 if you require it.
• The request parameter placeholders shown (e.g., “string”, “dateTime,” etc.) need to be replaced with actual values.

Request (This request is for UK server only)

Response:

Examples of the XML message can be found in the Testing section of this document, Section 9.

Overview of Request Parameters

Here is an overview of the request parameters for “GetDirectDebitDDICA” above.

Parameters in red are mandatory.

REPORTS TO OBTAIN FINANCIAL PROCESSING DETAILS

Financial ACH and CC Reconciliation Details for a Date Range

This section will explain how to use the Web service calls to request a report of financial information including gross, net, and charged merchant fees, over a date rage depending on the method of payment. These reports are available in .CSV format only.

• GetCreditCardBankReconciliationReportCSV
• GetACHEFTBankReconciliationReportCSV

These calls are available on either our NA or UK system.

SOAP Request and Response Server Addresses

Depending on which service you require, you can find the SOAP request and response structures at the following URLs:

• North America ACH CSV
• North America CC CSV
  
• UK/International DD/SEPA CSV
• UK/International CC CSV

SOAP Request and Response Structure

The code below shows the SOAP request and response structure for the North American CC version of “GetCreditCardBankReconciliationReportCSV”.

Notes:

• This code corresponds to SOAP 1.2 shown at the NA CC server address above.
• The addresses above also contain the code for SOAP 1.1 if you require it.
• The request parameter placeholders shown (e.g., “string”, “dateTime,” etc.) need to be replaced with actual values.

Request (This is for NA server, for UK server please use link above)

Response

Overview of Request Parameters

Here is an overview of the request parameters for the North American version of “GetCreditCardBankReconciliationReportCSV”.

Parameters in red are mandatory.

APPENDIX A: TESTING REPORTING SYSTEMS (NA and UK)

The following information will allow you to test iATS Payments systems to ensure that you can use our services.

Please note that these accounts are not live merchant accounts and that authorization and rejection results are for display purposes only.

Also, as this test information is provided to many clients, please do not change the user ID or password.

“TEST88” Account Details for NA ACH & CC, and UK CC:

• User ID:       TEST88
• Password:    TEST88
• URL:
  • NA: www.iatspayments.com
  • UK: www.uk.iatspayments.com

Please note there is a transaction limit of $2000.00 (£2000.00) per charge. Amounts above will be rejected.

To test the ReportLink functions, credit card data can be pulled via the TEST88 merchant account for North American ACH &CC data, and UK Credit Card Data.
There are numerous transactions and rejections on most days to retrieve in general, or you can first use the ProcessLink or AuraLink functions to process test credit card transactions, then pull them via ReportLink.

UDDD88 can be used to retrieve UK Direct Debit data.

“UDDD88” Account Details for UK Direct Debit only:

• User ID: UDDD88
• Password: DDTEST16
• URL:
  • UK: www.uk.iatspayments.com

ADDACS:

ref: UDDDA21835, name: Paul Distaff, effective date: 27/05/2015

Response:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">

   <soap:Body>
      <GetDirectDebitADDACSV1Response xmlns="https://www.iatspayments.com/NetGate/">

         <GetDirectDebitADDACSV1Result>
            <IATSRESPONSE xmlns="">

               <STATUS>Success</STATUS>
               <ERRORS/>
               <SMARTDEBITREPORT>

                     <MessagingAdvice reference="UDDDA21835" effective-date="2015-05-27"
reason-code="1" aosn="4261" payer-name="Paul Distaff " payer-account-number="****5678"
payer-sort-code="******" payer-reference="UDDDA21835"/>

                  </ADDACS>
               </SMARTDEBITREPORT>

            </IATSRESPONSE>
         </GetDirectDebitADDACSV1Result>

      </GetDirectDebitADDACSV1Response>
   </soap:Body>
</soap:Envelope>

ARUDD:

ref:UDDDA21678, name:Phil B, effective date: 27/05/2015

Response:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">

   <soap:Body>
      <GetDirectDebitARUDDV1Response xmlns="https://www.iatspayments.com/NetGate/">

         <GetDirectDebitARUDDV1Result>
            <IATSRESPONSE xmlns="">

<STATUS>Success</STATUS>
<ERRORS/>

                     <ReturnedDebitItem ref="david001" transCode="17" returnCode="1"
returnDescription="INSTRUCTION CANCELLED" originalProcessingDate="2015-02-22"

valueOf="5.00" currency="GBP">
                        <PayerAccount ref="david001" bankName="BARCLAYS BANK PLC"

number="4714" branchName="BEDFORD" name="DAVID" sortCode="******"/>
                     </ReturnedDebitItem>

                  </ARUDD>
               </SMARTDEBITREPORT>

            </IATSRESPONSE>
         </GetDirectDebitARUDDV1Result>

      </GetDirectDebitARUDDV1Response>
   </soap:Body>
</soap:Envelope>

AUDDIS:

ref:UDDDA21689, name Phil B, effective date: 27/05/2015

Response:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">

   <soap:Body>
      <GetDirectDebitAUDDISV1Response xmlns="https://www.iatspayments.com/NetGate/">

         <GetDirectDebitAUDDISV1Result>
            <IATSRESPONSE xmlns="">

<SMARTDEBITREPORT>
   <ARUDD>

<STATUS>Success</STATUS>
<ERRORS/>
<SMARTDEBITREPORT>

                     <MessagingAdvice reference="UDDDA21689" effective-date="2015-05-27"
reason-code="1" aosn="5324" payer-name="Phil B " payer-account-number="****5678" payer-
sort-code="******" payer-reference="UDDDA21689"/>

                  </AUDDIS>
               </SMARTDEBITREPORT>

            </IATSRESPONSE>
         </GetDirectDebitAUDDISV1Result>

      </GetDirectDebitAUDDISV1Response>
   </soap:Body>
</soap:Envelope>

DDICA:

ref: UDDDA21648, payer name: Phil B, effective date: 26/05/2015

Response:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">

   <soap:Body>
      <GetDirectDebitDDICAV1Response xmlns="https://www.iatspayments.com/NetGate/">

         <GetDirectDebitDDICAV1Result>
            <IATSRESPONSE xmlns="">

<STATUS>Success</STATUS>
<ERRORS/>
<SMARTDEBITREPORT>

   <DDICA>
      <DDICAdvice>

         <SeqNo>2014111103A938843265</SeqNo>
         <PayingBankReference>DDIC2011956057101</PayingBankReference>
         <SUNumber>100122</SUNumber>
         <PayingBankName>HSBC BANK PLC</PayingBankName>
         <SUReference>UDDDA21648</SUReference>

                           <DDCollection>
                              <DateOfDirectDebit>2015-05-15</DateOfDirectDebit>
                              <Amount>1.0</Amount>

                           </DDCollection>
                        </DDCollections>

                     </DDICAdvice>
                  </DDICA>

               </SMARTDEBITREPORT>
            </IATSRESPONSE>

         </GetDirectDebitDDICAV1Result>
      </GetDirectDebitDDICAV1Response>

   </soap:Body>
</soap:Envelope>

<ReasonCode>2</ReasonCode>
<PayerSortCode>******</PayerSortCode>
<PayerAccount>****5678</PayerAccount>
<PayerName>Phil B</PayerName>
<NoOfAdvForClaim>1</NoOfAdvForClaim>
<TotalAmount>1.0</TotalAmount>
<DDCollections>

APPENDIX B: DEFINITION OF XML ELEMENT ABBREVIATIONS

The elements in the below table may or may not apply directly to the ReportLink WebServices. All possible element options which are currently available within the different CustomerLink, ProcessLink, AuraLink, and ReportLink API calls are listed below.

For more information or if you have any questions, please reach out to iATS at webservice@iatspayments.com.