Guides
Go to Shutterscore.io

Mobile Money Withdrawals

Suggest Edits

Mobile money withdrawals allow merchants to make payouts to mobile money accounts via the Shutterscore API.

Mobile money represents an electronic service that enables users to send and receive money instantly, make payments, and handle additional transactions using their mobile phones. The system is really popular in a series of African markets like Kenya, Ghana and Nigeria.


📘

Supported Countries

Payouts to mobile money wallets on Shutterscore supports only mobile money wallets in Kenya (KE) and Ghana (GH). Support for other countries are currently in the works and this page will updated to reflect the new countries when new countries are supported.

When a customer requests a withdrawal to their mobile money wallet on your application, your application asks Shutterscore to process this payout. Our API then processes the request and makes a payment to the customer’s wallet, while also notifying your application about the completion of the payment. Easy peasy!

How to make a mobile money withdrawal using Shutterscore API

The following steps need to be taken in order to process payments to a mobile money wallet:

1. Fund merchant account

To make withdrawals, you must have funds in your merchant account. You can fund your account by making deposits into your account or by requesting a manual top-up.

Note : To test transactions, you can fund your sandbox account. For more information, please see the test section

2. Fetch provider list/provider codes

For any mobile money withdrawal, we need to know the recipient's mobile money provider by id. We refer to this as the provider code.

{{baseurl}}/v1/merchant/public/misc/mobile-money?country=KE

{
    "status": true,
    "statusCode": 200,
    "message": "Mobile money list retrieved",
    "data": [
        {
            "name": "Provider name", // e.g Safaricom M-Pesa
            "code": "Provider code", // e.g mpesa_ke
            "country": "2 Char Country Code", // e.g KE
            "min_amount": "Minimum Withdrawal Amount", // e.g 50
            "max_amount": "Maximum Withdrawal Amount" // e.g 100000
        }
    ]
}

3. Create and retrieve rate (Optional)

This is only required for cross currency withdrawal where the source currency differs from your the destination currency. For direct currency withdrawal (where source and destination currencies are the same), you may skip this step. For example, if the destination currency is NGN and the source currency is NGN, there will be no need to provide a rate.

Please take note of the following

  • A transaction type of WITHDRAWAL should be supplied when creating rates for cross withdrawal
  • Once created, a rate expires at a certain time (expires_at) or after a certain period of time (refresh_in)
  • An expired rate may be refreshed using the refresh rate API and it's rate reference

Create Rate Request 

{{baseurl}}/v1/merchant/public/rates/create

{
    "from_currency": "USDT",
    "to_currency": "KES",
    "from_amount": 5000,
    "transaction_type": "withdrawal",
    "withdrawal_method": "mobile-money-payout"
}

{
    "status": true,
    "statusCode": 200,
    "message": "Rate successfully created",
    "data": {
        "from_currency": "USDT",
        "to_currency": "KES",
        "from_amount": 5000,
        "to_amount": 100,
        "reference": "569f0de6-2d28-4abf-8210-c6531385d4e5",
        "expires_at": "2022-10-03T06:53:42.158Z",
        "fee": 10,
        "fee_type": "FLAT",
        "transaction_type": "WITHDRAWAL",
        "deposit_method": null,
        "withdrawal_method": "mobile-money-payout",
        "created_at": "2022-10-03T06:52:12.197Z",
        "updated_at": "2022-10-03T06:52:12.197Z",
        "fiat": "KES",
        "asset": "USDT",
        "refresh_in": 90,
        "used": false
    }
}

Refresh Rate Request

{{baseurl}}/v1/merchant/public/rates/refresh

{
    "reference": "569f0de6-2d28-4abf-8210-c6531385d4e5"
}

{
    "status": true,
    "statusCode": 200,
    "message": "Rate successfully created",
    "data": {
        "from_currency": "USDT",
        "to_currency": "KES",
        "from_amount": 5000,
        "to_amount": 100,
        "reference": "569f0de6-2d28-4abf-8210-c6531385d4e5",
        "expires_at": "2022-10-03T06:55:12.158Z",
        "fee": 10,
        "fee_type": "FLAT",
        "transaction_type": "WITHDRAWAL",
        "deposit_method": null,
        "withdrawal_method": "mobile-money-payout",
        "created_at": "2022-10-03T06:52:12.197Z",
        "updated_at": "2022-10-03T06:53:12.197Z",
        "fiat": "KES",
        "asset": "USDT",
        "refresh_in": 90,
        "used": false
    }
}

For more details on how to get or create a rate, please see the Rates API

4. Request withdrawal

The data sent in the request body depends on the type of withdrawal (Direct Withdrawal or cross) and the withdrawal currency. Kindly ensure you fill out all of the necessary fields in order for your payment to be processed. If the wrong payload is sent, the transaction will fail and you will receive a failed response.

Direct Withdrawal 

{{baseurl}}/v1/merchant/public/transactions/withdraw

{
    "beneficiary": {
        "provider": "mtn_ke",
        "account_name": "olukayode",
        "account_number": "233545503123"
    },
    "amount": 100,
    "currency": "KES",
    "withdrawal_method": "mobile-money-payout",
    "reference": "MOBILE-MONEY",
    "fee_bearer": "beneficiary",
    "narration": "Test-Mobile-Money-Payout"
}

