---
title: "Accept mobile money payments"
description: "Accept mobile money payments from MTN, Telecel, and AirtelTigo customers across Ghana with real-time settlement."
canonical: "https://studio.inttegro.com/guides/accept-mobile-money-payment"
format: inttegro-machine-docs/v1
language: "Ruby"
sdk_version: "v10.0.0"
reader_profile: optional
reader_manifest: "https://studio.inttegro.com/machine/ruby/readers/index.json"
reader_identification: "Optional: declare your client only if known and your current-session capabilities; use reader_manifest for supplemental recommendations."
preamble_estimated_tokens: 465
model_token_report: "https://studio.inttegro.com/machine/token-report.json"
preamble_questions: 5
preamble_source: "curated"
recommended_mcp_tools: ["get_integration_guide","check_integration_readiness","get_order"]
estimated_tokens: 2727
token_estimate_method: "utf8_bytes_divided_by_4"
---

## Machine preamble

**Summary:** Create a mobile-money order, follow its requested customer actions, and reconcile the final payment from current order state.

### Five questions

#### Q1. What sequence does a mobile-money payment require?

Create an order that starts payment execution, then use the returned next action to present any requested confirmation or authorization. [Orders](https://studio.inttegro.com/machine/ruby/api/orders.md#create-an-order) defines the request and current state.

#### Q2. How should the next customer action be chosen?

Inspect the current order payment next action after each phase. Do not assume that one SMS, one prompt, or one network-specific branch completes every payment.

#### Q3. Is a separate integration needed for each Ghanaian network?

No. The documented flow supports MTN, Telecel, and AirtelTigo wallets; Inttegro routes by phone-number prefix. Check enabled payment-method settings before promising availability.

#### Q4. When may the business treat the payment as paid?

Only after [reading current order state](https://studio.inttegro.com/machine/ruby/api/orders.md#lookup-an-order) and seeing the paid outcome. A confirmation request, authorization prompt, or browser return may be intermediate.

#### Q5. Which MCP abilities help with readiness and tracking?

With an authenticated connection, [get_payment_method_settings](https://studio.inttegro.com/machine/ruby/inttegro-mcp/tools.md#get_payment_method_settings) checks availability, [create_order](https://studio.inttegro.com/machine/ruby/inttegro-mcp/tools.md#create_order) creates an unpaid order, and [pay_order](https://studio.inttegro.com/machine/ruby/inttegro-mcp/tools.md#pay_order) starts collection only after exact confirmation. [get_order](https://studio.inttegro.com/machine/ruby/inttegro-mcp/tools.md#get_order) reconciles status.

## Document content

# 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.

> Mcp Guide Callout is interactive content. Use the canonical page to view it.

## How it works

Mobile money payments can require more than one customer action. Create an order with `execute_payment` set to `true`, inspect [`order.payment.next_action`](https://ruby.inttegro.dev/v10.0.0/Inttegro/order.Order.html), 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 `execute_payment` to `true` starts payment execution; the response tells you whether customer confirmation is required.

**Create mobile money order — POST /orders/create**

```ruby
require "inttegro"

client = Inttegro::Client.new(api_key: ENV.fetch("INTTEGRO_API_KEY"))
result = client.orders.create(
  request_meta: {
    idempotency_key: "order_momo_2025_001",
  },
  execute_payment: true,
  customer_data: {
    name: "Akosua Mensah",
    email_address: "akosua@example.com",
    phone_number: "+233244123456",
  },
  payment_method_data: {
    type: Inttegro::PaymentMethodType::MOBILE_MONEY,
    mobile_money: {
      network: Inttegro::MobileMoneyNetwork::MTN,
      account_number: "0244123456",
    },
  },
  line_items: [
    {
      type: Inttegro::LineItemType::PRODUCT,
      product: {
        type: Inttegro::ProductType::DIGITAL,
        name: "Premium Subscription - 1 Month",
        quantity: 1,
        price: {
          currency: "ghs",
          value: 5000,
        },
      },
    },
  ]
)
```

### Key parameters

- **`execute_payment`** - Set to `true` to initiate payment immediately.
- **`payment_method_data.mobile_money.network`** - Use [`Inttegro::Shared::MobileMoneyNetwork::AIRTEL`](https://ruby.inttegro.dev/v10.0.0/Inttegro/Shared/MobileMoneyNetwork.html#AIRTEL-constant), [`Inttegro::Shared::MobileMoneyNetwork::MTN`](https://ruby.inttegro.dev/v10.0.0/Inttegro/Shared/MobileMoneyNetwork.html#MTN-constant), [`Inttegro::Shared::MobileMoneyNetwork::TELECEL`](https://ruby.inttegro.dev/v10.0.0/Inttegro/Shared/MobileMoneyNetwork.html#TELECEL-constant), or [`Inttegro::Shared::MobileMoneyNetwork::VODAFONE`](https://ruby.inttegro.dev/v10.0.0/Inttegro/Shared/MobileMoneyNetwork.html#VODAFONE-constant).
- **`payment_method_data.mobile_money.account_number`** - The wallet phone number in local or international format.
- **`line_items[].product.price.value`** - Use minor units (pesewas). GHS 50.00 is `5000`.

The response includes the order, payment, and confirmation-request identifiers needed for the next action. Read [`order.payment.next_action.confirm_payment.request.token_size`](https://ruby.inttegro.dev/v10.0.0/Inttegro/order.Order.html), [`order.payment.next_action.confirm_payment.request.sent_via`](https://ruby.inttegro.dev/v10.0.0/Inttegro/order.Order.html), and [`order.payment.next_action.confirm_payment.expires_at`](https://ruby.inttegro.dev/v10.0.0/Inttegro/order.Order.html)  instead of assuming fixed values.

## Step 2: confirm customer intent with OTP

When [`order.payment.next_action.type`](https://ruby.inttegro.dev/v10.0.0/Inttegro/order.Order.html)  is [`Inttegro::Payment::NextActionType::CONFIRM_PAYMENT`](https://ruby.inttegro.dev/v10.0.0/Inttegro/Payment/NextActionType.html#CONFIRM_PAYMENT-constant), collect the token from the customer and submit it before [`order.payment.next_action.confirm_payment.expires_at`](https://ruby.inttegro.dev/v10.0.0/Inttegro/order.Order.html). 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](https://studio.inttegro.com/machine/ruby/api/orders.md#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 [`order.payment.next_action`](https://ruby.inttegro.dev/v10.0.0/Inttegro/order.Order.html); 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**

```ruby
require "inttegro"

client = Inttegro::Client.new(api_key: ENV.fetch("INTTEGRO_API_KEY"))
result = client.orders.lookup(order_id: "or_abc123xyz")
```

Payment statuses: [`Inttegro::Payment::Status::REQUIRES_ACTION`](https://ruby.inttegro.dev/v10.0.0/Inttegro/Payment/Status.html#REQUIRES_ACTION-constant)  while waiting for confirmation, [`Inttegro::Payment::Status::PAID`](https://ruby.inttegro.dev/v10.0.0/Inttegro/Payment/Status.html#PAID-constant)  after success, [`Inttegro::Payment::Status::FAILED`](https://ruby.inttegro.dev/v10.0.0/Inttegro/Payment/Status.html#FAILED-constant)  after a failed or canceled payment, and [`Inttegro::Payment::Status::EXPIRED`](https://ruby.inttegro.dev/v10.0.0/Inttegro/Payment/Status.html#EXPIRED-constant)  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 [`Inttegro::Money::Currency::GHS`](https://ruby.inttegro.dev/v10.0.0/Inttegro/Money/Currency.html#GHS-constant)  and 50,000 for all other supported currencies, measured in the currency's smallest unit. Contact [support](mailto:support@inttegro.com)  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 `payment_method_data.mobile_money.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:

- **[Charge repeat customers](https://studio.inttegro.com/machine/ruby/guides/charge-repeat-customers.md)** - Save payment methods for one-click checkout
- **[Handle payment failures](https://studio.inttegro.com/machine/ruby/guides/retry-a-payment.md)** - Retry failed transactions gracefully
- **[Set up payouts](https://studio.inttegro.com/machine/ruby/products/payouts.md)** - Withdraw funds to your bank account
- **[Understand payment method settings](https://studio.inttegro.com/machine/ruby/guides/understand-payment-method-settings.md)** - Configure verification and confirmation requirements

For detailed parameter documentation, see the [Orders API reference](https://studio.inttegro.com/machine/ruby/api/orders.md).