# 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.

# Setup a Recurring Payment

This diagram illustrates the setting-up of a recurring payment via a debit mandate. The service provider initiates the request which is authorised by the account holding customer. In this diagram, an asynchronous flow is used with a final callback.

sequenceDiagram participant Service Provider participant Mobile Money Provider participant Account Holder Service Provider->>Mobile Money Provider: POST /accounts/{identifierType}/{identifier}/debitmandates activate Service Provider activate Mobile Money Provider Note right of Mobile Money Provider: (1) The service provider submits the debit mandate request for
processing to the MMP. The MMP will return the Request
State object to indicate that the request is 'pending'. Mobile Money Provider-->>Service Provider: HTTP 202 (Request State Object) Mobile Money Provider->>Account Holder: Obtain Customer Authorisation activate Account Holder Note right of Account Holder: (2) The customer is requested to the MMP to
authorise the mandate. This can be
achieved through a number of means
including USSD Push and One Time Code.
OpenId can also be used to secure
customer authorisation. Account Holder-->>Mobile Money Provider: (Authorised) deactivate Account Holder Mobile Money Provider->>Service Provider: PUT {Callback URL} (Debit Mandates Object) Note right of Mobile Money Provider: (3) The MMP informs the service provider that the
debit mandate has been successfully created
by returning the final representation of the
debit mandate. Service Provider-->>Mobile Money Provider: HTTP 204 deactivate Service Provider deactivate Mobile Money Provider

Open Postman Collection Open Postman Collection with Authentication

# Setup a Recurring Payment Failure

In this diagram, the account holder declines to provide authorisation to setup the recurring payment. The service provider receives a callback containing an error object detailing the reason for failure.

sequenceDiagram participant Service Provider participant Mobile Money Provider participant Account Holder Service Provider->>Mobile Money Provider: POST /accounts/{identifierType}/{identifier}/debitmandates activate Service Provider activate Mobile Money Provider Note right of Mobile Money Provider: (1) The service provider submits the payment request for
processing to the MMP. The MMP will return the Request
State object to indicate that the request is 'pending'. Mobile Money Provider-->>Service Provider: HTTP 202 (Request State Object) Mobile Money Provider->>Account Holder: Obtain Customer Authorisation activate Account Holder Note right of Account Holder: (2) The customer declines the request by the
MMP to accept the debit mandate. Account Holder-->>Mobile Money Provider: (Declined) deactivate Account Holder Mobile Money Provider->>Service Provider: PUT {Callback URL} (Error Object) Note right of Mobile Money Provider: (3) The MMP informs the service provider that the
debit mandate has been declined by returning
an error object. Service Provider-->>Mobile Money Provider: HTTP 204 deactivate Service Provider deactivate Mobile Money Provider

# Take a Recurring Payment

In this diagram, the service provider initiates a payment request to the FSP to debit the account-holders account as per the debit mandate.

Open Postman Collection Open Postman Collection with Authentication

# Take a Recurring Payment Failure

In this diagram, the service provider initiates a payment request to the FSP to debit the account-holders account as per the debit mandate. The FSP is unable to process the payment and returns a callback containing the error object.

# Take a Recurring Payment using the Polling Method

In this example, an asynchronous payment flow is used with the polling method. The client polls against the request state object to determine the outcome of the payment request.

sequenceDiagram participant Service Provider participant Mobile Money Provider Service Provider->>Mobile Money Provider: POST /transactions/type/merchantpay activate Service Provider activate Mobile Money Provider Note right of Mobile Money Provider: (1) The service provider submits the payment request for
processing to the MMP, ensuring that a mandate reference
is provided for the payment. The MMP will return the
Request State object to indicate that the request is
'pending'. Mobile Money Provider-->>Service Provider: HTTP 202 (Request State Object) deactivate Service Provider loop activate Service Provider Service Provider->>Mobile Money Provider: GET /requeststates/{serverCorrelationId} Note right of Mobile Money Provider: (2) The service provider polls the MMP for the Request State
until the transaction is authorised or declied or until the
polling limit is reached. Mobile Money Provider-->>Service Provider: HTTP 200 (Request State Object) end deactivate Mobile Money Provider opt activate Mobile Money Provider Service Provider->>Mobile Money Provider: GET /transactions/transactionReference Note right of Mobile Money Provider: (3) The service provider can use the objectReference returned in
the Request State to retrieve a representation of the
completed payment. Mobile Money Provider-->>Service Provider: HTTP 200 (Transactions Object) end deactivate Service Provider deactivate Mobile Money Provider

Open Postman Collection Open Postman Collection with Authentication

# Recurring Payment Refund

Service Providers can issue a refund to payers. In this diagram, the refund is not linked to the original transaction and hence the /transactions API is used. Where a refund needs to be linked to the original transaction, the /reversals API must be used to perform the refund.

