Developers

This guide provides an explanation of iATS AURALink Web services, how they work, and how to set them up.

Our AURALink Web Services are meant to serve as a supplement to Aura, our easy to use online setup wizard that lets you quickly create and integrate secure donation forms on your website.

Because they are directly connected with your iATS payment account, AURA forms give you the ability to process both single and recurring transactions using either credit cards or direct debit right from your website without having to send donors away to a third-party payment processor. (More details on AURA—including video walk-throughs of the AURA wizard—are available at iatspayments.com.)

Our AURALink Web services complement AURA by giving you advanced customization control of the code beyond the features available from the AURA form set-up wizard, while still being able to utilize the Post Back URL to get transaction results and captured fields back to your database or to our Salesforce Application Brickwork.

How to use AURALink Web services:

First, to use AURALInk Web services we’ll need to set you up with an iATS merchant account. (Getting started with opening an account is as easy as calling us at 1-866-300-4287 or sending a request to iats@iatspayments.com). Alternatively you can use our testing credentials to mimic live processing results. Please see the Testing section of this document.

The next step is to create an AURA ID. This is necessary because AURALink Web service requests need to include an AURA ID as one of the request parameters and is key to using AuraLink with our Salesforce Application Brickwork. That ID is generated by creating an AURA Event using the AURA wizard:

1.	Log in to our site at iatspayments.com (NA) or www.uk.iatspayments.com (UK or International).
2.	Click “AURA SETUP” from the top navigation.
3.	Complete the form per your requirements, and click Save. If this form is being used with our Salesforce Application Brickwork, the Salesforce Site ID needs to be pasted into the “Post Back URL” field. Otherwise, add your own URL to post transaction data to your own CRM system.
4.	In the code generated in the “Script” box, the ID will be the alphanumeric string following “PID”.

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 http://www.w3schools.com/webservices/ws_soap_syntax.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 example is available for download by clicking 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 AURA and our payment systems. Please see, Appendix A: Testing AURA for details on how to use it.

For technical assistance, please email webservice@iatspayments.com.

Guide to the AURALink Web Services

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

Explanation of the specific Web service.
NA and/or 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 B: 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 cutoff 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:
- Unlike credit card processing, 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.

GUIDE TO AURALink WEB SERVICES

Processing Credit Cards

This section will explain how to use the Web service “ProcessCreditCardV1” to process credit cards through AURA.

SOAP Request and Response Server Addresses

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

SOAP Request and Response Structure

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

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.
The request parameter placeholders shown (e.g., “string”, “Boolean,” etc.) need to be replaced with actual values.

Request (This is for the NA server, if you require the UK server please use the link above)

POST /NetGate/AURALink.asmx HTTP/1.1

Host: www.iatspayments.com

Content-Type: application/soap+xml; charset=utf-8

Content-Length: length

<?xml version="1.0" encoding="utf-8"?>

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

<soap12:Body>

<customerIPAddress>string</customerIPAddress>

<firstName>string</firstName>

<lastName>string</lastName>

<address>string</address>

<city>string</city>

<state>string</state>

<zipCode>string</zipCode>

<country>string</country>

<phone>string</phone>

<phone2>string</phone2>

<fax>string</fax>

<email>string</email>

<comment>string</comment>

<item1>string</item1>

<item2>string</item2>

<item3>string</item3>

<item4>string</item4>

<item5>string</item5>

<item6>string</item6>

<mop>string</mop>

<creditCardNum>string</creditCardNum>

<creditCardExpiry>string</creditCardExpiry>

<cvv2>string</cvv2>

<amount0Name>string</amount0Name>

<amount0Value>string</amount0Value>

<amount0Quantity>string</amount0Quantity>

<amount1Name>string</amount1Name>

<amount1Value>string</amount1Value>

<amount1Quantity>string</amount1Quantity>

<amount2Name>string</amount2Name>

<amount2Value>string</amount2Value>

<amount2Quantity>string</amount2Quantity>

<amount3Name>string</amount3Name>

<amount3Value>string</amount3Value>

<amount3Quantity>string</amount3Quantity>

<amount4Name>string</amount4Name>

<amount4Value>string</amount4Value>

<amount4Quantity>string</amount4Quantity>

<amount5Name>string</amount5Name>

<amount5Value>string</amount5Value>

<amount5Quantity>string</amount5Quantity>

<amount6Name>string</amount6Name>

<amount6Value>string</amount6Value>

<amount6Quantity>string</amount6Quantity>

<amount7Name>string</amount7Name>

<amount7Value>string</amount7Value>

<amount7Quantity>string</amount7Quantity>

<amountOtherName>string</amountOtherName>

<amountOtherValue>string</amountOtherValue>

<amountOtherQuantity>string</amountOtherQuantity>

<total>string</total>

<auraID>string</auraID>

<emailCheck>Boolean</emailCheck>

</ProcessCreditCardV1>

</soap12:Body>

</soap12:Envelope>

Response

HTTP/1.1 200 OK

Content-Type: application/soap+xml; charset=utf-8

Content-Length: length

<?xml version="1.0" encoding="utf-8"?>

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

<soap12:Body>

</ProcessCreditCardV1Response>

</soap12:Body>

</soap12:Envelope>

Overview of Request Parameters

Here is an overview of the request parameters for the “ProcessCreditCardV1,” above. Parameters in red are mandatory.

Parameter	Notes/Options	Char. Limit
customerIPAddress	This is the IP address of the donor’s computer. Please send to fully utilise the Fraud tools available from iATS. IPv4 only.	N/A
firstName	Optional but highly recommended.	30
lastName	Optional but highly recommended.	30
address	Optional but highly recommended.	100
city	Optional but highly recommended.	30
state	Optional but highly recommended. State or province (North America only)	40
zipCode	Optional but highly recommended.	20
country	Optional but highly recommended.	40
Phone		40
Phone2		40
Fax		40
email	Optional but highly recommended.	40
comment		110
item1		39
item2		39
item3		39
item4		39
item5		39
item6		39
mop	Optional but highly recommended for proper processing. NA: VISA, MC, AMX, DSC UK: VISA, MC, AMX, MAESTR	N/A
creditCardNum	Credit Card Number	30 digits
creditCardExpiry	“MM/YY”	5
cvv2	Optional but highly recommended for all online transactions. If passed, iATS will validate.	40 digits
amount0Name		149
amount0Value	Prevent the use of commas (,) within the dollar amount fields if possible. 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.	N/A
amount0Quantity		N/A
amount1Name		149
amount1Value		N/A
amount1Quantity		N/A
…		N/A
amount7Name		149
amount7Value		N/A
amount7Quantity		N/A
amountOtherName		149
amountOtherValue		N/A
amountOtherQuantity		N/A
total		N/A
auraID	auraID is named as PID in the EVENT INFO tab of AURA SETUP page	80
emailCheck	Boolean: true (1)/false (0)	N/A

Sample Reply Message Format

The response message format will be as follows:

<STATUS>StatusType</STATUS>

<ERRORS>ErrorCodeType</ERRORS>

<AUTHORIZATIONRESULT>AuthorizationResultType </AUTHORIZATIONRESULT>

<TRANSACTIONID>TransactionId</TRANSACTIONID>

