Add a supported country (SMS 2FA + notifications)

The IBA delivers SMS 2FA codes and SMS notifications to members via Twilio. Members can only receive SMS at a phone number whose country is on both the IBA’s internal list and Twilio’s geographic permissions allow-list. Adding a country requires four changes — database, cache, third-party console, and service restart — in this order.

When to do this

A member from a country not on the IBA’s supported list tries to enable SMS 2FA or sign up for SMS notifications, and the feature is blocked or silently fails.

Steps

1. Add the country to the countries table

The reference list lives in the production database. Insert a row with the country’s name, ISO code, currency, dialing code, and fees (if applicable).

INSERT INTO countries (name, iso_code, currency_code, currency_symbol, dialing_code, fees)
VALUES ('Cyprus', 'CYP', 'EUR', '€', '357', NULL);

The table schema for reference:

CREATE TABLE `countries` (
  `id` int unsigned NOT NULL AUTO_INCREMENT,
  `name` varchar(50) DEFAULT NULL,
  `iso_code` varchar(20) DEFAULT NULL,
  `currency_code` varchar(20) DEFAULT NULL,
  `currency_symbol` varchar(20) DEFAULT NULL,
  `dialing_code` varchar(20) DEFAULT NULL,
  `fees` int DEFAULT NULL,
  PRIMARY KEY (`id`)
);

A typical existing row for comparison:

2. Clear the Redis countries cache

The API caches the countries list in Redis under the key countries. Until the cache is cleared, the new country won’t appear anywhere the API serves country data (member profile, signup, 2FA setup).

From an environment that can reach production Redis:

redis-cli DEL countries

3. Add the country to Twilio geo-permissions

Even with the database and cache updated, Twilio will reject SMS to unlisted countries. Update Twilio’s allow-list:

1. Sign in to the Twilio console: https://console.twilio.com/us1/develop/sms/settings/geo-permissions 
2. Find the new country in the list and tick its checkbox.
3. Save.

This step is on the Twilio side only — the IBA database has no knowledge of it. If you skip it, the IBA will accept the member’s phone number and try to send SMS, but Twilio will silently reject delivery.

4. Restart the API server

Restarting the API process triggers the countries cache to be rebuilt from the database on the next request. After this step the new country is live in all surfaces (member onboarding, profile editing, 2FA setup, notification subscriptions).

The exact restart command depends on the environment (Docker compose in dev, DigitalOcean App Platform in production).

How to verify

1. Sign in to a test account and edit the phone number — the new country should appear in the picker.
2. Trigger an SMS 2FA challenge on a number using the new country code — the code should arrive within a few seconds.
3. Check Twilio’s message log to confirm delivery wasn’t blocked by geo-permissions.

Rollback

If the country needs to be removed for any reason:

1. Untick it in the Twilio geo-permissions console (step 3 in reverse).
2. Delete the row from countries (or set a disabled flag if one is added later).
3. Clear the Redis countries key again.
4. Restart the API.

Members whose phone numbers used the removed country will lose SMS functionality on their next sign-in attempt — review who’s affected before rolling back in production.