Cashonrails - Developer Documentation

Pay with MoMo

Overview

Pay with MoMo allows customers to make payments directly through supported mobile money providers like MTN, Airtel, and other networks across different countries.

Base URL

https://mainapi.cashonrails.com/api/v1/s2s

Integration Steps

1. Get Supported Currencies

First, retrieve the list of supported currencies for mobile money payments:

curl -X GET '{{baseurl}}/paywithmomo-list' \
-H "Authorization: Bearer YOUR_SECRET_KEY"

Sample Response

{
    "success": true,
    "status": "00",
    "data": [
        "GHS",
        "TZS",
        "KES",
        "SLE",
        "CMR",
        "UGX",
        "BEN",
        "CIV"
    ]
}

2. Get Available MoMo Providers

Retrieve the list of supported mobile money providers for a specific currency:

curl -X GET '{{baseurl}}/paywithmomo/{currency}' \
-H "Authorization: Bearer YOUR_SECRET_KEY"

Replace {currency} with the desired currency code (e.g., GHS, UGX, KES).

Sample Response

{
    "success": true,
    "status": "00",
    "data": [
        {
            "name": "MTN MOBILE MONEY",
            "code": "MTN"
        },
        {
            "name": "VODAFONE CASH",
            "code": "VOD"
        },
        {
            "name": "AIRTELTIGO MONEY",
            "code": "AIR"
        }
    ]
}

3. Initialize Payment

Make a POST request to initialize the mobile money payment:

curl --location '{{baseurl}}/paywithmomo/initialize' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_SECRET_KEY' \
--data-raw '{
    "email": "customer@email.com",
    "amount": "100",
    "currency": "GHS",
    "reference": "{{reference}}",
    "phone_number": "233244123456",
    "code": "MTN"
}'

Request Parameters

Parameter	Type	Required	Description
email	string	Yes	Customer’s email address
amount	string	Yes	Amount to charge
currency	string	Yes	Currency code (e.g., GHS, UGX, KES)
reference	string	Yes	Unique transaction reference
phone_number	string	Yes	Customer’s mobile money number
code	string	Yes	MoMo provider code from step 2

Sample Response

{
    "status": true,
    "message": "Mobile money payment initiated successfully",
    "data": {
        "reference": "s2sref_2858705278271676",
        "status": "pending",
        "payment_method": "mobile_money",
        "provider": "MTN",
        "phone_number": "233244123456"
    }
}

4. Customer Authorization

After initialization, the customer will receive a USSD prompt or push notification on their mobile device to authorize the payment. They need to enter their mobile money PIN to complete the transaction.

5. Verify Transaction

After the customer completes the authorization, verify the transaction status:

curl -X GET '{{baseurl}}/transaction/verify/{reference}' \
-H "Authorization: Bearer YOUR_SECRET_KEY"

Sample Success Response

{
    "status": true,
    "message": "Transaction verified successfully",
    "data": {
        "reference": "s2sref_2858705278271676",
        "amount": "100",
        "currency": "GHS",
        "status": "success",
        "payment_method": "mobile_money",
        "provider": "MTN",
        "phone_number": "233244123456",
        "transaction_date": "2024-02-21T12:34:56Z"
    }
}

Sample Failed Response

{
    "status": false,
    "message": "Transaction failed",
    "data": {
        "reference": "s2sref_2858705278271676",
        "status": "failed",
        "reason": "Insufficient balance"
    }
}

⚠️

Always verify the transaction status before confirming payment to the customer. Mobile money transactions may take a few minutes to process.

6. Cancel Transaction

You can cancel a transaction that is still pending:

curl -X GET {{baseurl}}/transaction/cancel/{reference} \
-H "Authorization: Bearer YOUR_SECRET_KEY"

Replace {reference} with your transaction reference.

Cancel Transaction Response

Success Response:

{
    "success": true,
    "message": "Transaction cancelled successfully",
    "data": {
        "reference": "s2sref_2858705278271676",
        "status": "cancelled",
        "amount": "100",
        "currency": "GHS",
        "cancelledAt": "2024-02-21T12:34:56Z"
    }
}

Cancellation Rules

⚠️

Only pending transactions can be cancelled
Once the customer has authorized the payment, it cannot be cancelled
Completed transactions cannot be cancelled (use refund instead)
Failed transactions are already inactive and don’t need cancellation

Supported Countries & Currencies

Currency	Country/Region	Providers
GHS	Ghana	MTN, Vodafone, AirtelTigo
TZS	Tanzania	Various providers
KES	Kenya	Various providers
SLE	Sierra Leone	Various providers
CMR	Cameroon	Various providers
UGX	Uganda	Various providers
BEN	Benin	Various providers
CIV	Ivory Coast	Various providers

Best Practices

Phone Number Format: Ensure phone numbers include the country code
Timeout Handling: Mobile money transactions may take 2-5 minutes
Status Polling: Check transaction status periodically for pending payments
Error Handling: Implement proper error handling for failed authorizations
Currency Selection: Always fetch supported currencies first to ensure availability

Pay with Phone Pay with EFT