Mobile Money

The Mobile Money Payout API allows merchants to disburse funds directly to mobile money wallets across multiple African countries. This API uses a single-step process where you provide the recipient's details directly in the payout request.

Note: Currency and network availability depends on your business account permissions. Contact support to enable additional currencies.

How it works

The payout flow is asynchronous. Here is the typical journey:

Initiation: Send a POST request with the recipient's details and amount.
Processing: OGateway validates the request and processes the disbursement.
Verification: OGateway sends a Webhook to your callbackURL confirming the success or failure.

Base URL

https://api.ogateway.io

Authentication

All requests must include your API key in the Authorization header:

Authorization: your_api_key

API Key Types

Test Keys: Start with test_ (e.g., test_sk_xxxxx) - Used for testing in sandbox mode.
Live Keys: Start with live_ (e.g., live_sk_xxxxx) - Used for real transactions.

Important: V1 Payouts are primarily accessed via Test Keys for development.

Initiate Payout

Disburse funds to a mobile money wallet. Endpoint: POST /disbursements/mobilemoney

Body Parameters

Parameter	Type	Required	Description
recipients	array	Yes	An array containing the recipient details. Note: V1 currently supports only one recipient per request.
reference	string	Yes	A unique string to identify this transaction in your system. Must be unique.
callbackURL	string	No	The URL for the final transaction status webhook. This overrides the default callback URL saved under your business.

Recipient Object (inside `recipients` array)

Parameter	Type	Required	Description
amount	number	Yes	The amount to transfer (e.g., 50.00).
currency	string	Yes	The currency code (See Currency codes for available countries).
network	string	Yes	The mobile network provider (e.g., `MTN`, `VOD`, `ATM`, `ORANGE`).
accountName	string	Yes	The registered name of the wallet holder.
accountNumber	string	Yes	The recipient's mobile money number. Phone number will be automatically cleaned and normalized to international format.

Example Request

curl --request POST \
  --url https://api.ogateway.io/disbursements/mobilemoney \
  --header 'Authorization: your_api_key' \
  --header 'Content-Type: application/json' \
  --data '{
    "recipients": [
      {
        "amount": 50,
        "currency": "GHS",
        "network": "MTN",
        "accountName": "Jane Doe",
        "accountNumber": "0244123456"
      }
    ],
    "reference": "momo_payout_001",
    "callbackURL": "https://your-website.com/webhook"
  }'

Example Response (200 OK)

The API returns an array containing the initiated transaction details.

[
  {
    "id": "trans_987654321",
    "amount": 50,
    "fee": 0,
    "currency": "GHS",
    "status": "INITIATED",
    "channel": "MOMO",
    "type": "CREDIT",
    "customer": {
      "email": "",
      "accountName": "Jane Doe",
      "accountNumber": "0244123456"
    },
    "metadata": {
      "smsFee": 0
    },
    "reason": "CREDIT_MOMO",
    "network": "MTN",
    "checkout_url": null,
    "reference_business": "momo_payout_001",
    "provider_message": "",
    "virtual_account": null
  }
]

Example Error Response (400 Bad Request)

{
  "statusCode": 400,
  "message": "Only one recipient at a time please!",
  "error": "Bad Request"
}

See Error Codes for Error Responses.

Handling the Callback

See full details in our Callbacks section

Payouts are processed asynchronously. Listen for a Webhook at your callbackURL to confirm the final status.

Success Payload Example

{
  "id": "trans_987654321",
  "amount": 50,
  "fee": 0.5,
  "currency": "GHS",
  "status": "COMPLETED",
  "channel": "MOMO",
  "type": "CREDIT",
  "customer": {
    "accountName": "Jane Doe",
    "accountNumber": "233244123456"
  },
  "metadata": null,
  "reason": "CREDIT_MOMO",
  "network": "MTN",
  "checkout_url": null,
  "provider_message": "Success",
  "reference_business": "momo_payout_001",
  "created_at": "2023-10-27T10:05:00.000Z",
  "updated_at": "2023-10-27T10:05:30.000Z",
  "virtual_account": null,
  "error_message": null,
  "telco_response": "APPROVED",
  "instructions": null
}

Failed Payload Example

{
  "id": "trans_987654321",
  "amount": 50,
  "fee": 0,
  "currency": "GHS",
  "status": "FAILED",
  "channel": "MOMO",
  "type": "CREDIT",
  "customer": {
    "accountName": "Jane Doe",
    "accountNumber": "233244123456"
  },
  "metadata": null,
  "reason": "CREDIT_MOMO",
  "network": "MTN",
  "checkout_url": null,
  "provider_message": "Failed",
  "reference_business": "momo_payout_001",
  "created_at": "2023-10-27T10:05:00.000Z",
  "updated_at": "2023-10-27T10:06:00.000Z",
  "virtual_account": null,
  "error_message": "Transaction failed at the Provider",
  "telco_response": null,
  "instructions": null
}

Best Practices

Unique References: Always use a unique reference for each payout to avoid duplicates.
Wallet Balance: Ensure your OGateway wallet has sufficient funds for the payout amount plus applicable fees.
Idempotency: Do not retry failed requests immediately with the same reference; check the status first.
Single Recipient: Although the API accepts an array, ensure you only send one recipient object per request as multi-recipient support has been removed. The array has been left as-is for backward compatibility and may be removed in future versions.
Webhook Security: Verify webhook signatures to ensure callbacks originate from OGateway.