</PROCESSRESULT>

</IATSRESPONSE >

The table below describes what can be expected for each of the return values:

Explanation of Sample Reply Message Values
Return Value	Occurrence	Explanation
STATUS	Always	The system-level acknowledgement code that indicates the iATS system status: · Success - iATS system processing succeeded · Failure - An error has occurred on the iATS system side, such as a database or server down.
ERRORS	Conditional	Return information when Status = Failure. Return value will depend on the error
AUTHORIZATIONRESULT	Conditional	Return information when Status = Success. This value represents the application-level result that iATS processed the request: · OK - Request has been approved · Error - Request not approved, an error has occurred—possibly due to problems in delivery, attempt by end-user to submit invalid or missing data, etc. iATS does not currently have a list of possible error messages as they can be sent due to different types of processing and from different components, etc. Reject 3: Customer Code does not exist Or Account num is too long Reject 40: Invalid card number
TRANSACTIONID	Conditional	Return information when Status = Success and AUTHORIZATIONRESULT = OK; value is transactionID.

Processing ACHEFT Transactions (Not for UK Direct Debit or Euro SEPA Use)

This section will explain how to use the Web service “ProcessACHEFTV1” to process single one-time ACHEFT transactions through AURA.

Note that this service is for NA and certain International customers only; for UK customers wanting to process recurring transaction using ACHEFT, please use “DirectDebitCreateACHEFTRecurringV1,” which is described in Section 1.5 Creating a Recurring ACHEFT Transaction for UK Clients.

SOAP Request and Response Server Addresses

The SOAP request and response structures for “ProcessACHEFTV1” is available at the following URLs:

SOAP Request and Response Structure

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

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.
The request parameter placeholders shown (e.g., “string”, “Boolean,” etc.) need to be replaced with actual values.

Request

POST /NetGate/AURALink.asmx HTTP/1.1

Host: www.iatspayments.com

Content-Type: application/soap+xml; charset=utf-8

Content-Length: length

<?xml version="1.0" encoding="utf-8"?>

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

<soap12:Body>

<customerIPAddress>string</customerIPAddress>

<firstName>string</firstName>

<lastName>string</lastName>

<address>string</address>

<city>string</city>

<state>string</state>

<zipCode>string</zipCode>

<country>string</country>

<phone>string</phone>

<phone2>string</phone2>

<fax>string</fax>

<email>string</email>

<comment>string</comment>

<item1>string</item1>

<item2>string</item2>

<item3>string</item3>

<item4>string</item4>

<item5>string</item5>

<item6>string</item6>

<accountNum>string</accountNum>

<accountType>string</accountType>

<ACHEFTAgreement>Boolean</ACHEFTAgreement>

<amount0Name>string</amount0Name>

<amount0Value>string</amount0Value>

<amount0Quantity>string</amount0Quantity>

<amount1Name>string</amount1Name>

<amount1Value>string</amount1Value>

<amount1Quantity>string</amount1Quantity>

<amount2Name>string</amount2Name>

<amount2Value>string</amount2Value>

<amount2Quantity>string</amount2Quantity>

<amount3Name>string</amount3Name>

<amount3Value>string</amount3Value>

<amount3Quantity>string</amount3Quantity>

<amount4Name>string</amount4Name>

<amount4Value>string</amount4Value>

<amount4Quantity>string</amount4Quantity>

<amount5Name>string</amount5Name>

<amount5Value>string</amount5Value>

<amount5Quantity>string</amount5Quantity>

<amount6Name>string</amount6Name>

<amount6Value>string</amount6Value>

<amount6Quantity>string</amount6Quantity>

<amount7Name>string</amount7Name>

<amount7Value>string</amount7Value>

<amount7Quantity>string</amount7Quantity>

<amountOtherName>string</amountOtherName>

<amountOtherValue>string</amountOtherValue>

<amountOtherQuantity>string</amountOtherQuantity>

<total>string</total>

<auraID>string</auraID>

<emailCheck>Boolean</emailCheck>

</ProcessACHEFTV1>

</soap12:Body>

</soap12:Envelope>

Response

HTTP/1.1 200 OK

Content-Type: application/soap+xml; charset=utf-8

Content-Length: length

<?xml version="1.0" encoding="utf-8"?>

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

<soap12:Body>

</ProcessACHEFTV1Response>

</soap12:Body>

</soap12:Envelope>

Overview of Request Parameters

Here is an overview of the request parameters for the “ProcessACHEFTV1,” above. Parameters in red are mandatory.

