Lodgements

A Lodgement is a Consumer initiated payment from a Consumer to a Merchant. It is initiated by an Operator provided USSD menu or a Menu deployed onto the handset. If successful Tola will receive a notification that the Lodgement was completed and an unsolicited Mobile Money event will be passed to the Merchant. See the appropriate page below for a full specification:

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

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 to configure the Tola Wallet platform to receive Lodgements from these Accounts/Paybills. The Tola Merchant onboarding team will verify connectivity and carry out any UAT required by the Operator.

Tola will use its API connection with the Operator to receive the notification of the lodgement payment. In some rare cases this process can fail. Tola provides a reconciliation tool to resolve Lodgements that were not delivered to it via the Operator API (where supported).

Merchant Notifications

To notify your merchant platform that a lodgement has taken place, the Tola Wallet Platform will insert a type=lodgement event in your Event Stream (see Tola Wallet Events API) and optionally issue a callback to your pre configured webhook URL:

{
  "reference": "1.123.1435455096.2",
  "success": "true",
  "sourcereference": "",
  "customerreference": "test message",
  "operatorreference": "CI220530.1717.A38729",
  "channel": "KENYA.SAFARICOM",
  "target": "000001",
  "date":"2022-05-30T17:19:01Z",
  "type": "lodgement",
  "currency": "KES",
  "amount": "100",
  "amounttype": "centile",
  "msisdn": "254000000001",
  "campaignid": "10001"
}

• success — a lodgement will always be successful.
• reference is the unique Tola reference for this lodgement.
• customerreference — a freeform string that the consumer can choose to enter when submitting a Lodgement.

It is vital that you perform an idempotency check before recording a lodgement on your merchant platform. Use the reference field to detect whether it is in-fact a new lodgement or one previously seen.

See the appropriate page below for a full specification:

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