The iATS Gateway

This document explains how to process single and recurring credit or debit card transactions via the iATS gateway. 

There are two versions of the iATS gateway available – IATS North America and IATS UK.

Using the iATS gateway, we can process donations from Visa, Mastercard, American Express or Discover credit cards as well as Maestro debit cards with UK version of the gateway. With the North America version of the gateway, we also support ACHEFT transactions in USD and CAD (more details below). The available currencies are CAD, EUR, GBP and USD, subject to your arrangements with IATS.

We strongly recommend that you explicitly confirm the payment methods and currencies available to you with IATS.

The currency is selected when you set up the gateway with iATS – it is not necessary to include a currency form field in your default supporter record, or on your donation pages. It is important to note that it is therefore not possible to collect different alternate currencies through the same donation page, as donations in different currencies must be submitted to separate gateways. It is possible to take single and recurring payments through the same page, by including the ‘Recurring Payment’ field as a drop-down, radio button or check box.

Before creating iATS donation pages, you will need to have arranged your merchant account with iATS. 

Setting up a gateway

It is recommended that you create and keep two separate gateway records in your account, one for testing and one linked to your live gateway. Donation pages should be linked to a test gateway initially, and then switched to a live gateway before launch. To create each one:

  1. Go to Hello (username) > Account Settings > Gateways
  2. Click New payment gateway to create a new entry
  3. The fields are set up as follows:
Field Description
Reference name

A unique name for the gateway. It is a good idea for the name to include the type of gateway (eg. iATS NA), the currency, and whether it is a live or test gateway.

Select gateway

Select the iATS gateway with country appropriate to the arrangements you have made with IATS: NA (North America) or UK (United Kingdom).

Username

Your iATS account username (Use TEST88 for the test gateway)

Password

Your iATS account password (Use TEST88 for the test gateway)

Currency

Select the appropriate currency for the gateway, subject to what you have agreed with iATS. Note that changing this field in Engaging Networks will only change how currency is reported in our platform. The actual currency of donations is determined by the currency of your iATS account.

Test mode

Should be checked for a test gateway, but must be unchecked for a gateway that will accept live donations.

Required form fields

The following fields need to be set up in the default supporter record and then added to the form in ‘build’.

Basic required fields:

Form Field Value type Comments
Email Address Alphanumeric Email address identifying the supporter record
Payment Type Alpha

The donation page will accept any of the following strings, case insensitive: visa, master card, mastercard, mc, american express, americanexpress, amex, amx, discover, maestro, switch or ACHEFT. Please see the donation page help document for instructions on how to create ‘select’ or ‘radio’ fields for displaying user-friendly values to supporters.

Donation Amount Numeric May be entered as a whole number or number with two decimal places. Eg. Twelve dollars may be entered as ’12’ or ‘12.00’. You may want to consider using the ‘select with input’ or ‘radio with input’ field types.
First Name Alpha The cardholder’s first name.
Last Name Alpha The cardholder’s last name.
Address 1 Alphanumeric The first address line of the cardholder
City Alpha The address city of the cardholder
Region Alphanumeric

The address region of the cardholder. For the US and Canada, this should be a 2 character code for the state/province. For other countries, it is a free text field.

ZIP/ postal code Alphanumeric

The post/postal/zip code of the
cardholder

Additional fields required for card payments

Form Field Value type Description
Credit Card Number Integer Credit card number w/o spaces
Credit Card Expiration Date Format must be MM/YY. It is strongly recommended that you use the ‘split select’ field type for this form field.

Credit Card Verification value

(CVV2 or CVC2)

Numeric The additional Card Verification Value printed on the card, used for fraud checks.

Credit card number and credit card verification values are not stored in the default supporter record.

ACHEFT Fields (NA only)

Important

For ACHEFT payments, you should ensure that your form meets the legal requirements for NACHA. For example, you could include a mandatory checkbox question authorizing the transfer with text along the lines of:”By clicking the provided checkbox, I authorize electronic debits from my bank account in the amount displayed above. This authorization is to remain in full force and effect unless I provide written notification within and appropriate time frame.”

Form field Value type Comments
Bank Account Type Alpha ‘CHECKING’ or ‘SAVING’
Bank Account Number Integer Account number.
Bank Routing Transit Number Integer

This is the routing number for the ACHEFT payment. For Canadian Dollars, this is in the format XXXXXYYY, where X is the routing number and Y is the branch ID.

Additional Fields for card Recurring Payments

If you wish to process IATS recurring payments you will need to have this feature enabled by IATS, as well as make the necessary changes in Engaging Networks, described below.

Form Field Value Description
Recurring Payment Alpha Submitting ‘Y’ will flag the transaction as a recurring payment. Any other value will result in a single payment.
Recurring Frequency Alpha Permitted values are MONTHLY, QUARTERLY, SEMI_ANNUAL and ANNUAL. Please see the notes below on ‘select’ field types for details of ways of presenting these fields to supporters.
Recurring Day Numeric The day of the month on which the recurring payment should be taken.
Recurring End Date (optional) Numeric When this recurring payment should cease. The value must be in the format DD/MM/YYYY

Please note that the currency field is not required for iATS, and should not be included on donation pages – the currency for donations is defined in the gateway setup page.

Testing donation pages

Provided that you are using a gateway set up in test mode, you can use the following details during the testing process. Entering different donation amounts will simulate different scenarios from the IATS gateway as detailed below. You will be able to check responses are being returned correctly by viewing the supporter record used for testing in ‘Supporter Data > Manage supporters’.

Card testing

  • Payment type: Visa
  • Card number: 4222222222222220
  • Expiration date: some MM/YY combination in the future
  • CVV: Any three digits

To trigger specific codes:

  • Payment type: Visa
  • Card number: 4111111111111111
  • Expiration date: some MM/YY combination in the future
  • CVV: Any three digits

Specific donation amounts are used for testing, and will return “OK” or “REJ” (rejected) and an error code. This information is visible in the transactional exports of your donation page.

  • Dollar Amount 1.00 OK: 678594;
  • Dollar Amount 2.00 REJ: 15;
  • Dollar Amount 3.00 OK: 678594;
  • Dollar Amount 4.00 REJ: 15;
  • Dollar Amount 5.00 REJ: 15;
  • Dollar Amount 6.00 OK: 678594:X;
  • Dollar Amount 7.00 OK: 678594:y;
  • Dollar Amount 8.00 OK: 678594:A;
  • Dollar Amount 9.00 OK: 678594:Z;
  • Dollar Amount 10.00 OK: 678594:N;
  • Dollar Amount 15.00, if CVV2=1234 OK: 678594:Y; if there is no CVV2:REJ:19
  • Dollar Amount 16.00 REJ: 2;
  • Other Amount REJ: 15.

All fields other than donation amount may take any valid value for testing.

Please note that you should not submit real credit card or bank account details to a test configuration – IATS test merchant accounts are shared, and anyone with the test login details will be able to see transactions.

Bank account testing

  • Payment type: ACHEFT
  • Routing Transit Number: 000000000
  • Bank Account Number : 1234567

 

Updated on October 28, 2020

Was this article helpful?

Need Support?
Can’t find the answer you’re looking for? Don’t worry we’re here to help!
Contact Support