Parameter	Notes/Options	Char. Limit
customerIPAddress	This is the IP address of the donor’s computer. Please send to fully utilise the Fraud tools available from iATS. IPv4 only.	N/A
firstName	Optional but highly recommended.	30
lastName	Optional but highly recommended.	30
address	Optional but highly recommended.	100
city	Optional but highly recommended.	30
state	Optional but highly recommended. State or province (North America only)	40
zipCode	Optional but highly recommended.	20
country	Optional but highly recommended.	40
phone		40
phone2		40
fax		40
email	Optional but highly recommended.	40
comment		110
item1		39
item2		39
item3		39
item4		39
item5		39
item6		39
accountNum	· USD: Routing no. (9 digits) + account no. (# of digits varies) · CAD: Bank no. (3 digits) + transit no. (5 digits) + account no. (# of digits varies) · AUD: BIC (Bank ID) + IBAN (Account) Order must be followed with NO spaces	30
accountType	Optional but highly recommended for recurring processing to function. Options: CHECKING, SAVING (*Applies to North America only)	N/A
ACHEFTAgreement	Boolean: true (1)/false (0)	N/A
amount0Name		149
amount0Value	Prevent the use of commas (,) within the dollar amount fields if possible. 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.	N/A
amount0Quantity		N/A
amount1Name		149
amount1Value		N/A
amount1Quantity		N/A
…
amount7Name		149
amount7Value		N/A
amount7Quantity		N/A
amountOtherName		149
amountOtherValue		N/A
amountOtherQuantity		N/A
total		N/A
auraID	auraID is named as PID in the EVENT INFO tab of AURA SETUP page	80
emailCheck	Boolean: true (1)/false (0)	N/A

Sample Reply Message Format

The response message format will be as follows:

<STATUS>StatusType</STATUS>

<ERRORS>ErrorCodeType</ERRORS>

<AUTHORIZATIONRESULT>AuthorizationResultType </AUTHORIZATIONRESULT>

<TRANSACTIONID>TransactionId</TRANSACTIONID>

</PROCESSRESULT>

</IATSRESPONSE >

The table below describes what can be expected for each of the return values:

Explanation of Sample Reply Message Values
Return Value	Occurrence	Explanation
STATUS	Always	The system-level acknowledgement code that indicates the iATS system status: · Success - iATS system processing succeeded · Failure - An error has occurred on the iATS system side, such as a database or server down.
ERRORS	Conditional	Return information when Status = Failure. Return value will depend on the error
AUTHORIZATIONRESULT	Conditional	Return information when Status = Success. This value represents the application-level result that iATS processed the request: · OK - Request has been approved · Error - Request not approved, an error has occurred—possibly due to problems in delivery, attempt by end-user to submit invalid or missing data, etc. iATS does not currently have a list of possible error messages as they can be sent due to different types of processing and from different components, etc. Reject 3: Customer Code does not exist Or Account num is too long Reject 40: Invalid card number
TRANSACTIONID	Conditional	Return information when Status = Success and AUTHORIZATIONRESULT = OK; value is transactionID.

Explanation of ACH Processing Stages

As ACH/EFT Transaction processing is not processed in “Real Time” like credit card transactions, there can be processing delays while the data is moving between iATS, our Bank and the donors Bank.

When ACH/EFT transactions are submitted to iATS, we will submit them to our processing bank as per the following schedule:

- Monday and Tuesday: File sent twice per day (3am and 3pm)

- Wednesday to Friday: File sent once per day (3pm)

When ACH/EFT transactions are sent to iATS for processing, there are three stages which each transaction will go through, even though you receive a successful ACH Transaction ID immediately:

1.	Immediately following the submission, each transaction will be listed as “Tobesent” within iATS systems. This stage indicates the transaction is waiting to be sent to iATS’ bank as per above schedule.
2.	Once the transactions have been sent to the bank, but before final approval/rejection has been received, each transaction will be listed as “Pending”. A response should be received within 1 business day.
3.	Once a response has been received, each transaction will be listed as EITHER OK:BankAccept, or OK:Reject. These results can be pulled using our WebService ReportLink options if desired (Journal for approvals, ACH Reject for rejections).

All transactions with the result “OK:Bank Accept” will be sent to the Donor’s bank for final approval. At this point, the Donor or the Donor’s bank may refuse the debit, for example because of an account closure or insufficient funds. If this occurs, a separate iATS Return record is added to the iATS Journal reports (ACH Returns) and a notification email is sent to the client. These returns can be pulled using our WebService ReportLink options if desired.

Create Recurring Credit Card Transaction

This section will explain how to use the Web service “CreateCreditCardRecurringV1” to create a recurring credit card Customer Code Token and to start processing recurring transactions through iATS.

Note that this call results in the Recurring Status value on the resulting Customer Code Token auto-defaulting to “True” (1). This means that iATS will auto-process all future transactions.
If today’s date is used for the Begin/Schedule dates, iATS will auto-process a new transaction within 1 hour (CC). The “Begin Date” of the recurring schedule should be set to the date you would like iATS to auto-process a transaction for the first time. Ex. If you set up a new token on September 12^th for a monthly recurring cycle, the Begin Date field should be set to the first date you would like iATS to process, say September 15^th, with a Schedule Date value of the 15^th and a Schedule Type of Monthly. This will ask iATS to create a token to process a monthly transaction on the 15^th of each month, beginning in September.
Please reach out to webservice@iatspayments.com for more details on best practises for creating a new Recurring Customer Code token.

For recurring schedules, please avoid using any sub-codes ending in 90-99 (for example ABDC99) as these will affect future scheduled transactions. We recommend using an 80 level code (eg ABDC80) for online webpage initiated schedules via AuraLink. Please contact iATS support at webservice@iatspayments.com for more information or to request a new sub-code.

SOAP Request and Response Server Addresses

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

North America

SOAP Request and Response Structure

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

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.
The request parameter placeholders shown (e.g., “string”, “Boolean,” etc.) need to be replaced with actual values.

Request

POST /NetGate/AURALink.asmx HTTP/1.1

Host: www.iatspayments.com

Content-Type: application/soap+xml; charset=utf-8

Content-Length: length

<?xml version="1.0" encoding="utf-8"?>

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

<soap12:Body>

<customerIPAddress>string</customerIPAddress>

<firstName>string</firstName>

<lastName>string</lastName>

<address>string</address>

<city>string</city>

<state>string</state>

<zipCode>string</zipCode>

<country>string</country>

<phone>string</phone>

<phone2>string</phone2>

<fax>string</fax>

<email>string</email>

<comment>string</comment>

<item1>string</item1>

<item2>string</item2>

<item3>string</item3>

<item4>string</item4>

<item5>string</item5>

<item6>string</item6>

<mop>string</mop>

<creditCardNum>string</creditCardNum>

<creditCardExpiry>string</creditCardExpiry>

<amount0Name>string</amount0Name>

<amount0Value>string</amount0Value>

<amount0Quantity>string</amount0Quantity>

<amount1Name>string</amount1Name>

<amount1Value>string</amount1Value>

<amount1Quantity>string</amount1Quantity>

<amount2Name>string</amount2Name>

<amount2Value>string</amount2Value>

<amount2Quantity>string</amount2Quantity>

<amount3Name>string</amount3Name>

<amount3Value>string</amount3Value>

<amount3Quantity>string</amount3Quantity>

<amount4Name>string</amount4Name>

<amount4Value>string</amount4Value>

<amount4Quantity>string</amount4Quantity>

<amount5Name>string</amount5Name>

<amount5Value>string</amount5Value>

<amount5Quantity>string</amount5Quantity>

<amount6Name>string</amount6Name>

<amount6Value>string</amount6Value>

<amount6Quantity>string</amount6Quantity>

<amount7Name>string</amount7Name>

<amount7Value>string</amount7Value>

<amount7Quantity>string</amount7Quantity>

<amountOtherName>string</amountOtherName>

<amountOtherValue>string</amountOtherValue>

<amountOtherQuantity>string</amountOtherQuantity>

<total>string</total>

<auraID>string</auraID>

<emailCheck>Boolean</emailCheck>

<scheduleType>string</scheduleType>

<beginDate>dateTime</beginDate>

<endDate>dateTime</endDate>

<scheduleDate>string</scheduleDate>

</CreateCreditCardRecurringV1>

</soap12:Body>

</soap12:Envelope>

Response

HTTP/1.1 200 OK

Content-Type: application/soap+xml; charset=utf-8

Content-Length: length

<?xml version="1.0" encoding="utf-8"?>

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

<soap12:Body>

</CreateCreditCardRecurringV1Response>

</soap12:Body>

</soap12:Envelope>

Overview of Request Parameters

Here is an overview of the request parameters for the “CreateCreditCardRecurringV1,” above. Parameters in red are mandatory.

Parameter	Notes/Options	Char. Limit
customerIPAddress	This is the IP address of the donor’s computer. Please send to fully utilise the Fraud tools available from iATS. IPv4 only.	N/A
firstName	Optional but highly recommended	100
lastName	Optional but highly recommended	100
address	Optional but highly recommended	100
city	Optional but highly recommended	40
state	Optional but highly recommended State or province (North America only)	40
zipCode	Optional but highly recommended	40
country	Optional but highly recommended	40
phone		40
phone2		40
fax		40
email	Optional but highly recommended	100
comment		100
item1		39
item2		39
item3		39
item4		39
item5		39
item6		39
mop	Optional but highly recommended to prevent processing issues. NA: VISA, MC, AMX, DSC UK: VISA, MC, AMX, MAESTR	N/A
creditCardNum	Credit Card Number	32 digits
creditCardExpiry	“MM/YY”	10
amount0Name		149
amount0Value	Prevent the use of commas (,) within the dollar amount fields if possible. 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.	N/A
amount0Quantity		N/A
amount1Name		149
amount1Value		N/A
amount1Quantity		N/A
…
amount7Name		149
amount7Value		N/A
amount7Quantity		N/A
amountOtherName		149
amountOtherValue		N/A
amountOtherQuantity		N/A
total	Optional but needs to be passed for recurring processing to function.	N/A
auraID	auraID is named as PID in the EVENT INFO tab of AURA SETUP page	80
emailCheck	Boolean: true (1)/false (0).	N/A
scheduleType	Optional but needs to be passed for recurring processing to function. Options: Weekly, Monthly, Quarterly, Annually	N/A
beginDate	Value=”dateTime”; ISO 8601 format, see example on page 4.	N/A
endDate	Value=”dateTime”; ISO 8601 format, see example on page 4.	N/A
scheduleDate	Options: Monthly: 1~28,29,30 or 31; Weekly: 1~7; Quarterly or Annually: empty string	N/A

Sample Reply Message Format

<STATUS>StatusType</STATUS>

<ERRORS>ErrorCodeType</ERRORS>

<AUTHORIZATIONRESULT>AuthorizationResultType

</AUTHORIZATIONRESULT>

<CUSTOMERCODE>CustomerCode</CUSTOMERCODE>

</PROCESSRESULT>

</IATSRESPONSE >

The table below describes what can be expected for each of the return values:

Explanation of Sample Reply Message Values
Return Value	Occurrence	Explanation
STATUS	Always	The system-level acknowledgement code that indicates the iATS system status: · Success - iATS system processing succeeded. · Failure - An error has occurred on the iATS system side, such as a database or server down.
ERRORS	Conditional	Return information when Status = Failure. Return value will depend on the error.
AUTHORIZATIONRESULT	Conditional	Return information when Status = Success. This value represents the application-level result that iATS processed the request: · OK - Request has been approved · Error - Request not approved, an error has occurred—possibly due to problems in delivery, attempt by end-user to submit invalid or missing data, etc. iATS does not currently have a list of possible error messages as they can be sent due to different types of processing and from different components, etc. Reject 3: Customer Code does not exist Or Account num is too long Reject 40: Invalid card number
CUSTOMERCODE	Conditional	Return information when Status = Success and AUTHORIZATIONRESULT = OK; value is new Token (Customer code).

Create a Recurring ACHEFT Transaction (Not for UK Direct Debit or Euro SEPA Use)

This section will explain how to use “CreateACHEFTRecurringV1” to create a recurring ACHEFT Customer Code Token and to start processing recurring transactions through iATS.

Note that this service is for NA and certain international customers only; for UK customers wanting to process recurring transaction using ACHEFT, please use “DirectDebitCreateACHEFTRecurringV1,” which is described section 1.5 of this AuraLink Guide.

Note that this call results in the Recurring Status value on the resulting Customer Code Token auto-defaulting to “True” (1). This means that iATS will auto-process all future transactions.
If today’s date is used for the Begin/Schedule dates, iATS will auto-process a new transaction within 1 business day (ACHEFT). The “Begin Date” of the recurring schedule should be set to the date you would like iATS to auto-process a transaction for the first time. Ex. If you set up a new token on September 12^th for a monthly recurring cycle, the Begin Date field should be set to the first date you would like iATS to process, say September 15^th, with a Schedule Date value of the 15^th and a Schedule Type of Monthly. This will ask iATS to create a token to process a monthly transaction on the 15^th of each month, beginning in September.

Please reach out to webservice@iatspayments.com for more details on best practises for creating a new Recurring Customer Code token.

For recurring schedules, please avoid using any sub-codes ending in 90-99 (for example ABDC99) as these will affect future scheduled transactions. We recommend using an 80 level code (eg ABDC80) for online webpage initiated schedules via AuraLink. Please contact iATS support at webservice@iatspayments.com for more information or to request a new sub-code.

SOAP Request and Response Server Addresses

The SOAP request and response structures for “CreateACHEFTRecurringV1” is available at the following URLs:

SOAP Request and Response Structure

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

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.
The request parameter placeholders shown (e.g., “string”, “Boolean,” etc.) need to be replaced with actual values.

Request

POST /NetGate/AURALink.asmx HTTP/1.1

Host: www.iatspayments.com

Content-Type: application/soap+xml; charset=utf-8

Content-Length: length

<?xml version="1.0" encoding="utf-8"?>

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

<soap12:Body>

<customerIPAddress>string</customerIPAddress>

<firstName>string</firstName>

<lastName>string</lastName>

<address>string</address>

<city>string</city>

<state>string</state>

<zipCode>string</zipCode>

<country>string</country>

<phone>string</phone>

<phone2>string</phone2>

<fax>string</fax>

<email>string</email>

<comment>string</comment>

<item1>string</item1>

<item2>string</item2>

<item3>string</item3>

<item4>string</item4>

<item5>string</item5>

<item6>string</item6>

<AccountNum>string</AccountNum>

<AccountType>string</AccountType>

<ACHEFTAgreement>Boolean</ACHEFTAgreement>

<amount0Name>string</amount0Name>

<amount0Value>string</amount0Value>

<amount0Quantity>string</amount0Quantity>

<amount1Name>string</amount1Name>

<amount1Value>string</amount1Value>

<amount1Quantity>string</amount1Quantity>

<amount2Name>string</amount2Name>

<amount2Value>string</amount2Value>

<amount2Quantity>string</amount2Quantity>

<amount3Name>string</amount3Name>

<amount3Value>string</amount3Value>

<amount3Quantity>string</amount3Quantity>

<amount4Name>string</amount4Name>

<amount4Value>string</amount4Value>

<amount4Quantity>string</amount4Quantity>

<amount5Name>string</amount5Name>

<amount5Value>string</amount5Value>

<amount5Quantity>string</amount5Quantity>

<amount6Name>string</amount6Name>

<amount6Value>string</amount6Value>

<amount6Quantity>string</amount6Quantity>

<amount7Name>string</amount7Name>

<amount7Value>string</amount7Value>

<amount7Quantity>string</amount7Quantity>

<amountOtherName>string</amountOtherName>

<amountOtherValue>string</amountOtherValue>

<amountOtherQuantity>string</amountOtherQuantity>

<total>string</total>

<auraID>string</auraID>

<emailCheck>Boolean</emailCheck>

<scheduleType>string</scheduleType>

<beginDate>dateTime</beginDate>

<endDate>dateTime</endDate>

<scheduleDate>string</scheduleDate>

</CreateACHEFTRecurringV1>

</soap12:Body>

</soap12:Envelope>

Response

HTTP/1.1 200 OK

Content-Type: application/soap+xml; charset=utf-8

Content-Length: length

<?xml version="1.0" encoding="utf-8"?>

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

<soap12:Body>

</CreateACHEFTRecurringV1Response>

</soap12:Body>

</soap12:Envelope>

Overview of Request Parameters

Here is an overview of the request parameters for the “CreateACHEFTRecurringV1,” above. Parameters in red are mandatory.

Parameter	Notes/Options	Char. Limit
customerIPAddress	This is the IP address of the donor’s computer. Please send to fully utilise the Fraud tools available from iATS. IPv4 only.	N/A
firstName	Optional but highly recommended.	100
lastName	Optional but highly recommended.	100
address	Optional but highly recommended.	100
city	Optional but highly recommended.	40
state	Optional but highly recommended. State or province (North America only)	40
zipCode	Optional but highly recommended.	40
country	Optional but highly recommended.	40
phone		40
phone2		40
fax		40
email	Optional but highly recommended.	100
comment		100
item1		39
item2		39
item3		39
item4		39
item5		39
item6		39
accountNum	· USD: Routing no. (9 digits) + account no. (# of digits varies) · CAD: Bank no. (3 digits) + transit no. (5 digits) + account no. (# of digits varies) · AUD: BIC (Bank ID) + IBAN (Account) Order must be followed with NO spaces	32
accountType	Optional but needed for recurring functions to work. Options: CHECKING, SAVING (*Applies to North America only)	N/A
ACHEFTAgreement	Boolean: true (1)/false (0)	N/A
amount0Name		149
amount0Value	Prevent the use of commas (,) within the dollar amount fields if possible. 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.	N/A
amount0Quantity		N/A
amount1Name		149
amount1Value		N/A
amount1Quantity		N/A
…
amount7Name		149
amount7Value		N/A
amount7Quantity		N/A
amountOtherName		149
amountOtherValue		N/A
amountOtherQuantity		N/A
total
auraID	auraID is named as PID in the EVENT INFO tab of AURA SETUP page
emailCheck	Boolean: true (1)/false (0)
scheduleType	Optional but needed for recurring option to function. Options: Weekly, Monthly, Quarterly, Annually
beginDate	Value=”dateTime”; ISO 8601 format, see example on page 4.
endDate	Value=”dateTime”; ISO 8601 format, see example on page 4.
scheduleDate	Optional but needed for recurring option to function. Options: Monthly: 1~28,29,30 or 31; Weekly: 1~7; Quarterly or Annually: empty string

Sample Reply Message Format

<STATUS>StatusType</STATUS>

<ERRORS>ErrorCodeType</ERRORS>

<AUTHORIZATIONRESULT>AuthorizationResultType

</AUTHORIZATIONRESULT>

<CUSTOMERCODE>CustomerCode</CUSTOMERCODE>

</PROCESSRESULT>

</IATSRESPONSE >

The table below describes what can be expected for each of the return values:

Explanation of Sample Reply Message Values
Return Value	Occurrence	Explanation
STATUS	Always	The system-level acknowledgement code that indicates the iATS system status: · Success - iATS system processing succeeded. · Failure - An error has occurred on the iATS system side, such as a database or server down.
ERRORS	Conditional	Return information when Status = Failure. Return value will depend on the error.
AUTHORIZATIONRESULT	Conditional	Return information when Status = Success. This value represents the application-level result that iATS processed the request: · OK - Request has been approved · Error - Request not approved, an error has occurred—possibly due to problems in delivery, attempt by end-user to submit invalid or missing data, etc. iATS does not currently have a list of possible error messages as they can be sent due to different types of processing and from different components, etc. Reject 3: Customer Code does not exist Or Account num is too long Reject 40: Invalid card number
CUSTOMERCODE	Conditional	Return information when Status = Success and AUTHORIZATIONRESULT = OK; value is new Token (Customer code).

Creating a Recurring Direct Debit Schedule for UK Clients

What is UK Direct Debit?

Direct Debit collection is the preferred payment method for over 50% of the UK’s bill paying population for memberships, subscriptions, and donations. It is the method of electronically debiting funds directly from a Pound Sterling bank account in the UK.

UK Direct Debit processing is highly controlled by BACS (Bankers' Automated Clearing Services), and certain guidelines must be followed. Single one-time transactions and refunds are restricted for example, and only recurring scheduled transactions can be processed in the UK.

iATS uses the Direct Debiting Bureau Smart Debit to process Direct Debit transactions. For more information regarding Smart Debit and how to set up a Direct Debit Merchant Account with iATS, please call 1.866.300.4287, Option 2.

Scheduling a new Direct Debit Instruction - Online vs. Offline Processing

A new Direct Debit Instruction can be scheduled either online via an organizations website, or offline via a software application.

Online Website: Scheduling a new Direct Debit Instruction via an organizations website should be handled by the donor directly. The donor must read and complete four BACS mandated web pages that become visible on the client’s website when the Direct Debit method of payment is selected, and bank account validation must be completed before the Token (Customer Code) is created.

** Important: As UK Direct Debit’s are strictly controlled by BACS, iATS must control the schedule for all Recurring donors.

For more information regarding the necessary pages and WebService calls needed for online scheduling, please refer to the Workflow Requirements for Online Direct Debit section below.

When a client is collecting new Direct Debit’s online, the webpages they use must be approved to ensure they are meeting the Direct Debit BACS guidelines for formatting and content.

In the case where the client is building their own collection pages (such as using CustomerLink or AuraLink), or using a third party software, they need to be approved,

Who needs to provide the approval depends on their SUN type:

When a client applies for their Direct Debit merchant account and brings their own SUN with them, their Bank Manager needs to approve the new pages.
If the client received a Facilities Managed SUN from Smart Debit/iATS during their application process, Smart Debit needs to approve the new pages.

Offline Software: Scheduling a new Direct Debit Instruction via internal software on behalf of a donor is considered a phone order, and should only be set-up with the donor on the phone while a BACS mandated phone script is read to the donor. The process of setting up a new DD Instruction with iATS must include a number of WebService calls.

** Important: As UK Direct Debit’s are strictly controlled by BACS, iATS must control the schedule for all Recurring donors.

For more information, please refer to our ProcessLink WebService documentation.

Workflow Requirements for Online Direct Debit

For UK Direct Debit clients to validate and schedule Direct Debit Instructions via their website, the following steps are required. For samples of the required online pages, please click here. **Important: These pages have already been approved by the bank and should be followed exactly. Any format changes will result in the need to be approved by your UK bank.

1.	Donor selects recurring Direct Debit option on website (singles are not allowed), and enters processing schedule, amount, personal details, etc. Please note that due to the lengthy process of registering a new donor in the UK, there is a 12 day lead time required for all new Direct Debit schedules. Please ensure the donor cannot select a begin date within 12 days of the current date.
2.	Donor is directed to the first of four required online pages, called the Declaration. This page asks the donor to checkmark a box indicating they wish to start a new Direct Debit Instruction.
3.	Donor is directed to the second of four required online pages, called the Account/Payer Details page. This page asks the donor to enter their bank account details (Sort and Account) for validation purposes. Previously entered personal details can be carried over to pre-populate this form if desired. In order to validate the donors bank account details and pull their bank name and address (for visual verification purposes), you will need to program the “DirectDebitACHEFTPayerValidateV1” WebService to validate the payer details as the donor clicks to the next page as per the instructions in the next section. Once the “proceed” button on the second page is clicked, the bank details will be displayed on the third page. During this call, a unique Reference Number is created and should also be displayed on the third online page. While you are able to supply your own unique Reference ID if desired, we recommend leaving the value blank to allow iATS to create one. The format will be the 4 digit Client Code + Unique Number, for example “TEST123456”. If you choose to use your own Reference numbers instead, our system will check to ensure the number is unique, and send back an error if not.
4.	As the validation and creation of the Reference number is occurring, the donor will be directed to the third of four required online pages, called Validation Details and Confirmation. This page displays the donors bank account information, their new reference number, and all schedule and personal details they have already entered. Also, the Clients SUN (UK Direct Debit merchant number) must be displayed. The donor needs to review these details, and have the option to print or edit if needed.
5.	As the donor clicks from the third page to the fourth and final required online page, you will need to program the “DirectDebitCreateACHEFTRecurringV1” WebService (for use with AuraLink) to obtain a new Token (Customer code) that links to the new Reference Number.
6.	If the post back URL has been set up for this AURA event, all details can be pushed to the URL specified, for example a Salesforce Site URL which allows our Salesforce Application Brickwork to receive the transaction and Customer Code data. We recommend storing the Reference Number with the Token (Customer Code) for future reference. For information regarding how to update an existing Direct Debit reference, please see the CustomerLink WebService documentation.
7.	Testing can be done using the UDDD88 UK Direct Debit test credentials found in the testing section of this document.
8.	Once the new donor has been registered, our Acquirer Smart Debit will send an email confirmation to the new donor confirming the details. These emails are also mandated by BACS and examples can be provided for reference if needed. If desired, you can take over the email notification process for Smart Debit, however different emails need to be sent for different update reasons and it’s usually easier to leave this task to them.
9.	Six days before the Direct Debit process date, iATS will send a file to Smart Debit for processing. Results can be pulled using ProcessLink if desired.

Validating Payer Information for UK Direct Debit

This section will explain how to use the Web service “DirectDebitACHEFTPayerValidateV1” to validate direct debit payer information. Please note that this Web service is only required for UK clients.

DD Validation SOAP Request and Response Server Address

The SOAP request and response structures for “DirectDebitACHEFTPayerValidateV1” are available at the following URL:

DD Validation SOAP Request and Response Structure

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

Notes:

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

Request

POST /NetGate/CustomerLink.asmx HTTP/1.1

Host: www.uk.iatspayments.com

Content-Type: application/soap+xml; charset=utf-8

Content-Length: length

<?xml version="1.0" encoding="utf-8"?>

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

<soap12:Body>

<agentCode>string</agentCode>

<customerIPAddress>string</customerIPAddress>

<ACHEFTReferenceNum>string</ACHEFTReferenceNum>

<beginDate>dateTime</beginDate>

<endDate>dateTime</endDate>

<accountCustomerName>string</accountCustomerName>

<accountNum>string</accountNum>

<companyName>string</companyName>

<firstName>string</firstName>

<lastName>string</lastName>

<address>string</address>

<city>string</city>

<state>string</state>

<country>string</country>

<email>string</email>

<zipCode>string</zipCode>

</DirectDebitACHEFTPayerValidateV1>

</soap12:Body>

</soap12:Envelope>

Response

HTTP/1.1 200 OK

Content-Type: application/soap+xml; charset=utf-8

Content-Length: length

<?xml version="1.0" encoding="utf-8"?>

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

<soap12:Body>

</DirectDebitACHEFTPayerValidateV1Response>

</soap12:Body>

</soap12:Envelope>

Overview of DD Validation Request Parameters

Here is an overview of the request parameters for the “DirectDebitACHEFTPayerValidateV1,” above. Parameters in red are mandatory.

Parameter	Notes/Options	Char. Limit
agentCode		10
customerIPAddress	This is the IP address of the donor’s computer. Please send to fully utilise the Fraud tools available from iATS. IPv4 only.	N/A
ACHEFTReferenceNum	Leave blank to allow iATS to create unique reference	60
beginDate	Value=”dateTime”; ISO 8601 format. For an example please see page 6. Due to BACS registration lead times, new DD Tokens (Customer codes) must begin at least 12 days from current date.	N/A
endDate	Value=”dateTime”; ISO 8601 format. For an example please see page 6.	N/A
accountCustomerName	Donor’s full name, or name on file with bank. If left empty we will use firstName + lastName and cut at 30 characters.	30
accountNum	GBP: Sort code (6 digits) + account no. (8 digits) Order must be followed with NO spaces	32 digits
companyName		100
firstName		100
lastName		100
address		100
city		40
state	State or province (North America only)	40
country		40
email		100
zipCode		40

Sample DD Validation Reply Message Format

The response message format will be as follows:

<STATUS>StatusType</STATUS>

<ERRORS>ErrorCodeType</ERRORS>

<AUTHSTATUS>AuthorizationResultType</AUTHSTATUS>

<AUTHCODE>AUTHCODE</AUTHCODE>

<BANKERROR>ErrorInfo</BANKERROR>

<BANK_NAME></BANK_NAME>

<BANK_BRANCH></BANK_BRANCH>

<BANK_CITY></BANK_CITY>

<BANK_STATE></BANK_STATE>

<BANK_POSTCODE></BANK_POSTCODE>

</AUTHRESULT>

</IATSRESPONSE >

The table below describes what can be expected for each of the return values:

Explanation of Sample Reply Message Format Values
Return Value	Occurrence	Explanation
STATUS	Always	The system-level acknowledgement code that indicates the iATS system status: · Success - iATS system processing succeeded. · Failure - An error has occurred on the iATS system side, such as a database or server down.
ERRORS	Conditional	Return information when Status = Failure. Return value will depend on the error.
AUTHSTATUS	Conditional	Return information when Status = Success. This value represents the application-level result that iATS processed the request: · OK - ACHEFT validation result is OK · REJ - ACHEFT validation result is Reject. Reject reason will be return in <AUTHCODE> or <BANKERROR>
AUTHCODE	Conditional	Explanation for AUTHSTATUS REJ value; hidden if value is OK.
BANKERROR	Conditional	Explanation for AUTHSTATUS REJ value; hidden if value is OK.

Create Recurring Customer Code Token for UK Direct Debit via AuraLink

This section will explain how to use the Web service “DirectDebitCreateACHEFTRecurringV1” to create a recurring ACHEFT transaction through AURA for clients using our UK server. Please note that this call is different than the similar call in our CustomerLink Guide. This call includes the Aura ID value which enables the transaction data to post to a separate CRM system, such as our Salesforce Application Brickwork.

DD Create SOAP Request and Response Server Address

The SOAP request and response structures for “DirectDebitCreateACHEFTRecurringV1” is available at the following URL:

DD Create SOAP Request and Response Structure

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

Notes:

This code corresponds to SOAP 1.2 shown at the UK 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”, “Boolean,” etc.) need to be replaced with actual values.

Request

POST /NetGate/AURALink.asmx HTTP/1.1

Host: www.uk.iatspayments.com

Content-Type: application/soap+xml; charset=utf-8

Content-Length: length

<?xml version="1.0" encoding="utf-8"?>

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

<soap12:Body>

<customerIPAddress>string</customerIPAddress>

<firstName>string</firstName>

<lastName>string</lastName>

<address>string</address>

<city>string</city>

<state>string</state>

<zipCode>string</zipCode>

<country>string</country>

<phone>string</phone>

<phone2>string</phone2>

<fax>string</fax>

<email>string</email>

<comment>string</comment>

<item1>string</item1>

<item2>string</item2>

<item3>string</item3>

<item4>string</item4>

<item5>string</item5>

<item6>string</item6>

<AccountNum>string</AccountNum>

<AccountType>string</AccountType>

<ACHEFTAgreement>Boolean</ACHEFTAgreement>

<amount0Name>string</amount0Name>

<amount0Value>string</amount0Value>

<amount0Quantity>string</amount0Quantity>

<amount1Name>string</amount1Name>

<amount1Value>string</amount1Value>

<amount1Quantity>string</amount1Quantity>

<amount2Name>string</amount2Name>

<amount2Value>string</amount2Value>

<amount2Quantity>string</amount2Quantity>

<amount3Name>string</amount3Name>

<amount3Value>string</amount3Value>

<amount3Quantity>string</amount3Quantity>

<amount4Name>string</amount4Name>

<amount4Value>string</amount4Value>

<amount4Quantity>string</amount4Quantity>

<amount5Name>string</amount5Name>

<amount5Value>string</amount5Value>

<amount5Quantity>string</amount5Quantity>

<amount6Name>string</amount6Name>

<amount6Value>string</amount6Value>

<amount6Quantity>string</amount6Quantity>

<amount7Name>string</amount7Name>

<amount7Value>string</amount7Value>

<amount7Quantity>string</amount7Quantity>

<amountOtherName>string</amountOtherName>

<amountOtherValue>string</amountOtherValue>

<amountOtherQuantity>string</amountOtherQuantity>

<total>string</total>

<auraID>string</auraID>

<emailCheck>Boolean</emailCheck>

<scheduleType>string</scheduleType>

<beginDate>dateTime</beginDate>

<endDate>dateTime</endDate>

<scheduleDate>string</scheduleDate>

<ACHEFTReferenceNum>string</ACHEFTReferenceNum>

</DirectDebitCreateACHEFTRecurringV1>

</soap12:Body>

</soap12:Envelope>

Response

HTTP/1.1 200 OK

Content-Type: application/soap+xml; charset=utf-8

Content-Length: length

<?xml version="1.0" encoding="utf-8"?>

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

<soap12:Body>

</DirectDebitCreateACHEFTRecurringV1Response>

</soap12:Body>

</soap12:Envelope>

DD Create Overview of Request Parameters

Here is an overview of the request parameters for the “DirectDebitCreateACHEFTRecurringV1,” above. Parameters in red are mandatory.

Parameter	Notes/Options	Char. Limit
customerIPAddress	This is the IP address of the donor’s computer. Please send to fully utilise the Fraud tools available from iATS. IPv4 only.	N/A
firstName	Donor’s full name or name on file with their bank.	100
lastName	Donor’s full name or name on file with their bank.	100
address		100
city		40
state	State or province (North America only)	40
zipCode		40
country		40
phone		40
phone2		40
fax		40
email		100
comment		100
item1		39
item2		39
item3		39
item4		39
item5		39
item6		39
accountNum	GBP: Sort code (6 digits) + account no. (8 digits) Order must be followed with NO spaces	32
accountType	N/A	N/A
ACHEFTAgreement	Boolean: true (1)/false (0)	N/A
amount0Name		149
amount0Value	Prevent the use of commas (,) within the dollar amount fields if possible. 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.	N/A
amount0Quantity		N/A
amount1Name		149
amount1Value		N/A
amount1Quantity		N/A
…
amount7Name		149
amount7Value		N/A
amount7Quantity		N/A
amountOtherName		149
amountOtherValue		N/A
amountOtherQuantity		N/A
total		N/A
auraID	auraID is named as PID in the FORM INFO tab of AURA SETUP page	80
emailCheck	Boolean: true (1)/false (0)	N/A
scheduleType	Options: Weekly, Monthly, Quarterly, Annually	N/A
beginDate	Value=”dateTime”; ISO 8601 format, see example on page 4. Due to BACS registration lead times, new DD Tokens (Customer codes) must begin at least 12 days from current date.	N/A
endDate	Value=”dateTime”; ISO 8601 format, see example on page 4.	N/A
scheduleDate	Options: Monthly: 1~28,29,30 or 31; Weekly: 1~7; Quarterly or Annually: empty string	N/A
ACHEFTReferenceNum	The previously created Reference number (during Validation) needs to be captured from the validation response (<ACHREFNUM></ACHREFNUM> field) and included here to ensure the new token (Customer Code) is linked to the Ref ID.	60

DD Create Sample Reply Message Format

<STATUS>StatusType</STATUS>

<ERRORS>ErrorCodeType</ERRORS>

<AUTHORIZATIONRESULT>AuthorizationResultType

</AUTHORIZATIONRESULT>

<CUSTOMERCODE>CustomerCode</CUSTOMERCODE>

<REGISTERREFNUMRESULT>RegisterResult</REGISTERREFNUMRESULT> <BANKERROR>ErrorMessage</BANKERROR>

<ACHEFTREFERENCENUM>ReferenceNumber</ACHEFTREFERENCENUM>

</PROCESSRESULT>

</IATSRESPONSE >

The table below describes what can be expected for each of the return values:

Explanation of Sample Reply Message Values
Return Value	Occurrence	Explanation
STATUS	Always	The system-level acknowledgement code that indicates the iATS system status: · Success - iATS system processing succeeded. · Failure - An error has occurred on the iATS system side, such as a database or server is down.
ERRORS	Conditional	Return information when Status = Failure. Return value will depend on the error.
AUTHORIZATIONRESULT	Conditional	Return information when Status = Success. This value represents the application-level result that iATS processed the request: · OK - Request has been approved · Error - Request not approved, an error has occurred—possibly due to problems in delivery, attempt by end-user to submit invalid or missing data, etc. iATS does not currently have a list of possible error messages as they can be sent due to different types of processing and from different components, etc. Reject 3: Customer Code does not exist Or Account num is too long Reject 40: Invalid card number
CUSTOMERCODE	Conditional	Return information when Status = Success and AUTHORIZATIONRESULT = OK; value is new Token (Customer code).
REGISTERREFNUMRESULT	Conditional	Return information when status = Success and AUTHORIZATIONRESULT = OK. Value is ACHEFT registration result from bank.
BANKERROR	Conditional	Return error information when REGISTERREFNUMRESULT is Registration REJ.
ACHEFTREFERENCENUM	Conditional	Return information when status = Success and AUTHORIZATIONRESULT = OK. Value is ACHEFT reference number iATS has registered with bank.

Appendix A: Testing AURA

The AURA88 and UDDD88 iATS Client Codes have been created to allow for testing iATS Payments systems, now available for both Credit Card and dynamic North American ACH/EFT processing.

These accounts are not live merchant accounts, therefore Authorization and Rejection results are not real.

Please note that this test information is provided to many clients, therefore please do not modify or delete any pre-existing Aura Event’s or change the password of this code.

User ID = AURA88

Password = AURA88

User ID = UDDD88 (UK Direct Debit and CC testing only)

Password = DDTEST16

URL: NA = www.iatspayments.com

UK = www.uk.iatspayments.com

Credit Card Testing

Notes on Credit Card processing:

To test the Authorization and Rejection responses related to a Charge, use
- Visa number 4111111111111111
- MC number 5111111111111118
- AMX number 371111111111114
- DSC number 6011111111111117
To test the Auth responses related to both Charges and Refunds, use credit card number 4222222222222220
If needed, use 3 digit CVV2 code for Visa, MC and DSC. Use 4 digit CVV2 code for AMX.

Amount	Results when using Visa (4111111111111111), MC, AMX or DSC #’s above
1.00	OK: 678594
2.00	REJ: 15
3.00	OK: 678594
4.00	REJ: 15
5.00	REJ: 15
6.00	OK: 678594:X
7.00	OK: 678594:y
8.00	OK: 678594:A
9.00	OK: 678594:Z
10.00	OK: 678594:N
15.00	If CVV2 = 1234, the response is OK: 678594:Y. If no CVV2 is entered, the response is REJ: 19
16.00	REJ: 2
17.00	REJ: 22
192.00 (NA Only)	If sent via API (iATSLink or WebService) a) IP address is invalid format: Rej: 5. b) IP address is valid format: OK: 678594.
All Other Amounts	REJ: 15
All Refund Amounts	REJ: 15
Amount		Results when using 4222222222222220 only
Any Sale Amount		OK: 678594
Any Refund Amount		OK: 678594

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

