List of Mobile Money API Use Cases
The Use Case (UC) code identifies the use case in relation to the others. The code contains the acronym UC and a reference code (e.g. UC19). All use cases currently available on the MMAPI Compliance platform and those under development are listed below.
UC01 - Payee/Merchant-Initiated Merchant Payment
This use case describes the process in which a user (payer) purchases a service or goods from a merchant. The transaction is initiated by the merchant (payee) and needs to be validated by the user (payer).
User Story
Didier walks into a store to purchase a modem for his home.
After giving his information to the merchant, the merchant generates a transaction request which gets processed through the system. Didier is notified of the request by his FSP, and approves the payment. After approval, both parties receive a confirmation of payment from their respective FSPs.
| Use Case Name: | Payee/Merchant-Initiated Merchant Payment |
|---|---|
| Summary: | Service Provider requests a Payee-initiated merchant payment through the Mobile Money API sending both their own and customer’s details and the Mobile Money Provider handles the request and responds with an asynchronous callback. The payment request is successful and the transaction object is sent back to the service provider. |
| Actors: |
|
| Preconditions: |
|
| Description: |
|
| Exceptions1: | Business rule failure, Validation failure |
- Callback
- Polling
- w/ Authorisation Code
UC02 - Payer/Customer-Initiated Merchant Payment
This use case describes the process in which a user (payer) purchases a service or goods from a merchant. The transaction is initiated by the customer (payer).
User Story
Abiba wants to purchase goods from a merchant.
She first submits the payment requests via her preferred channel (e.g Mobile Money app) for processing to the Mobile Money Provider (MMP). The MMP will return the Request state object to indicate the request is pending.
The MMP then informs the Payer’s channel (Mobile Money app) that the payment has been successfully completed by returning the final representation of the transaction. The merchant is also notified that the payment was successful.
| Use Case Name: | Payer/Customer-Initiated Merchant Payment |
|---|---|
| Summary: | Service Provider requests a Payer-initiated merchant payment through the Mobile Money API sending both their own and customer’s details and the Mobile Money Provider handles the request and responds with an asynchronous callback. The payment request is successful and the transaction object is sent back to the service provider. |
| Actors: |
|
| Preconditions: |
|
| Description: |
|
| Exceptions1: | Business rule failure, Validation failure |
- Callback
- Callback Failure
The sequence diagram below shows the typical flow for an authorized transaction with callback:
UC03 - Disbursements
The Disbursement Mobile Money APIs allow organisations to disburse funds to mobile money recipients.
- Individual
- Bulk
User Story
Global Health NGO wants to make an individual disbursement. They simply submit the request for processing to the Mobile Money Provider, who will then return the final representation of the transaction once successfully completed.
| Use Case Name: | Disbursements |
|---|---|
| Summary: | This use case simulates a scenario where the a service provider would like to disbuse funds to a single mobile money recipient |
| Actors: |
|
| Preconditions: |
|
| Description: |
|
| Exceptions1: | 1-Step Async failure, 1-step Sync failure, 2-Step failure, Callback failure, Polling failure |
The sequence diagram below shows the typical flow for an individual disbursement:
UC04 - Refunds & Reversals
This use case describes the process involved when a user (payer) is requesting a refund or reversal for a merchant payment through the Mobile Money API.
User Story
Africa Utilities wants to issue a refund/reversal to a payer. They first submit a refund/reversal request for processing to the MMP, who will then inform the merchant (Africa Utilities) that the refund/reversal has been successfully completed along with the final representation of the refund/reversal.
| Use Case Name: | Refunds & Reversals |
|---|---|
| Summary: | Service Provider requests a refund/reversal for a merchant payment through the Mobile Money API and the Mobile Money Provider handles the request and responds with an asynchronous callback. The refund/reversal is successful and the refund/reversal object is sent back to the service provider. |
| Actors: |
|
| Preconditions: |
|
| Description: |
|
| Exceptions1: | Reversal Validation Format Failure, Refund Validation Format Failure |
- Refund
- Reversal
The sequence diagram below shows the typical flow for a merchant refund:
UC05 - Transactions
This use case describes the process involved when a Service Provider wants to retrieve a single transaction through the Mobile Money API.
User Story
SA Digital wants to retrieve a particular transaction by using a transaction reference. They request the transaction from the Mobile Money Provider using the transaction reference, who then responds with the appropriate transaction object.
| Use Case Name: | Transactions |
|---|---|
| Summary: | Service Provider requests their own account transaction history through the Mobile Money API and the Mobile Money Provider handles the request and successfully responds synchronously with the request transaction(s). |
| Actors: |
|
| Preconditions: |
|
| Description: |
|
| Exceptions1: | identifierType error |
The sequence diagram below shows the typical flow for a transaction retrieval:
UC06 - Account Information
This use case describes the process involved when a Service Provider needs to request certain account information, such as account balance or transaction information, from a Mobile Money API provider.
- Transaction History
- Account Balance
User Story
The Service Provider wants to retrieve their own transaction history for review. They first request a maximum of 20 transactions from the Mobile Money Provider using the limit parameter, who then returns an array of 20 transactions, and indicates via a response header that there 40 records available in total.
With this in mind the Service Provider decides to request the remaining transactions, and does so using the offset parameter in addition to the limit parameter, to retrieve the rest of the transactions.
| Use Case Name: | Account Information |
|---|---|
| Summary: | Service Provider requests their own transaction history through the Mobile Money API and the Mobile Money Provider handles the request and successfully responds synchronously with the requested transaction(s). |
| Actors: |
|
| Preconditions: |
|
| Description: |
|
| Exceptions1: | Format Error (identifierType) |
The sequence diagram below shows the typical flow for retrieving a transaction history:
UC07 - General
This use case describes the process involved when a Service Provider wants to make general requests, such as checking the service's availability or retrieving a missing API response.
- Check Service Availability
- Retrieve Missing API Response
User Story
A merchant wants to check whether the Mobile Money Provider is capable of receiving requests for processing. Using the Heartbeat API they request the availability of the service from the MMP, who will then return its current status (available, unavailable, or degraded).
| Use Case Name: | General |
|---|---|
| Summary: | This use case simulates a scenario where the Service Provider would like to check the status of the Mobile Money Provider. |
| Actors: |
|
| Preconditions: |
|
| Description: |
|
| Exceptions1: |
The sequence diagram below shows the typical flow for checking the service's availability
Exceptions
- 1 : The exceptions listed are directly related to alternative paths the use case can take. Using the exceptions, it is possible to derive the unhappy flows covered by the appropriate test cases. Below are the 2 generic flows for both synchronous and asynchronous unhappy flows:
- Asynchronous
- Synchronous
