Mobile Money Payouts

This section covers the parameters needed to process payments to mobile money wallets. Bank account transfers follow the same basic format: make a POST request to our Payout API. However, depending on the type of beneficiary and the account's currency, you might need to give some extra information.

To view all currencies supported for mobile money transfers, please view the supported currencies page

Common Details

So first, let's go through the basic information needed for any account. You'll need to provide these details.

Field	Mandatory	Type	Description
business	Yes	String	The ID of the business making the payout.
sourceCurrency	Yes	String	The currency which is used to fund the payout
destinationCurrency	Yes	String	The currency in which the recipient will be receiving funds
amount	Yes	String	The value that is to be transferred from the source currency wallet. Note: Decimals are not allowed as 'amount', for UGX payouts
description	Yes	String	This is the type of account you want to send your payments to, see payment destinations for more details
paymentDestination	Yes	String	The value should be sent as mobile_money_wallet
customerReference	Yes	String	The transaction's unique identifier on your system. Customer references prevent duplicate transactions. We advice that you add it to your payload
quoteReference	No	String	This is the reference generated when the source currency is compared against the destination currency. This is required when the source currency is not the same as the destination currency. You can generate a quote using the Generate quote endpoint.

In addition to the common details needed to process successful payments, the following fields are also required when sending money to a mobile money wallet.

Field	Mandatory	Type	Description
beneficiary	Yes	Object	The recipient of the funds. Depending on the currency and beneficiary type, the properties of the beneficiaries are different.
beneficiary.firstName	Yes	String	The first name of the beneficiary.
beneficiary.lastName	Yes	String	The last name of the beneficiary
beneficiary.phone	No	String	The mobile number of the beneficiary. It should be in this format countryCallingCode(mobile number).e.g 2348027438483. NB: please exclude passing the plus(+) with the number
beneficiary.accountHolderName	Yes	String	This field is required by all types of beneficiaries.
beneficiary.accountNumber	Yes	String	The mobile number of the beneficiary. It should be in this format countryCallingCode(mobile number).e.g 2348027438483. NB: please exclude passing the plus(+) with the number
beneficiary.type	Yes	String	The type of beneficiary, see beneficiary types for more details
beneficiary.country	Yes	String	The country in which the bank of the beneficiary is located. This field should be in ISO 3166-1 alpha-2 codes e.g NG, GB
beneficiary.email	No	String	The beneficiary's email
beneficiary.mobileMoneyCode	Yes	String	This value is the mobile money wallet provider's code. You must use the List bank endpoint to obtain this value. Note: When mobileMoneyCode is "AIRTEL", the 'amount' field must be a whole number, not a decimal.
sender	No	Object	The details of the customer initiating the payout. This is required only for cross-border merchants/transactions.
sender.type	No	String	One of: `individual`, `corporate`
sender.name	No	String	The customer's full name. This name would show up in the transfer narration.
sender.email	No	String	The customer's email.
sender.idType	No	String	One of: `business_registration_number`, `passport`, `national_identification_number`, `drivers_license`
sender.idNumber	No	String	Identity number of selected identification type
sender.countryOfOrigin	No	String	Country code in ISO 3166-alpha2 format (e.g., NG, US, GB). Only required if sender.type is individual
sender.countryOfIncorporation	No	String	Country code in ISO 3166-alpha2 format (e.g., NG, US, GB). Only required if sender.type is corporate
sender.address	No	String	Full address of business or individual
sender.birthDate	No	String	Person's date of birth (for individual senders)
sender.nationality	No	String	The senders nationality

The payload should look like this :

{
   "business":"{{The business ID}}",
   "sourceCurrency":"KES",
   "destinationCurrency":"KES",
   "amount":"1000",
   "description":"I want to pay my vendor",
   "paymentDestination":"mobile_money_wallet",
   "customerReference":"b67vfv",
   "quoteReference":"1330bd3c-1e09-4c1c-887f-7f1d72ff905e",
   "beneficiary":{
      "firstName":"Hassan",
      "lastName":"Sarz",
      "accountHolderName":"Hassan Sarz",
      "country":"KE",
      "phone":"2548034567898",
      "mobileMoneyCode":"SAFARICOM",
      "accountNumber":"2548034567898",
      "type":"individual",
      "email":"[email protected]"
   },
   "sender":{
      "name":"Customer Name",
      "phone":"2548034567898",
      "address":"Customer full address"
   }
}

