Mobile Money – BudPay

Server to Server (Mobile Money)

The Mobile Money API lets you collect payments from customers' mobile money wallets directly from your application or custom checkout. BudPay sends a payment prompt to the customer's phone, and the customer approves it with their wallet PIN.

⚠️

Mobile Money supports GHS (Ghana) and KES (Kenya) only.

How it works

Get providers. Fetch the mobile money providers available for the currency.
Send a payment request. Call the payment_request endpoint. BudPay sends a payment prompt (STK push) to the customer's phone.
Receive a webhook. When the customer approves the payment, BudPay sends a notification to your callbackUrl.
Verify the payment. Confirm the status with the verify endpoint before you give value.

Step 1: Get Mobile Money Providers

Fetch the providers available for a currency. Use the name of the provider the customer chooses as bankName in Step 2.

Sample Request for KES

Endpoint: GET https://api.budpay.com/api/s2s/v2/momo/providers/KES

1curl -X GET 'https://api.budpay.com/api/s2s/v2/momo/providers/KES' \2  -H 'Content-Type: application/json' \3  -H 'Authorization: Bearer YOUR_SECRET_KEY'

Sample Response for KES

{
    "status": true,
    "message": "Momo Collection Providers Fetched",
    "currency": "KES",
    "banks": [
        {
            "name": "MPesa",
            "code": "63902"
        },
        {
            "name": "AirtelMoney",
            "code": "63903"
        },
        {
            "name": "T-Kash",
            "code": "63907"
        }
    ]
}

Sample Request for GHS

Endpoint: GET https://api.budpay.com/api/s2s/v2/momo/providers/GHS

1curl -X GET 'https://api.budpay.com/api/s2s/v2/momo/providers/GHS' \2  -H 'Content-Type: application/json' \3  -H 'Authorization: Bearer YOUR_SECRET_KEY'

Sample Response for GHS

{
    "status": true,
    "message": "Momo Collection Providers Fetched",
    "currency": "GHS",
    "banks": [
        {
            "name": "Airtel",
            "code": "AIR"
        },
        {
            "name": "Tigo",
            "code": "TIG"
        },
        {
            "name": "Vodafone",
            "code": "VOD"
        },
        {
            "name": "MTN",
            "code": "MTN"
        },
        {
            "name": "MasterCard",
            "code": "MAS"
        },
        {
            "name": "Bank",
            "code": "BNK"
        },
        {
            "name": "VISA",
            "code": "VIS"
        }
    ]
}

Step 2: Send a Payment Request

Call the payment_request endpoint to charge the customer's wallet. BudPay sends a payment prompt to the customer's phone, and the customer approves it by entering their wallet PIN.

Headers

Parameter	Description
`URL`	https://api.budpay.com/api/s2s/v2/momo/payment_request (opens in a new tab)
`Method`	`POST`
`Content-Type`	The content type of the request. Set this to `application/json`.
`Authorization`	The secret key used to authenticate the request, set this to `Bearer YOUR_SECRET_KEY`.

Request Body

Parameter	Type	Required	Description
`amount`	string	Yes	Amount to be paid.
`currency`	string	Yes	Currency of the payment.
`reference`	string	Yes	Unique reference for the transaction.
`bankName`	string	Yes	The provider `name` from Step 1, e.g. `MPesa`.
`phone`	string	Yes	Customer's mobile money number in international format, e.g. `25471xxxxxxx`.
`description`	string	Yes	Description of the payment.
`callbackUrl`	string	Yes	URL that receives the payment notification.

Sample Request

Endpoint: POST https://api.budpay.com/api/s2s/v2/momo/payment_request

1curl -X POST 'https://api.budpay.com/api/s2s/v2/momo/payment_request' \2  -H 'Content-Type: application/json' \3  -H 'Authorization: Bearer YOUR_SECRET_KEY' \4  -d '{5  "amount": "10",6  "bankName": "MPesa",7  "callbackUrl": "http://your_callback_url",8  "currency": "KES",9  "description": "Server to Server test",10  "phone": "25471xxxxxxx",11  "reference": "12536xxxxxxxx6350"12}'

Sample Response for KES

{
    "success": true,
    "detail": "MPESA STK sent. Enter your PIN to complete transaction",
    "ResponseDescription": "Success. STK PUSH SENT",
    "CustomerMessage": "1. GO TO 'LIPA NA MPESA' 2. SELECT 'PAY BILL' 3. ENTER BUSINESS NUMBER: 756756  4. ENTER ACCOUNT NUMBER: PR4571313_BUD INFRASTUCTURE LIMITED  5. ENTER AMOUNT:10 6. ENTER YOUR MPESA PIN AND PRESS OK"
}

Sample Response for GHS

{
    "success": true,
    "detail": "Request Sent",
    "ResponseDescription": "Request successfully received for processing",
    "CustomerMessage": "Kindly complete transaction on your phone"
}

Step 3: Handle the Payment Notification

When the customer approves the payment, BudPay sends a notification to your callbackUrl. Use it to update the order in your system, then verify the transaction before you give value.

Sample payload:

{
    "status": "success",
    "event": "collection",
    "channel": "momo",
    "currency": "KES",
    "amount": "10",
    "fee": "1",
    "requested_amount": "10",
    "type": "transaction",
    "reference": "BUD_16871757xxxxxxx57",
    "phone": "25471xxxxxxx",
    "PaymentGateway": "MPesa",
    "MerchantRequestID": "BUD_16871757xxxxxxx57",
    "CheckoutRequestID": "5ecd1799-c91b-xxxx-xxxx-xxxxxxxxd421",
    "domain": "live",
    "timestamp": "2023-06-19 12:05:00"
}

Verifying Transactions

Call the Verify Transaction API with the transaction reference:

GET https://api.budpay.com/api/v2/transaction/verify/:reference

Example Request:

Endpoint: GET https://api.budpay.com/api/v2/transaction/verify/BUD_1673600359168063493

1curl -X GET 'https://api.budpay.com/api/v2/transaction/verify/BUD_1673600359168063493' \2  -H 'Authorization: Bearer YOUR_SECRET_KEY'

{  "status": true,  "message": "Transaction verified successfully",  "data": {    "currency": "NGN",    "amount": "550",    "reference": "BUD_1673600359168063493",    "status": "success",    "message": "Payment successful",    "customer": {      "email": "customer@email.com"    }  }}

Always verify transactions on your server before fulfilling orders. Never rely solely on client-side callbacks or redirects.

Verification Workflow:

Receive callback/webhook with transaction reference
Call Verify API (server-side)
Check status === "success"
Verify amount matches expected
Fulfill order/deliver service

Learn more about verifying transactions.

Bank Transfer Pay with OPay