Paywithmomo – Cashonrails 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://api.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",
        "XOF",
        "XAF",
        "UGX",
        "MWK",
        "RWF",
        "ZMW",
        "SSP",
        "ETB"
        ]
}

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


{
    "success": true,
    "message": "Test Successful, Kindly check your device for prompt",
    "data": {
        "_links": {
            "url": "https://api.cashonrails.com/api/v1/s2s/transaction/verify/s2sref_2858705278271673",
            "method": "GET"
        }
    }
}

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 Mobile Money, Vodafone Cash, AirtelTigo Money
TZS	Tanzania	Tigo, Airtel, Halotel
KES	Kenya	M-Pesa, Airtel Money, T-Kash, SAFKEN
SLE	Sierra Leone	Orange
XOF	West Africa (BCEAO)	Moov, MTN, Orange, Wave
XAF	Central Africa (BEAC)	MTN, Orange
UGX	Uganda	MTN Mobile Money, Airtel
MWK	Malawi	Airtel, TNM Mpamba
RWF	Rwanda	MTN, Airtel
ZMW	Zambia	MTN, Airtel, Zamtel
SSP	South Sudan	MTN
ETB	Ethiopia	Telebirr, CBE Birr, Mpesa

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