# About Use Case Scenarios

The GSMA Simulator for the Mobile Money API is a simulated API implementation developed by the GSMA to facilitate API adoption and testing, thereby decreasing implementation effort and time to market for Mobile Money Providers and ecosystem Service Providers. Developers can navigate through Use Case Scenarios providing access to a set of pre-defined Postman Collections for the Simulator to try out some of the most common mobile money API use cases, or directly access the OAS interface for the API Specification and use the API Try It Out functionality from there.

# Successful Retrieval of Bills

This diagram illustrates how a mobile money provider can retrieve bills for a given service provider customer account.

sequenceDiagram participant Mobile Money Provider participant Service Provider Mobile Money Provider->>Service Provider: GET /accounts/{identifierType}/{identifier}/bills activate Mobile Money Provider activate Service Provider Note right of Service Provider: (1) Obtain all bills of a given account. Service Provider-->>Mobile Money Provider: HTTP 200 (Bills Object) deactivate Mobile Money Provider deactivate Service Provider

Open Postman Collection Open Postman Collection with Authentication

# Unsuccessful Retrieval of Bills

This diagram illustrates the return of an error object where a service provider is unable to return bill details to a mobile money provider.

sequenceDiagram participant Mobile Money Provider participant Service Provider Mobile Money Provider->>Service Provider: GET /accounts/{identifierType}/{identifier}/bills activate Mobile Money Provider activate Service Provider Note right of Service Provider: (1) Retrieve all bills for a given account. Service Provider-->>Mobile Money Provider: HTTP 4xx/5xx (Error Object) Note right of Service Provider: (2) Return the error object providing
detais of the failure reason. deactivate Mobile Money Provider deactivate Service Provider

# Make a Successful Bill Payment with Callback

This diagram illustrates how a mobile money provider can make a bill payment to a service provider using the asynchronous callback method. To illustrate the end to end flow, a leg has been added to describe how a third payment provider can initiate a bill payment request to a mobile money provider.

sequenceDiagram participant Third Party Payment Provider participant Mobile Money Provider participant Service Provider Note right of Third Party Payment Provider: (1) The provider that enables the payer to pay
bills submits a payment request to the MMP. Third Party Payment Provider->>Mobile Money Provider: POST /transactions/type/billpay activate Third Party Payment Provider activate Mobile Money Provider Mobile Money Provider-->>Third Party Payment Provider: HTTP 202 (Request State Object) deactivate Third Party Payment Provider Mobile Money Provider->>Service Provider: POST /accounts/{identifierType}/{identifier}/bills/{billReference}/payments activate Service Provider Note right of Service Provider: (2) The MMP submits the bill payment request
for processing to the Service Provider. The
Service Provider will return the Request State
object to indicate that the request is 'pending'. Service Provider-->>Mobile Money Provider: HTTP 202 (Request State Object) deactivate Mobile Money Provider Service Provider->>Mobile Money Provider: PUT {Callback URL} (Bill Payments Object) activate Mobile Money Provider Note right of Service Provider: (3) The Service Provider informs the MMP
that the request has been succesfully
completed by returning the final
representation of the bill payment. Mobile Money Provider-->>Service Provider: HTTP 204 deactivate Service Provider Note right of Third Party Payment Provider: (4) The MMP informs the third party payment provider that the
request has been succesfully completed by returning the
final representation of the transactions object. Mobile Money Provider->>Third Party Payment Provider: PUT {Callback URL} (Transactions Object) activate Third Party Payment Provider Third Party Payment Provider-->> Mobile Money Provider: HTTP 204 deactivate Mobile Money Provider deactivate Third Party Payment Provider

Open Postman Collection Open Postman Collection with Authentication

# Make an Unsuccessful Bill Payment with Callback

This diagram illustrates the return of an error object where a service provider fails to process a bill payment request.

