Developer Docs

MTN Bridge

Forward an authenticated request to an MTN Nigeria endpoint. The bridge generates an MTN access token for the auth_phone, attaches it as a Bearer token and relays your request.

The upstream MTN response (body, status code and headers) is returned to you as-is, it is not wrapped in the usual status/message/data format.

Billing

Usage is billed in blocks: the charge amount configured for your account is debited from your wallet for every 10,000 requests made to this endpoint. Every request forwarded to MTN counts, regardless of the upstream response.

Access not enabled (HTTP 403)

MTN Bridge is available only to accounts enabled by an administrator. Requests from other accounts return 403.

Suspension (HTTP 402)

If a usage charge cannot be debited (e.g insufficient balance), access to this endpoint is suspended and every request returns 402 until the configured charge is paid. Funding your wallet automatically settles the outstanding charge and restores access.

Temporarily unavailable (HTTP 503)

When the bridge cannot verify or record usage, requests are refused with 503. Retry after a short while.

Errors

Bridge errors (validation, invalid endpoint, suspension, unavailability, connection failure) use the standard error format below. Errors returned by MTN itself are relayed unchanged with their original status code.

Body

{
    "auth_phone": "Auth Phone",
    "method": "Method",
    "endpoint": "Endpoint",
    "payload": "Payload",
    "headers": "Headers"
}

Parameters

auth_phone MTN phone number used to generate the access token, 11 digits starting with 0 e.g 08031234567
method HTTP method to use upstream, one of GET, POST, PUT, PATCH, DELETE (uppercase)
endpoint Full MTN URL to call. Must use https and the host must be mtnnigeria.net or one of its subdomains e.g https://api.mtnnigeria.net/...
payload Object of data sent upstream. Sent as query string for GET, and as JSON body for other methods. Pass an empty object {} if not needed
headers Object of extra headers sent upstream (Optional). The Authorization header is set by the bridge

Sample Response

{
    "...": "Raw response returned by the MTN endpoint"
}

{
    "status": "error",
    "message": "MTN Bridge access suspended due to an unpaid usage charge. Kindly fund your wallet to restore access."
}