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:
  • Service Provider
  • Mobile Money API Provider
Preconditions:
  • Mobile Money API Provider has GSMA Mobile Money API Implemented.
  • Mobile Money API Provider is capable of handling async calls.
Description:
  1. Payer wants to buy goods/services from a merchant.
  2. Merchant sends a transaction request to their FSP (Payee FSP).
  3. The Payee FSP then sends this request to the Payer FSP
  4. Payer FSP sends a quote back to Payee FSP for confirmation
  5. After confirmation, the transfer is sent from the Payer FSP to the Payee FSP
Exceptions1:Business rule failure, Validation failure
The sequence diagram below shows the typical flow for an authorized transaction with callback:

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:
  • Service Provider
  • Mobile Money API Provider
Preconditions:
  • Mobile Money API Provider has GSMA Mobile Money API Implemented.
  • Mobile Money API Provider is capable of handling async calls.
Description:
  1. Payer wants to buy goods/services from a merchant.
  2. Customer sends a transaction request to their FSP (Payer FSP).
  3. The Payer FSP then sends this request to the Payee FSP
  4. Payee FSP sends a quote back to Payer FSP for conformation
  5. After conformation, the transfer is sent from the Payer FSP to the Payee FSP
Exceptions1:Business rule failure, Validation 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.

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:
  • Service Provider
  • Mobile Money API Provider
Preconditions:
  • Mobile Money API Provider has GSMA Mobile Money API Implemented.
  • Mobile Money API Provider is capable of handling async calls.
Description:
  1. Service Provider submits disbursement request to MMP
  2. MMP responds with final transactions object once successful
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:
  • Service Provider
  • Mobile Money API Provider
Preconditions:
  • Mobile Money API Provider has GSMA Mobile Money API Implemented.
  • Mobile Money API Provider is capable of handling async calls.
Description:
  1. Service Provider submits a refund or reversal request to the Mobile Money Provider (MMP)
  2. MMP returns the Request State object to indicate that the request is ‘pending’
  3. MMP informs the Service Provider that the refund / reversal has been successfully completed by returning the final representation of the refund/reversal.
Exceptions1:Reversal Validation Format Failure, Refund Validation Format Failure

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:
  • Service Provider
  • Mobile Money API Provider
Preconditions:
  • Mobile Money API Provider has GSMA Mobile Money API Implemented.
  • Mobile Money API Provider is capable of handling async calls.
Description:
  1. Service Provider submits a request to retrieve a singular transaction using a transaction reference to the Mobile Money Provider (MMP)
  2. MMP sends back a transaction object matching the transaction reference
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.

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:
  • Service Provider
  • Mobile Money API Provider
Preconditions:
  • Mobile Money API Provider has GSMA Mobile Money API Implemented.
  • Mobile Money API Provider is capable of handling async calls.
Description:
  1. Service Provider requests a number of transactions from the Mobile Money Provider (MMP)
  2. MMP returns an array with the number of transactions requested
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.

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:
  • Service Provider
  • Mobile Money API Provider
Preconditions:
  • Mobile Money API Provider has GSMA Mobile Money API Implemented.
  • Mobile Money API Provider is capable of handling async calls.
Description:
  1. Service Provider request the availability of the service from the MMP
  2. MMP returns its current status (available, unavailable, or degraded)
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: