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.

Individual Disbursement

This diagram illustrates an individual disbursement using an asynchronous flow with the notification provided via a callback.

sequenceDiagram participant Disbursement Organisation participant Mobile Money Provider Disbursement Organisation->>Mobile Money Provider: POST /transactions/type/disbursement activate Disbursement Organisation activate Mobile Money Provider Note right of Mobile Money Provider: (1) The disbursement organisation 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-->>Disbursement Organisation: HTTP 202 (Request State Object) deactivate Disbursement Organisation Mobile Money Provider->>Disbursement Organisation: PUT {Callback URL} (Transactions Object) activate Disbursement Organisation Note right of Mobile Money Provider: (2) The MMP informs the disbursement
organisation that the disbursement has been
successfully completed by returning the final
representation of the transaction. Disbursement Organisation-->>Mobile Money Provider: HTTP 204 deactivate Disbursement Organisation deactivate Mobile Money Provider

Open Postman Collection Open Postman Collection with Authentication

Individual Disbursement Failure

In this example, an asynchronous flow is used with a final callback that contains the reason for failure.

sequenceDiagram participant Disbursement Organisation participant Mobile Money Provider Disbursement Organisation->>Mobile Money Provider: POST /transactions/type/disbursement activate Disbursement Organisation activate Mobile Money Provider Note right of Mobile Money Provider: (1) The disbursement organisation 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-->>Disbursement Organisation: HTTP 202 (Request State Object) deactivate Disbursement Organisation Mobile Money Provider->>Disbursement Organisation: PUT {Callback URL} (Error Object) activate Disbursement Organisation Note right of Mobile Money Provider: (2) The MMP informs the disbursement
organisation that the disbursement has failed
and returns the error object datailing the
reason for failure. Disbursement Organisation-->>Mobile Money Provider: HTTP 204 deactivate Disbursement Organisation deactivate Mobile Money Provider

Bulk Disbursement

This diagram illustrates the flow for a ‘one-shot’ bulk disbursement.

sequenceDiagram participant Disbursement Organisation participant Mobile Money Provider Disbursement Organisation->>Mobile Money Provider: POST /batchtransactions activate Disbursement Organisation activate Mobile Money Provider Note right of Mobile Money Provider: (1) The disbursement organisation submits the batch of
transactions for processing to the MMP. The MMP will
return the Request State object to indicate that the batch
request is 'pending'. Mobile Money Provider-->>Disbursement Organisation: HTTP 202 (Request State Object) deactivate Disbursement Organisation Mobile Money Provider->>Disbursement Organisation: PUT {Callback URL} (Batch Transactions Object) activate Disbursement Organisation Note right of Mobile Money Provider: (2) The MMP informs the disbursement organisation that
the request has been processed by returning the
representation of the batch. Disbursement Organisation-->>Mobile Money Provider: HTTP 204 deactivate Disbursement Organisation deactivate Mobile Money Provider opt Disbursement Organisation->>Mobile Money Provider: GET /batchtransactions/{batchId} activate Disbursement Organisation activate Mobile Money Provider Note right of Mobile Money Provider: (3) The disbursement organisation can optionally retrieve a
representation of the batch transactions object that will
confirm the overall success of the approval request. Mobile Money Provider-->>Disbursement Organisation: HTTP 200 (Batch Transactions Object) Disbursement Organisation->>Mobile Money Provider: GET /batchtransactions/{batchId}/completions Note right of Mobile Money Provider: (4) The disbursement organisation can optionally request
details of all transactions in the batch that have been
completed. Mobile Money Provider-->>Disbursement Organisation: HTTP 200 (Batch Completions Object) Disbursement Organisation->>Mobile Money Provider: GET /batchtransactions/{batchId}/rejections Note right of Mobile Money Provider: (5) The disbursement organisation can optionally request
details of all transactions in the batch that have been
rejected. Mobile Money Provider-->>Disbursement Organisation: HTTP 200 (Batch Rejections Object) end deactivate Disbursement Organisation deactivate Mobile Money Provider

Open Postman Collection Open Postman Collection with Authentication

Bulk Disbursement Failure

In this example, an asynchronous flow is used with a final callback that contains the reason for failure to process the bulk request.

