MTN

MTN

This page contains information about configuring the MTN FSP integration in a 121 Platform Instance.

Configuration

The MTN integration requires two layers of configuration:

1. Environment variables (services/.env) — control the operating mode and connection to the MTN API.
2. Per-program FSP configuration (via 121 portal or API) — store the actual MTN wallet credentials for each program.

---

Environment Variables

All MTN env vars are defined in services/.env. The only variable that is always required is MTN_MODE. The rest depend on its value.

Variable	Required when	Description
MTN_API_URL	MTN_MODE=EXTERNAL	Base URL for all MTN API calls (e.g., https://sandbox.momodeveloper.mtn.com)
MTN_SUBSCRIPTION_KEY	MTN_MODE=EXTERNALwhen developing locally	Ocp-Apim-Subscription-Key — primary key from the Disbursements product on the MTN portal
MTN_REFERENCE_ID	MTN_MODE=EXTERNAL when developing locally	API User UUID (v4), created during provisioning on the MTN portal
MTN_TARGET_ENVIRONMENT	MTN_MODE=EXTERNAL	sandbox for sandbox; country-specific for production (e.g., mtnuganda, mtnghana)
MTN_API_KEY	MTN_MODE=EXTERNAL when developing locally	API Key generated for the API User on the MTN portal
EXTERNAL_121_SERVICE_URL	No (optional)	Public URL of the 121 service. Sets the X-Callback-Url header. If unset, polling uses http://localhost:3000

---

Per-Program FSP Configuration

Each program using MTN must have its own FSP configuration with these properties. These are configured in the 121 portal (or via the API) — not in .env.

Property	Required	Description
subscriptionKeyMtn	Yes	Subscription key for this program's MTN wallet (Ocp-Apim-Subscription-Key header)
referenceIdMtn	Yes	API User UUID for this program's MTN wallet (used as username in Basic Auth)
apiKeyMtn	Yes	API Key for this program's MTN wallet (used as password in Basic Auth)

Why do credentials appear in both env vars and per-program config? The env vars MTN_SUBSCRIPTION_KEY, MTN_REFERENCE_ID, and MTN_API_KEY exist only for the local/test seed setup (so program-mtn.json can reference them via process.env substitution). In production, these env vars are not set — the actual credentials are configured per-program via the portal or API. The startup validation still requires them when MTN_MODE=EXTERNAL, but the API calls always use the per-program values.

---