Payments API

Errors

{
  "error": {
    "code": "invalid_parameter",
    "message": "Provider is required for mobile money payouts.",
    "doc_url": "https://omni.mojo-pay.com/doc/payments",
    "request_id": "REQ_8F3A2C1B9D0E"
  }
}

Common HTTP codes: 400, 401, 403, 404, 409, 429, 500.

Idempotency conflict (409) — same Idempotency-Key reused with a different JSON body than the first request:

{
  "error": {
    "code": "idempotency_key_mismatch",
    "message": "Key was already used with a different request body.",
    "doc_url": "https://omni.mojo-pay.com/doc/payments",
    "request_id": "REQ_9F3A2C1B8E7D"
  }
}

Error code catalog (v1)

doc_url points to https://omni.mojo-pay.com/doc/payments for the in-app guide and error catalog. Responses may omit doc_url in some environments.

Code	HTTP	Meaning
`invalid_parameter`	400	Validation or missing required header/field (e.g. `Idempotency-Key`).
`idempotency_key_mismatch`	409	Same idempotency key, different request body.
`idempotency_key_in_progress`	409	A request with the same idempotency key is still being processed; retry shortly.
`duplicate_merchant_reference`	409	`merchant_reference` already used for another payout; use a new reference.
`invalid_client`	401	OAuth client id/secret invalid or client revoked.
`forbidden`	403	Authenticated but not allowed (e.g. merchant API access disabled).
`unauthorized`	401	Missing/invalid Bearer token or expired token.
`not_found`	404	Unknown resource for this merchant.
`rate_limited`	429	Too many requests; use `Retry-After` when present.
`gateway_error`	502	Upstream payment/KYC provider error or timeout; safe to retry idempotent reads or a new idempotency key for writes.
`internal_error`	500	Unexpected server error (reserved; include `request_id` for support).

Machine-readable contract: docs/openapi/mojopay-v1.openapi.yaml.