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

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

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

Form Field

Value type

Description

Credit Card Number

Token

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)

Token

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)

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. An example: ”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

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

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

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

  • Payment type: Mastercard

  • Card number: 5111111111111118

  • 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.

* There is a transaction limit of $2000.00 (£2000.00) per charge. Amounts above $2000.00 (£2000.00) per charge will be rejected.

Bank account testing

  • Payment type: ACHEFT

  • Routing Transit Number: 000000000

  • Bank Account Number : 1234567