Transactional Integrity
A core consideration of the Tola Wallet platform is to mitigate outages, connectivity issues and unexpected behaviour between the Mobile Network Operator (Operator) and your Merchant application.
When callbacks are enabled, Tola guarantees a callback to your Merchant application for every transaction created by the Create Transaction API as soon as the Operator has provided a final status. Where we are unable to obtain a final status from the Operator or to deliver the callback to your Merchant application, the Tola Wallet platform provides web based tools and utilities to attempt to resolve these issues manually.
Staging
The Tola Wallet platform Staging application and associated web portal will hold transactions and notifications which could not be finalised. This can occur when the Operator was unable to provide the final status of a transaction, or in cases where the Tola Wallet platform was unable to reach the configured callback endpoint for your Merchant application.
Staged Disbursements
A Disbursement will be moved to Staging in any situation where we are unable to determine a final status.
Staged Disbursements should be checked against the Operator records (Tola does not have access to these) and be resolved accordingly via the Tola Wallet web portal.
Where available there will be an option to upload the Operator ledger that will allow bulk resolution of Disbursements.
Managed Disbursements are also managed from staging, see Managed Disbursements.
Staged Lodgements and Notifications
For Merchant integrations configured to use webhooks, a Lodgement or Notification will be moved to Staging where:
- We have been unable to deliver it to the configured callback endpoint on the Merchant application.
- The Merchant application has responded to the Callback with a response indicating it has not been processed by the Merchant.
If your Merchant application is fully idempotent, Staged Lodgements and Notifications can be resent. In any other case check the status of the transaction on your Merchant application and resolve accordingly.
Staged Charges
A Charge should never be moved to Staging under normal circumstances. Where we are unable to determine the final status and no other mechanism exists to resolve the transaction, charges may be moved to Staging as a temporary or exceptional measure.
Staged Charges should be checked against the Operator records (Tola does not have access to these) and be resolved accordingly.
Manual C2B Reconciliation
Where a Lodgement has not been delivered or we have been unable to determine the final status of a Charge, the Manual C2B Reconciliation page on the Tola Wallet web portal can be used to upload an Operator transaction ledger for the appropriate Paybill.
When uploading a C2B Transaction Ledger, Tola will use the ledger's Operator reference field for that transaction to ensure it only creates C2B Transactions that haven't been seen before on the Tola platform. Tola maintains a cache of recent Operator References. Timestamps for ledger rows that are outside the cache window will result in the C2B row not being accepted.
This process can inject new transaction records and issue Notifications to the Merchant application. It needs to be used carefully and correctly to maintain reconciliation between the Tola platform, the Merchant application and the Operator Paybill Record. Please use with care.
Charges
Where a pending Charge can be matched to an entry in the ledger the Charge will be completed normally and your Merchant application will be notified. Pending charges that cannot be matched will remain pending until they can be resolved or will be failed as expired after an expiry timer has elapsed (see Callback Error Codes and Messages).
Lodgements
Tola Wallet maintains a cache of unique Operator references (operatorreference in the Callback) delivered with each Lodgement. Where a ledger record is within our cache period and there is no entry in the cache with a matching Unique Operator reference, a new Lodgement will be created and notified to your Merchant application.