North American ACH/EFT Debit Testing
Notes on ACH Processing for non-UK Direct Debit tests:

ACH/EFT Transaction processing is not processed in “Real Time” like credit card transactions and there can be processing delays while the data is moving between iATS, our Bank and the donors Bank.
Live and Test ACH/EFT processing is sent to the bank as per the following schedule:
- Monday and Tuesday: File sent twice per day (3am and 3pm)Live and Test ACH/EFT processing is sent to the bank as per the following schedule:
- Wednesday to Friday: File sent once per day (3pm)
- No files are sent over the weekend or on US bank holidays.
When ACH/EFT transactions are sent to iATS for processing, there are three stages which each transaction will go through:
- “Tobesent” - The transaction is waiting to be sent to iATS’ bank as per above schedule.
- “Pending” - The transactions have been sent to the bank, but final approval/rejection has not been received from the bank (1 Business day in general).
- “OK:BankAccept”, or “OK:Reject” – The final results from the bank indicating approval or decline. Check the Details of the Reject Journal on the iATS Portal for more information.
- “Return” - A separate Return record may be recorded on the iATS Journal report. These may be posted at any future date, and has been issued by the bank or donor. Check the Details of the Return report on the iATS Portal for more information.
For North American ACH testing, any account details can be used however we recommend:

Canada

Bank: 123

Transit: 00000

Account: 123456

USD

Routing: 111111111

Account: 12345678

ACH Dynamic Testing Parameters:

Desired Final Status	Amount Value to use	Results and Timing
Approved	$1.00	Final status received within 1 Business day · Status will be dynamically changed from ToBeSent (initial value) to Pending as per schedule in notes above. · Will be changed to Approved approx. 1 hour after sent to bank.
Rejected	Any value except $1.00 and $3.00	Final status received within 1 Business day · Status will be dynamically changed from ToBeSent (initial value) to Pending as per schedule in notes above. · Will be changed to Rejected approx. 1 hour after sent to bank.
Returned	$3.00	Final status received within 1 Business day · Status will be dynamically changed from ToBeSent (initial value) to Pending as per schedule in notes above. · Will be changed to Approved approx. 1 hour after sent to bank. · A new Return record will be created and posted the next business day.

Please note there is a transaction limit of $2000.00 per charge. Amounts above will be Rej:39

Appendix B: Testing Direct Debit (UK Direct Debit Only)

The following information will allow UK clients to test the UK Direct Debit calls.

Please note that this “UDDD88” account is not a live merchant account 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.

“UDDD88” Account Details:

User ID: UDDD88
Password: DDTESTUK

URL:
- UK: uk.iatspayments.com