{
    "status": true,
    "statusCode": 200,
    "message": "Withdrawal completed successfully",
    "data": {
        "from_amount": 100,
        "amount": 100,
        "amount_charged": 100,
        "amount_settled": 90,
        "currency": "KES",
        "from_currency": "KES",
        "from": "SELF",
        "to": "OTHER",
        "type": "WITHDRAWAL",
        "purpose": "WITHDRAWAL",
        "reference": "wth7x5cqtjms4ymltjbaai9q",
        "merchant_reference": "MOBILE-MONEY",
        "channel": "API",
        "settled_at": "2022-10-18T14:34:36.566Z",
        "narration": "Test-Mobile-Money-Payout",
        "beneficiary": "{\"provider\":\"mpesa_ke\",\"account_name\":\"olukayode\",\"account_number\":\"254740000123\"}",
        "fee_bearer": "beneficiary",
        "fee": 10,
        "destination": "main_balance",
        "payment_slug": "mobile-money-payout",
        "status": "pending",
        "from_merchant": "Prime Switch Limited",
        "to_amount": null,
        "to_currency": null,
        "trx_rate": null,
        "settlement_time": null,
        "settlement_date": null,
        "extra_data": null,
        "reject_reason": null,
        "provider_fee": null,
        "provider_amount": null,
        "trace_id": null,
        "payment_proof": null,
        "created_at": "2022-10-18T14:34:36.577Z",
        "updated_at": "2022-10-18T14:34:36.577Z",
        "to_merchant": null
    }
}

Cross Withdrawal

{{baseurl}}/v1/merchant/public/transactions/withdraw

{
    "beneficiary": {
        "provider": "mtn_ke",
        "account_name": "olukayode",
        "account_number": "233545503123"
    },
    "withdrawal_method": "mobile-money-payout",
    "rate_reference": "569f0de6-2d28-4abf-8210-c6531385d4e5",
    "reference": "MOBILE-MONEY",
    "fee_bearer": "beneficiary",
    "narration": "Test-Mobile-Money-Payout"
}

{
    "status": true,
    "statusCode": 200,
    "message": "Withdrawal completed successfully",
    "data": {
        "from_amount": 100,
        "amount": 100,
        "amount_charged": 100,
        "amount_settled": 90,
        "currency": "KES",
        "from_currency": "KES",
        "from": "SELF",
        "to": "OTHER",
        "type": "WITHDRAWAL",
        "purpose": "WITHDRAWAL",
        "reference": "wth7x5cqtjms4ymltjbaai9q",
        "merchant_reference": "MOBILE-MONEY",
        "channel": "API",
        "settled_at": "2022-10-18T14:34:36.566Z",
        "narration": "Test-Mobile-Money-Payout",
        "beneficiary": "{\"provider\":\"mpesa_ke\",\"account_name\":\"olukayode\",\"account_number\":\"254740000123\"}",
        "fee_bearer": "beneficiary",
        "fee": 10,
        "destination": "main_balance",
        "payment_slug": "mobile-money-payout",
        "status": "pending",
        "from_merchant": "Prime Switch Limited",
        "to_amount": null,
        "to_currency": null,
        "trx_rate": null,
        "settlement_time": null,
        "settlement_date": null,
        "extra_data": null,
        "reject_reason": null,
        "provider_fee": null,
        "provider_amount": null,
        "trace_id": null,
        "payment_proof": null,
        "created_at": "2022-10-18T14:34:36.577Z",
        "updated_at": "2022-10-18T14:34:36.577Z",
        "to_merchant": null
    }
}

Request Parameters
The parameters below are used with the withdrawal API to request a withdrawal to a mobile money wallet

FieldData TypeDescription
beneficiaryObjectRequired
beneficiary.providerStringRequired - The mobile money provider code
beneficiary.account_nameStringRequired - Name of the beneficiary account
beneficiary.account_numberStringRequired - Beneficiary account number
amountNumberRequired for direct withdrawal - the amount to be withdrawn (paid to the beneficiary). For cross withdrawal, the to_amount on the rate is used
currencyString - NGNRequired for direct withdrawal. For cross withdrawal, the to_currency on the rate is used
narrationStringOptional - description of the transaction
referenceStringOptional - Merchant's reference of the transaction.
rate_referenceStringRequired for cross withdrawal - Rate reference. Provides a reference to the rate that will be used for the cross withdrawal.
fee_bearerString - merchant or beneficiaryOptional - Fee Bearer. When not provided, the value used is merchant.
withdrawal_methodString - mobile-money-payoutRequired - the withdrawal method used for the withdrawal transaction

A payment status is returned after a request is received, and it can be successful, processing, or failed. Please see our transaction status page for additional information.


📘

Transaction Limits

While fetching the providers, each provider object contains min_amount and max_amount properties that define the minimum and maximum amount respectively, allowed for the transaction. This amount is exclusive of any fees you may be charged for processing the withdrawal.


5. Receive and validate notification

You can set your application to receive transaction status updates via webhooks if provided, and email, when the payout is completed. Please read the webhooks page for details on securing and validating the webhook notification on your end, as well as the webhook structure and body.

Updated about 2 years ago