LogoZebo Studio

Accept mobile money payments

Mobile money is Ghana's dominant payment method, accounting for over 70% of digital transactions. This guide shows you how to accept payments from MTN, Telecel, and AirtelTigo wallets through a three-phase flow: create an order, confirm customer intent with an OTP, then wait for payment authorization.

How it works

Mobile money payments can require more than one customer action. Create an order with execute_payment: true, inspect order.payment.next_action, and present the requested confirmation or authorization experience. After each action, use the returned order state to decide whether to wait, request confirmation, or consider the payment paid.

Supported networks

Commerce integrates with all three major networks in Ghana: MTN Mobile Money (24M+ wallets), Telecel Cash (8M+ wallets), and AirtelTigo Money (6M+ wallets). Commerce automatically routes transactions based on phone number prefix—no network-specific integration needed.

Prerequisites

Get your production API keys from your Commerce dashboard under Settings → API Keys. Test your integration in sandbox mode before going live.

Step 1: Create the order

Creating an order bundles the customer, payment method, and line items into one request. Setting execute_payment: true starts payment execution; the response tells you whether customer confirmation is required.

Create mobile money order

POST
/orders/new
curl https://api.zebo.dev/orders/new \
  -H "Authorization: Bearer $COMMERCE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "request_meta": {
    "idempotency_key": "order_momo_2025_001"
  },
  "execute_payment": true,
  "customer_data": {
    "name": "Akosua Mensah",
    "email_address": "[email protected]",
    "phone_number": "+233244123456"
  },
  "payment_method_data": {
    "type": "mobile_money",
    "mobile_money": {
      "network": "mtn",
      "account_number": "0244123456"
    }
  },
  "line_items": [
    {
      "type": "product",
      "product": {
        "type": "digital",
        "name": "Premium Subscription - 1 Month",
        "quantity": 1,
        "price": {
          "currency": "ghs",
          "value": 5000
        }
      }
    }
  ]
}'

Key parameters

  • request_meta.idempotency_key or Idempotency-Key - Unique identifier to prevent duplicate charges. Use order references or UUIDs.
  • execute_payment - Set to true to initiate payment immediately.
  • payment_method_data.mobile_money.network - Network: "airtel", "mtn", "telecel", or "vodafone".
  • payment_method_data.mobile_money.account_number - Wallet phone number (local or international format).
  • Amounts - In minor units (pesewas). GHS 50.00 = 5000.

The response includes the order, payment, and confirmation-request identifiers needed for the next action. Read the token size, delivery channel, and expiry from order.payment.next_action.confirm_payment instead of assuming fixed values.

Step 2: Confirm customer intent with OTP

When the next action is confirm_payment, collect the token from the customer and submit it before the response's expires_at time. After confirmation, inspect the returned order again; some payments require a separate authorization action before they become paid.

Confirmation is bound to one order, payment, and confirmation request. Use order.payment.id as payment_id and order.payment.next_action.confirm_payment.request.id as confirmation_id, then submit those values with order_id and token. See Confirm a payment for complete language-native HTTPS examples in all eight supported languages.

Commerce validates the token and returns the latest order state. Continue only according to order.payment.next_action; don't assume confirmation alone completed the charge.

Common errors:

  • confirmation_bad_token - Ask the customer for the latest token and retry with the same four identifiers.
  • confirmation_expired - Request a new confirmation before retrying.
  • confirmation_max_reached - Request a new confirmation because the active request has no attempts remaining.

Step 3: Verify payment status

After the customer authorizes the payment with their mobile money provider, look up the order to verify completion. This typically happens within 5-15 seconds after authorization:

Check payment status

POST
/orders/lookup
curl https://api.zebo.dev/orders/lookup \
  -H "Authorization: Bearer $COMMERCE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "order_id": "or_abc123xyz"
}'

Statuses: requires_action (waiting for OTP), paid (success), failed (insufficient balance, cancelled), expired (5-minute window closed).

Important details

Transaction limits: MTN (GHS 5K/transaction, 10K daily), Telecel (3K/transaction, 5K daily), AirtelTigo (2K/transaction, 3K daily). Exceeding limits returns amount_too_large error.

Settlement: Real-time to your balance, but 7-day aging period before payout eligibility (Bank of Ghana dispute window).

Pricing: 1.5% + GHS 0.50 per transaction, deducted before funds reach your balance.

Network detection: Commerce validates network matches phone prefix (MTN: 024/054/055/059, Telecel: 020/050, AirtelTigo: 027/057/026/056).

Next steps

You're now accepting mobile money payments! Here's what to explore next:

For detailed parameter documentation, see the Orders API reference.

Was this page helpful?