Configuring New Zealand States for Zone AP Payments Beneficiary Bank Accounts

Add New Zealand regions to NetSuite so the State list on the beneficiary bank account record is populated and TransferMate accepts the registration. Following the ISO 3166-2 Short Name format prevents save and registration errors.

Note: Clicking on the images within this guide will enlarge them for better viewing.

Overview

When you configure a Zone AP Payments beneficiary bank account for a vendor banking in New Zealand, you must provide the payee's state or region. Native NetSuite does not include pre-loaded regional subdivisions for New Zealand, so the State field on native address forms is a free-text field. Zone AP Payments requires you to select from the native NetSuite State list instead of entering free text. As a result, the State list can appear empty or lack New Zealand regions, which prevents the beneficiary record from saving.

This guide explains the TransferMate requirement for New Zealand states, how to add the missing regions in NetSuite, and how to format the required Short Name using the ISO 3166-2 standard.

For the complete beneficiary bank account setup, including IBAN, account number, and payment reference options, see Setting Up Beneficiary Bank Accounts for Zone AP Payments.

Prerequisites

• Use the Administrator role, or a role with permission to manage company setup.
• Identify the New Zealand regions where your vendors bank.

Why the State field is mandatory for New Zealand

TransferMate's V2 Beneficiary API requires the payee state or subdivision in ISO code format for 4 countries:

• New Zealand
• Australia
• Canada
• United States

Because native NetSuite does not supply state or subdivision records for New Zealand, you must create these records in NetSuite so they appear in the Zone AP Payments beneficiary State list.

ISO 3166-2 Short Name requirement

For TransferMate to validate and accept the beneficiary bank registration, the Short Name on the NetSuite State record must follow the ISO 3166-2 specification.

The ISO 3166-2:NZ standard represents New Zealand subdivisions as <countrycode>-<statecode>. For example, Hawke's Bay is NZ-HKB, and Auckland is NZ-AUK.

Important: In the NetSuite Short Name field, enter only the 3-letter subdivision code (for example, enter HKB, not NZ-HKB). The Zone AP Payments integration extracts the country prefix and combines the country code with the Short Name during API transmission.

New Zealand regions and ISO Short Names

Refer to ISO 3166-2:NZ for the complete standard. The table below lists the 16 regional subdivisions and the exact Short Name values to enter in NetSuite.

Step 1: Configure New Zealand states in NetSuite

1. Navigate to Setup > Company > States/Provinces/Counties.
2. Select New Zealand in the Country filter at the top of the record. If no New Zealand states exist yet, New Zealand may not appear in the filter until you create the first state record.
3. Follow the scenario below that matches your current setup.

Scenario A: New Zealand has no states configured

1. Click New State/Province/County (or New).
2. Select New Zealand in the Country field.
3. Enter the region name in the Full Name field (for example, Auckland).
4. Enter the exact 3-letter ISO code in the Short Name field (for example, AUK).
5. Click Save.
6. Repeat these steps for each additional region where your New Zealand vendors bank.

Scenario B: New Zealand states exist but have non-ISO Short Names

If your team previously entered New Zealand states with custom abbreviations (for example, AKL instead of AUK) or non-standard formatting, choose one of these options:

• Option 1: Edit the existing record. Click Edit next to the record, update the Short Name field to match the official 3-letter code from ISO 3166-2:NZ, and click Save.
• Option 2: Create a compliant record. If historical transactions prevent you from modifying the existing state record, create a dedicated record with the ISO Short Name (for example, State: Auckland (ISO), Short Name: AUK).

Step 2: Assign the state on the beneficiary bank account record

1. Navigate to AP Payment > Setup > AP Payment Beneficiary Bank Account > New. To update an existing record, open it and click Edit.
2. Verify that the Bank Country field is set to New Zealand.
3. Click the State list. Your configured New Zealand regions now appear.
4. Select the vendor's bank state or region, and complete the remaining required banking details.
5. Click Save.

Step 3: Confirm the registration

When you save the record, Zone AP Payments transmits the beneficiary banking details to TransferMate. After TransferMate validates the details and the ISO-compliant state, the system generates the Beneficiary Bank Registration ID and populates it on the record. This confirms the registration succeeded.

Frequently asked questions

Can I enter the state name as free text on the beneficiary record?

No. Zone AP Payments requires you to select a state from the configured NetSuite list. This ensures strict ISO formatting compliance with TransferMate's API.

Why did my New Zealand beneficiary registration fail after I selected a state?

Verify the Short Name under Setup > Company > States/Provinces/Counties. If the Short Name contains lowercase characters, contains spaces, or includes the country prefix (such as NZ-AUK), update it to the exact 3-letter uppercase code (for example, AUK) and re-save the beneficiary record.

Do I need to configure all 16 New Zealand regions at once?

No. Configure only the regions where your current vendors' bank accounts reside.