Developers

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.

During single transaction processing calls, if a Customer Code Token is not being used, the default placeholder value is “Quick Client”. Please do not remove this default value during processing. When needed, this value should be replaced with the Customer Code token storing the payment details.

Encrypted Swipe credit card functionality is available. For more information or a copy of the installation guide, please email partnersupport@iatspayments.com.

iATS held auto-processing for Recurring Transactions: Logic Explained

Below is an outline regarding how the auto-processing works, and how some changes which are made to the Customer Code may affect when the donor is charged.

Customer Code Overview:

• Recurring scheduling and payment details are stored within iATS servers as "Customer Codes". These customer codes can be created and edited, but not deleted once a transaction has been processed.
• If the Recurring function of a Customer Code is enabled, it is flagged as Status “ON” or 1 in Boolean. If it's not functional i.e. you are holding the schedule instead of iATS, the flag is OFF, 0 in Boolean.
• The Recurring function contains fields which tell the iATS system when to auto- process transactions against the donors payment details, which include:
  • Enable Recurring Payments toggle, which indicates if the auto-process function is ON or OFF.
  • Recurring Schedule, with options of Monthly, Annual, Quarterly, and Weekly.
  • Schedule Date, with options for the Weekly (days of the week) and Monthly (dates of the month) types. The Begin Date field is utilized instead for Annual and Quarterly types.
  • Begin Date which indicates when the processing should begin. iATS will ignore a Customer Code until this date.
  • End Date which indicates when the processing should end. iATS will ignore a Customer Code token once this date has passed.
    
• Recurring credit card transactions are processed at 3am each day, with the exception of newly created/modified tokens which have today as the schedule date. These are processed within the hour.
• Recurring ACH recurring transactions are processed at 3am & 3pm on Monday/Tuesday, and 3am on Wednesdays, Thursdays, and Fridays, excluding holidays.
• Recurring transactions scheduled to process on the 29th - 31st will be processed on the actual last date of the given month should it not exist. Example, a donation scheduled to be processed on the 31st of each month will be processed on the 30th of November.

What happens when the schedule fields are modified?

• If a recurring transaction is attempted and either approved or rejected, a flag is added to the Customer Code on our server to indicated the transaction was attempted to ensure it is not re-attempted during the same Recurring Schedule cycle (Month, Year, etc). This flag will be removed if you modify the Schedule Date, Schedule Type, or Begin Date fields. When these fields are modified, another transaction will be re- attempted as per the new schedule cycle. The exception is for Quarterly schedule types. We will not reattempt in these cases, even if the schedule fields are modified.
• If the Customer Code Recurring Status field is OFF (0), and values are sent to update the recurring schedule details, iATS will ignore the values and not validate them to ensure proper format. When the status is OFF, we utilize our own internal placeholder values to ensure data quality.
  • Recurring Type will be default to Monthly
  • Schedule Date will be default to 1
  • Begin Date and End Date will be defaulted to 2000-01-01
• If the Customer Code Recurring Status field is ON (1), and values are sent to update the recurring schedule details, iATS will perform a validation on the Recurring Type and Schedule Date to make sure the values are in the proper format. We DO NOT currently perform a validation on the Begin Date or End Date value, and we encourage you to ensure you are passing the values correctly to prevent errors. The Begin Date must be a date later than the current date or an error is received.
• If the Customer Code Recurring Status field is OFF (0), and is updated to ON (1), iATS will automatically process a new transaction if one hasn't yet been attempted for the Recurring Schedule cycle.
  
  

We will not attempt a new transaction if an approval or reject was already processed for that cycle. For example if a donor is charged each month on the 15th and they request a pause in their giving cycle for 6 months, the day the Recurring Status flag is set to back to ON (1), a new transaction will be attempted for the missing current cycle within 1 hour. New future transactions will continue to be processed on the 15th of each month.

Back to Top

2. Notes on Recurring Processing with iATS Payments

CustomerLink is primarily used for creating, updating, and deleting credit card and ACHEFT (ACH or direct debit) Customer Code Tokens and to setup recurring transactions. Creating Customer Code Tokens allows future transactions to be carried out using the same credentials without the need to store sensitive credit card or ACH information on local servers.

For managing recurring transactions, you have the option of managing them or having iATS manage them for you:

1. If iATS manages the recurring schedule:
   1. You use CustomerLink to setup the recurring details (credit card, start/end date, etc.) with the recurring tag set to true (1)
2. If you manage the recurring schedule:
   1. You use CustomerLink to setup the individual Tokens (CustomerCodes) with the recurring tag set to false (0);
   2. You then send a batch file containing the Tokens (CustomerCodes) using ProcessLink;
   3. Or process a single transaction using either of the following ProcessLink services (depending on whether the transaction is using a credit card or ACHEFT): “ProcessCreditCardWithCustomerCodeV1” or “ProcessACHEFTWithCustomerCodeV1.”

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.

