# 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 an Account Link

This diagram illustrates the setting-up of an account link. The requesting FSP 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 Requesting FPS participant FSP participant Account Holder Requesting FPS->>FSP: POST /accounts/{identifierType}/{identifier}/links activate Requesting FPS activate FSP Note right of FSP: (1) The requesting FPS submits the debit mandate request for
processing to the FSP. The FSP will return the Request
State object to indicate that the request is 'pending'. FSP-->>Requesting FPS: HTTP 202 (Request State Object) FSP->>Account Holder: Obtain Customer Authorisation activate Account Holder Note right of Account Holder: (2) The account holder is requested by the
FSP to authorise the link. 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-->>FSP: (Authorised) deactivate Account Holder FSP->>Requesting FPS: PUT {Callback URL} (Debit Mandates Object) Note right of FSP: (3) The FSP informs the requesting FPS that the
link has been successfully created by
returning the final representation of the link. Requesting FPS-->>FSP: HTTP 204 deactivate Requesting FPS deactivate FSP

Open Postman Collection Open Postman Collection with Authentication

# Setup an Account Link Failure

In this diagram, the account holder declines to provide authorisation to setup the account link. The requesting FSP receives a callback containing an error object detailing the reason for failure.

sequenceDiagram participant Requesting FPS participant FSP participant Account Holder Requesting FPS->>FSP: POST /accounts/{identifierType}/{identifier}/links activate Requesting FPS activate FSP Note right of FSP: (1) The requesting FPS submits the debit mandate request for
processing to the FSP. The FSP will return the Request
State object to indicate that the request is 'pending'. FSP-->>Requesting FPS: HTTP 202 (Request State Object) FSP->>Account Holder: Obtain Customer Authorisation activate Account Holder Note right of Account Holder: (2) The account holder declines the link
request. Account Holder-->>FSP: (Declined) deactivate Account Holder FSP->>Requesting FPS: PUT {Callback URL} (Error Object) Note right of FSP: (3) The FSP informs the requesting FPS that the
link has been declined by returning an error
object. Requesting FPS-->>FSP: HTTP 204 deactivate Requesting FPS deactivate FSP

# Perform a Transfer for a Linked Account

In this diagram, the requesting FSP initiates a transfer to the FSP using an established link.

sequenceDiagram participant Requesting FSP participant FSP Requesting FSP->>FSP: POST /transactions/type/transfer activate Requesting FSP activate FSP Note right of FSP: (1) The requesting FSP submits the transfer request for
processing to the FSP, ensuring that a link reference
is provided for the transfer. The FSP will return the Request
State object to indicate that the request is 'pending'. FSP-->>Requesting FSP: HTTP 202 (Request State Object) deactivate Requesting FSP FSP->>Requesting FSP: PUT {Callback URL} (Transactions Object) activate Requesting FSP Note right of FSP: (2) The FSP informs the requesting FSP that the
transfer has been successfully completed by
returning the final representation of the
transaction. Requesting FSP-->>FSP: HTTP 204 deactivate Requesting FSP deactivate FSP

Open Postman Collection Open Postman Collection with Authentication

# Perform a Transfer for a Linked Account - Failure

In this diagram, the requesting FSP initiates a transfer to the FSP using an established link. The FSP is unable to process the transfer and returns a callback containing the error object.

# Perform a Transfer using an Account Link via the Polling Method

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

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

Open Postman Collection Open Postman Collection with Authentication

# Perform a Transfer Reversal

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

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

Open Postman Collection Open Postman Collection with Authentication

# Obtain a Financial Service Provider Balance

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

Open Postman Collection Open Postman Collection with Authentication

# Retrieve Transfers for a Financial Service Provider

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

sequenceDiagram participant Requesting FSP participant FSP Requesting FSP->>FSP: GET /accounts/{identifierType}/{identifier}/transactions?offset=0&limit=20 activate Requesting FSP activate FSP Note right of FSP: (1) The requesting FSP requests
up to 20 transactions for the
account from the FSP. FSP-->>Requesting FSP: HTTP 200 (Transactions Array) (X-Records-Available-Count=40) Note right of FSP: (2) The FSP returns an array of
20 transactions and indicates
via a response header that
there are 40 records
available in total. Requesting FSP->>FSP: GET /accounts/{identifierType}/{identifier}/transactions?offset=20&limit=20 Note right of FSP: (3) The requesting FSP requests
the remaining transactions for
the account from the FSP. FSP-->>Requesting FSP: HTTP 200 (Transactions Array) (X-Records-Available-Count=40) deactivate Requesting FSP deactivate 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 Requesting FSP participant FSP Requesting FSP->>FSP: GET /heartbeat activate Requesting FSP activate FSP Note right of FSP: (1) The requesting FSP requests the
availability of the service from the FSP. FSP-->>Requesting FSP: HTTP 200 (Heartbeat Object) Note right of FSP: (2) The FSP returns the availability of
the service - available, unavailable
or degraded. deactivate Requesting FSP deactivate FSP

Open Postman Collection Open Postman Collection with Authentication

# Retrieve a Missing API Response

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

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

Open Postman Collection Open Postman Collection with Authentication

← Account Linking API Service Definition →