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.

International Transfer via Hub

In this diagram, a hub is used by the sending FSP to obtain a quotation and perform the transfer with the receiving FSP. A callback is provided by the receiving FSP to return the quotation and the confirmation of the transfer.

This flow can also be used for bilateral international transfers.

sequenceDiagram participant Sending FSP participant International Transfer Hub participant Receiving FSP Sending FSP->>International Transfer Hub: POST /quotations activate Sending FSP activate International Transfer Hub activate Receiving FSP Note right of International Transfer Hub: (1) The Sending FSP submits a quotation request to
the International Remittance Hub. The Hub will return the
Request State object to indicate that the request
is 'pending'. International Transfer Hub-->>Sending FSP: HTTP 202 (Request State Object) deactivate Sending FSP International Transfer Hub->>Sending FSP: PUT {Callback URL} (Quotations Object) activate Sending FSP Note right of International Transfer Hub: (2) The Hub returns the quotation to the Sending FSP. Sending FSP-->>International Transfer Hub: HTTP 204 deactivate International Transfer Hub deactivate Sending FSP Sending FSP->>International Transfer Hub: POST /transactions/type/inttransfer activate International Transfer Hub activate Sending FSP activate Receiving FSP Note right of International Transfer Hub: (3) Subject to sender confirmation, the Sending FSP submits a transaction
request to the International Remittance Hub. The Hub will return the
Request State object to indicate that the request is 'pending'. International Transfer Hub->>Receiving FSP: POST /transactions/type/inttransfer Note right of Receiving FSP: (4) The Hub in turn submits the transaction request to the
Receiving FSP. The Receiving FSP will return the
Request State object to indicate that the request is
'pending'. Receiving FSP-->>International Transfer Hub: HTTP 202 (Request State Object) International Transfer Hub-->>Sending FSP: HTTP 202 (Request State Object) deactivate International Transfer Hub deactivate Sending FSP Receiving FSP->>International Transfer Hub: PUT {Callback URL} (Transactions Object) activate International Transfer Hub activate Sending FSP Note right of Receiving FSP: (5) The FSP informs the Hub that the transaction
has been successfully completed by returning
the final representation of the transaction. International Transfer Hub-->>Receiving FSP: HTTP 204 deactivate Receiving FSP International Transfer Hub->>Sending FSP: PUT {Callback URL} (Transactions Object) Note right of International Transfer Hub: (6) The Hub in turn informs the Sending FSP that the
transaction has been successfully completed
by returning the final representation of the transaction. Sending FSP-->>International Transfer Hub: HTTP 204 deactivate International Transfer Hub deactivate Sending FSP

Open Postman Collection Open Postman Collection with Authentication

Bilateral International Transfer

In this diagram, the sending FSP connects directly with the receiving FSP to obtain a quotation and to perform the transfer. A callback is provided by the receiving FSP to return confirmation of the transfer.

sequenceDiagram participant Sending FSP participant Receiving FSP Sending FSP->>Receiving FSP: POST /quotations activate Sending FSP activate Receiving FSP Note right of Receiving FSP: (1) The Sending FSP submits a quotation request to the
Receiving FSP. The Receiving FSP will return the Request
State object to indicate that the request is 'pending'. Receiving FSP-->>Sending FSP: HTTP 202 (Request State Object) deactivate Sending FSP Receiving FSP->>Sending FSP: PUT {Callback URL} (Quotations Object) activate Sending FSP Note right of Receiving FSP: (2) The Receiving FSP returns the quotation to the Sending
FSP. Sending FSP-->>Receiving FSP: HTTP 204 deactivate Sending FSP deactivate Receiving FSP Sending FSP->>Receiving FSP: POST /transactions/type/inttransfer activate Sending FSP activate Receiving FSP Note right of Receiving FSP: (3) Subject to sender confirmation, the Sending FSP submits a transaction
request to the Receiving FSP. The Receiving FSP will return the Request
State object to indicate that the request is 'pending'. Receiving FSP-->>Sending FSP: HTTP 202 (Request State Object) deactivate Sending FSP deactivate Receiving FSP Receiving FSP->>Sending FSP: PUT {Callback URL} (Transactions Object) activate Sending FSP activate Receiving FSP Note right of Receiving FSP: (4) The FSP in turn informs the Sending FSP that the
transation has been successfully completed by
returning the final representation of the transaction. Sending FSP-->>Receiving FSP: HTTP 204 deactivate Sending FSP deactivate Receiving FSP