To test the authorization and rejection responses related to a charge, the following bank account information should be used:
- Sort: 000000
- Account: 12345678

Amounts and corresponding results:

The amounts and corresponding responses detailed below have been created for you to test a range of possible requests and responses:

Amount	Result
1.00	Completed (Followed by a reference number)

Appendix B: Definition of XML Element Abbreviations

The elements in the below table may or may not apply directly to the AuraLink 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.

Element	Definition	Association
AC1, AC2	Account1, Account2,	Start element
ACH	ACHEFT	Start element
ACN	Account number	ACHEFT
ACTYP	Account type	ACHEFT
ADD	Address	Customer
AGT	Agent	Transaction
AMT	Amount	Transaction / recurring
ANM	Anonymous	Transaction
BD	Begin date	Recurring
CC	Credit card	Start element
CCN	Credit card number	Credit card
CM	Comment	Transaction / customer
CNT	Country	Customer
CO	Company	Customer
CST	Customer	Start element
CSTC	Token (Customer code)	Customer
CSTN	Customer name	Credit card / ACHEFT
CTY	City	Customer
DTM	Date and time	Transaction
ED	End date	Recurring
EM	Email	Customer
EXP	Expiry	Credit card
FLN	Full name	Customer
FN	First name	Customer
FX	Fax	Customer
INV	Invoice	Transaction
IT1, IT2, …	Item1, item2, etc.	Transaction
LN	Last name	Customer
MB	Mobile	Customer
MP	Method of payment	Credit card
PH	Phone	Customer
RCR	Recurring	Start element
RE	Received email	Transaction
RST	Result	Transaction
SCHD	Schedule date	Recurring
SCHTYP	Schedule type	Recurring
ST	State	Customer
TN	Transaction	Start element
TNID	Transaction ID	Transaction
TNTYP	Transaction type	Transaction
ZC	Zip code	Customer

