openapi: 3.0.1
info:
  title: Customer Transfer
  description: API will enable MTN customers to transfer part of their active airtime
    or data to another MTN customer. This service excludes special data plans
  license:
    name: MADAPI
    url: https://developers.mtn.com/
  version: 3.0.0 - Last updated date:2026-08-05 16:16:51
servers:
- url: https://api.mtn.com/v1
  description: Production Server
security:
- OAuth2: []
tags:
- name: CustomerTransferService
paths:
  /customers/transactionStatus:
    get:
      tags:
      - CustomerTransferService
      summary: Customers
      description: Provides the status of a Transaction and ensures that the state
        of the transaction is communicated to service providers.
      operationId: CustomerTransferService_get_transactionStatus_customerstransaction
      parameters:
      - name: network
        in: query
        required: false
        schema:
          type: string
      - name: operation
        in: query
        required: false
        schema:
          type: string
      - name: targetSystem
        in: header
        required: false
        schema:
          type: string
      - name: transactionId
        in: query
        required: false
        schema:
          type: string
      - name: x-country-code
        in: header
        required: false
        schema:
          type: string
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                title: CustomerTransferResponse
                type: object
                properties:
                  statusCode:
                    type: string
                  statusMessage:
                    type: string
                  supportMessage:
                    type: string
                  transactionId:
                    type: string
                  sequenceNo:
                    type: string
                  data:
                    title: CustomerTransferResponseData
                    type: object
                    properties:
                      description:
                        type: string
                      valueCharged:
                        type: integer
                        format: int64
                      unit:
                        type: string
                      productName:
                        type: string
                      productId:
                        type: string
                      productType:
                        type: string
                      productCode:
                        type: string
                      agentId:
                        type: string
                      notification:
                        type: string
                      localTransactionId:
                        type: string
                      transactionState:
                        type: string
                      customerId:
                        type: string
                      receiverMsisdn:
                        type: string
                      accountBalances:
                        type: array
                        items:
                          title: AccountBalance
                          type: object
                          properties:
                            amount:
                              title: Amount
                              type: object
                              properties:
                                value:
                                  type: string
                                currencyCode:
                                  type: string
                            balanceType:
                              type: string
                  downstreamStatusCode:
                    type: integer
                    format: int32
        "400":
          description: "Bad request. Invalid request parameters, missing required\
            \ fields, or validation errors."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        "401":
          description: "Unauthorized. Invalid or missing authorization credentials,\
            \ insufficient permissions, or authentication failure."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        "403":
          description: Forbidden. Access denied. The request is valid but the server
            refuses to perform it.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        "404":
          description: Not found. The requested resource was not found or does not
            exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        "500":
          description: "Internal server error. Unexpected system failure, database\
            \ connectivity issues, or external service integration problems."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        "502":
          description: Bad gateway. The server acting as a gateway received an invalid
            response from an upstream server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        "503":
          description: Service unavailable. The server is temporarily unable to handle
            the request due to maintenance or overload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      deprecated: false
  /customers/{senderMsisdn}:
    post:
      tags:
      - CustomerTransferService
      summary: Customers
      description: Customers will be able to transfer airtime or data to other MTN
        customers using both traditional and digital channel options available to
        them.
      operationId: CustomerTransferService_post_transfer_customerssenderMsisd
      parameters:
      - name: network
        in: query
        required: false
        schema:
          type: string
      - name: senderMsisdn
        in: path
        required: true
        schema:
          type: string
      - name: transactionId
        in: header
        required: false
        schema:
          type: string
      - name: x-country-code
        in: header
        required: false
        schema:
          type: string
      - name: x-origin-channelid
        in: header
        required: false
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              title: CustomerTransferRequest
              required:
              - receiverMsisdn
              - targetSystem
              - type
              type: object
              properties:
                receiverMsisdn:
                  type: string
                productCode:
                  type: string
                productId:
                  type: integer
                  format: int32
                type:
                  type: string
                agentId:
                  type: string
                transferAmount:
                  type: string
                callbackUrl:
                  type: string
                pin:
                  type: string
                additionalInformation:
                  type: array
                  items:
                    title: AdditionalInformation
                    type: object
                    properties:
                      name:
                        type: string
                      description:
                        type: string
                targetSystem:
                  type: string
                paysrc:
                  type: string
                srcAccountType:
                  type: integer
                  format: int32
                dstAccountType:
                  type: integer
                  format: int32
        required: true
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/com_mtn_aggregator_models_response_CustomerTransferResponse'
        "400":
          description: "Bad request. Invalid request parameters, missing required\
            \ fields, or validation errors."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        "401":
          description: "Unauthorized. Invalid or missing authorization credentials,\
            \ insufficient permissions, or authentication failure."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        "403":
          description: Forbidden. Access denied. The request is valid but the server
            refuses to perform it.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        "404":
          description: Not found. The requested resource was not found or does not
            exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        "500":
          description: "Internal server error. Unexpected system failure, database\
            \ connectivity issues, or external service integration problems."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        "502":
          description: Bad gateway. The server acting as a gateway received an invalid
            response from an upstream server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        "503":
          description: Service unavailable. The server is temporarily unable to handle
            the request due to maintenance or overload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      deprecated: false
  /notification:
    post:
      tags:
      - CustomerTransferService
      summary: a User Consent Response object
      description: The users consent information is posted here as a callback notification
        once the consent action has been completed.
      operationId: CustomerTransferService_post_handleConsentNotification_notification
      parameters:
      - name: transactionId
        in: header
        required: false
        schema:
          type: string
      - name: x-country-code
        in: header
        required: false
        schema:
          type: string
      - name: x-origin-channelid
        in: header
        required: false
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              title: ConsentNotificationResponse
              type: object
              properties:
                statusCode:
                  type: string
                msisdn:
                  type: string
                userResponse:
                  type: string
                customData:
                  type: array
                  items:
                    type: string
                partnerName:
                  type: string
                sequenceNo:
                  type: string
                transactionId:
                  type: string
        required: true
      responses:
        "201":
          description: Created
        "200":
          description: Success
        "400":
          description: "Bad request. Invalid request parameters, missing required\
            \ fields, or validation errors."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        "401":
          description: "Unauthorized. Invalid or missing authorization credentials,\
            \ insufficient permissions, or authentication failure."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        "403":
          description: Forbidden. Access denied. The request is valid but the server
            refuses to perform it.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        "404":
          description: Not found. The requested resource was not found or does not
            exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        "500":
          description: "Internal server error. Unexpected system failure, database\
            \ connectivity issues, or external service integration problems."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        "502":
          description: Bad gateway. The server acting as a gateway received an invalid
            response from an upstream server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        "503":
          description: Service unavailable. The server is temporarily unable to handle
            the request due to maintenance or overload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      deprecated: false
