GSMA Mobile Money API

openapi: 3.0.0
info:
  description: |
    This schema defines the RESTful endpoints provided by the GSMA Mobile Money API.
    You can find out more about what the API can do for your business at [https://developer.mobilemoneyapi.io]
  version: "1.2.0"
  title: Mobile Money API
servers:
  - description: This url points to the GSMA Mobile Money API v1.2 Simulator.
    url: https://sandbox.mobilemoneyapi.io/simulator/v1.2/passthrough/mm
tags:
  - name: Transactions
    description: |
      The **Transactions** APIs are used to support mobile money financial transaction use cases.
      Transactions are used for a wide range of use cases including merchant payments, international transfers,
      domestic transfers and agent cash-in/cash-out. Reversals and adjustments are also treated as transactions.
  - name: Quotations
    description: |
      The **Quotations** APIs are used to obtain one or multiple quotes for a mobile money customer who wishes to
      transfer money. The creation of a quote involves returning any fees that will be levied on the sending customer
      and if the request is international, the forex rate is returned. A request is made for a quotation by the requesting
      Service Provider in response to a customer request. The quotation is calculated and returned. If the customer is
      satisfied with the quotation, then they can confirm and proceed with a transaction request using the **/transactions** API.
  - name: Accounts
    description: |
      The **Accounts** APIs are used to support a range of operations on a financial account resource and associated resources.
      Types of accounts include mobile wallets, financial institution accounts and utility accounts (e.g. for electricity).

      **Identifying a Target Account**

      Two methods are provided for identifying an account, the single identifier method and the multiple identifiers method.

      Single Identifier Method:

      - In the scenario where one identifier suffices to uniquely identify an account, the following path is to be used: **/accounts/{identifierType}/{identifier}**.

      Multiple Identifiers Method:

      - Where a single identifier is not sufficient to identify an account, the following path is to be used: ' **/accounts/{accountIdentifier1}@{value1}${accountIdentifier2}@{value2}${accountIdentifier3}@{value3}**'. The list of permitted account identifiers supported by the Mobile Money API can be found in the API documentation. As there can be multiple identifiers required to identify the target account, the path uses a '$' delimiter to separate each identifier, up to a limit of three account identifiers.
  - name: Bills
    description: |
      The **Bills** APIs allow a mobile money provider to allow customers to retrieve and pay bills. Specific use cases include:

      - Retrieving information on service providers (bill companies) that accept bill payments.
      - Retrieving bills at a service provider for a given mobile money customer.
      - Allowing mobile money customers to partially or fully pay bills for a service provider.
      - Retrieving bill payment information from a service provider for a given customer.
  - name: Debit Mandates
    description: |
      The **Debit Mandates** APIs allow a mobile money customer to provide prior approval for payments to be taken from their account by
      a requesting payee. If the amount limit field is not supplied, the payee will be able to take any amount. Mandates can be open-ended
      or can be constrained by a quantified number of payments for a given frequency.

      Mandates can be created, viewed and modified. The request to create a debit mandate will be typically initiated by the
      service provider (payee) but can also be requested by the customer (payer).
  - name: Links
    description: |
      The **Links** APIs are used to establish a link between two separate accounts on the client and provider systems. The API can be used for example to link a mobile wallet account to a Microfinance Institution account or a bank account. The link object does not mandate the processes to verify and authenticate a link request - this depends upon the use case. A link needs to be associated with a mode of operation:

      - pull. The link can be used by the client to debit the target account held by the provider.
      - push. The link can be used by the client to credit the target account held by the provider.
      - both. The link can be used for Push and Pull requests.
  - name: Authorisation Codes
    description: |
      The **Authorisation** Codes APIs allow a payer to generate a payment code which when presented to the payee, can be redeemed for an amount associated with the code.
      Authorisation codes can be set to expire. Note that expiry time can be specified via the API, however the mobile money provider
      may mandate a common expiry period for all codes.
      Authorisation Codes are used widely in the industry across a range of use cases, including:

      - ATM Codes for card-less withdrawals. A code is generated in advance by the customer and entered into the ATM to facilitate the withdrawal.
      - Pre-authorised codes for agent withdrawals. A code is generated in advance by the customer and given to the agent to facilitate the withdrawal.
      - Pre-authorised codes for merchant payments. The customer generates a code which can be redeemed at a merchant.
  - name: Supporting
    description: |
      Supporting APIs consist of the following:

      - **Heartbeat API:** Used for monitoring purposes and establishes whether the system of an API provider is in a state that enables a client to submit a request for processing within established SLAs.
      - **Request State API** : Used to determine the state of an asynchronous request.
      - **Responses API** : In some circumstances, the client may not have received the final representation of the resource for which it attempted to create or update. The **Responses** API allows a client to identify and retrieve the final representation of the resource assuming that the resource was created.
paths:
  # Transactions APIs. These support creation, modification and viewing of financial transactions in singular and bulk.

  /transactions:
    post:
      deprecated: true # This POST operation is to be deprecated. Please use POST /transactions/type/{transactionType} instead.
      tags:
        - Transactions
      summary: Create a Transaction
      description: Provided with a valid object representation, this endpoint allows
        for a new transaction to be created
      operationId: transactionsPOST
      parameters:
        - $ref: '#/components/parameters/X-Date'
        - $ref: '#/components/parameters/X-CorrelationID'
        - $ref: '#/components/parameters/X-API-Key'
        - $ref: '#/components/parameters/X-User-Bearer'
        - $ref: '#/components/parameters/X-Client-Id'
        - $ref: '#/components/parameters/X-Content-Hash'
        - $ref: '#/components/parameters/X-User-Credential-1'
        - $ref: '#/components/parameters/X-User-Credential-2'
        - $ref: '#/components/parameters/X-Channel'
        - $ref: '#/components/parameters/X-Callback-URL'
        - $ref: '#/components/parameters/X-Account-Holding-Institution-Identifier-Type'
        - $ref: '#/components/parameters/X-Account-Holding-Institution-Identifier'
      requestBody:
        $ref: '#/components/requestBodies/requestTransaction'
      callbacks:
        transactionsSuccessEvent:
          '{$request.header.X-Callback-URL}': # This is the callback URL provided by the client in the request header
            put:
              summary: Transaction Success Callback
              description: This callback communicates the final representation of the transaction requested by the client.
                The client endpoint is identified from the X-Callback-URL supplied in the POST request header.
              operationId: "transactionsSuccessPUT"
              parameters:
                - $ref: '#/components/parameters/X-Date'
                - $ref: '#/components/parameters/X-CorrelationID'
                - $ref: '#/components/parameters/X-Content-Hash'
                - $ref: '#/components/parameters/X-API-Key'
                - $ref: '#/components/parameters/X-User-Bearer'
                - $ref: '#/components/parameters/X-Client-Id'
              requestBody:
                $ref: '#/components/requestBodies/updateTransaction' # The callback consists of the same body as a synchronous /transactions response
              responses:
                204:
                  description: Your server returns this code if it accepts the callback
                400:
                  description: Your server returns this code if it rejects the callback due to a violation of a business rule
                401:
                  description: Your server returns this code if it rejects the callback due to an authorisation failure
                404:
                  description: Your server returns this code if it rejects the callback due to a failure to identify the target resource
                500:
                  description: Your server returns this code if it rejects the callback due to general server-side issue
                503:
                  description: Your server returns this code if it rejects the callback due to systems unavailability
        transactionsFailureEvent:
          '{$request.header.X-Callback-URL}': # This is the callback URL provided by the client in the request header
            put:
              summary: Transaction Failure Callback
              description: This callback communicates the information regarding a transaction failure in the form of an error object.
                The client endpoint is identified from the X-Callback-URL supplied in the POST request header.
              operationId: "transactionsFailurePUT"
              parameters:
                - $ref: '#/components/parameters/X-Date'
                - $ref: '#/components/parameters/X-CorrelationID'
                - $ref: '#/components/parameters/X-Content-Hash'
                - $ref: '#/components/parameters/X-API-Key'
                - $ref: '#/components/parameters/X-User-Bearer'
                - $ref: '#/components/parameters/X-Client-Id'
              requestBody:
                $ref: '#/components/requestBodies/updateError' # The callback returns the error object in the event of failure
              responses:
                204:
                  description: Your server returns this code if it accepts the callback
                400:
                  description: Your server returns this code if it rejects the callback due to a violation of a business rule
                401:
                  description: Your server returns this code if it rejects the callback due to an authorisation failure
                404:
                  description: Your server returns this code if it rejects the callback due to a failure to identify the target resource
                500:
                  description: Your server returns this code if it rejects the callback due to general server-side issue
                503:
                  description: Your server returns this code if it rejects the callback due to systems unavailability
      responses:
        201:
          description: Represents a Transaction response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/responseTransaction"
          headers:
            'X-Date':
              $ref: '#/components/headers/X-Date'
        202:
          description: Represents an Asynchronous response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/requestStateObject"
          headers:
            'X-Date':
              $ref: '#/components/headers/X-Date'
        400:
          description: Represents an Error Caused by the Violation of a Business Rule
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/errorObject"
          headers:
            'X-Date':
              $ref: '#/components/headers/X-Date'
        401:
          description: Represents an Error Caused by an Authorisation Failure
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/errorObject"
          headers:
            'X-Date':
              $ref: '#/components/headers/X-Date'
        404:
          description: Represents an Error Caused by a Failure to Identify the Target Resource
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/errorObject"
          headers:
            'X-Date':
              $ref: '#/components/headers/X-Date'
        500:
          description: Represents an Error Caused by a General Server-Side Issue
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/errorObject"
          headers:
            'X-Date':
              $ref: '#/components/headers/X-Date'
        503:
          description: Represents an Error Caused by System Unavailability
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/errorObject"
          headers:
            'X-Date':
              $ref: '#/components/headers/X-Date'
  /transactions/type/{transactionType}:
    post:
      tags:
        - Transactions
      summary: Create a Transaction
      description: Provided with a valid object representation, this endpoint allows
        for a new transaction to be created for a given transaction type passed via the URL.
      operationId: "transactionstypetransactionTypePUT"
      parameters:
        - $ref: '#/components/parameters/transactionTypePath'
        - $ref: '#/components/parameters/X-Date'
        - $ref: '#/components/parameters/X-CorrelationID'
        - $ref: '#/components/parameters/X-API-Key'
        - $ref: '#/components/parameters/X-User-Bearer'
        - $ref: '#/components/parameters/X-Client-Id'
        - $ref: '#/components/parameters/X-Content-Hash'
        - $ref: '#/components/parameters/X-User-Credential-1'
        - $ref: '#/components/parameters/X-User-Credential-2'
        - $ref: '#/components/parameters/X-Channel'
        - $ref: '#/components/parameters/X-Callback-URL'
        - $ref: '#/components/parameters/X-Account-Holding-Institution-Identifier-Type'
        - $ref: '#/components/parameters/X-Account-Holding-Institution-Identifier'
      requestBody:
        $ref: '#/components/requestBodies/requestTransactionType'
      callbacks:
        transactionsSuccessEvent:
          '{$request.header.X-Callback-URL}': # This is the callback URL provided by the client in the request header
            put:
              summary: Transaction Success Callback
              description: This callback communicates the final representation of the transaction requested by the client.
                The client endpoint is identified from the X-Callback-URL supplied in the POST request header.
              operationId: "transactionsTransactionTypeSuccessPUT"
              parameters:
                - $ref: '#/components/parameters/X-Date'
                - $ref: '#/components/parameters/X-CorrelationID'
                - $ref: '#/components/parameters/X-Content-Hash'
                - $ref: '#/components/parameters/X-API-Key'
                - $ref: '#/components/parameters/X-User-Bearer'
                - $ref: '#/components/parameters/X-Client-Id'
              requestBody:
                $ref: '#/components/requestBodies/updateTransaction' # The callback consists of the same body as a synchronous /transactions response
              responses:
                204:
                  description: Your server returns this code if it accepts the callback
                400:
                  description: Your server returns this code if it rejects the callback due to a violation of a business rule
                401:
                  description: Your server returns this code if it rejects the callback due to an authorisation failure
                404:
                  description: Your server returns this code if it rejects the callback due to a failure to identify the target resource
                500:
                  description: Your server returns this code if it rejects the callback due to general server-side issue
                503:
                  description: Your server returns this code if it rejects the callback due to systems unavailability
        transactionsFailureEvent:
          '{$request.header.X-Callback-URL}': # This is the callback URL provided by the client in the request header
            put:
              summary: Transaction Failure Callback
              description: This callback communicates the information regarding a transaction failure in the form of an error object.
                The client endpoint is identified from the X-Callback-URL supplied in the POST request header.
              operationId: "transactionsTransactionTypeFailurePUT"
              parameters:
                - $ref: '#/components/parameters/X-Date'
                - $ref: '#/components/parameters/X-CorrelationID'
                - $ref: '#/components/parameters/X-Content-Hash'
                - $ref: '#/components/parameters/X-API-Key'
                - $ref: '#/components/parameters/X-User-Bearer'
                - $ref: '#/components/parameters/X-Client-Id'
              requestBody:
                $ref: '#/components/requestBodies/updateError' # The callback returns the error object in the event of failure
              responses:
                204:
                  description: Your server returns this code if it accepts the callback
                400:
                  description: Your server returns this code if it rejects the callback due to a violation of a business rule
                401:
                  description: Your server returns this code if it rejects the callback due to an authorisation failure
                404:
                  description: Your server returns this code if it rejects the callback due to a failure to identify the target resource
                500:
                  description: Your server returns this code if it rejects the callback due to general server-side issue
                503:
                  description: Your server returns this code if it rejects the callback due to systems unavailability
      responses:
        201:
          description: Represents a Transaction response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/responseTransactionType"
          headers:
            'X-Date':
              $ref: '#/components/headers/X-Date'
        202:
          description: Represents an Asynchronous response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/requestStateObject"
          headers:
            'X-Date':
              $ref: '#/components/headers/X-Date'
        400:
          description: Represents an Error Caused by the Violation of a Business Rule
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/errorObject"
          headers:
            'X-Date':
              $ref: '#/components/headers/X-Date'
        401:
          description: Represents an Error Caused by an Authorisation Failure
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/errorObject"
          headers:
            'X-Date':
              $ref: '#/components/headers/X-Date'
        404:
          description: Represents an Error Caused by a Failure to Identify the Target Resource
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/errorObject"
          headers:
            'X-Date':
              $ref: '#/components/headers/X-Date'
        500:
          description: Represents an Error Caused by a General Server-Side Issue
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/errorObject"
          headers:
            'X-Date':
              $ref: '#/components/headers/X-Date'
        503:
          description: Represents an Error Caused by System Unavailability
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/errorObject"
          headers:
            'X-Date':
              $ref: '#/components/headers/X-Date'
  /transactions/{transactionReference}:
    parameters:
      - $ref: '#/components/parameters/transactionReference'
      - $ref: '#/components/parameters/X-Date'
      - $ref: '#/components/parameters/X-API-Key'
      - $ref: '#/components/parameters/X-User-Bearer'
      - $ref: '#/components/parameters/X-Client-Id'
      - $ref: '#/components/parameters/X-Content-Hash'
      - $ref: '#/components/parameters/X-User-Credential-1'
      - $ref: '#/components/parameters/X-User-Credential-2'
      - $ref: '#/components/parameters/X-Channel'
      - $ref: '#/components/parameters/X-Account-Holding-Institution-Identifier-Type'
      - $ref: '#/components/parameters/X-Account-Holding-Institution-Identifier'
    get:
      tags:
        - Transactions
      summary: View A Transaction
      description: This endpoint returns the details of a transaction
      operationId: "transactionsTransactionReferenceGET"
      responses:
        200:
          description: Represents a Transaction response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/responseTransaction"
          headers:
            'X-Date':
              $ref: '#/components/headers/X-Date'
        400:
          description: Represents an Error Caused by the Violation of a Business Rule
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/errorObject"
          headers:
            'X-Date':
              $ref: '#/components/headers/X-Date'
        401:
          description: Represents an Error Caused by an Authorisation Failure
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/errorObject"
          headers:
            'X-Date':
              $ref: '#/components/headers/X-Date'
        404:
          description: Represents an Error Caused by a Failure to Identify the Target Resource
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/errorObject"
          headers:
            'X-Date':
              $ref: '#/components/headers/X-Date'
        500:
          description: Represents an Error Caused by a General Server-Side Issue
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/errorObject"
          headers:
            'X-Date':
              $ref: '#/components/headers/X-Date'
        503:
          description: Represents an Error Caused by System Unavailability
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/errorObject"
          headers:
            'X-Date':
              $ref: '#/components/headers/X-Date'
    patch:
      tags:
        - Transactions
      summary: Update A Transaction
      description: This endpoint allows the transactionStatus of a transaction to be updated.
      operationId: "transactionsTransactionReferencePATCH"
      parameters:
        - $ref: '#/components/parameters/X-CorrelationID'
        - $ref: '#/components/parameters/X-Callback-URL'
      requestBody:
        $ref: '#/components/requestBodies/genericPatch'
      callbacks:
        transactionsUpdateSuccessEvent:
          '{$request.header.X-Callback-URL}': # This is the callback URL provided by the client in the request header
            put:
              summary: Transactions Update Success Callback
              description: This callback communicates a simple message to communicate that the transaction update completed successfully.
              operationId: "transactionsTransactionsUpdatePUT"
              parameters:
                - $ref: '#/components/parameters/X-Date'
                - $ref: '#/components/parameters/X-CorrelationID'
                - $ref: '#/components/parameters/X-Content-Hash'
                - $ref: '#/components/parameters/X-API-Key'
                - $ref: '#/components/parameters/X-User-Bearer'
                - $ref: '#/components/parameters/X-Client-Id'
              requestBody:
                $ref: '#/components/requestBodies/genericUpdateSuccess'
              responses:
                204:
                  description: Your server returns this code if it accepts the callback
                400:
                  description: Your server returns this code if it rejects the callback due to a violation of a business rule
                401:
                  description: Your server returns this code if it rejects the callback due to an authorisation failure
                404:
                  description: Your server returns this code if it rejects the callback due to a failure to identify the target resource
                500:
                  description: Your server returns this code if it rejects the callback due to general server-side issue
                503:
                  description: Your server returns this code if it rejects the callback due to systems unavailability
        transactionsUpdateFailureEvent:
          '{$request.header.X-Callback-URL}': # This is the callback URL provided by the client in the request header
            put:
              summary: Transaction Update Failure Callback
              description: This callback communicates the information regarding a failure to update a transaction in the form of an error object.
                The client endpoint is identified from the X-Callback-URL supplied in the POST request header.
              operationId: "transactionsTransactionsUpdateFailurePUT"
              parameters:
                - $ref: '#/components/parameters/X-Date'
                - $ref: '#/components/parameters/X-CorrelationID'
                - $ref: '#/components/parameters/X-Content-Hash'
                - $ref: '#/components/parameters/X-API-Key'
                - $ref: '#/components/parameters/X-User-Bearer'
                - $ref: '#/components/parameters/X-Client-Id'
              requestBody:
                $ref: '#/components/requestBodies/updateError' # The callback returns the error object in the event of failure
              responses:
                204:
                  description: Your server returns this code if it accepts the callback
                400:
                  description: Your server returns this code if it rejects the callback due to a violation of a business rule
                401:
                  description: Your server returns this code if it rejects the callback due to an authorisation failure
                404:
                  description: Your server returns this code if it rejects the callback due to a failure to identify the target resource
                500:
                  description: Your server returns this code if it rejects the callback due to general server-side issue
                503:
                  description: Your server returns this code if it rejects the callback due to systems unavailability
      responses:
        202:
          description: Represents an Asynchronous response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/requestStateObject"
          headers:
            'X-Date':
              $ref: '#/components/headers/X-Date'
        204:
          description: An empty response is returned for a synchronous successful patch.
        400:
          description: Represents an Error Caused by the Violation of a Business Rule
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/errorObject"
          headers:
            'X-Date':
              $ref: '#/components/headers/X-Date'
        401:
          description: Represents an Error Caused by an Authorisation Failure
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/errorObject"
          headers:
            'X-Date':
              $ref: '#/components/headers/X-Date'
        404:
          description: Represents an Error Caused by a Failure to Identify the Target Resource
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/errorObject"
          headers:
            'X-Date':
              $ref: '#/components/headers/X-Date'
        500:
          description: Represents an Error Caused by a General Server-Side Issue
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/errorObject"
          headers:
            'X-Date':
              $ref: '#/components/headers/X-Date'
        503:
          description: Represents an Error Caused by System Unavailability
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/errorObject"
          headers:
            'X-Date':
              $ref: '#/components/headers/X-Date'
  /transactions/{transactionReference}/reversals:
    post:
      tags:
        - Transactions
      summary: Create A Reversal
      description: Provided with a valid object representation, this endpoint allows for a new reversal to be created
      operationId: "transactionsTransactionReferenceReversalsPOST"
      parameters:
        - $ref: '#/components/parameters/transactionReference'
        - $ref: '#/components/parameters/X-Date'
        - $ref: '#/components/parameters/X-CorrelationID'
        - $ref: '#/components/parameters/X-API-Key'
        - $ref: '#/components/parameters/X-User-Bearer'
        - $ref: '#/components/parameters/X-Client-Id'
        - $ref: '#/components/parameters/X-Content-Hash'
        - $ref: '#/components/parameters/X-User-Credential-1'
        - $ref: '#/components/parameters/X-User-Credential-2'
        - $ref: '#/components/parameters/X-Channel'
        - $ref: '#/components/parameters/X-Callback-URL'
        - $ref: '#/components/parameters/X-Account-Holding-Institution-Identifier-Type'
        - $ref: '#/components/parameters/X-Account-Holding-Institution-Identifier'
      requestBody:
        $ref: '#/components/requestBodies/requestReversal'
      callbacks:
        reversalsSuccessEvent:
          '{$request.header.X-Callback-URL}': # This is the callback URL provided by the client in the request header
            put:
              summary: Reversal Callback
              description: This callback communicates the final representation of the reversal requested by the client.
                The client endpoint is identified from the X-Callback-URL supplied in the POST request header.
              operationId: "transactionsTransactionReferenceReversalsSuccessPUT"
              parameters:
                - $ref: '#/components/parameters/X-Date'
                - $ref: '#/components/parameters/X-CorrelationID'
                - $ref: '#/components/parameters/X-Content-Hash'
                - $ref: '#/components/parameters/X-API-Key'
                - $ref: '#/components/parameters/X-User-Bearer'
                - $ref: '#/components/parameters/X-Client-Id'
              requestBody:
                $ref: '#/components/requestBodies/updateReversal' # The callback consists of the same body as a synchronous /reversals response
              responses:
                204:
                  description: Your server returns this code if it accepts the callback
                400:
                  description: Your server returns this code if it rejects the callback due to a violation of a business rule
                401:
                  description: Your server returns this code if it rejects the callback due to an authorisation failure
                404:
                  description

# --- truncated at 32 KB (445 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/gsma/refs/heads/main/openapi/gsma-mobile-money-api-openapi.yml