Scopes

Every API key is minted with a list of scopes that determine what it can do. Scopes are checked at the gateway before your request reaches the underlying service.

A request with a key that doesn’t carry the required scope returns:

{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "This endpoint requires the 'payments:create' scope."
  }
}

HTTP 403.

Available scopes

These are the only scopes that exist. A key can carry any combination of them.

Scope	Endpoints	Notes
`payments:create`	`POST /v1/api/payment-links`, `POST /v1/api/mandates`, `DELETE /v1/api/mandates/{id}`, `POST /v1/api/charges`, `POST /v1/api/webhook-endpoints`, `DELETE /v1/api/webhook-endpoints/{id}`	Create payment links, recurring mandates/charges, and manage your webhook endpoints. The core scope for a checkout integration.
`payments:read`	`GET /v1/api/payment-links/`, `GET /v1/api/payments/`, `GET /v1/api/mandates/{id}`, `GET /v1/api/webhook-endpoints`	Retrieve/list payments and payment links, read mandates, list your webhook endpoints. Read-only.
`sub_merchants:create`	`POST /v1/api/sub-merchants/start`, `POST /v1/api/sub-merchants/complete`	Provision a sub-account under your merchant (platforms onboarding their own sellers).
`sub_merchants:read`	`GET /v1/api/sub-merchants`	List your sub-accounts.
`payroll:create`	`POST /v1/api/payroll/*`	Create and run payroll batches via the API.
`payroll:read`	`GET /v1/api/payroll/*`	Read payroll run status and history.
`payouts:create`	`POST /v1/api/payouts`	Disburse to a MoMo/Orange payee you already PIN-approved from the dashboard. This scope never authorizes a new destination or raises a cap — only creating/managing payees from the dashboard does that.
`payouts:read`	`GET /v1/api/payouts/*`	Read payout status and history.
`gift_cards:redeem`	`POST /v1/gift-cards/redeem`	Redeem a gift card at the point of sale. Typical scope for a POS integration. Note the path — gift cards are not under `/v1/api/*`.
`gift_cards:read`	—	Reserved; not enforced by any endpoint today.
`fleet_cards:redeem`	`POST /v1/fleet-cards/redeem`	Redeem a fleet card at the point of sale. Also not under `/v1/api/*`.

There is no scope for refunds, wallet-to-wallet transfers, gift-card issuance, or bill payments — those aren’t exposed on the merchant API surface today. See “What this API does not do” on the reference page.

Picking scopes

Two rules:

Least privilege. A checkout integration needs payments:create and payments:read only. A POS terminal needs fleet_cards:redeem or gift_cards:redeem and nothing else. A platform onboarding sellers needs sub_merchants:create/sub_merchants:read in addition to its payments scopes.
One key per role. Don’t mint one master key with every scope and use it everywhere. If your POS gets compromised, the blast radius should be redemption at that terminal — not your entire payment surface.

Minting a key

Scopes are chosen when you mint the key, from the business dashboard under Settings → Developers (self-serve, no waiting on us — see API keys). Pick exactly what this key needs — if you mint via the API directly and omit scopes, it defaults to gift_cards:redeem only (the most common POS scope), not “everything.” Scopes can’t be changed on an existing key — mint a new one with the right scopes and revoke the old one if you need to add or remove access.

What scope a request needs

Every endpoint in the API Reference lists its required scope. A request without that scope fails fast at the gateway — your downstream services never see the call.

API keys Rotating & revoking keys