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).
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
The sequence diagram below shows the typical flow for an authorized transaction with callback:
The sequence diagram below shows the typical flow for an authorized transaction with polling:
The sequence diagram below shows the typical flow for an authorized transaction with an 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).
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:
The sequence diagram below shows the typical flow for an failed transaction with callback:
UC03 - Disbursements
The Disbursement Mobile Money APIs allow organisations to disburse funds to mobile money recipients.
- Individual
- Bulk
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:
Global Health NGO wants to make a bulk disbursement. They simply submit the request for processing to the Mobile Money Provider, who will then return the final representation of the batch once successfully completed.
Global Health NGO also decides to retrieve a representation of the batch transactions, so that they can confirm the overall success of the approval request.
Global Health NGO may also optionally request details of all transactions in the batch that have been completed, or rejected.
| Use Case Name: | Disbursements |
|---|---|
| Summary: | This use case simulates a scenario where the a service provider would like to disbuse funds to multiple mobile money recipients |
| Actors: |
|
| Preconditions: |
|
| Description: |
|
| Exceptions1: | Retrieve Bulk failure, Retrieve Bulk Rejections failure, Retrieve Bulk Completions failure |
The sequence diagram below shows the typical flow for a bulk 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.
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:
The sequence diagram below shows the typical flow for a merchant reversal:
UC05 - Transactions
This use case describes the process involved when a Service Provider wants to retrieve a single transaction through the Mobile Money API.
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
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: |
The Service Provider wants to request their own balance. To do so they simply send a request to the Mobile Money Provider, who returns with a balance object.
| Use Case Name: | Account Information |
|---|---|
| Summary: | Service Provider requests their own account balance through the Mobile Money API and the Mobile Money Provider handles the request and successfully responds synchronously with the requested account's balance. |
| Actors: |
|
| Preconditions: |
|
| Description: |
|
| Exceptions1: | Target Resource Failure |
| The sequence diagram below shows the typical flow for retrieving a merchant's balance: |
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
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
A merchant fails to receive a callback from the Mobile Money Provider, so they want to get understand what happened to the missing resource. To do so the merchant uses their client correlation ID to make a request for the missing API response. The MMP returns a link to the missing resource, which the merchant can then use to obtain the final representation of the missing resource.
| Use Case Name: | General |
|---|---|
| Summary: | This use case simulates a scenario where the Service Provider would like to retrieve a missing API response. |
| Actors: |
|
| Preconditions: |
|
| Description: |
|
| Exceptions1: | clientCorrelationId error |
The sequence diagram below shows the typical flow for retrieving a missing API response:
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