sequenceDiagram participant Mobile Money Provider participant Service Provider Mobile Money Provider->>Service Provider: POST /accounts/{identifierType}/{identifier}/bills/{billReference}/payments activate Service Provider activate Mobile Money Provider Note right of Service Provider: (1) The MMP submits the bill payment request
for processing to the Service Provider. The
Service Provider will return the Request State
object to indicate that the request is 'pending'. Service Provider-->>Mobile Money Provider: HTTP 202 (Request State Object) deactivate Mobile Money Provider Service Provider->>Mobile Money Provider: PUT {Callback URL} (Error Object) activate Mobile Money Provider Note right of Service Provider: (2) The Service Provider informs the MMP
that the request failed by returning a
representation of the error object. Mobile Money Provider-->>Service Provider: HTTP 204 deactivate Service Provider deactivate Mobile Money Provider

# Make a Bill Payment with Polling

This diagram illustrates how a mobile money provider can make a bill payment to a service provider using the asynchronous polling method.

sequenceDiagram participant Mobile Money Provider participant Service Provider Mobile Money Provider->>Service Provider: POST /accounts/{identifierType}/{identifier}/bills/{billReference}/payments activate Service Provider activate Mobile Money Provider Note right of Service Provider: (1) The MMP submits the bill payment request for processing
to the Service Provider. The Service Provider will return
the Request State object to indicate that the request is
'pending'. Service Provider-->>Mobile Money Provider: HTTP 202 (Request State Object) deactivate Mobile Money Provider loop activate Mobile Money Provider Mobile Money Provider->>Service Provider: GET /requeststates/{serverCorrelationId} Note right of Service Provider: (2) The MMP polls the Service Provider for the Request State
until the bill payment is processed or until the polling limit is
reached. The request state will return the final status of the
required, i.e. completed or failed. Service Provider-->>Mobile Money Provider: HTTP 200 (Request State Object) end deactivate Service Provider deactivate Mobile Money Provider

Open Postman Collection Open Postman Collection with Authentication

# Retrieval of Bill Payments

This diagram illustrates how a mobile money provider can retrieve payments against a given bill for a given service provider customer account.

sequenceDiagram participant Mobile Money Provider participant Service Provider Mobile Money Provider->>Service Provider: GET /accounts/{identifierType}/{identifier}/bills/{billReference}/payments?offset=0&limit=10 activate Mobile Money Provider activate Service Provider Note right of Service Provider: (1) The MMP requests up to 10 bill
payments for the account from the
Service Provider. Service Provider-->>Mobile Money Provider: HTTP 200 (Bill Payments Array) (X-Records-Available-Count=20) Note right of Service Provider: (2) The Service Provider returns an array
of 10 bill payments and indicates via a
response header that there are 20
records available in total. Mobile Money Provider->>Service Provider: GET /accounts/{identifierType}/{identifier}/bills/{billReference}/payments?offset=10&limit=10 Note right of Service Provider: (3) The MMP requests the remaining
bill payments for the account
from the Service Provider. Service Provider-->>Mobile Money Provider: HTTP 200 (Bill Payments Array) (X-Records-Available-Count=20) deactivate Mobile Money Provider deactivate Service Provider

Open Postman Collection Open Postman Collection with Authentication

# Check for Service Availability

The Heartbeat API is used for monitoring purposes and establishes whether the Service Provider is in a state that enables an FSP to submit a request for processing.

sequenceDiagram participant Mobile Money Provider participant Service Provider Mobile Money Provider->>Service Provider: GET /heartbeat activate Mobile Money Provider activate Service Provider Note right of Service Provider: (1) The MMP requests the availability of the
service from the Service Provider. Service Provider-->>Mobile Money Provider: HTTP 200 (Heartbeat Object) Note right of Service Provider: (2) The Service Provider returns the
availability of the service - available,
unavailable or degraded. deactivate Mobile Money Provider deactivate Service Provider

Open Postman Collection Open Postman Collection with Authentication

← Bill Payments API Service Definition →