Overview

Welcome to the FCDA Mobile Money API Documentation. This API allows you to easily integrate mobile money payments into your applications using MTN and Orange mobile money services in Cameroon.

Base URL: https://market.fcdacameroon.org/api/mobile_money_api.php
Test Page: https://market.fcdacameroon.org/api/test_api.php

Key Features:

Supported Services:

MTN Mobile Money

Phone numbers starting with 67, 65, 68

Orange Money

Phone numbers starting with 69, 66

Quick Start

Follow these steps to get started with the FCDA Mobile Money API.

1. Obtain API Credentials

Contact the FCDA team to get your API Key. For testing, you can use the demo key: demo_key_123

2. Test the API

Visit the test page to verify the API is working:


# Visit in your browser:
https://market.fcdacameroon.org/api/test_api.php

3. Make Your First API Call

Check API status using curl:


curl -X GET "https://market.fcdacameroon.org/api/mobile_money_api.php" \
-H "Content-Type: application/json" \
-H "X-API-Key: demo_key_123"

Authentication

The API uses API Key authentication. Include your API Key in the X-API-Key header of all requests.

Available API Keys

API Key Client Environment
demo_key_123 Demo Client Development
live_key_456 Production Client Production

Header Format

X-API-Key: YOUR_API_KEY

API Endpoints

All endpoints are accessed through /api/mobile_money_api.php with different HTTP methods and request bodies.

API Status

Check the status and configuration of the API.

GET /api/mobile_money_api.php

Example Request


curl -X GET "https://market.fcdacameroon.org/api/mobile_money_api.php" \
-H "Content-Type: application/json" \
-H "X-API-Key: demo_key_123"

Response


{
    "success": true,
    "data": {
        "api_version": "1.0.0",
        "status": "online",
        "timestamp": "2024-05-31 10:30:00",
        "timezone": "Africa/Douala",
        "supported_services": ["MTN", "ORANGE"],
        "supported_currency": "XAF",
        "minimum_amount": {
            "collection": 100,
            "deposit": 500
        }
    },
    "timestamp": "2024-05-31 10:30:00",
    "api_version": "1.0.0"
}

Collect Payment

Initiate a payment collection from a mobile money account.

POST /api/mobile_money_api.php

Request Body Parameters

Parameter Type Required Description
amount number Yes Amount to collect (minimum 100 XAF)
phone string Yes Mobile money number (with or without +237)
service string Yes MTN or ORANGE
reference string No Your unique transaction reference
message string No Description for the transaction
callback_url string No URL to receive webhook notifications

Example Request


curl -X POST "https://market.fcdacameroon.org/api/mobile_money_api.php" \
-H "Content-Type: application/json" \
-H "X-API-Key: demo_key_123" \
-d '{
    "amount": 1500,
    "phone": "671234567",
    "service": "MTN",
    "reference": "order-12345",
    "message": "Payment for order #12345"
}'

Success Response


{
    "success": true,
    "data": {
        "reference": "order-12345",
        "transaction_id": "mesomb-tx-abcdef123456",
        "amount": 1500,
        "phone": "671234567",
        "service": "MTN",
        "status": "completed",
        "message": "Payment processed successfully"
    },
    "timestamp": "2024-05-31 10:35:00",
    "api_version": "1.0.0"
}

Send Money (Deposit)

Send money to a mobile money account (payout).

POST /api/mobile_money_api.php

Request Body Parameters

Parameter Type Required Description
amount number Yes Amount to send (minimum 500 XAF)
phone string Yes Mobile money number (service auto-detected)
reference string No Your unique transaction reference
message string No Description for the transaction
callback_url string No URL to receive webhook notifications

Example Request


curl -X POST "https://market.fcdacameroon.org/api/mobile_money_api.php" \
-H "Content-Type: application/json" \
-H "X-API-Key: demo_key_123" \
-d '{
    "amount": 5000,
    "phone": "691234567",
    "reference": "payout-67890",
    "message": "Withdrawal payment"
}'

Transaction Status

Check the status of a specific transaction.

GET /api/mobile_money_api.php?reference=YOUR_REFERENCE

Example Request


curl -X GET "https://market.fcdacameroon.org/api/mobile_money_api.php?reference=order-12345" \
-H "X-API-Key: demo_key_123"

Response


