Developers

When clients sign up with iATS they are provided with a unique merchant account. With this account and once you set up the Web services you require, you will be able to process transactions directly from your donor database, website, or online fundraising solution (without having to negotiate with individual credit card companies and payment processing vendors).

Our Web services are standard SOAP messages that are supported by a server-side programming language. If your Web server is Microsoft Internet Information Server (MS IIS), you can use C# to write the server side code to use the Web service. If your server is PHP-based, you can write PHP code to use the Web service.

A SOAP message is an XML file that contains the following elements:

• An envelope element that identifies the XML document as a SOAP message
• A header element that contains header information
• A body element that contains call and response information
• A fault element containing errors and status information

For a full explanation of SOAP messages, please see https://www.w3schools.com/xml/xml_soap.asp.

A C# sample of an iATS consumer Web service is available for download here. In order to run the sample code, you will need Microsoft Visual Studio 2008 or later installed. The sample calls “GetCreditCardJournalCSVV1” method from our ReportLink.asmx Web service to get details (a journal) of a successful credit card transaction in csv type.

A PHP wrapper is available on our Github repository here. The base SOAP request and response structure for the specific services are explained below. To implement the services, you need to complete the code with your information and then integrate the code into your site or software platform. (Please note that all code will be hosted on your servers.) Once the calls are tested, you are good to go!

We have created a sample client code that allows you to test our payment systems. Please see, “Appendix A: Testing iATS Payments Systems” for details on how to use it.

For clients in the UK, you should also test the direct debit request, which requires additional parameters. That test is available below in Appendix B: Testing Direct Debit (UK Only).

Please note that iATS operates two server systems, one based in North America (NA) and one in the United Kingdom (UK). Clients in the United States and Canada will use the NA servers, while all other clients use our UK servers. The explanation of the specific services that follows will provide the links to each server address as available.

Guide to the ManagementLink Web Services

The guide that follows includes a complete overview of the requests available using our ManagementLink Web services. Each request overview includes the following:

• Explanation of the specific Web service.
• NA and UK server addresses for the Web service.
• Example of the SOAP request and response structure.
• Overview of the parameters included in the service. Please note:
  • String type parameters in red should have actual values.
  • Though some string type parameters are not required, it is best practice to include all the parameters in the same sequence when sending their request to iATS web service server. Leave the value blank if it is not required (Example: <customerIPAddress></customerIPAddress>).
  • Parameters with Boolean or DateTime as data types should always have the actual values and never leave these blank (Example: give 0 as default value of Boolean parameters if not required).
  • The XML element value will be “string” (e.g., letters or numerals) unless otherwise noted. (For more details on any of the elements, please see Appendix C: Definition of XML Element Abbreviations).
  • The tag name in the XML/SOAP message format is case sensitive. For example, agentCode will work, but agentcode will not.
  • Character limits for string values will be noted where applicable.
  • Characters values are all case sensitive and should be entered as shown in the call unless otherwise specified.
  • For setting the time, our servers are in the following time zones:
    • North America server: PST
    • UK server: GMT
  • For setting the date, both the North America and UK WebServices utilize standard xml Date Time type as the parameter. Please use the ISO 8601 format, e.g. 2008-10-31T15:07:38.6875000 ("yyyy-MM- dd'T'HH:mm:ss.fffffffZ") wherever the date should be included in your code.
  • iATS utilizes maintenance/update windows of 10:00 pm to 11:00 pm in both Pacific and GMT each day. While downtime, if any, is minimal we highly discourage sending batch processing transactions during this time.
  • Daily cut-off times are aligned with those of our processing banks and are as follows:
    • 2am PT / 5am ET for US Merchants
    • 11pm PT / 2am ET for Canadian Merchants
    • 12 Midnight GMT for all UK and International Merchants
  • Values requiring a True/False response should be entered as 1/0 within the code. Note that if left blank or NULL is used, we will default to True (1).
  • Where possible, it’s recommended to prevent the use of comma’s (,) within the dollar amount fields. iATS reads a comma as a period in this field to compensate for different countries use of the comma within currency. For example: $1,000 should be not allowed.
• Explanation of return values to expect in typical responses. Please note:
  • ACH transactions are not processed in real time. When an ACH transaction is submitted, iATS provides a general response of OK:555555, which indicates iATS has received the transaction attempt and that the request is pending approval.

Call to Create a Process Key

Create a Process Key on behalf of the Client

This service is for when you want to create a Process Key to use with mutual systems. A Process Key is a secure encrypted version of the “Client Code and Password” that is issued to the client on their iATS Welcome Letter.

• CreateSubCodeProcessKey

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

SOAP Request and Response Server Addresses

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

• North America
• UK/International

SOAP Request and Response Structure

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

Notes:

• This code corresponds to SOAP 1.2 shown at the NA server address above.
• The addresses above also contain the code for SOAP 1.1 if you require it.
  
  

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

Response

Response Example:

Overview of Request Parameters

Call to Obtain Merchant Account Data

Obtain Merchant Account Details for Mutual Clients

This service is for when you want to obtain certain merchant account data for our mutual clients. This data includes Process Key, DBA Name, Address, System Country (processing server), Currency, and Transaction Limit.

• GetSubCodeStatus

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

SOAP Request and Response Server Addresses

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

• North America
• UK/International

SOAP Request and Response Structure

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

Notes:

• This code corresponds to SOAP 1.2 shown at the NA server address above.
• The addresses above also contain the code for SOAP 1.1 if you require it.

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

Response

Example of Response:

Overview of Request Parameters