Merchant Onboarding Guide

Terminology

For consistency, we will use the following terminology within this document and in technical discussions.

Term	Definition
Operator	Mobile Network Operator in a given country, such as Airtel or Safaricom in Kenya
Channel	A Channel is an Operator operating a Mobile Money or eWallet technology platform
Merchant	From Tola's perspective, this is you
Account	You will have at least one account with Tola. Where you have multiple businesses these can be arranged in an account tree so that a single user can have access to multiple accounts
Transaction Relay	This is an endpoint that you will use to interact with the Tola Wallet API
Paybill	This is an identifier for the financial account that the Operator holds on your behalf. Your funds are stored here and maintained by the Operator (see Channels and Paybills)
MSISDN	A phone number
Customer	This is a Customer of your service identified by their MSISDN
C2B	Abbreviation for Customer to Business. Funds are moving from a Customer's Wallet to a Merchant's Paybill
B2C	Abbreviation for Business to Customer. Funds are moving from a Merchant's Paybill to a Customer's Wallet
Charge	A C2B transaction initiated by the Merchant via a Relay and subject to approval by the Customer on the handset
Disbursement	A B2C transaction initiated by the Merchant via a Relay
Lodgement	A Customer Initiated C2B transaction where the Customer initiates a payment from their handset

Transaction Types

Charge

A charge is a Merchant initiated C2B transaction. For a more detailed explanation see the Charge Guide.

Disbursement

A disbursement is a Merchant initiated B2C transaction. For a more detailed explanation see the Disbursement Guide.

Lodgement

A lodgement is a Customer initiated C2B transaction. For a more detailed explanation see the Lodgement Guide.

Channels and Paybills

The Tola Wallet Platform uses a Channel identifier to specify the name of a specific Operator. Tola refers to Channels in the format <country>.<name>, for example ZAMBIA.AIRTEL.

The funds you have stored with a given Operator can be grouped into different financial accounts. Those accounts are identified by their Paybill identifier.

For example, with a given Operator, you may have two financial accounts or Paybills:

Paybill	Purpose
00001	used for C2B transactions
00002	used for B2C transactions

When interacting with the Tola Wallet API you will need to supply both the Channel identifier and the Paybill identifier (or target) so that we can ensure the funds move to or from your desired Operator financial account.

For the Tola Wallet Platform to interact with the Operator on your behalf you will also need to supply Tola with the necessary Paybill credentials for each Paybill on each Channel during the onboarding process.

To monitor the money flows in and out of your Paybills you will need access to each Operator's Mobile Money Portal.

You will need to provide Paybill credentials for each Channel / Paybill pair, or a contact that can provide these. We recommend beginning this process at the earliest opportunity as Operator integrations can be delayed by availability of the Operator teams and commercial requirements.

The Onboarding Process

Initial Setup

We recommend beginning a technical integration by setting up a chat room with the concerned parties. Typically we use Skype as it is freely available.

You will be provided with one or more Transaction Relays and the credentials to access them which will be securely shared with a single trusted member of your team.

Mode	Description
Integration Test	Valid transactions will not be sent to the Operator but will be completed and notifications will be sent to your configured endpoints
Production Test	Up to 5 MSISDNs will be whitelisted for use. Valid transactions will be sent to the Operator and processed as live transactions
Production	The MSISDN whitelist will be removed and your URL is fully live
Inactive	All transactions will be rejected

Integration Test

In this phase, your integration team should be able to fully simulate transactions and integrate the Tola Wallet API into your systems, receiving callbacks as if the Operator was approving the transactions. This will allow your technical team to test the API calls, receive responses from the Tola platform and fully test your Merchant application.

Test transactions in this phase can be initiated against any MSISDN with the correct length and country code for the passed channel. The last two digits of the MSISDN will determine the final status of the test transaction according to the Code in Callback Error Codes. For example:

MSISDN	Result
254000000000	successful
254000000005	insufficientfunds
254000000013	msisdn-invalid
254000000099	rejected (default response)

If the last two digits of the MSISDN do not match a valid code, transactions will return a rejected status in the callback.

Please provide:

• URLs for callback notifications. We require a webhook URL for each transaction type you will be using, though this can be the same URL for all transaction types. These can be changed at your convenience at any time during the integration process.
• A list of originating IP Addresses that you use to send us requests so that we can whitelist them for security.

Production Test

When Tola has completed Paybill integration with one or more Channels and your Merchant application has fully implemented the Tola Wallet API we will move the Transaction Relay to Production Test mode so that a real funds transfer can be attempted.

Several transactions of varying types and amounts should be completed and checked on your Merchant platform, Tola Wallet portal and Operator portal to ensure that amounts and other details are consistent across all platforms. Failure cases and how your Merchant Application should be handling them should be included in this testing.

In this phase, the Transaction Relay will be limited to 5 MSISDNs that you can specify and these can be changed at any time to facilitate testing.

Tola requires a downloaded transaction ledger from each of the Operator Mobile Money Portals showing transactions generated during this phase. This will allow us to verify that we can recover transactions lost during outages and so on.

Please provide:

• Up to 5 test MSISDNs (these can be changed at any time)
• Operator Portal Ledgers showing each transaction type for each channel

Production

When you are satisfied that the service is ready to move to Production the MSISDN whitelist will be removed and requests for any MSISDN will be accepted.

Subject to your commercial agreement with Tola, transactions completed on the Tola Wallet platform against your Paybills will be eligible for transactional Billing. This is undertaken in a historical nature and a Monthly Invoice will be presented for the previous month's activity.

Production Checklist

In order to access Tola support and manage basic service issues please ensure that your operations team have:

• Access to the Tola Service Desk. This is a 24 hour monitored service where issues can be reported and tracked. This will be your only way to reach Tola Support outside office hours (GMT+1). If you require access please contact support@tolamobile.com.

• Access to the Tola self service portal. This portal provides a number of applications to track activity, view transactions and recover from service issues. This is a vital tool for managing your service. Training will be provided for new merchants and can be repeated upon request. Only subscribed portal users will receive service updates. New users can be requested via the Tola Service Desk.