Gravity Forms Bank Details Validator Setup Guide

The Gravity Forms Bank Details Validator Premium Add-on adds a Bank Details field to Gravity Forms. It collects the account holder name, the country, the bank code and the account number in one field, and checks them on your server before the form can be sent. This guide covers installation, the UK modulus files, the field settings, what each country check does, how the numbers are saved and shown, and answers to common questions.

What the add-on checks

Every country has its own bank code and its own rules. The add-on supports five countries and runs the strongest check that is publicly available for each one:

• United Kingdom: 6-digit sort code and an account number of 6 to 10 digits. With the UK modulus files loaded, the sort code and an 8-digit account number are checked together against the weights and exceptions for that sort code range. Without the files, the format is checked.
• United States: 9-digit ABA routing number with the 3-7-1 check digit, and a first two digits in the ranges the Federal Reserve uses (01 to 12, 21 to 32, 61 to 72 and 80). The account number must have 4 to 17 digits.
• New Zealand: 2-digit bank and 4-digit branch, then the account number and its suffix (for example 12-3456-1234567-00). The check-digit method published by Inland Revenue is chosen by bank and applied to the whole number.
• Australia: 6-digit BSB and an account number of 5 to 9 digits. There is no public check digit for Australian accounts, so the format is checked.
• Canada: 5-digit transit number and 3-digit institution number (12345-003, or the electronic form 0003 12345), and an account number of 7 to 12 digits. Format check only.

A passed check means the numbers are well formed and, where the country has check digits, that they add up. It catches typing mistakes such as a swapped pair of digits or a missing digit. It does not show that an account exists or who holds it, and the add-on never contacts a bank. For IBANs, use the IBAN Validator add-on.

Requirements and installation

1. WordPress 6.5 or newer, PHP 7.4 or newer and Gravity Forms 2.8 or newer (tested with 2.9 and 3.1).
2. Upload the add-on zip under Plugins → Add New → Upload Plugin and activate it.
3. Go to Forms → Settings → Bank Details, enter your license key and click Activate License. The field and the Bank Details page appear once the licence is active.

Step 1: load the UK modulus files

If you accept UK bank accounts, load the modulus files first. Vocalink publishes two text files for the UK schemes: the weight table valacdos.txt, which lists sort code ranges with the method and weights to use, and the sort code substitution table scsubtab.txt, which a few sort codes need. The files change several times a year when banks open or merge sort codes, so they are not included in the add-on. You load the current version, and load it again when a new one is published.

Open Forms → Bank Details. You have two ways to load the files:

• Upload the files: download valacdos.txt and scsubtab.txt from Vocalink’s modulus checking page, choose them in the two file boxes and click Upload and check.
• Fetch from Vocalink: the two file addresses are filled in for you. Click Fetch from Vocalink and your site downloads both files over HTTPS. Nothing is fetched automatically; the download happens only when you click. When a new version is published, paste the new addresses from Vocalink’s page before you click.

Every line of a file is checked before it is stored. A file that is empty, too large or not in the expected layout is refused with a message, and the table you had before stays in place. The status table shows how many rows are loaded, when and from where. Remove the modulus files takes you back to the format check.

The Try bank details box on the same page checks any combination with the loaded files, so you can test a sort code and account number from a customer without sending a form. Nothing typed there is stored.

Step 2: add the field to a form

Open your form in the editor and click Bank Details under Advanced Fields. The field has these settings on the General tab:

• Bank account countries: tick the countries you accept. With one country the visitor sees no country menu; with more than one, the visitor picks the country and the labels and examples change to match.
• Selected first: the country the menu starts on.
• Ask for the account holder name: on by default. When it is shown and the field is required, the name must be filled in.
• Ask for the account type: checking or savings, shown for US and Canadian accounts only.
• Show only the last 4 digits: on by default. The account number appears as ••••5678 in the entry list, in {all_fields} and in merge tags.

The usual Gravity Forms settings work as well: label, description, required, custom validation message, sub-label placement, conditional logic, visibility and CSS class. If you type a custom validation message, it is shown for every problem; leave it empty to get the default message for each country and problem.

Step 3: what the visitor sees

The visitor types the bank code and account number with or without spaces and dashes. When they leave the account number box, a hint appears under the field if the numbers are clearly wrong: a routing number whose check digit does not add up, a sort code with five digits, a New Zealand number that fails its check. The hint helps, but the decision is made on your server when the page or the form is sent, so the check also works when the browser has scripts turned off.

If the details fail, the form stops on the page with the field and shows the message under it. The default messages say what to look at, for example “Please enter the 9-digit routing number.” or “This sort code and account number do not match the bank’s check-digit rules. Please check both numbers.” Nothing is saved until the details pass.