{
    "business":"{{The business ID}}",
    "sourceCurrency":"GHS",
    "destinationCurrency":"GHS",
    "amount":"1000",
    "description":"i want to pay my vendor",
    "paymentDestination":"mobile_money_wallet",
    "customerReference":"b67vfv",
    "quoteReference":"1330bd3c-1e09-4c1c-887f-7f1d72ff905e",
    "beneficiary":{
        "firstName":"Hassan",
        "lastName":"Sarz",
        "accountHolderName":"Hassan Sarz",
        "country":"GH",
        "phone":"2330803443433",
        "mobileMoneyCode":"AIRTEL",
        "accountNumber":"2330803443433",
        "type":"individual",
        "email":"[email protected]"
    },
    "sender":{
      "name":"Customer Name",
      "phone":"2548034567898",
      "address":"Customer full address"
   }
}

{
    "business": "{{The business ID}}",
    "sourceCurrency": "UGX",
    "destinationCurrency": "UGX",
    "amount": "1000",
    "description": "I want to pay my vendor",
    "paymentDestination": "mobile_money_wallet",
    "customerReference": "b67vfv",
    "quoteReference": "1330bd3c-1e09-4c1c-887f-7f1d72ff905e",
    "beneficiary": {
        "firstName": "Hassan",
        "lastName": "Sarz",
        "accountHolderName": "Hassan Sarz",
        "country": "UG",
        "phone": "2567734567898",
        "mobileMoneyCode": "SAFARICOM",
        "accountNumber": "2567734567898",
        "type": "individual",
        "email": "[email protected]"
    },
    "sender":{
      "name":"Customer Name",
      "phone":"2567734567898",
      "address":"Customer full address"
   }
}

{
    "business": "{{The business ID}}",
    "sourceCurrency": "ZMW",
    "destinationCurrency": "ZMW",
    "amount": "10",
    "paymentDestination": "mobile_money_wallet",
    "customerName": "Test Fincra",
    "customerReference": "02_11_2024_26_39PM",
    "beneficiary": {
        "firstName": "Test",
        "lastName": "Technologies",
        "email": "[email protected]",
        "accountHolderName": "Test TECHNOLOGIES LTD",
        "accountNumber": "0961111111",
        "type": "individual",
        "country": "ZM",
        "mobileMoneyCode": "MTN"
    },
    "files": {},
    "description": "I want to pay my vendor"
}

{
   "business":"{{The business ID}}",
   "sourceCurrency":"TZS",
   "destinationCurrency":"TZS",
   "amount":"1000",
   "description":"I want to pay my vendor",
   "paymentDestination":"mobile_money_wallet",
   "customerReference":"b67vfv",
   "quoteReference":"1330bd3c-1e09-4c1c-887f-7f1d72ff905e",
   "beneficiary":{
      "firstName":"Hassan",
      "lastName":"Sarz",
      "accountHolderName":"Hassan Sarz",
      "country":"TZ",
      "phone":"255789292000",
      "mobileMoneyCode":"SAFARICOM",
      "accountNumber":"2548034567898",
      "type":"individual",
      "email":"[email protected]"
   },
   "sender":{
      "name":"Customer Name",
      "phone":"255717292000",
      "address":"Customer full address"
   }
}

{
    "business": "{{The business ID}}",
    "sourceCurrency": "XOF",
    "destinationCurrency": "XOF",
    "amount": "10",
    "paymentDestination": "mobile_money_wallet",
    "customerName": "Test Fincra",
    "customerReference": "02_11_2024_26_39PM",
    "beneficiary": {
        "firstName": "Test",
        "lastName": "Technologies",
        "email": "[email protected]",
        "accountHolderName": "Test TECHNOLOGIES LTD",
        "accountNumber": "0961111111",
        "type": "individual",
        "country": "BN",
        "mobileMoneyCode": "MTN"
    },
    "files": {},
    "description": "I want to pay my vendor"
}

{
    "business": "{{The business ID}}",
    "sourceCurrency": "XAF",
    "destinationCurrency": "XAF",
    "amount": "10",
    "paymentDestination": "mobile_money_wallet",
    "customerName": "Test Fincra",
    "customerReference": "02_11_2024_26_39PM",
    "beneficiary": {
        "firstName": "Test",
        "lastName": "Technologies",
        "email": "[email protected]",
        "accountHolderName": "Test TECHNOLOGIES LTD",
        "accountNumber": "0961111111",
        "type": "individual",
        "country": "CM",
        "mobileMoneyCode": "MTN"
    },
    "files": {},
    "description": "I want to pay my vendor"
}

❗️
Note
When paying out to UGX, amount must be a whole number