Getting started

1. Get onboardedCopy Anchor Link

The Mobile Wallet team creates your partner record and your first credential, and invites you to the Partner Dashboard. You receive:

• An AppId — your partner's public identifier.
• An AppKey — shown in plaintext exactly once, at creation or rotation. It is hashed at rest (PBKDF2) from that point on — nobody, including the gateway's own operators, can retrieve it again. Store it securely; if you lose it, ask an admin to rotate your credential.
• An environment — Sandbox or Live. Each environment has its own independent credential and IP whitelist, the same way a real payment provider gives you separate test/live key pairs.

By default, no service is granted to a new partner. An admin grants each service (MOMO_DEPOSIT, MOMO_WITHDRAWAL, …) individually, along with per-service amount/daily limits.

2. Whitelist your IP (Live only)Copy Anchor Link

Live fails closed — a partner with zero configured IP whitelist entries cannot make any Live request at all. Sandbox is open by default, so you can start testing immediately without waiting on a whitelist entry. Ask an admin to add your outbound IP (or CIDR range) before going live.

3. Make your first requestCopy Anchor Link

Every request authenticates with HTTP Basic auth — AppId as the username, AppKey as the password:

curl -u "$APP_ID:$APP_KEY" https://gateway.example.com/api/v1/services

This endpoint needs no service grant — it just lists the platform's service catalogue, and is a good way to confirm your credential works at all before trying anything that moves money.

A wrong AppId or a wrong AppKey fail with the exact same 401 — you can never tell from the response which half was wrong.

4. Try a Sandbox transactionCopy Anchor Link

With a Sandbox credential, use one of the magic MSISDNs to get a deterministic outcome without touching any real provider:

curl -u "$APP_ID:$APP_KEY" -X POST https://gateway.example.com/api/v1/momo/deposit \
  -H "Content-Type: application/json" \
  -d '{
    "partnerOrderId": "my-first-deposit-001",
    "msisdn": "+237670000001",
    "amount": 1000,
    "currency": "XAF"
  }'

+237670000001 always resolves to an immediate success — see Sandbox testing for the full table of deterministic outcomes, including rejections, timeouts, and delayed resolution.

5. Read the status backCopy Anchor Link

curl -u "$APP_ID:$APP_KEY" "https://gateway.example.com/api/v1/transactions/my-first-deposit-001"

From here: wire up a webhook so you don't have to poll, understand idempotency before you build real retry logic, and check the error reference for what every GW-xxx code means.