Mobile Money – BudPay

Server to Server (Mobile Money)

The mobile money payment request API allows you to accept momo payment from your customer directly from your application or custom checkout. You can use mobile money collection to accept payment from customers paying with GHS and KES

⚠️

Only GHS and KES are supported.

Quick overview

Get Mobile Money Providers: Use the providers endpoint to get a list of mobile money providers available.
Initialize Mobile Money Payment Request: Use the payment_request endpoint to initialize a mobile money payment request. An STK push will be sent to the customer's phone.
Webhook notification: BudPay sends a webhook notification to the callbackUrl provided when the payment is received.
Check payment status: Verify the payment status using the verify endpoint.

Step 1: Get Mobile Money Providers

Use the providers endpoint to get a list of mobile money providers available.

Sample Request for KES:

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

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"
        }
    ]
}

Try it out (KES)

Sample Request for GHS:

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

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"
        }
    ]
}

Try it out (GHS)

Step 2: Initialize Mobile Money Payment Request

Use the payment_request endpoint to initialize a mobile money payment request. An STK push will be sent to the customer's phone.

Process

Request Parameters
- amount: Amount to be paid.
- currency: Currency of the payment.
- reference: Unique reference for the transaction.
- bankName: Mobile money provider.
- phone: Customer's phone number. = description: Description of the payment.
- callbackUrl: URL to receive webhook notification.

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	Mobile money provider.
`phone`	string	Yes	Customer's phone number.
`description`	string	Yes	Description of the payment.
`callbackUrl`	string	Yes	URL to receive webhook notification.

Sample Request:

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

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"
}

Try it out

Step 3: Webhook notification

We will send a webhook notification to the callbackUrl provided when the payment is received. You can use the webhook to update the payment status in your system. The webhook payload will look like this:

{
    "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:

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

Example Response:

{
  "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 Overview