FinTech Providers (Insurance Savings Loans) | Mobile Money API Developer Portal

Fintech companies that provide services such as insurance and other digital financial services can use the GSMA API specification to enable their customer to make one-off bill payments or set up recurring payments for services such as subscriptions.

# 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

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

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.

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.

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

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

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

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

Obtain a Service Provider Balance

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

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

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

Start developing

# API Case Study

The third party provides inclusive insurance services to multiple countries within the Sub-Saharan region. Services available include health, life, funeral and property insurance. The insurance provider is currently directly integrated with five MMPs, and working on expanding integrations with other MMPs. Working with MMPs, is expanding the reach of the insurance provider as the MMPs’ distributions tend to be higher, enabling the insurer to distribute services to consumers that have been traditionally excluded.

Challenges

The drawback for the third-party insurance provider when dealing with multiple MMP integrations has included maintenance, costs and speed of integrations as the expectations tend to vary on a partner basis.

Opportunities

To continue reaching low income people, the insurance provider would benefit from integrating with a larger range of MMPs, enabling higher distribution. In addition, offering insurance as part of a bundle package can also increase mobile money usage as MMPs can cross-sell other services. Currently, there is no Standardised API available for the Insurance Provider; however, having access to one will enable it to offer inclusive insurance to a wider range of users, particularly those in remote areas.

Inclusivity

Insurance Provider

Bill Payments

Recurring Payments

# Ready to explore?

Find our latest API documentation.

Start developing