mobile money api
Companies in the Energy, Utilities and Agritech industries can use the GSMA API specification to support their customers save time by automating the bill payment process. As an example, monthly utility payments can be set up which saves time for customers and resources for companies as this type of set up removes the need for manual payment processing.
# Use cases
# Introduction
The Recurring Payments Mobile Money APIs allow service providers to setup electronic payment mandates for mobile money customers and initiate payments against payment mandates.
For further reading, please refer to the following:
- Getting Started. Specifies the design principles, behaviours, and error handling of the Mobile Money API.
- API Service Definition. Documents all Mobile Money API endpoints, fields, objects, and enumerations.
All documentation can be found on the GSMA Mobile Money API Developer Portal.
# Intended Audience
| Audience | Usage | Role |
|---|---|---|
| Mobile Money Providers | - To understand how to implement the Mobile Money API to receive recurring payment requests from service providers. - To understand how to implement the Mobile Money API to create recurring payment requests initiated by customers using a channel (e.g. app) provided by the mobile money provider. | API Provider |
| Service Providers | To understand how to implement the Mobile Money API to request recurring payment mandates against mobile money accounts. | API Consumer |
Use case scenarios
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
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
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
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.
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 Mobile Money Provider->>Service Provider: PUT {Callback URL} (Transactions Object) activate Service Provider Note right of Mobile Money Provider: (2) The MMP informs the service provider that the
transaction has been successfully completed
by returning the final representation of the
transaction. Service Provider-->>Mobile Money Provider: HTTP 204 deactivate Service Provider deactivate Mobile Money Provider
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 Mobile Money Provider->>Service Provider: PUT {Callback URL} (Transactions Object) activate Service Provider Note right of Mobile Money Provider: (2) The MMP informs the service provider that the
transaction has been successfully completed
by returning the final representation of the
transaction. Service Provider-->>Mobile Money Provider: HTTP 204 deactivate Service Provider deactivate Mobile Money Provider
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.
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 Mobile Money Provider->>Service Provider: PUT {Callback URL} (Error Object) activate Service Provider Note right of Mobile Money Provider: (2) The MMP informs the service provider that the
payment has failed and returns the error
object detailing the reason for failure. Service Provider-->>Mobile Money Provider: HTTP 204 deactivate Service Provider deactivate Mobile Money Provider
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 Mobile Money Provider->>Service Provider: PUT {Callback URL} (Error Object) activate Service Provider Note right of Mobile Money Provider: (2) The MMP informs the service provider that the
payment has failed and returns the error
object detailing the reason for failure. Service Provider-->>Mobile Money Provider: HTTP 204 deactivate Service Provider deactivate Mobile Money Provider
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
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
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
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
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
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
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
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
Obtain a Service Provider Balance
sequenceDiagram
participant Service Provider
participant Mobile Money Provider
Service Provider->>Mobile Money Provider: GET /accounts/{identifierType}/{identifier}/balance
activate Service Provider
activate Mobile Money Provider
Note right of Mobile Money Provider: (1) Obtain the balance of the
requested account. Mobile Money Provider-->>Service Provider: HTTP 200 (Balance Object) deactivate Service Provider deactivate Mobile Money Provider
requested account. Mobile Money Provider-->>Service Provider: HTTP 200 (Balance Object) deactivate Service Provider deactivate Mobile Money Provider
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
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
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
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
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
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
# Succeed case study
As an energy provider whose business is mainly in rural areas, partnerships with MNOs are of extreme importance to its operations. Mobile Money is regarded an enabler of its business. Most of the third-party service provider’s consumers are pay-as-you go customers and by being directly integrated with over 10 MNO partners, it facilitates faster and smoother payments.
Challenges
Although the process of direct integrations has improved since its first integration over seven years ago, the provider are still experiences some challenges when integrating with new partners, particularly the length of integration. The energy provider has previously considered using aggregators; however, the costs proved to be significantly high.
Opportunities
The business has stated it would be beneficial to use a Standardised API, as will allow the provider to connect with more MNOs and expand services it offers at a faster rate. One of the provider’s struggles has been maintaining the multiple MNO API connections, which can be minimised by using a Standard API.
Engie
Energy Provider
# Ready to explore?
Find our latest API documentation.