sequenceDiagram participant Disbursement Organisation participant Mobile Money Provider Disbursement Organisation->>Mobile Money Provider: POST /batchtransactions activate Disbursement Organisation activate Mobile Money Provider Note right of Mobile Money Provider: (1) The disbursement organisation submits the batch of
transactions for processing to the MMP. The MMP will
return the Request State object to indicate that the batch
request is 'pending'. Mobile Money Provider-->>Disbursement Organisation: HTTP 202 (Request State Object) deactivate Disbursement Organisation Mobile Money Provider->>Disbursement Organisation: PUT {Callback URL} (Error Object) activate Disbursement Organisation Note right of Mobile Money Provider: (2) The MMP informs the disbursement organisation that
the request has failed by returning the representation of
the error object. Disbursement Organisation-->>Mobile Money Provider: HTTP 204 deactivate Disbursement Organisation deactivate Mobile Money Provider

Bulk Disbursement with Maker / Checker

This flow allows a bulk request to be processed in two steps. The first step involves the ‘maker’ system loading the request into the mobile money provider. The second step involves the ‘checker’ system approving the request.

sequenceDiagram participant Disbursement Organisation Maker participant Disbursement Organisation Checker participant Mobile Money Provider Disbursement Organisation Maker->>Mobile Money Provider: POST /batchtransactions activate Disbursement Organisation Maker activate Mobile Money Provider Note right of Mobile Money Provider: (1) The disbursement organisation maker submits the batch of
transactions for processing to the MMP. The MMP will
return the Request State object to indicate that the batch
request is 'pending'. Mobile Money Provider-->>Disbursement Organisation Maker: HTTP 202 (Request State Object) deactivate Disbursement Organisation Maker Mobile Money Provider->>Disbursement Organisation Maker: PUT {Callback URL} (Batch Transactions Object) activate Disbursement Organisation Maker Note right of Mobile Money Provider: (2) The MMP informs the disbursement organisation maker
that the request has been processed by returning the
representation of the batch. Disbursement Organisation Maker-->>Mobile Money Provider: HTTP 204 opt Disbursement Organisation Maker->>Mobile Money Provider: GET /batchtransactions/{batchId}/rejections Note right of Mobile Money Provider: (3) The disbursement organisation maker can optionally
request details of all transactions in the batch that have
been rejected. Mobile Money Provider-->>Disbursement Organisation Maker: HTTP 200 (Batch Rejections Object) end deactivate Disbursement Organisation Maker deactivate Mobile Money Provider Disbursement Organisation Checker->>Mobile Money Provider: PATCH /batchtransactions/{batchId} activate Disbursement Organisation Checker activate Mobile Money Provider Note right of Mobile Money Provider: (4) The disbursement organisation checker submits a request
to approve the transaction batch. The MMP will return the
Request State object to indicate that the request is
'pending'. Mobile Money Provider-->>Disbursement Organisation Checker: HTTP 202 (Request State Object) deactivate Disbursement Organisation Checker Mobile Money Provider->>Disbursement Organisation Checker: PUT {Callback URL} (Success) activate Disbursement Organisation Checker Note right of Mobile Money Provider: (5) The MMP informs the disbursement organisation checker
that the request has been processed by returning the
representation of the batch. Disbursement Organisation Checker-->>Mobile Money Provider: HTTP 204 deactivate Mobile Money Provider deactivate Disbursement Organisation Checker opt activate Mobile Money Provider activate Disbursement Organisation Checker Disbursement Organisation Checker->>Mobile Money Provider: GET /batchtransactions/{batchId} Note right of Mobile Money Provider: (6) The disbursement organisation checker can optionally
retrieve a representation of the batch transactions object
that will confirm the overall success of the approval
request. Mobile Money Provider-->>Disbursement Organisation Checker: HTTP 200 (Batch Transactions Object) Disbursement Organisation Checker->>Mobile Money Provider: GET /batchtransactions/{batchId}/completions Note right of Mobile Money Provider: (7) The disbursement organisation checker can optionally
request details of all transactions in the batch that have
been completed. Mobile Money Provider-->>Disbursement Organisation Checker: HTTP 200 (Batch Completions Object) Disbursement Organisation Checker->>Mobile Money Provider: GET /batchtransactions/{batchId}/rejections Note right of Mobile Money Provider: (8) The disbursement organisation checker can optionally
request details of all transactions in the batch that have
been rejected. Mobile Money Provider-->>Disbursement Organisation Checker: HTTP 200 (Batch Rejections Object) end deactivate Disbursement Organisation Checker deactivate Mobile Money Provider