components:
  schemas:
    com_mtn_aggregator_models_response_AccountBalance:
      title: AccountBalance
      type: object
      properties:
        amount:
          title: Amount
          type: object
          properties:
            value:
              type: string
            currencyCode:
              type: string
        balanceType:
          type: string
    com_mtn_aggregator_models_request_transfer_CustomerTransferRequest:
      title: CustomerTransferRequest
      required:
      - receiverMsisdn
      - targetSystem
      - type
      type: object
      properties:
        receiverMsisdn:
          type: string
        productCode:
          type: string
        productId:
          type: integer
          format: int32
        type:
          type: string
        agentId:
          type: string
        transferAmount:
          type: string
        callbackUrl:
          type: string
        pin:
          type: string
        additionalInformation:
          type: array
          items:
            title: AdditionalInformation
            type: object
            properties:
              name:
                type: string
              description:
                type: string
        targetSystem:
          type: string
        paysrc:
          type: string
        srcAccountType:
          type: integer
          format: int32
        dstAccountType:
          type: integer
          format: int32
    com_mtn_aggregator_models_response_Amount:
      title: Amount
      type: object
      properties:
        value:
          type: string
        currencyCode:
          type: string
    com_mtn_aggregator_models_response_consent_ConsentNotificationResponse:
      title: ConsentNotificationResponse
      type: object
      properties:
        statusCode:
          type: string
        msisdn:
          type: string
        userResponse:
          type: string
        customData:
          type: array
          items:
            type: string
        partnerName:
          type: string
        sequenceNo:
          type: string
        transactionId:
          type: string
    com_mtn_aggregator_models_response_data_CustomerTransferResponseData:
      title: CustomerTransferResponseData
      type: object
      properties:
        description:
          type: string
        valueCharged:
          type: integer
          format: int64
        unit:
          type: string
        productName:
          type: string
        productId:
          type: string
        productType:
          type: string
        productCode:
          type: string
        agentId:
          type: string
        notification:
          type: string
        localTransactionId:
          type: string
        transactionState:
          type: string
        customerId:
          type: string
        receiverMsisdn:
          type: string
        accountBalances:
          type: array
          items:
            title: AccountBalance
            type: object
            properties:
              amount:
                title: Amount
                type: object
                properties:
                  value:
                    type: string
                  currencyCode:
                    type: string
              balanceType:
                type: string
    com_mtn_aggregator_models_request_transfer_AdditionalInformation:
      title: AdditionalInformation
      type: object
      properties:
        name:
          type: string
        description:
          type: string
    APIError:
      title: APIError
      required:
      - statusCode
      - statusMessage
      type: object
      properties:
        statusCode:
          type: string
          description: Error status code
          example: "400"
        statusMessage:
          type: string
          description: Human-readable error message
          example: Bad request. Invalid parameters provided.
        supportMessage:
          type: string
          description: Technical support message or error code for troubleshooting
          example: VALIDATION_ERROR
        transactionId:
          type: string
          description: Transaction identifier for tracking and correlation
          example: "1234567890"
        sequenceNo:
          type: string
          description: Sequence number for request tracking
          example: "20250115120000001"
        timestamp:
          type: string
          description: Error timestamp in ISO 8601 format
          format: date-time
          example: 2025-01-15T12:00:00Z
        path:
          type: string
          description: API endpoint path where the error occurred
          example: /api/v1/resource
        method:
          type: string
          description: HTTP method of the request that caused the error
          example: POST
        downstreamStatusCode:
          type: string
          description: Downstream service error code if applicable
      description: Generic MADAPI error response structure
      example:
        statusCode: "400"
        statusMessage: "Bad request. Invalid request parameters, missing required\
          \ fields, or validation errors."
        supportMessage: API_ERROR
        transactionId: "1234567890"
        sequenceNo: "20250115120000001"
        timestamp: 2025-01-15T12:00:00Z
    com_mtn_aggregator_models_response_CustomerTransferResponse:
      title: CustomerTransferResponse
      type: object
      properties:
        statusCode:
          type: string
        statusMessage:
          type: string
        supportMessage:
          type: string
        transactionId:
          type: string
        sequenceNo:
          type: string
        data:
          title: CustomerTransferResponseData
          type: object
          properties:
            description:
              type: string
            valueCharged:
              type: integer
              format: int64
            unit:
              type: string
            productName:
              type: string
            productId:
              type: string
            productType:
              type: string
            productCode:
              type: string
            agentId:
              type: string
            notification:
              type: string
            localTransactionId:
              type: string
            transactionState:
              type: string
            customerId:
              type: string
            receiverMsisdn:
              type: string
            accountBalances:
              type: array
              items:
                title: AccountBalance
                type: object
                properties:
                  amount:
                    title: Amount
                    type: object
                    properties:
                      value:
                        type: string
                      currencyCode:
                        type: string
                  balanceType:
                    type: string
        downstreamStatusCode:
          type: integer
          format: int32
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api.mtn.com/v1/oauth/access_token
          scopes: {}
    Bearer:
      type: http
      description: Bearer token received from OAuth2.0 authentication with the MADAPI
      scheme: bearer
      bearerFormat: JWT