Mobile Money Payouts

The API enables you to transfer funds directly from your available balance to a mobile money account. The documentation below explains further.

We recommend checking out the Getting Started section to understand the basics of payouts first and the general workflow. This guide assumes that you have read that

Overview

The currently supported mobile money channels are listed here (to be updated from time to time). Test mobile money phone numbers are also described in this section. It's very important that you track the available balance on your PAYOUT wallet before initiating these transactions.

Step 1: Obtain the required data for the payment request

The table below describes the request parameters that are used for the payout/disbursement request. Most/all will be collected from the paying customer.

Parameter	Type	Required	Description
merchant_reference	String	true	The unique reference for this request. It must be at least 8 characters long.
transaction_method	String	true	The transaction method to be used. This will be MOBILE_MONEY for this request
currency	String	true	The 3-character ISO currency code for the request currency
amount	Number	true	The amount to be transferred
provider_code	String	true	The provider code as obtained from the payment options list
account_number	String	true	The phone number of the recipient. This should be sent in international format e.g. 256777000001 for Ugandan numbers
customer_name	String	true	The name of the customer
description	String	true	The description/narration for the transaction

After collecting the necessary mobile money payment information from your customer, prepare your request payload as demonstrated below.

{
	"merchant_reference": "MCTREFT2WMNWZ23SBN6Y",
	"transaction_method": "MOBILE_MONEY",
	"currency": "UGX",
	"amount": 4000,
	"provider_code": "mtn_ug",
	"account_number": "256777000001",
	"customer_name": "JOHN DOE",
	"description": "Test Payout"
}

POST https://gwapisdbx.gbipayments.com/payout/send-funds

The request is sent as a JSON body as demonstrated by the sample request below. Sample responses (acknowledgement and failure) are also shared.

curl -X POST "https://gwapisdbx.gbipayments.com/payout/send-funds" \
   -H 'Content-Type: application/json' \
   -H "x-api-version: 1" \
   -H "public-key: your-public-key" \
   -H "secret-key: your-secret-key" \
   -d '{
        "merchant_reference": "MCTREFT2WMNWZ23SBN6Y",
        "transaction_method": "MOBILE_MONEY",
        "currency": "UGX",
        "amount": 10000,
        "provider_code": "mtn_ug",
        "account_number": "256777000001",
        "customer_name": "JOHN DOE",
        "description": "Test Payout"
    }'

202: Accepted - Request acknowledged for processing

{
    "code": 202,
    "status": "accepted",
    "message": "Request Accepted",
    "data": {
        "internal_reference": "GBPREFFFZNGLVH96GSKK",
        "merchant_reference": "MCTREFT2WMNWZ23SBN6Y"
    }
}

400: Bad Request - Request is not formed as expected

Step 2: Handshake - Verify transaction

The API will attempt to verify the transaction from your platform as described in this section. Ensure that the correct URL is configured on your merchant account and that you're handling the verification request appropriately.

Step 3: Handle the final status webhook

Every merchant account is expected to have configured a callback/webhook URL for payouts. For all payouts that transition to the final state (COMPLETED or FAILED), a JSON POST request will be made to the callback URL. Sample callback payloads (request bodies) are shared below. Be sure to check out Handling Notifications to see how you should verify the signature(s) in the request headers and how to respond.

Successful Mobile Money Payout

{
    "event": "transaction.completed",
    "payload": {
        "id": 20760,
        "merchant_reference": "MCTREFT2WMNWZ23SBN6Y",
        "internal_reference": "GBPREFFFZNGLVH96GSKK",
        "transaction_type": "PAYOUT",
        "request_currency": "UGX",
        "transaction_amount": 10000,
        "transaction_currency": "UGX",
        "transaction_charge": 1000,
        "transaction_account": "256777000001",
        "charge_customer": false,
        "total_debit": 11000,
        "provider_code": "mtn_ug",
        "request_amount": 10000,
        "customer_name": "JOHN DOE",
        "transaction_status": "COMPLETED",
        "status_message": "Transaction Completed Successfully"
    }
}

Failed Mobile Money Payout