mobile money api
Humanitarian agencies such as non-governmental organisations (NGOs) can use the GSMA Mobile Money API specification to increase the speed, efficiency, accountability and transparency on how cash disbursements are delivered.
# Use cases
# Introduction
The P2P Transfer Mobile Money APIs allow financial service providers (FSPs) to transfer funds from an account holding individual to another account holding individual or to a non-account holding individual (known as an unregistered customer). The API supports a wide number of financial service providers including mobile money providers, banks, and micro-finance institutions. The API supports ‘on-us’ P2P transfers (both accounts held within one FSP) and ‘off-us’ P2P transfers (accounts held in different FSPs). Bilateral and Switch-based transfers can be supported.
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.
Use case scenarios
P2P Transfer via Switch
In this diagram, a switch is used by the sending FSP to (1) confirm the recipient name, (2) request a quotation and and to (3) perform the transfer with the receiving FSP. A callback is provided by the receiving FSP to return confirmation of the transfer.
sequenceDiagram
participant Sending FSP
participant Switch
participant Receiving FSP
Sending FSP->>Switch: GET /accounts/{identifierType}/{identifier}/accountname
activate Sending FSP
activate Switch
activate Receiving FSP
Note right of Switch: (1) The Sending FSP retrieves the name of the intended recipient from the Receiving FSP via the Switch.
Switch->>Receiving FSP: GET /accounts/{identifierType}/{identifier}/accountname
Receiving FSP-->>Switch: HTTP 200 (Account Holder Name Object)
Switch-->>Sending FSP: HTTP 200 (Account Holder Name Object)
deactivate Sending FSP
deactivate Switch
deactivate Receiving FSP
Sending FSP->>Switch: POST /quotations
activate Sending FSP
activate Switch
activate Receiving FSP
Note right of Switch: (2) Subject to sender confirmation of the name returned in step 1, the Sending FSP submits a quotation
request to the Switch. The Switch will return the Request State object to indicate that the request
is 'pending'. Switch->>Receiving FSP: POST /quotations Note right of Receiving FSP: (3) The Swith in turn submits the quotation request to the Receiving FSP.
The Receiving FSP will return the Request State object to indicate
that the request is 'pending'. Receiving FSP-->>Switch: HTTP 200 (Request State Object) Switch-->>Sending FSP: HTTP 200 (Request State Object) deactivate Sending FSP deactivate Switch Receiving FSP->>Switch: PUT {Callback URL} (Quotations Object) activate Switch activate Sending FSP Note right of Receiving FSP: (4) The FSP informs the Switch that the quotation has been successfully
created by returning the final representation of the quotation. Switch-->>Receiving FSP: HTTP 204 deactivate Receiving FSP Switch->>Sending FSP: PUT {Callback URL} (Quotations Object) Note right of Switch: (5) The Swith in turn informs the Sending FSP that the transaction has succesfully complteted
by returning the final representation of the transaction. Sending FSP-->>Switch: HTTP 204 deactivate Switch deactivate Sending FSP Sending FSP->>Switch: POST /transactions/type/transfer activate Switch activate Sending FSP activate Receiving FSP Note right of Switch: (6) Subject to sender confirmation, the Sending FSP submits a transfer request to the Swith. The Switch
will return the Request State object to indicate that the request is 'pending'. Switch->>Receiving FSP: POST /transactions/type/transfer Note right of Receiving FSP: (7) The Switch 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-->>Switch: HTTP 202 (Request State Object) Switch-->>Sending FSP: HTTP 202 (Request State Object) deactivate Switch deactivate Sending FSP Receiving FSP->>Switch: PUT {Callback URL} (Transactions Object) activate Switch activate Sending FSP Note right of Receiving FSP: (8) The FSP informs the Switch that the transaction has been
successfully completed by returning the final representation of the
transaction. Switch-->>Receiving FSP: HTTP 204 deactivate Receiving FSP Switch->>Sending FSP: PUT {Callback URL} (Transactions Object) Note right of Switch: (9) The Swith in turn informs the Sending FSP that the transaction has been successfully completed
by returning the final representation of the transaction. Sending FSP-->>Switch: HTTP 204 deactivate Switch deactivate Sending FSP
request to the Switch. The Switch will return the Request State object to indicate that the request
is 'pending'. Switch->>Receiving FSP: POST /quotations Note right of Receiving FSP: (3) The Swith in turn submits the quotation request to the Receiving FSP.
The Receiving FSP will return the Request State object to indicate
that the request is 'pending'. Receiving FSP-->>Switch: HTTP 200 (Request State Object) Switch-->>Sending FSP: HTTP 200 (Request State Object) deactivate Sending FSP deactivate Switch Receiving FSP->>Switch: PUT {Callback URL} (Quotations Object) activate Switch activate Sending FSP Note right of Receiving FSP: (4) The FSP informs the Switch that the quotation has been successfully
created by returning the final representation of the quotation. Switch-->>Receiving FSP: HTTP 204 deactivate Receiving FSP Switch->>Sending FSP: PUT {Callback URL} (Quotations Object) Note right of Switch: (5) The Swith in turn informs the Sending FSP that the transaction has succesfully complteted
by returning the final representation of the transaction. Sending FSP-->>Switch: HTTP 204 deactivate Switch deactivate Sending FSP Sending FSP->>Switch: POST /transactions/type/transfer activate Switch activate Sending FSP activate Receiving FSP Note right of Switch: (6) Subject to sender confirmation, the Sending FSP submits a transfer request to the Swith. The Switch
will return the Request State object to indicate that the request is 'pending'. Switch->>Receiving FSP: POST /transactions/type/transfer Note right of Receiving FSP: (7) The Switch 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-->>Switch: HTTP 202 (Request State Object) Switch-->>Sending FSP: HTTP 202 (Request State Object) deactivate Switch deactivate Sending FSP Receiving FSP->>Switch: PUT {Callback URL} (Transactions Object) activate Switch activate Sending FSP Note right of Receiving FSP: (8) The FSP informs the Switch that the transaction has been
successfully completed by returning the final representation of the
transaction. Switch-->>Receiving FSP: HTTP 204 deactivate Receiving FSP Switch->>Sending FSP: PUT {Callback URL} (Transactions Object) Note right of Switch: (9) The Swith in turn informs the Sending FSP that the transaction has been successfully completed
by returning the final representation of the transaction. Sending FSP-->>Switch: HTTP 204 deactivate Switch deactivate Sending FSP
Bilateral P2P Transfer
In this diagram, the sending FSP connects directly with the receiving FSP to confirm the recipient name and to perform the transfer. A callback is provided by the receiving FSP to return confirmation of the transfer. In this example, a quotation is not requested.
sequenceDiagram
participant Sending FSP
participant Receiving FSP
Sending FSP->>Receiving FSP: GET /accounts/{identifierType}/{identifier}/accountname
activate Sending FSP
activate Receiving FSP
Note right of Receiving FSP: (1) The Sending FSP retrieves the name of the intended recipient from the Receiving FSP.
Receiving FSP-->>Sending FSP: HTTP 200 (Account Holder Name Object)
deactivate Receiving FSP
Sending FSP->>Receiving FSP: POST /transactions/type/transfer
activate Receiving FSP
Note right of Receiving FSP: (2) Subject to sender confirmation, the Sending FSP submits a transfer request.
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} (Transaction Object) activate Sending FSP activate Receiving FSP Note right of Receiving FSP: (3) The FSP in turn informs the Sending FSP that the transation has been succesfully completed
by returning the final representation of the transaction. Sending FSP-->>Receiving FSP: HTTP 204 deactivate Sending FSP deactivate 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} (Transaction Object) activate Sending FSP activate Receiving FSP Note right of Receiving FSP: (3) The FSP in turn informs the Sending FSP that the transation has been succesfully completed
by returning the final representation of the transaction. Sending FSP-->>Receiving FSP: HTTP 204 deactivate Sending FSP deactivate Receiving FSP
‘On-us’ P2P Transfer Initiated by a Third Party Provider
In this diagram, A third party provider enables a sender to transfer money to a recipient in the same FSP. The third party provider (1) confirms the recipient name, (2) requests a quotation and (3) performs the transfer with the FSP. A callback is provided by the FSP to return confirmation of the transfer.
sequenceDiagram
participant Third Party Provider
participant FSP
Third Party Provider->>FSP: GET /accounts/{identifierType}/{identifier}/accountname
activate Third Party Provider
activate FSP
Note right of FSP: (1) The Third Party Provider retrieves the name of the
intended recipient from the FSP. FSP-->>Third Party Provider: HTTP 200 (Account Holder Name Object) deactivate Third Party Provider deactivate FSP Third Party Provider->>FSP: POST /quotations activate Third Party Provider activate FSP Note right of FSP: (2) Subject to sender confirmation, the Third Party Provider
submits a quotation request. The FSP will return the
Request State object to indicate that the request is
'pending'. Third Party Provider-->>FSP: HTTP 202 (Request State Object) deactivate Third Party Provider deactivate FSP FSP->>Third Party Provider: PUT {Callback URL} (Quotations Object) activate Third Party Provider activate FSP Note right of FSP: (3) The FSP in turn informs the Third Party Provider that
the quotation has been successfully completed by
returning the final representation of the quotation. Third Party Provider-->>FSP: HTTP 204 deactivate Third Party Provider deactivate FSP Third Party Provider->>FSP: POST /transactions/type/transfer activate Third Party Provider activate FSP Note right of FSP: (4) Subject to sender confirmation, the Third Party Provider
submits a transfer request. The FSP will return the
Request State object to indicate that the request is
'pending'. Third Party Provider-->>FSP: HTTP 202 (Request State Object) deactivate Third Party Provider deactivate FSP FSP->>Third Party Provider: PUT {Callback URL} (Transactions Object) activate Third Party Provider activate FSP Note right of FSP: (5) The FSP in turn informs the Third Party Provider that
the transaction has been successfully completed by
returning the final representation of the transaction. Third Party Provider-->>FSP: HTTP 204 deactivate Third Party Provider deactivate FSP
intended recipient from the FSP. FSP-->>Third Party Provider: HTTP 200 (Account Holder Name Object) deactivate Third Party Provider deactivate FSP Third Party Provider->>FSP: POST /quotations activate Third Party Provider activate FSP Note right of FSP: (2) Subject to sender confirmation, the Third Party Provider
submits a quotation request. The FSP will return the
Request State object to indicate that the request is
'pending'. Third Party Provider-->>FSP: HTTP 202 (Request State Object) deactivate Third Party Provider deactivate FSP FSP->>Third Party Provider: PUT {Callback URL} (Quotations Object) activate Third Party Provider activate FSP Note right of FSP: (3) The FSP in turn informs the Third Party Provider that
the quotation has been successfully completed by
returning the final representation of the quotation. Third Party Provider-->>FSP: HTTP 204 deactivate Third Party Provider deactivate FSP Third Party Provider->>FSP: POST /transactions/type/transfer activate Third Party Provider activate FSP Note right of FSP: (4) Subject to sender confirmation, the Third Party Provider
submits a transfer request. The FSP will return the
Request State object to indicate that the request is
'pending'. Third Party Provider-->>FSP: HTTP 202 (Request State Object) deactivate Third Party Provider deactivate FSP FSP->>Third Party Provider: PUT {Callback URL} (Transactions Object) activate Third Party Provider activate FSP Note right of FSP: (5) The FSP in turn informs the Third Party Provider that
the transaction has been successfully completed by
returning the final representation of the transaction. Third Party Provider-->>FSP: HTTP 204 deactivate Third Party Provider deactivate FSP
P2P Transfer Failure
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: GET /accounts/{identifierType}/{identifier}/accountname
activate Sending FSP
activate Receiving FSP
Note right of Receiving FSP: (1) The Sending FSP retrieves the name of the
intended recipient from the Receiving FSP. Receiving FSP-->>Sending FSP: HTTP 200 (Account Holder Name Object) deactivate Receiving FSP Sending FSP->>Receiving FSP: POST /transactions/type/transfer activate Receiving FSP Note right of Receiving FSP: (2) Subject to sender confirmation, the Sending FSP
submits a transfer request. 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: (3) 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
intended recipient from the Receiving FSP. Receiving FSP-->>Sending FSP: HTTP 200 (Account Holder Name Object) deactivate Receiving FSP Sending FSP->>Receiving FSP: POST /transactions/type/transfer activate Receiving FSP Note right of Receiving FSP: (2) Subject to sender confirmation, the Sending FSP
submits a transfer request. 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: (3) 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
P2P 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 bve 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 bve 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 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
Requesting FSP's account. FSP-->>Requesting FSP: HTTP 200 (Balance Object) deactivate Requesting FSP deactivate FSP
Requesting FSP's account. FSP-->>Requesting FSP: HTTP 200 (Balance Object) deactivate Requesting FSP deactivate FSP
Retrieve Transactions for an FSP
This diagram illustrates use of a cursor mechanism to retrieve all transactions for a sending requesting FSP 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 their 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 from the
account from the Receiving FSP. FSP-->>Requesting FSP: HTTP 200 (Transactions Array) (X-Records-Available-Count=40) deactivate Requesting FSP deactivate FSP
20 transactions for their 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 from the
account from the Receiving FSP. FSP-->>Requesting FSP: HTTP 200 (Transactions Array) (X-Records-Available-Count=40) deactivate Requesting FSP deactivate 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 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
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
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. Sending FSP-->>Receiving 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. Sending FSP-->>Receiving 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 disbursement process has to be efficient and being directly integrated with the MNOs results in faster and more successful outreach. A lot of humanitarian work will be in non-urban areas, which might be more difficult to reach physically. Being able to distribute money via mobile wallets, which can be easily facilitated through integrations with MNOs, offers lot of convenience to the organisation’s disbursement process. The organisation is currently directly integrated with over 30 MNOs in various regions, mainly in the Sub-Saharan African region. As an organisation, it works with two types of beneficiaries, those that receive a large chunk of money as a response to a disaster, and those that receive recurring payments, such as supplementary income.
Challenges
The pandemic intensified the need for MNO integrations, for instance, it was easier to disburse money to women in slums in East Africa. Additionally, the advantages of disbursing directly to mobile wallets has been felt particularly when dealing with vulnerable women, who can access funds discreetly.
Opportunities
Overall, the process is fast and secure. The organisation favours API integrations is it feels it lowers the security risk associated with physical distribution, for both the beneficiary and the humanitarian worker. As an organisation that response to global crises, it would benefit from a Standard API which can allow it to connect to more MNOs in various regions globally.
Humanitarian Agency
# Ready to explore?
Find our latest API documentation.