Mobile Money

Fincra allows your customers to pay you by entering their mobile phone numbers. When the customer clicks to pay, they will receive a prompt on the mobile device attached to their number asking them to confirm the payment by inputting a PIN. When customers make payments, you will receive a webhook notification that payments have been made to your account.

Mobile Money is a fast, simple, convenient, secure, and affordable way of transferring money, making payments, and doing other transactions using a mobile phone. Kindly find the currencies and providers supported for mobile money payments below.

List Of Available Currencies

KES (Kenyan Shilling)GHS (Ghanian Cedis)UGX (Ugandan Shilling)
ZMW (Zambian Kwacha)

List Of Available Operators (Providers)

MPESAAIRTELTNM_MPAMBAORANGE
MTNETISALATVODACOMECOCASH
ZAMTELTIGOPESAVODAFONEEQUITEL
TIGOWEPAY

Take note
The List available mobile money operators endpoints can be used to get details about the available mobile money operators.


The following steps are required to accept mobile money payments :

1 - Initiate Payment

To charge a customer, you will need to collect the necessary payment information from the customer.

FieldRequiredTypeDescription
typeYesStringThis is the payment method. In this case, it will be mobile_money.
referenceYesStringThe unique reference generated for the transaction.
amountYesStringThe amount to be charged
currencyYesStringThe currency
phoneYesStringThe mobile number of the customer to be charged e.g 254700000000
operatorYesStringThe mobile money operator.
customerYesObjectThe customer details
customer.nameYesStringThe customer name
customer.emailYesStringThe customer email
customer.phoneNumberNoStringThe customer's phone number
settlementDestinationNoStringA settlement destination is the location where you want your payments to be settled. It could be a wallet or a bank account. The settlement destination is your Fincra wallet by default.
callbackUrlNoStringThe URL to redirect your customer when the transaction is complete.

Then, prepare your data object to look like the sample below :

{
    "type": "mobile_money",
    "amount": 600,
    "reference": "o8bfuweukn",
    "currency": "KES",
      "customer": {
      "name": "Kweku Kwabena",
      "email": "[email protected]"
    },
    "phone":"254700000000",
    "operator":"MPESA",
    "settlementDestination": "wallet",

}

Send a POST request with the payment data above to the initiate a mobile money charge endpoint. If the request is successful, you will receive a response containing the transaction status pending as well as other important parameters such as:

  • data.id refers to the unique identifier of the transaction
  • data.reference refers to the unique identifier of the transaction on your platform.
  • data.message This is the message which contains the payment procedures. You are expected to display the data.message to your customer to make payments, and then listen to webhook for transaction notification or query the verify payment endpoint at intervals.

Here is a sample response that you will receive after initiating a payment and requires the customer to complete the process:

{
    "status": true,
    "message": "Charge created",
    "data": {
        "id": 2586,
        "authorization": {
            "mode": null
        },
        "auth_model": null,
        "amount": 600,
        "currency": "KES",
        "fee": 1,
        "vat": 0,
        "message": "<p>You will receive a prompt on mobile number <b>254700000000</b>. <br/> Enter your M-Pesa PIN to authorize your payment of <b>KES 600.00</b> to account number <b>254700000000</b>. <br/><br/> If you do not get a prompt within 30 seconds, use the instructions below to make your payment: </p> <ol> <li>Go to your Safaricom SIM Tool Kit</li> <li>Select M-PESA menu</li> <li>Select Lipa na M-PESA</li> <li>Select Pay Bill</li> <li>Enter Business no. <b>000000</b></li> <li>Enter Account no. <b>254700000000</b></li> <li>Amount to pay <b>600.00</b></li> <li>Enter your M-PESA PIN and press OK</li> </ol>",
        "status": "pending",
        "reference": "K8-Mobile-Data",
        "type": "mobile_money",
        "customer": {
            "name": "Fincra Developers",
            "email": "[email protected]",
            "phoneNumber": null
        },
        "metadata": {
            "phone": "254700000000",
            "operator": "MPESA"
        },
        "settlementDestination": "wallet"
    }
}

2 - Verify Payment

The final step after receiving payment is to ensure that the payment was successful before providing value to your customer. To do so, send a verification request to the verify payment endpoint from your server to confirm the payment's final status. The reference you enter here should be the same as the one you used for your payment.

Here's an example of payment verification and response:

{
    "status": true,
    "message": "Charge found",
    "data": {
        "id": 2586,
        "authorization": {
            "mode": null,
            "redirect": null
        },
        "auth_model": null,
        "amount": 600,
        "amountReceived": 0,
        "currency": "KES",
        "fee": 1,
        "message": "<p>You will receive a prompt on mobile number <b>254700000000</b>. <br/> Enter your M-Pesa PIN to authorize your payment of <b>KES 600.00</b> to account number <b>254700000000</b>. <br/><br/> If you do not get a prompt within 30 seconds, use the instructions",
        "status": "success",
        "reference": "Mobile Data",
        "description": "",
        "type": "mobile_money",
        "customer": {
            "name": "Fincra Developers",
            "email": "[email protected]",
            "phoneNumber": null
        },
        "metadata": {
            "phone": "254700000000",
            "operator": "MPESA"
        },
        "settlementDestination": "wallet"
    }
}

3 - Set Up Webhook

As an optional step, you can configure your application to receive confirmation via webhooks. See Webhooks for more information. After configuring your webhook, we'll send you a notification with the transaction status to the URL you specified when initiating a payment.

Read our guide to learn how to secure and validate webhook notifications on your end.

Here's a sample of the webhook response:

{
  "event": "charge.successful",
  "data": {
    "id": 932,
    "authorization": {
      "mode": "NONE",
      "redirect": null
    },
    "auth_model": "NONE",
    "amount": 50000,
    "currency": "NGN",
    "fee": 699.99,
    "message": "Mobile money charged successfully",
    "status": "success",
    "reference": "98329uniwud",
    "description": "",
    "type": "mobile_money",
    "customer": {
      "name": "Fincra Developers",
      "email": "[email protected]",
      "phoneNumber": "+2348142986562"
    },
    "settlementDestination": "wallet"
  }
}
}