During single transaction processing calls, if a Customer Code Token is not being used, the default placeholder value is “Quick Client”. Please do not remove this default value during processing. When needed, this value should be replaced with the Customer Code token storing the payment details.

Encrypted Swipe credit card functionality is available. For more information or a copy of the installation guide, please email partnersupport@iatspayments.com 

For technical assistance, please email partnersupport@iatspayments.com 

4. Calls to Create Customer Code Tokens

Create a Customer Code for Credit Card

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

Response

Overview of Request Parameters

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

Sample Reply Message Format

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

Create a Customer Code for Bank Account for NA or AUD

This service is for when you want to create a new Customer Code token to store Bank Account information, and to optionally enable automated recurring processing within iATS. This call cannot be used to setup new UK Direct Debit bank debit or Euro SEPA bank debit Customer Codes. It can be used to setup new Australian Dollar bank debit transactions however.

If iATS manages the recurring schedule:

1. You use CustomerLink to set up there curring details (credit card, start/end date, etc.) with the recurring tag set to true (1).

If you manage the recurring schedule:

1. You use CustomerLink to set up the individual Tokens (Customer Codes) with the recurring tag set to false (0);

• CreateACHEFTCustomerCode

This call is available on either our NA or the AUD portion of our UK systems.

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
• AUD International

SOAP Request and Response Structure

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

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”, “dateTime”, etc.) need to be replaced with actual values.

Back to Top

Request (NA, for AUD International use link above)

Response

Overview of Request Parameters

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

Sample Reply Message Format

The response message format will be as follows:

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

Back to Top

5. Calls to Obtain Details, Update, and Delete a Customer  Code

These calls are for when you want to obtain details on a Customer Code token, and then update its values. You can also pull a list of Customer Codes in bulk.

If Customer Code has not yet been used to process a transaction, it can be deleted. If the token has already been used for transaction processing, it cannot be deleted from the iATS system.

Please note that Euro SEPA and UK Direct Debit services have their own update calls within their respective sections.

The following calls will be included in the below sections:

• GetCustomerCodeDetail
• UpdateCreditCardCustomerCode
• UpdateACHEFTCustomerCode
• DeleteCustomerCode
• GetCustomerListByCreationTimeCSV
• GetCustomerListByCreationTimeXML

These calls are available on either our NA or UK systems however the ACH calls only apply to NA and the AUD portion of our UK system.

Notes on how to perform Customer Code Token Updates

Important: In order to avoid data integrity issues when updating values within an existing Customer Code (Token), we recommend calling the existing values from the iATS Servers first and then the sending the update call. For example:

1. Call “GetCustomerCodeDetail” method to get all information within the existing Customer Code (Token) from iATS servers.
2. Change the fields that should be updated. **See recommendations regarding updates below.
3. Call UpdateCreditCardCustomerCode to pass new information to be stored within iATS servers.

** If you are not updating the Credit Card or Bank Account numbers, use the value **** (four star symbols) in the credit card number field. This will ensure the card details are not overwritten with a blank value.

Obtain the Details of a Specific Customer Code Token

This call is to obtain the details of a specific Customer Code (any method of payment) to prepare for an update.

• GetCustomerCodeDetail

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

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 “GetCustomerCodeDetail”.

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”, “dateTime,” etc.) need to be replaced with actual values.

Request (NA, for UK see link above)

Response

Overview of Request Parameters

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

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

Back to Top

In the case of a successful request, the response will resemble the example below. (The message type inside every xml node is an encoded XML string):

Update a Credit Card Customer Code

This call is to update the details of a Credit Card Customer Code token. Before proceeding, please refer to section 5.2 as you must perform the “GetCustomerCodeDetail” call to obtain the details of the Customer Code before sending the updated data.

Important: In order to avoid data integrity issues when updating values within an existing Customer Code (Token), we recommend calling the existing values from the iATS Servers first and then the sending the update call. For example:

1. Call GetCustomerCodeDetail method to get all information within the existing Customer Code (Token) from iATS servers.
2. Change the fields that should be updated. **See recommendations regarding updates below.
3. Call UpdateCreditCardCustomerCode to pass new information to be stored within iATS servers.

** If you are not updating the Credit Card or Bank Account numbers, use the value **** (four star symbols) in the credit card number field. This will ensure the card details are not overwritten with a blank value.

• UpdateCreditCardCustomerCode

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

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 “UpdateCreditCardCustomerCode”.

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”, “dateTime,” etc.) need to be replaced with actual values.

Request (NA, for UK see link above)

Response

Overview of Request Parameters

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

Sample Reply Message Format 

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

Back to Top