Open Postman Collection Open Postman Collection with Authentication

International Transfer Failure

The failure of a transfer is reflected by the return of an error object in the callback from the receiving FSP. The same pattern would also apply to a quotation failure.

sequenceDiagram participant Sending FSP participant Receiving FSP Sending FSP->>Receiving FSP: POST /quotations activate Sending FSP activate Receiving FSP Note right of Receiving FSP: (1) The Sending FSP submits a quotation request to the
Receiving FSP. The Receiving FSP will return the Request
State object to indicate that the request is 'pending'. Receiving FSP-->>Sending FSP: HTTP 202 (Request State Object) deactivate Sending FSP Receiving FSP->>Sending FSP: PUT {Callback URL} (Quotations Object) activate Sending FSP Note right of Receiving FSP: (2) The Receiving FSP returns the quotation to the Sending
FSP. Sending FSP-->>Receiving FSP: HTTP 204 deactivate Sending FSP deactivate Receiving FSP Sending FSP->>Receiving FSP: POST /transactions/type/inttransfer activate Sending FSP activate Receiving FSP Note right of Receiving FSP: (3) Subject to sender confirmation, the Sending FSP submits a transaction
request to the Receiving FSP. The Receiving FSP will return the Request
State object to indicate that the request is 'pending'. Receiving FSP-->>Sending FSP: HTTP 202 (Request State Object) deactivate Sending FSP deactivate Receiving FSP Receiving FSP->>Sending FSP: PUT {Callback URL} (Error Object) activate Sending FSP activate Receiving FSP Note right of Receiving FSP: (4) The FSP in turn informs the Sending FSP that the
transation has been failed by returning an Error
object containing the reason for failure. Sending FSP-->>Receiving FSP: HTTP 204 deactivate Sending FSP deactivate Receiving FSP

International Transfer Reversal

In some failure scenarios, a transfer may need to be reversed. This diagram illustrates an reversal with the final result communicated via the callback.

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

Open Postman Collection Open Postman Collection with Authentication

Obtain an FSP Balance

sequenceDiagram participant Sending FSP participant Receiving FSP Sending FSP->>Receiving FSP: GET /accounts/{identifierType}/{identifier}/balance activate Sending FSP activate Receiving FSP Note right of Receiving FSP: (1) Obtain the balance of the
Receiving FSP's account with
the Sending FSP. Receiving FSP-->>Sending FSP: HTTP 200 (Balance Object) deactivate Sending FSP deactivate Receiving FSP

Open Postman Collection Open Postman Collection with Authentication

Retrieve Transactions for an FSP

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

sequenceDiagram participant Sending FSP participant Receiving FSP Sending FSP->>Receiving FSP: GET /accounts/{identifierType}/{identifier}/transactions?offset=0&limit=20 activate Sending FSP activate Receiving FSP Note right of Receiving FSP: (1) The Sending FSP requests up to 20
transactions for their account from
the Receiving FSP. Receiving FSP-->>Sending FSP: HTTP 200 (Transactions Array) (X-Records-Available-Count=40) Note right of Receiving FSP: (2) The Receiving FSP returns an array
of 20 transactions and indicates via a
response header that there are 40
records available in total. Sending FSP->>Receiving FSP: GET /accounts/{identifierType}/{identifier}/transactions?offset=20&limit=20 Note right of Receiving FSP: (3) The Sending FSP requests the
remaining transactions from the
account from the Receiving FSP. Receiving FSP-->>Sending FSP: HTTP 200 (Transactions Array) (X-Records-Available-Count=40) deactivate Sending FSP deactivate Receiving FSP

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 Sending FSP participant Receiving FSP Sending FSP->>Receiving FSP: GET /heartbeat activate Sending FSP activate Receiving FSP Note right of Receiving FSP: (1) The Sending FSP requests the
availability of the service from the
Receiving FSP. Receiving FSP-->>Sending FSP: HTTP 200 (Heartbeat Object) Note right of Receiving FSP: (2) The Receiving FSP returns the
availability of the service - available,
unavailable or degraded. deactivate Sending FSP deactivate Receiving FSP

Open Postman Collection Open Postman Collection with Authentication

Retrieve a Missing API Response

This API can be used by the sending FSP 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 receiving FSP.

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

Open Postman Collection Open Postman Collection with Authentication