How the numbers are saved

Details that pass are saved in one standard form, whatever the visitor typed: UK sort codes as 12-34-56 and account numbers with 8 digits (6 and 7 digit numbers get leading zeros, as UK banks expect), New Zealand as 01-0902 and 0068389-00, Canadian transit and institution as 12345-003, US routing numbers and Australian BSBs as plain digits. The country is saved as a two-letter code (GB, US, CA, AU, NZ) so you can filter and export by it.

Each part of the field is its own input, so you can map them separately in feeds and exports: .1 account holder name, .2 country, .3 bank code, .4 account number and .5 account type. For a field with ID 5, the account number merge tag is {Bank details:5.4}.

Masking in entries, e-mails and merge tags

Bank details are sensitive, so the account number is masked by default wherever it travels:

• The entry list shows the bank code and ••••5678.
• {all_fields} in notifications and confirmations shows ••••5678.
• Merge tags for the field or the account number input show ••••5678.
• The entry screen shows the full number to staff who can view entries, because they need it to set up the payment.
• Entry exports contain the full number, for the same reason.

When an internal notification needs the full number, add the :unmasked modifier to the merge tag, for example {Bank details:5.4:unmasked}. Use it only in e-mails that go to your own team. To show the full number everywhere, turn off Show only the last 4 digits on the field.

The Bank check column and entry box

Every entry records which check was made for each Bank Details field: UK modulus check passed, Routing number check digit passed, Check digits passed (New Zealand), Format checked, or Format checked (these numbers have no check digits that can be tested) for UK account numbers with 9 or 10 digits and a few special account ranges. The result is shown in a Bank details check box on the entry screen and in a Bank check column you can add to the entry list.

Country notes

United Kingdom

The modulus rules cover sort code ranges, not every sort code. When a sort code is not in any range, the rules say the details cannot be checked and should be treated as valid, so the add-on accepts them with the format check and records “Format checked (no modulus rule for this sort code)”. Some building society and bank accounts have 9 or 10 digits; they are accepted with the format check because each bank shortens them in its own way. Foreign currency accounts in a few ranges are also accepted without the modulus check, as the rules require.

United States

The routing number check catches nearly every single typing mistake. Account numbers have no public check digit, so they are checked for length (4 to 17 digits). Add the account type option if your process needs checking or savings.

New Zealand

Visitors can type the full number in the two boxes in the usual way: bank and branch (12-3456) in the first, account and suffix (1234567-00 or 1234567-000) in the second. Banks without a published method get the format check, so new banks are never refused by mistake.

Australia and Canada

These countries have no public check digit for bank accounts. The add-on checks the length and that only digits were typed, which still catches a missing or extra digit.

Who can do what

The Bank Details page and the add-on settings need the Gravity Forms edit settings capability (administrators have it). Every action on the page is a signed request checked on the server. Staff who can view entries see the full account number on the entry screen; everyone else only sees masked numbers in e-mails and lists.

Privacy and outside requests

All checks run on your own server. Visitors’ bank details are never sent anywhere by the add-on. The only outside requests are the GravityExtra licence check and updates, and the download of the two modulus files when an administrator clicks Fetch from Vocalink. Bank details are stored in your Gravity Forms entries like any other field, so apply your usual entry retention and access settings.

Troubleshooting

• The Bank Details button is missing in the editor: activate the licence under Forms → Settings → Bank Details.
• An upload is refused: make sure you chose the plain text files valacdos.txt and scsubtab.txt, not the PDF specification or a renamed spreadsheet.
• Fetch from Vocalink reports an error: some hosts block outside downloads. Download the two files in your browser and upload them instead.
• A customer says their correct details were refused: try them in the Try bank details box. If the sort code is new, load the latest files; your custom message can also invite the visitor to contact you.

Frequently asked questions

Does a passed check mean the account is real?

No. It means the numbers are well formed and their check digits add up, which catches typing mistakes. Only the bank can tell whether an account is open and who holds it.

How often should I reload the UK files?

Whenever a new version appears on Vocalink’s modulus checking page; it is usually updated a few times a year. The Bank Details page shows when you last loaded them.

Can I use the field for IBANs?

No. Use the IBAN Validator add-on for IBANs; it can sit on the same form as the Bank Details field.

What happens without a licence?

The field keeps showing and saving data, but no bank check is made and the Bank Details page is hidden until the licence is active again.

What is removed when I uninstall?

The settings, the licence data and the loaded modulus files. The Bank check results are removed only if you switch that on in the settings. Entries and the bank details in them are never touched.