mobile money api
Organisations involved in transferring money across international borders such as remittance service providers rely on partnerships with mobile money providers.
The GSMA Mobile Money Specification can be used by international transfer organisations to integrate with mobile money wallets for a quick and easy pay-out channel for their customer’s recipients.
# Use cases
# Introduction
The International Transfer Mobile Money APIs allow financial service providers to perform cross-border mobile money transfers, including remittances.
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 |
|---|---|---|
| FSP - Mobile Money Providers | - To understand how to implement the Mobile Money API to receive International transfers from other FSPs. | API Provider |
| - To understand how to implement the Mobile Money API to send international transfers to other FSPs. | API Consumer | |
| FSP – International Remittance Organisations | - To understand how to implement the Mobile Money API to receive international remittances from Mobile Money Providers. | API Provider |
| - To understand how to implement the Mobile Money API to send international remittances to Mobile Money Providers. | API Consumer | |
| International Transfer Hubs | - To understand how to implement the Mobile Money APIs to receive international transfers from FSPs. | API Provider |
| - To understand how to implement the Mobile Money APIs to send international transfers to FSPs. | API Consumer |
Use case scenarios
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
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
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
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
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
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
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
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
Receiving FSP's account with
the Sending FSP. Receiving FSP-->>Sending FSP: HTTP 200 (Balance Object) deactivate Sending FSP deactivate Receiving FSP
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
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
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
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
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
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
# API Case Study
The remittance provider completed its first direct integration with an MNO six years ago, and now currently integrated with multiple MNO partners. According to the provider, the direct API Integrations offer a higher level of convenience as the recipients do not have to go to physical locations to cash out. During the pandemic, it was difficult for some to access agents or banks and direct integrations speeded remittance transactions to end users.
Challenges
The organisation is currently looking to increase its MNO integration partners; however, some challenges are slowing down the speed of expansion. Recently, it experienced a length integration with a provider, taking nearly two years to complete.
Opportunities
Integrating with more providers will increase the reach of users. A Standardised API would be beneficial for the organisation as it will allow integrations with multiple MMPs in a seamless manner.
Mama Money
# Ready to explore?
Find our latest API documentation.