Skip to content
MojoPay Omni OMNI Payments API

Payments API

Global conventions

  • JSON request/response; send Content-Type: application/json for JSON bodies.
  • currency: ISO 4217 (GHS, NGN, ...).
  • mobile: digits only, country code first, no + and no spaces (example: 233544338841).
  • amount: non-negative string decimal; up to 4 dp internally, displayed/settled at 2 dp (ceil).
  • merchant_reference: merchant-generated reference; echoed in responses and webhooks.
  • Authorization: Bearer <access_token> on every protected endpoint.
  • Idempotency-Key: required on POST endpoints that move money or create sessions/mandates, and on mandate cancellation (state-changing).
  • Public IDs — uppercase prefixes such as CL_, CS_, PO_, MD_ (lookups are case-insensitive).
  • request_id (errors) — REQ_ + 12 uppercase alphanumeric characters (example: REQ_8F3A2C1B9D0E).
  • Webhook event id — EVT_ + 24 uppercase alphanumeric characters.
  • Flat request bodies (collections, checkout, payouts, mandates): use top-level mobile and provider for wallet rails instead of nested customer / beneficiary objects. This reduces nesting and copy-paste mistakes.
  • Sub-accounts (only when enabled for your merchant): send X-Mojo-Account-Ref on every bearer-authenticated request to scope it to a specific sub-account (use main for the primary account). Metadata endpoints (/v1/metadata/*) ignore the header. Idempotency keys and merchant_reference lookups are scoped per resolved account. Call GET /v1/account to confirm the account a request resolves to. When sub-accounts are not enabled, omit the header.