mobile money api

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

# Payee-Initiated Merchant Payment

In this example, an asynchronous payment flow is used with a final callback. The merchant initiates the request and will be credited when the payer approves the request.

sequenceDiagram participant Merchant participant Mobile Money Provider participant Payer Merchant->>Mobile Money Provider: POST /transactions/type/merchantpay activate Merchant activate Mobile Money Provider Note right of Mobile Money Provider: (1) The Merchant 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-->>Merchant: HTTP 202 (Request State Object) deactivate Merchant Mobile Money Provider->>Payer: Obtain Customer Authorisation activate Payer Note right of Payer: (2) The Payer is requested to the MMP to
authorise the payment. This can be
achieved through a number of means
including USSD Push and One Time Code.
OpenId can also be used for Payer authorisation. Payer-->>Mobile Money Provider: (Authorised) deactivate Payer activate Merchant Mobile Money Provider->>Merchant: PUT {Callback URL} (Transactions Object) Note right of Mobile Money Provider: (3) The MMP informs the Merchant that the
transaction has been successfully completed
by returning the final representation of the
transaction. Merchant-->>Mobile Money Provider: HTTP 204 deactivate Merchant deactivate Mobile Money Provider
Open Postman Collection Open Postman Collection with Authentication

# Payee-Initiated Merchant Payment Failure

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

sequenceDiagram participant Merchant participant Mobile Money Provider participant Payer Merchant->>Mobile Money Provider: POST /transactions/type/merchantpay activate Merchant activate Mobile Money Provider Note right of Mobile Money Provider: (1) The Merchant 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-->>Merchant: HTTP 202 (Request State Object) deactivate Merchant Mobile Money Provider->>Payer: Obtain Customer Authorisation activate Payer Note right of Payer: (2) The Payer is requested to the MMP to
authorise the payment. This can be
achieved through a number of means
including USSD Push and One Time Code.
OpenId can also be used for Payer authorisation. Payer-->>Mobile Money Provider: (Authorised) deactivate Payer activate Merchant Mobile Money Provider->>Merchant: PUT {Callback URL} (Transactions Object) Note right of Mobile Money Provider: (3) The MMP informs the Merchant that the
transaction has been successfully completed
by returning the final representation of the
transaction. Merchant-->>Mobile Money Provider: HTTP 204 deactivate Merchant deactivate Mobile Money Provider

# Payee-Initiated Merchant 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 Merchant participant Mobile Money Provider participant Payer Merchant->>Mobile Money Provider: POST /transactions/type/merchantpay activate Merchant activate Mobile Money Provider Note right of Mobile Money Provider: (1) The Merchant 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-->>Merchant: HTTP 202 (Request State Object) deactivate Merchant par loop activate Merchant Merchant->>Mobile Money Provider: GET /requeststates/{serverCorrelationId} Note right of Mobile Money Provider: (2) The Merchant polls the MMP for the Request State until the
transaction is authorised or declined or until the polling limit
is reached. Mobile Money Provider-->>Merchant: HTTP 200 (Request State Object) end and Mobile Money Provider->>Payer: Obtain Customer Authorisation activate Payer Note right of Payer: (3) The Payer is requested to the MMP to
authorise the payment. This can be
achieved through a number of means
including USSD Push and One Time Code.
OpenId can also be used for Payer
authorisation. Payer-->>Mobile Money Provider: (Authorised) end deactivate Merchant deactivate Payer deactivate Mobile Money Provider opt activate Mobile Money Provider activate Merchant Merchant->>Mobile Money Provider: GET /transactions/transactionsReference Note right of Mobile Money Provider: (4) The Merchant can use the objectReference returned in the
Request State to retrieve a representation of the complete
payment transaction. Mobile Money Provider-->>Merchant: HTTP 200 (Transactions Object) end deactivate Merchant deactivate Mobile Money Provider
Open Postman Collection Open Postman Collection with Authentication

# Payer-Initiated Merchant Payment

In this example, an asynchronous payment flow is used with a final callback. The payer initiates the request and will be debited upon successful completion of the request.

sequenceDiagram participant Payer participant Mobile Money Provider participant Merchant Payer->>Mobile Money Provider: POST /transactions/type/merchantpay activate Payer activate Mobile Money Provider Note right of Mobile Money Provider: (1) The Payer's channel (e.g. Mobile Money App) 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-->>Payer: HTTP 202 (Request State Object) deactivate Payer Mobile Money Provider->>Payer: PUT {Callback URL} (transactions Object) activate Payer Note right of Mobile Money Provider: (2) The MMP informs the Payer's channel that the
payment has been successfully completed
by returning the final representation of the
transaction. Payer-->>Mobile Money Provider: HTTP 204 deactivate Payer activate Merchant Mobile Money Provider->>Merchant: Notify Note right of Merchant: (3) The MMP notifies the merchant tha the
payment has successfully compeleted. deactivate Mobile Money Provider deactivate Merchant
Open Postman Collection Open Postman Collection with Authentication

# Payer-Initiated Merchant Payment Failure

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