Update a Bank Debit Customer Code for NA and AUD

This call is to update the details of a Bank Debit Customer Code token for North American or Australian Dollar. Before proceeding, please refer to section 5.2 as you must perform the “GetCustomerCodeDetail” call to obtain the details of the Customer Code before sending the updated data.

Important: In order to avoid data integrity issues when updating values within an existing Customer Code (Token), we recommend calling the existing values from the iATS Servers first and then the sending the update call. For example:

1. Call GetCustomerCodeDetail method to get all information within the existing Customer Code (Token) from iATS servers.
2. Change the fields that should be updated. **See recommendations regarding updates below.
3. Call UpdateACHEFTCustomerCode to pass new information to be stored within iATS servers.

** If you are not updating the Credit Card or Bank Account numbers, use the value **** (four star symbols) in the credit card number field. This will ensure the card details are not overwritten with a blank value.

• UpdateACHEFTCustomerCode

This call is available on either our NA or AUD International system.

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 “UpdateACHEFTCustomerCode”.

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”, “dateTime,” etc.) need to be replaced with actual values.

Request (NA, for AUD International see link above)

Response

Overview of Request Parameters

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

Sample Reply Message Format

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

Delete a Customer Code

This call is to delete Customer Code token, when possible. If Customer Code has not yet been used to process a transaction, it can be deleted. If the token has already been used for transaction processing, it cannot be deleted from the iATS system.

• DeleteCustomerCode

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

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 “DeleteCustomerCode”.

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”, “dateTime,” etc.) need to be replaced with actual values.

Request (NA, for UK see link above)

Response

Overview of Request Parameters

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

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

Obtain List of all Customer Code Details

This service is to allow you to pull a full list of Customer Codes and their details. The call is setup to be pulled based on the creation time of the Customer Code, allowing you to obtain only those codes that were setup in a particular time frame, such as yesterday for example. These reports are available in either .csv or XML.

• GetCustomerListByCreationTimeCSV
• GetCustomerListByCreationTimeXML

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

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

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

SOAP Request and Response Structure

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

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”, “dateTime,” etc.) need to be replaced with actual values.

Request (NA, for UK see link above)

Response

Overview of Request Parameters

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

6. Calls to Create and Update a Bank Debit Customer Code for UK Direct Debit

Notes on Workflow for 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 a Direct Debiting Bureau partner to process Direct Debit transactions. For information regarding the set up a Direct Debit Merchant Account with iATS, please call 1.888.955.5545, Option 2 or email iats@iatspayments.com 

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.

• 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 to validate the donors bank account details and create a new Token (Customer Code).

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

• 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 by a bank (or Smart Debit) to ensure they are meeting the Direct Debit BACS guidelines for formatting and content.

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.

Back to Top

This call is used to perform the first step in creating a new UK Direct Debit Bank Debit Customer Code for UK Pound Sterling processing. This step both validates the bank account information, and creates or utilizes an existing Reference Number. The Reference Number is then used to create the Customer Code token for recurring processing with iATS.

• These calls are located within the UK CustomerLink directory and point to our UK server.
• No one-time/single debits are permitted.
• iATS must hold the recurring schedule for all Direct Debit transactions. For DD, iATS must manage the recurring schedule: You use CustomerLink to set up the recurring details (credit card, start/end date, etc.) with the recurring tag set to true (1).

If not already done, please read Section 6.1 for important information on our Direct Debit services.

• DirectDebitACHEFTPayerValidateV1
  

This call is only available on our UK system.

SOAP Request and Response Server Addresses

You can find the SOAP request and response structures at the following URL:

• UK

SOAP Request and Response Structure

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

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”, “dateTime,” etc.) need to be replaced with actual values.

Request

Response

Overview of DD Validate Request Parameters

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

Back to Top

DD Validate Sample Reply Message Format

The response message format will be as follows:

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

Create a Recurring Customer Code for UK Direct Debit – Step 2

This call is to create a Customer Code Token for recurring processing of UK Pound Sterling Direct Debit. If not already done, please read Section 6.1 for important information on our Direct Debit services.

When creating new tokens with a recurring schedule, the customer’s iATS account username, sub-code and password are included in the details that are sent to the iATS servers. 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 and a 01 level code (eg ABCD01) for offline software initiated schedules.

Please contact iATS support at webservice@iatspayments.com for more information or to request a new sub-code.

• DirectDebitCreateACHEFTCustomerCodeV1
  

This call is only available on our UK system.

SOAP Request and Response Server Addresses

You can find the SOAP request and response structures at the following URL:

• UK

SOAP Request and Response Structure

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

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”, “dateTime,” etc.) need to be replaced with actual values.

Response

Overview of DD Create Request Parameters

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

Sample Reply Message Format

The response message format will be as follows:

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