Individual Disbursement Using the Polling Method

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

sequenceDiagram participant Disbursement Organisation participant Mobile Money Provider Disbursement Organisation->>Mobile Money Provider: POST /transactions/type/disbursement activate Disbursement Organisation activate Mobile Money Provider Note right of Mobile Money Provider: (1) The disbursement organisation 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-->>Disbursement Organisation: HTTP 202 (Request State Object) deactivate Disbursement Organisation loop activate Disbursement Organisation Disbursement Organisation->>Mobile Money Provider: GET /requeststates/{serverCorrelationId} Note right of Mobile Money Provider: (2) The disbursement organisation polls the MMP for the
Request State until the transaction is authorised or declied
or until the polling limit is reached. Mobile Money Provider-->>Disbursement Organisation: HTTP 200 (Request State Object) end deactivate Mobile Money Provider opt activate Mobile Money Provider Disbursement Organisation->>Mobile Money Provider: GET /transactions/transactionReference Note right of Mobile Money Provider: (3) The disbursement organisation can use the objectReference
returned in the Request State to retrieve a representation of
the completed disbursement. Mobile Money Provider-->>Disbursement Organisation: HTTP 200 (Transactions Object) end deactivate Disbursement Organisation deactivate Mobile Money Provider

Open Postman Collection Open Postman Collection with Authentication

Disbursement Reversal

In some failure scenarios, a organisation may need to reverse an individual disbursement transaction. This diagram illustrates a reversal with the final result communicated via the callback.

sequenceDiagram participant Disbursement Organisation participant Mobile Money Provider Disbursement Organisation->>Mobile Money Provider: POST /transactions/{original transaction reference}/reversals activate Disbursement Organisation activate Mobile Money Provider Note right of Mobile Money Provider: (1) The disbursement organisation 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-->>Disbursement Organisation: HTTP 202 (Request State Object) Mobile Money Provider->>Disbursement Organisation: PUT {Callback URL} (Reversal Object) Note right of Mobile Money Provider: (2) The MMP informs the The disbursement
organisation that the reversal has been
successfully completed by returning the final
representation of the reversal transaction. Disbursement Organisation-->>Mobile Money Provider: HTTP 204 deactivate Disbursement Organisation deactivate Mobile Money Provider

Open Postman Collection Open Postman Collection with Authentication

Obtain a Disbursement Organisation Balance

sequenceDiagram participant Disbursement Organisation participant Mobile Money Provider Disbursement Organisation->>Mobile Money Provider: GET /accounts/{identifierType}/{identifier}/balance activate Disbursement Organisation activate Mobile Money Provider Note right of Mobile Money Provider: (1) Obtain the balance of the
requested account. Mobile Money Provider-->>Disbursement Organisation: HTTP 200 (Balance Object) deactivate Disbursement Organisation deactivate Mobile Money Provider

Open Postman Collection Open Postman Collection with Authentication

Retrieve Transactions for a Disbursement Organisation

This diagram illustrates use of a cursor mechanism to retrieve all transactions for a disbursement organisation via multiple requests.

sequenceDiagram participant Disbursement Organisation participant Mobile Money Provider Disbursement Organisation->>Mobile Money Provider: GET /accounts/{identifierType}/{identifier}/transactions?offset=0&limit=20 activate Disbursement Organisation activate Mobile Money Provider Note right of Mobile Money Provider: (1) The disbursement
organisation requests up to
20 transactions for the
account from the MMP. Mobile Money Provider-->>Disbursement Organisation: 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. Disbursement Organisation->>Mobile Money Provider: GET /accounts/{identifierType}/{identifier}/transactions?offset=20&limit=20 Note right of Mobile Money Provider: (3) The disbursement
organisation requests the
remaining transactions for
the account from the MMP. Mobile Money Provider-->>Disbursement Organisation: HTTP 200 (Transactions Array) (X-Records-Available-Count=40) deactivate Disbursement Organisation 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 mobile money provider is in a state that enables a client to submit a request for processing.sts.

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

Open Postman Collection Open Postman Collection with Authentication

Retrieve a Missing API Response

This API can be used by the disbursement organisation 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 mobile money provider.

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

Open Postman Collection Open Postman Collection with Authentication