Disbursements

A Disbursement is a Merchant initiated request for payment from a Merchant to a Consumer.

Account / Paybill Setup

Before you can use the Tola Mobile Wallet you will need to contact the Operators you want Mobile Money support with to obtain Merchant accounts (often referred to as Paybills).

Once approved the Operator will supply details including credentials to these Accounts/Paybills. Please supply the API related credentials to the Tola Merchant onboarding team who will verify connectivity and carry out any UAT required by the Operator.

You will be supplied with a Tola Wallet API URL and associated credentials. For additional security we will only allow access to this URL from your IP address(s).

If you would like to receive callback webhooks you can provide a HTTPS URL to the Tola Wallet Merchant onboarding team at this point. Note however that for reliability we recommend you use the Tola Wallet Events API instead of the callback mechanism.

How you initiate a Disbursement

A Disbursement will typically be initiated from your app or website. In addition to the msisdn you will need to know the channel the msisdn is registered with and the target account that will be deducted to make the payment.

It is important that the channel supplied correctly identifies the Operator of the msisdn - if it does not, the Disbursement will most likely fail.

In most cases Operators prefer separate accounts/Paybills for C2B and B2C.

curl --request POST \
  --user username:password \
  --url https://apidocs.tolamobile.com/transaction \
  --header 'Content-Type: application/json' \
  --data '{
  "msisdn": "254000000001",
  "type": "disbursement",
  "channel": "KENYA.SAFARICOM",
  "currency": "KES",
  "amount": 100,
  "sourcereference": "8FD2KuZNJnBPLKmz"
}'

channel uses the convention COUNTRY.OPERATOR. The Tola Merchant onboarding team will supply the valid channels for each connection.
target is the account that will be deducted — an identifier supplied by the Operator.
sourcereference should be a unique identifier supplied from your application. This can be used to cross reference records between your application and Tola. Recent duplicates (within 48hrs) will be rejected.

If the request is validated by the Tola Wallet Platform a unique reference for the Disbursement will be returned.

{
   "reference" : "5.101.1650635745.1",
   "success" : true
}

Based on the transaction type and channel the Disbursement will be routed within the Tola Wallet Platform to the appropriate Operator API where Tola will initiate the Disbursement.

See creating a transaction for the full specification.

Confirmation of the transaction

If the Disbursement is processed correctly and funds are transferred, the Tola platform will use its API connection with the Operator to determine the final status of the Disbursement. This results in the creation of a Notification transaction on the Wallet platform. This can be consumed by the Tola Wallet Events API or reported to your merchant application by issuing a callback to your pre configured webhook.

{
  "reference": "1.123.1435455096.2",
  "success": "false",
  "sourcereference": "5.101.1650635745.1",
  "customerreference": "8FD2KuZNJnBPLKmz",
  "operatorreference": "CI220530.1717.A38729",
  "channel": "KENYA.SAFARICOM",
  "target": "000001",
  "date":"2022-05-30T17:19:01Z",
  "type": "notification",
  "currency": "KES",
  "amount": "100",
  "amounttype": "centile",
  "msisdn": "254000000001",
  "errorcode": 1,
  "errormessage": "insufficient funds",
  "campaignid": "10001"
}

Important Fields

success indicates the outcome of the funds-transfer where true indicates that funds were transferred.
sourcereference is the unique Tola reference for the Transaction which was created when you called POST /transaction.
customerreference is the reference you provided when calling POST /transaction.
errorcode and errormessage will map to a Callback Error. Different Operators provide different levels of information when failing a transaction. The Tola Wallet platform will map the Operator provided error code to the most appropriate Tola Wallet API error code.

See the appropriate page below for a full specification:

"Callbacks" section on the Create a Transaction page, or
Events page.

Handling Confirmations

When you receive a confirmation event with type=notification (by callback or Events API) you need to locate the associated pending record on your Merchant system by using either the sourcereference or customerreference from the confirmation payload.

If the reference you send to us is always unique then we recommend using the customerreference since it can better resolve situations where you experienced uncertainty (eg. a network timeout) when calling POST /transaction (very rare).

Lifecycle

As soon as you consume the Notification the lifecycle of the Disbursement is complete. It will form part of your statistical overview and will be available to view and download in our portal.

Typically the lifecycle of a Disbursement is a few seconds but might be longer in anomalous circumstances. This will vary from Operator to Operator.

The Tola Wallet Platform guarantees a Notification for every Disbursement.

In some rare cases this process can fail, for example if the Operator doesn't provide confirmation of the transaction's final status while the funds have already been deducted from the Merchant's Mobile Money Wallet. Tola provides a staging tool for the resolution of these cases.

C2B Charge Guide

C2B Lodgement Guide