{
    "success": true,
    "data": {
        "reference": "order-12345",
        "type": "collection",
        "amount": 1500,
        "phone": "671234567",
        "service": "MTN",
        "status": "completed",
        "created_at": "2024-05-31 10:30:00",
        "updated_at": "2024-05-31 10:35:00"
    },
    "timestamp": "2024-05-31 10:40:00",
    "api_version": "1.0.0"
}

Account Balance

Check account balance (placeholder endpoint).

GET /api/mobile_money_api.php with balance request

This endpoint is not fully implemented. Contact MeSomb for balance inquiries.

Webhooks

Receive real-time notifications when transaction status changes. Include a callback_url in your payment requests to enable webhooks.

Webhook Payload


{
    "reference": "order-12345",
    "status": "completed",
    "amount": 1500,
    "transaction_id": "mesomb-tx-abcdef123456"
}

Webhook Endpoint

The API also provides a webhook endpoint for receiving external notifications:

POST /api/mobile_money_api.php (webhook handler)

Error Handling

The API returns standardized error responses with appropriate HTTP status codes.

HTTP Status Codes

Client Errors (4xx)

  • 400 - Bad Request (missing/invalid parameters)
  • 401 - Unauthorized (invalid API key)
  • 404 - Not Found (endpoint/transaction not found)
  • 405 - Method Not Allowed

Server Errors (5xx)

  • 500 - Internal Server Error
  • 503 - Service Unavailable

Error Response Format


{
    "success": false,
    "message": "Missing required field: amount",
    "timestamp": "2024-05-31 10:30:00",
    "api_version": "1.0.0"
}

Code Examples

Complete examples in different programming languages.

PHP Example


Payment failed:

Python Example


import requests
import json

api_url = 'https://market.fcdacameroon.org/api/mobile_money_api.php'
api_key = 'demo_key_123'

headers = {
    'Content-Type': 'application/json',
    'X-API-Key': api_key
}

# Check API status
status_response = requests.get(api_url, headers=headers)
print("API Status:", status_response.json())

# Collect payment
payment_data = {
    'amount': 1500,
    'phone': '671234567',
    'service': 'MTN',
    'reference': 'order-123456',
    'message': 'Payment for goods'
}

payment_response = requests.post(api_url, 
                               headers=headers, 
                               data=json.dumps(payment_data))

result = payment_response.json()
if result['success']:
    print(f"Payment successful: {result['data']['transaction_id']}")
else:
    print(f"Payment failed: {result['message']}")

JavaScript (Node.js) Example


const axios = require('axios');

const apiUrl = 'https://market.fcdacameroon.org/api/mobile_money_api.php';
const apiKey = 'demo_key_123';

const headers = {
    'Content-Type': 'application/json',
    'X-API-Key': apiKey
};

// Collect payment
async function collectPayment() {
    try {
        const paymentData = {
            amount: 1500,
            phone: '671234567',
            service: 'MTN',
            reference: 'order-' + Date.now(),
            message: 'Payment for goods'
        };

        const response = await axios.post(apiUrl, paymentData, { headers });
        
        if (response.data.success) {
            console.log('Payment successful:', response.data.data.transaction_id);
        } else {
            console.log('Payment failed:', response.data.message);
        }
    } catch (error) {
        console.error('Error:', error.response?.data || error.message);
    }
}

collectPayment();

Testing

The API includes a comprehensive test suite to verify all endpoints are working correctly.

Test Suite

Visit the test page in your browser to run all API tests:

https://market.fcdacameroon.org/api/test_api.php

Test Configuration

The test suite uses the following default configuration:

Parameter Value
API Key demo_key_123
Test MTN Number 671234567
Test Orange Number 691234567
Test Collection Amount 1000 XAF
Test Deposit Amount 2000 XAF

What Gets Tested

Support

Need help integrating the FCDA Mobile Money API? We're here to help.

Contact Information

Developer Contact

Hans Ade

Business Inquiries

  • business@fcdacameroon.org
  • www.fcdacameroon.org

Quick Troubleshooting

401 Unauthorized Error

Check that you're including the X-API-Key header with a valid API key.

400 Bad Request Error

Verify all required parameters are included and have valid values. Check minimum amounts.

Transaction Failed

Ensure the phone number matches the selected service and has sufficient balance.