sequenceDiagram participant Payer participant Mobile Money Provider participant Merchant Payer->>Mobile Money Provider: POST /transactions/type/merchantpay activate Payer activate Mobile Money Provider Note right of Mobile Money Provider: (1) The Payer's channel (e.g. Mobile Money App) 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-->>Payer: HTTP 202 (Request State Object) deactivate Payer Mobile Money Provider->>Payer: PUT {Callback URL} (Error Object) activate Payer Note right of Mobile Money Provider: (2) The MMP informs the Payer's channel that the
payment has been failed and returns the error
object detailing the reason for failure. Payer-->>Mobile Money Provider: HTTP 204 deactivate Payer activate Merchant Mobile Money Provider->>Merchant: Notify Note right of Merchant: (3) The MMP notifies the merchant tha the
payment has failed. deactivate Mobile Money Provider deactivate Merchant

# Payee-Initiated Merchant Payment using a Pre-authorised Payment Code

In this example the /authorisationcodes API is used to obtain a pre-authorised payment code. This in turn is presented by the payer to the merchant who initiates the payment request. Both flows in the diagram result in a callback. This flow is primarily used for payment on delivery use cases.

sequenceDiagram participant Payer participant Merchant participant Mobile Money Provider Payer->>Mobile Money Provider: POST /accounts/{identifierType}/{identifier}/authorisationcodes activate Payer activate Mobile Money Provider Note right of Mobile Money Provider: (1) The Payer's channel (e.g. Mobile Money App) submits
the request to generate an authorisation code to the
MMP. The MMP will return the Request State object to
indicate that the request is 'pending'. Mobile Money Provider-->>Payer: HTTP 202 (Request State Object) Mobile Money Provider->>Payer: PUT {Callback URL} (Authorisation Code Object) Note right of Mobile Money Provider: (2) The MMP informs the Payer's channel that the
request has been successfully completed by
returing the final representation of the
authorisation code. Payer-->>Mobile Money Provider: HTTP 204 deactivate Payer deactivate Mobile Money Provider Note right of Payer: (3) The Payer communicates the code to the merchant. This
can be via QR code or by verbally communicating the code. Payer->>Merchant: Communicates Code Verbally or via QR Presentment activate Payer activate Merchant activate Mobile Money Provider Merchant->>Mobile Money Provider: POST /transactions/type/merchantpay Note right of Mobile Money Provider: (4) The Merchant submits the payment request for
processing to the MMP. The request will contain the
authorisation code. The MMP will return the Request
State object to indicate that the request is 'pending'. Mobile Money Provider-->>Merchant: HTTP 202 (Request State Object) deactivate Merchant Mobile Money Provider->>Merchant: PUT {Callback URL} (Transactions Object) activate Merchant Note right of Mobile Money Provider: (5) The MMP informs the Merchant that the
transaction has been successfully completed by
returning the final representation of the
transaction. Merchant-->>Mobile Money Provider: HTTP 204 deactivate Payer deactivate Merchant deactivate Mobile Money Provider
Open Postman Collection Open Postman Collection with Authentication

# Merchant Payment Refund

Merchants 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 Merchant participant Mobile Money Provider Merchant->>Mobile Money Provider: POST /transactions/type/adjustment activate Merchant activate Mobile Money Provider Note right of Mobile Money Provider: (1) The Merchant 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-->>Merchant: HTTP 202 (Request State Object) Mobile Money Provider->>Merchant: PUT {Callback URL} (Transactions Object) Note right of Mobile Money Provider: (2) The MMP informs the Merchant that the
refund has been successfully completed by
returning the final representation of the refund. Merchant-->>Mobile Money Provider: HTTP 204 deactivate Merchant deactivate Mobile Money Provider
Open Postman Collection Open Postman Collection with Authentication

# Merchant Payment Reversal

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

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

# Obtain a Merchant Balance

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

# Retrieve Payments for a Merchant

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

sequenceDiagram participant Merchant participant Mobile Money Provider Merchant->>Mobile Money Provider: GET /accounts/{identifierType}/{identifier}/transactions?offset=0&limit=20 activate Merchant activate Mobile Money Provider Note right of Mobile Money Provider: (1) The Merchant requests up to
20 transactions for the
account from the MMP. Mobile Money Provider-->>Merchant: 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. Merchant->>Mobile Money Provider: GET /accounts/{identifierType}/{identifier}/transactions?offset=20&limit=20 Note right of Mobile Money Provider: (3) The Merchant requests the
remaining transactions for
the account from the MMP. Mobile Money Provider-->>Merchant: HTTP 200 (Transactions Array) (X-Records-Available-Count=40) deactivate Merchant 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.

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

# Retrieve a Missing API Response

This API can be used by the merchant 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 Merchant participant Mobile Money Provider Merchant->>Mobile Money Provider: GET /responses{clientCorrelationId} activate Merchant activate Mobile Money Provider Note right of Mobile Money Provider: (1) Using the Merchant's
clientCorrelationId, a request for the
missing API response is sent. Mobile Money Provider-->>Merchant: HTTP 200 (Responses Object) Note right of Mobile Money Provider: (2) A Responses object is returned
containing a link to the missing
resource. Merchant->>Mobile Money Provider: GET /{link} Note right of Mobile Money Provider: (3) The Merchant uses the link to obtain
a representation of the missing
resource. Mobile Money Provider-->>Merchant: HTTP 200 (Requested Object) deactivate Merchant deactivate Mobile Money Provider
Open Postman Collection Open Postman Collection with Authentication

← API Service Definition →