The iATS Gateway
- Michael Kalnicki
- Sam Louk
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:
Go to Hello (username) > Account Settings > Gateways
Click New payment gateway to create a new entry
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 |
Additional fields required for card payments
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 |
|---|---|---|
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 |
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