Skip to main content
View as Markdown

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.

Use MCP for mobile-money readiness and payment

An authenticated AI agent can check enabled methods and create an unpaid order. pay_order starts collection only after your exact confirmation; new wallet details and OTP stay in secure Inttegro Checkout. get_order verifies the final state.

MCP tools: get_payment_method_settings, create_order, pay_order or get_order

Confirmed MCP actions require explicit form confirmation before Inttegro changes state.

How it works

Mobile money payments can require more than one customer action. Create an order with executePayment set to true, inspect payment.nextAction, 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

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

Step 1: create the order

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

Create mobile money order

POST/orders/create
SDK versionv12.0.0
import * as Inttegro from '@inttegro/inttegro-sdk'

const inttegro = new Inttegro.InttegroClient({
  apiKey: process.env.INTTEGRO_API_KEY!,
})
const result = await inttegro.orders.create({
  requestMeta: {
    idempotencyKey: "order_momo_2025_001",
  },
  executePayment: true,
  customerData: {
    name: "Akosua Mensah",
    emailAddress: "[email protected]",
    phoneNumber: "+233244123456",
  },
  paymentMethodData: {
    type: Inttegro.PaymentMethodTypes.MobileMoney,
    mobileMoney: {
      network: Inttegro.MobileMoneyNetworks.MTN,
      accountNumber: "0244123456",
    },
  },
  lineItems: [
    {
      type: Inttegro.LineItemTypes.Product,
      product: {
        type: Inttegro.ProductTypes.Digital,
        name: "Premium Subscription - 1 Month",
        quantity: 1,
        price: {
          currency: "ghs",
          value: 5000,
        },
      },
    },
  ],
})

Key parameters​

The response includes the order, payment, and confirmation-request identifiers needed for the next action. Read payment.nextAction.confirmPayment.tokenSize, payment.nextAction.confirmPayment.sentVia, and payment.nextAction.confirmPayment.expiresAt instead of assuming fixed values.

Step 2: confirm customer intent with OTP

When payment.nextAction.type is Inttegro.PaymentNextActionTypes.ConfirmPayment, collect the token from the customer and submit it before payment.nextAction.confirmPayment.expiresAt. After confirmation, inspect the returned order again; some payments require a separate authorization action before they become paid.

Note

Confirmation is bound to the current order and confirmation request. Pass the identifiers and token returned by the create call to your SDK's confirmation operation. See Confirm a payment for the exact request shape in the selected SDK.

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

Common errors:

  • confirmation_bad_token - Ask the customer for the latest token and retry the confirmation call.
  • 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
SDK versionv12.0.0
import * as Inttegro from '@inttegro/inttegro-sdk'

const inttegro = new Inttegro.InttegroClient({
  apiKey: process.env.INTTEGRO_API_KEY!,
})
const result = await inttegro.orders.lookup({
  orderId: "or_abc123xyz",
})

Payment statuses: Inttegro.PaymentStatuses.RequiresAction while waiting for confirmation, Inttegro.PaymentStatuses.Paid after success, Inttegro.PaymentStatuses.Failed after a failed or canceled payment, and Inttegro.PaymentStatuses.Expired when the authorization window closes.

Important details

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

Order limits: Each order can contain up to 64 line items. Order totals are capped at 100,000 for "ghs" and 50,000 for all other supported currencies, measured in the currency's smallest unit. Contact support if you need these limits increased.

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: Inttegro validates that paymentMethodData.mobileMoney.network matches the 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.