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:

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

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

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 Overview