Mobile Money Collections

This guide covers collecting payments via Mobile Money. The collection flow may require an OTP verification step depending on the customer's network and regulations.

There are two endpoints for Mobile Money collection: 1. Initiate Collection 2. Verify OTP (only if otpRequired is true in the initiate response)

Initiate Mobile Money Collection

• Path: /api/v1/mobile-money/collection
• Method: POST
• Headers:
• Accept: application/json
• Content-Type: application/json
• Authorization: Bearer {merchant_api_bearer_token}

Request Body Table

Field	Type	Required	Description
amount	string	Yes	Amount for the transaction
reference	string	Yes	Unique reference for the transaction
businessId	string	Yes	Your business identifier
customer	object	Yes	Customer information
customer.name	string	Yes	Customer's full name
customer.email	string	Yes	Customer's email address
customer.phone	string	Yes	Customer's phone number
customer.address	object	Yes	Customer's address information
customer.address.city	string	Yes	City
customer.address.postalCode	string	Yes	Postal code
customer.address.countryCode	string	Yes	Alpha-2 country code
narration	string	No	Description for the transaction
momoNetwork	string	Yes	Mobile money network code (see Fetch List of MoMo Networks)
initiatingCode	string	No	Pre-OTP code generated from the network; required only for networks that support Pre-OTP initiation

Request Body (Standard, all fields specified are required)

{
  "customer": {
    "name": "Olamide Smith",
    "email": "olamide.smith@mail.com",
    "address": {
      "postalCode": "101",
      "countryCode": "NG",
      "city": "Lagos"
    },
    "phone": "+2250788000001"
  },
  "amount": "3500",
  "businessId": "{{businessId}}",
  "reference": "{{unique_reference}}",
  "narration": "Mobile Money Payment from Olamide",
  "momoNetwork": "MPESA_KENYA"
}

Request Body (For networks that require Pre-OTP)

{
  "customer": {
    "name": "Olamide Smith",
    "email": "olamide.smith@mail.com",
    "address": {
      "postalCode": "101",
      "countryCode": "NG",
      "city": "Lagos"
    },
    "phone": "+2250788000001"
  },
  "amount": "3500",
  "businessId": "{{businessId}}",
  "reference": "{{unique_reference}}",
  "narration": "Mobile Money Payment from Olamide",
  "momoNetwork": "ORANGE_COTE_DIVOIRE",
  "initiatingCode": "{{pre_otp_code_generated_from_network}}"
}

Sample Response

{
  "status": 200,
  "message": "Success",
  "data": {
    "accountName": "Olamide Smith",
    "mobileNumber": "+2250788000001",
    "paymentStatus": "PROCESSING",
    "network": "ORANGE_COTE_DIVOIRE",
    "amount": 3500,
    "onusReference": "{{onusRef}}",
    "merchantReference": "{{reference}}",
    "otpRequired": true
  }
}

Notes: - Store both merchantReference and onusReference for reconciliation. - If otpRequired is true, call the Verify OTP endpoint below to complete the charge.

Verify OTP (if required)

• Path: /api/v1/mobile-money/collection/verify-otp
• Method: POST
• Headers:
• Accept: application/json
• Content-Type: application/json
• Authorization: Bearer {merchant_api_bearer_token}

Request Body Table

Field	Type	Required	Description
businessId	string	Yes	Your business identifier
onusReference	string	Yes	The onusReference returned in the Initiate Collection response
otp	string	Yes	The OTP received by the customer

Request Body

{
  "businessId": "{{businessId}}",
  "onusReference": "{{onusRef}}",
  "otp": "654321"
}

Sample Response

{
  "status": 200,
  "message": "Success",
  "data": {
    "accountName": "Olamide Smith",
    "mobileNumber": "+2250788000001",
    "paymentStatus": "PROCESSING",
    "network": "ORANGE_COTE_DIVOIRE",
    "amount": 3500,
    "onusReference": "{{onusRef}}",
    "merchantReference": "{{reference}}",
    "otpRequired": false
  }
}

Fetch List of MoMo Networks

• Path: /api/v1/mobile-money/networks
• Method: GET
• Headers:
  • Content-Type: application/json
  • Authorization: Bearer {merchant_api_bearer_token}

Sample Response

{
  "status": 200,
  "message": "Success",
  "data": [
    {
      "VODAFONE_GHANA": {
        "currency": "GHS",
        "countryCode": "GH"
      }
    },
    {
      "MPESA_KENYA": {
        "currency": "KES",
        "countryCode": "KE"
      }
    },
    {
      "ORANGE_COTE_DIVOIRE": {
        "currency": "XOF",
        "countryCode": "CI"
      }
    }
  ]
}

Additional Information

• The paymentStatus may transition from PROCESSING to a terminal state (SUCCESSFUL or FAILED). Monitor status via your webhooks, or query a specific transaction using the Verify Single Payment endpoint with the onusReference.
• momoNetwork should match the supported network codes for the customer's country.
• Ensure amount formatting matches your integration settings; provide as a string or decimal as shown.