Embed Payment Form

Developers

Auralink

GUIDE TO AURALink WEB SERVICES

Processing Credit Cards

SOAP Request and Response Server Addresses

SOAP Request and Response Structure

Overview of Request Parameters

Sample Reply Message Format

Processing ACHEFT Transactions (Not for UK Direct Debit or Euro SEPA Use)

SOAP Request and Response Server Addresses

SOAP Request and Response Structure

Overview of Request Parameters

Sample Reply Message Format

Explanation of ACH Processing Stages

SOAP Request and Response Server Addresses

SOAP Request and Response Structure

Overview of Request Parameters

Sample Reply Message Format

Create a Recurring ACHEFT Transaction (Not for UK Direct Debit or Euro SEPA Use)

SOAP Request and Response Server Addresses

SOAP Request and Response Structure

Overview of Request Parameters

Sample Reply Message Format

Creating a Recurring Direct Debit Schedule for UK Clients

Workflow Requirements for Online Direct Debit

DD Validation SOAP Request and Response Server Address

DD Validation SOAP Request and Response Structure

Overview of DD Validation Request Parameters

Sample DD Validation Reply Message Format

Create Recurring Customer Code Token for UK Direct Debit via AuraLink

DD Create SOAP Request and Response Server Address

DD Create SOAP Request and Response Structure

DD Create Overview of Request Parameters

DD Create Sample Reply Message Format

Appendix A: Testing AURA

Appendix B: Testing Direct Debit (UK Direct Debit Only)

Appendix B: Definition of XML Element Abbreviations