sequenceDiagram participant Service Provider participant Mobile Money Provider Service Provider->>Mobile Money Provider: POST /transactions/type/adjustment activate Service Provider activate Mobile Money Provider Note right of Mobile Money Provider: (1) The service provider submits the refund request for
processing to the MMP. The MMP will return the Request
State object to indicate that the request is 'pending'. Mobile Money Provider-->>Service Provider: HTTP 202 (Request State Object) Mobile Money Provider->>Service Provider: PUT {Callback URL} (Transactions Object) Note right of Mobile Money Provider: (2) The MMP informs the service provider that the
refund has been successfully completed by
returning the final representation of the refund. Service Provider-->>Mobile Money Provider: HTTP 204 deactivate Service Provider deactivate Mobile Money Provider

Open Postman Collection Open Postman Collection with Authentication

# Recurring Payment Reversal

In some failure scenarios, a service provider may need to reverse a transaction. This diagram illustrates a reversal with the final result communicated via the callback.

sequenceDiagram participant Service Provider participant Mobile Money Provider Service Provider->>Mobile Money Provider: POST /transactions/{original transaction reference}/reversals activate Service Provider activate Mobile Money Provider Note right of Mobile Money Provider: (1) The service provider submits the reversal request for
processing to the MMP - passing the reference of the
transaction that is to be reversed. The MMP will return the
Request State object to indicate that the request is
'pending'. Mobile Money Provider-->>Service Provider: HTTP 202 (Request State Object) Mobile Money Provider->>Service Provider: PUT {Callback URL} (Reversal Object) Note right of Mobile Money Provider: (2) The MMP informs the service provider that the
reversal has been successfully completed by
returning the final representation of the
reversal transaction. Service Provider-->>Mobile Money Provider: HTTP 204 deactivate Service Provider deactivate Mobile Money Provider

Open Postman Collection Open Postman Collection with Authentication

# Payer sets up a Recurring Payment using MMP Channel

This diagram illustrates how the MM API can be used by a mobile money provider to allow a payer to setup a recurring payment using a channel provided by the provider, for example, a mobile money app.

sequenceDiagram participant Mobile Money Provider Channel participant Mobile Money Provider Mobile Money Provider Channel->>Mobile Money Provider: POST /accounts/{identifierType}/{identifier}/debitmandates activate Mobile Money Provider Channel activate Mobile Money Provider Note right of Mobile Money Provider: (1) The MMP Channel submits the debit mandate request for
processing to the MMP. The MMP will return the Request
State object to indicate that the request is 'pending'. Mobile Money Provider-->>Mobile Money Provider Channel: HTTP 202 (Request State Object) Mobile Money Provider->>Mobile Money Provider Channel: PUT {Callback URL} (Debit Mandates Object) Note right of Mobile Money Provider: (2) The MMP informs the MMP Channel that the
debit mandate has been successfully created
by returning the final representation of the
debit mandate. Mobile Money Provider Channel-->>Mobile Money Provider: HTTP 204 deactivate Mobile Money Provider Channel deactivate Mobile Money Provider

Open Postman Collection Open Postman Collection with Authentication

# Obtain a Service Provider Balance

Open Postman Collection Open Postman Collection with Authentication

# Retrieve Payments for a Service Provider

This diagram illustrates use of a cursor mechanism to retrieve all payments for a service provider via multiple requests.

sequenceDiagram participant Service Provider participant Mobile Money Provider Service Provider->>Mobile Money Provider: GET /accounts/{identifierType}/{identifier}/transactions?offset=0&limit=20 activate Service Provider activate Mobile Money Provider Note right of Mobile Money Provider: (1) The service provider requests
up to 20 transactions for the
account from the MMP. Mobile Money Provider-->>Service Provider: HTTP 200 (Transactions Array) (X-Records-Available-Count=40) Note right of Mobile Money Provider: (2) The MMP returns an array of
20 transactions and indicates
via a response header that
there are 40 records
available in total. Service Provider->>Mobile Money Provider: GET /accounts/{identifierType}/{identifier}/transactions?offset=20&limit=20 Note right of Mobile Money Provider: (3) The service provider requests
the remaining transactions for
the account from the MMP. Mobile Money Provider-->>Service Provider: HTTP 200 (Transactions Array) (X-Records-Available-Count=40) deactivate Service Provider deactivate Mobile Money 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 FSP is in a state that enables a client to submit a request for processing.

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

Open Postman Collection Open Postman Collection with Authentication

# Retrieve a Missing API Response

This API can be used by the service provider to retrieve a link to the final representation of the resource for which it attempted to create. Use this API when a callback is not received from the FSP.

sequenceDiagram participant Service Provider participant Mobile Money Provider Service Provider->>Mobile Money Provider: GET /responses{clientCorrelationId} activate Service Provider activate Mobile Money Provider Note right of Mobile Money Provider: (1) Using the service provider's
clientCorrelationId, a request for the
missing API response is sent. Mobile Money Provider-->>Service Provider: HTTP 200 (Responses Object) Note right of Mobile Money Provider: (2) A Responses object is returned
containing a link to the missing
resource. Service Provider->>Mobile Money Provider: GET /{link} Note right of Mobile Money Provider: (3) The service provider uses the link to
obtain a representation of the missing
resource. Mobile Money Provider-->>Service Provider: HTTP 200 (Requested Object) deactivate Mobile Money Provider deactivate Service Provider

Open Postman Collection Open Postman Collection with Authentication

← Recurring Payments API Service Definition →