MTN Group Customer Transfer Service API

openapi: 3.2.0
info:
  title: Mtn Group Customer Transfer Service API
  version: 3.0.0
  license:
    name: MADAPI
    url: https://developers.mtn.com/
  description: 'Operations tagged CustomerTransferService across 2 of this provider''s published API definitions: mtn-group-customer-data-transfer-ng-prod.yml, mtn-group-mtn-customer-datatransfer.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.mtn.com/v1
  description: Production Server
security:
- OAuth2: []
tags:
- name: CustomerTransferService
paths:
  /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: senderMsisdn
        in: path
        required: true
        schema:
          type: string
      - name: network
        in: query
        required: false
        schema:
          type: string
      - name: x-country-code
        in: header
        required: false
        schema:
          type: string
      - name: transactionId
        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:
                additionalInformation:
                  type: array
                  items:
                    title: AdditionalInformation
                    type: object
                    properties:
                      name:
                        type: string
                      description:
                        type: string
                agentId:
                  type: string
                productId:
                  type: integer
                  format: int32
                dstAccountType:
                  type: integer
                  format: int32
                transferAmount:
                  type: string
                type:
                  type: string
                targetSystem:
                  type: string
                paysrc:
                  type: string
                productCode:
                  type: string
                pin:
                  type: string
                srcAccountType:
                  type: integer
                  format: int32
                callbackUrl:
                  type: string
                receiverMsisdn:
                  type: string
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                title: CustomerTransferResponse
                type: object
                properties:
                  downstreamStatusCode:
                    type: integer
                    format: int32
                  sequenceNo:
                    type: string
                  data:
                    title: CustomerTransferResponseData
                    type: object
                    properties:
                      agentId:
                        type: string
                      productId:
                        type: string
                      localTransactionId:
                        type: string
                      description:
                        type: string
                      productName:
                        type: string
                      notification:
                        type: string
                      unit:
                        type: string
                      productCode:
                        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
                      valueCharged:
                        type: integer
                        format: int64
                      customerId:
                        type: string
                      receiverMsisdn:
                        type: string
                      transactionState:
                        type: string
                      productType:
                        type: string
                  links:
                    type: array
                    items:
                      title: Link
                      type: object
                      properties:
                        template:
                          title: UriTemplate
                          type: object
                          properties:
                            template:
                              type: string
                            variables:
                              title: TemplateVariables
                              type: object
                              properties:
                                variables:
                                  type: array
                                  items:
                                    title: TemplateVariable
                                    type: object
                                    properties:
                                      name:
                                        type: string
                                      limit:
                                        type: integer
                                        format: int32
                                      description:
                                        type: string
                                      type:
                                        title: VariableType
                                        type: object
                                        properties:
                                          optional:
                                            type: boolean
                                          combiner:
                                            type: string
                                          key:
                                            type: string
                                      cardinality:
                                        title: Cardinality
                                        type: object
                            baseUri:
                              type: string
                            groups:
                              title: ExpandGroups
                              type: object
                              properties:
                                groupList:
                                  type: array
                                  items:
                                    title: ExpandGroup
                                    type: object
                                    properties:
                                      variables:
                                        title: TemplateVariables
                                        type: object
                                        properties:
                                          variables:
                                            type: array
                                            items:
                                              title: TemplateVariable
                                              type: object
                                              properties:
                                                name:
                                                  type: string
                                                limit:
                                                  type: integer
                                                  format: int32
                                                description:
                                                  type: string
                                                type:
                                                  title: VariableType
                                                  type: object
                                                  properties:
                                                    optional:
                                                      type: boolean
                                                    combiner:
                                                      type: string
                                                    key:
                                                      type: string
                                                cardinality:
                                                  title: Cardinality
                                                  type: object
                                      type:
                                        title: VariableType
                                        type: object
                                        properties:
                                          optional:
                                            type: boolean
                                          combiner:
                                            type: string
                                          key:
                                            type: string
                        affordances:
                          type: array
                          items:
                            title: Affordance
                            type: object
                            properties:
                              models:
                                type: object
                                additionalProperties:
                                  title: AffordanceModel
                                  type: object
                                  properties:
                                    output:
                                      title: PayloadMetadata
                                      type: object
                                    input:
                                      title: InputPayloadMetadata
                                      type: object
                                    queryMethodParameters:
                                      type: array
                                      items:
                                        title: QueryParameter
                                        type: object
                                        properties:
                                          name:
                                            type: string
                                          value:
                                            type: string
                                          required:
                                            type: boolean
                                    name:
                                      type: string
                                    link:
                                      title: Link
                                      type: object
                                    httpMethod:
                                      title: HttpMethod
                                      type: object
                                      properties:
                                        name:
                                          type: string
                        hreflang:
                          type: string
                        profile:
                          type: string
                        rel:
                          title: LinkRelation
                          type: object
                        name:
                          type: string
                        href:
                          type: string
                        media:
                          type: string
                        title:
                          type: string
                        type:
                          type: string
                        deprecation:
                          type: string
                  statusMessage:
                    type: string
                  transactionId:
                    type: string
                  statusCode:
                    type: string
                  supportMessage:
                    type: string
        '400':
          description: Bad request. Invalid request parameters, missing required fields, or validation errors.
          content:
            application/json:
              schema:
                title: APIError
                required:
                - statusCode
                - statusMessage
                type: object
                properties:
                  path:
                    type: string
                    description: API endpoint path where the error occurred
                    example: /api/v1/resource
                  downstreamStatusCode:
                    type: string
                    description: Downstream service error code if applicable
                  sequenceNo:
                    type: string
                    description: Sequence number for request tracking
                    example: '20250115120000001'
                  method:
                    type: string
                    description: HTTP method of the request that caused the error
                    example: POST
                  statusMessage:
                    type: string
                    description: Human-readable error message
                    example: Bad request. Invalid parameters provided.
                  transactionId:
                    type: string
                    description: Transaction identifier for tracking and correlation
                    example: '1234567890'
                  statusCode:
                    type: string
                    description: Error status code
                    example: '400'
                  supportMessage:
                    type: string
                    description: Technical support message or error code for troubleshooting
                    example: VALIDATION_ERROR
                  timestamp:
                    type: string
                    description: Error timestamp in ISO 8601 format
                    format: date-time
                    example: 2025-01-15 12:00:00+00:00
                description: Generic MADAPI error response structure
                example:
                  sequenceNo: '20250115120000001'
                  statusMessage: Bad request. Invalid request parameters, missing required fields, or validation errors.
                  transactionId: '1234567890'
                  statusCode: '400'
                  supportMessage: API_ERROR
                  timestamp: 2025-01-15 12:00:00+00:00
        '401':
          description: Unauthorized. Invalid or missing authorization credentials, insufficient permissions, or authentication failure.
          content:
            application/json:
              schema:
                title: APIError
                required:
                - statusCode
                - statusMessage
                type: object
                properties:
                  path:
                    type: string
                    description: API endpoint path where the error occurred
                    example: /api/v1/resource
                  downstreamStatusCode:
                    type: string
                    description: Downstream service error code if applicable
                  sequenceNo:
                    type: string
                    description: Sequence number for request tracking
                    example: '20250115120000001'
                  method:
                    type: string
                    description: HTTP method of the request that caused the error
                    example: POST
                  statusMessage:
                    type: string
                    description: Human-readable error message
                    example: Bad request. Invalid parameters provided.
                  transactionId:
                    type: string
                    description: Transaction identifier for tracking and correlation
                    example: '1234567890'
                  statusCode:
                    type: string
                    description: Error status code
                    example: '400'
                  supportMessage:
                    type: string
                    description: Technical support message or error code for troubleshooting
                    example: VALIDATION_ERROR
                  timestamp:
                    type: string
                    description: Error timestamp in ISO 8601 format
                    format: date-time
                    example: 2025-01-15 12:00:00+00:00
                description: Generic MADAPI error response structure
                example:
                  sequenceNo: '20250115120000001'
                  statusMessage: Unauthorized. Invalid or missing authorization credentials, insufficient permissions, or authentication failure.
                  transactionId: '1234567890'
                  statusCode: '401'
                  supportMessage: API_ERROR
                  timestamp: 2025-01-15 12:00:00+00:00
        '403':
          description: Forbidden. Access denied. The request is valid but the server refuses to perform it.
          content:
            application/json:
              schema:
                title: APIError
                required:
                - statusCode
                - statusMessage
                type: object
                properties:
                  path:
                    type: string
                    description: API endpoint path where the error occurred
                    example: /api/v1/resource
                  downstreamStatusCode:
                    type: string
                    description: Downstream service error code if applicable
                  sequenceNo:
                    type: string
                    description: Sequence number for request tracking
                    example: '20250115120000001'
                  method:
                    type: string
                    description: HTTP method of the request that caused the error
                    example: POST
                  statusMessage:
                    type: string
                    description: Human-readable error message
                    example: Bad request. Invalid parameters provided.
                  transactionId:
                    type: string
                    description: Transaction identifier for tracking and correlation
                    example: '1234567890'
                  statusCode:
                    type: string
                    description: Error status code
                    example: '400'
                  supportMessage:
                    type: string
                    description: Technical support message or error code for troubleshooting
                    example: VALIDATION_ERROR
                  timestamp:
                    type: string
                    description: Error timestamp in ISO 8601 format
                    format: date-time
                    example: 2025-01-15 12:00:00+00:00
                description: Generic MADAPI error response structure
                example:
                  sequenceNo: '20250115120000001'
                  statusMessage: Forbidden. Access denied. The request is valid but the server refuses to perform it.
                  transactionId: '1234567890'
                  statusCode: '403'
                  supportMessage: API_ERROR
                  timestamp: 2025-01-15 12:00:00+00:00
        '404':
          description: Not found. The requested resource was not found or does not exist.
          content:
            application/json:
              schema:
                title: APIError
                required:
                - statusCode
                - statusMessage
                type: object
                properties:
                  path:
                    type: string
                    description: API endpoint path where the error occurred
                    example: /api/v1/resource
                  downstreamStatusCode:
                    type: string
                    description: Downstream service error code if applicable
                  sequenceNo:
                    type: string
                    description: Sequence number for request tracking
                    example: '20250115120000001'
                  method:
                    type: string
                    description: HTTP method of the request that caused the error
                    example: POST
                  statusMessage:
                    type: string
                    description: Human-readable error message
                    example: Bad request. Invalid parameters provided.
                  transactionId:
                    type: string
                    description: Transaction identifier for tracking and correlation
                    example: '1234567890'
                  statusCode:
                    type: string
                    description: Error status code
                    example: '400'
                  supportMessage:
                    type: string
                    description: Technical support message or error code for troubleshooting
                    example: VALIDATION_ERROR
                  timestamp:
                    type: string
                    description: Error timestamp in ISO 8601 format
                    format: date-time
                    example: 2025-01-15 12:00:00+00:00
                description: Generic MADAPI error response structure
                example:
                  sequenceNo: '20250115120000001'
                  statusMessage: Not found. The requested resource was not found or does not exist.
                  transactionId: '1234567890'
                  statusCode: '404'
                  supportMessage: API_ERROR
                  timestamp: 2025-01-15 12:00:00+00:00
        '500':
          description: Internal server error. Unexpected system failure, database connectivity issues, or external service integration problems.
          content:
            application/json:
              schema:
                title: APIError
                required:
                - statusCode
                - statusMessage
                type: object
                properties:
                  path:
                    type: string
                    description: API endpoint path where the error occurred
                    example: /api/v1/resource
                  downstreamStatusCode:
                    type: string
                    description: Downstream service error code if applicable
                  sequenceNo:
                    type: string
                    description: Sequence number for request tracking
                    example: '20250115120000001'
                  method:
                    type: string
                    description: HTTP method of the request that caused the error
                    example: POST
                  statusMessage:
                    type: string
                    description: Human-readable error message
                    example: Bad request. Invalid parameters provided.
                  transactionId:
                    type: string
                    description: Transaction identifier for tracking and correlation
                    example: '1234567890'
                  statusCode:
                    type: string
                    description: Error status code
                    example: '400'
                  supportMessage:
                    type: string
                    description: Technical support message or error code for troubleshooting
                    example: VALIDATION_ERROR
                  timestamp:
                    type: string
                    description: Error timestamp in ISO 8601 format
                    format: date-time
                    example: 2025-01-15 12:00:00+00:00
                description: Generic MADAPI error response structure
                example:
                  sequenceNo: '20250115120000001'
                  statusMessage: Internal server error. Unexpected system failure, database connectivity issues, or external service integration problems.
                  transactionId: '1234567890'
                  statusCode: '500'
                  supportMessage: API_ERROR
                  timestamp: 2025-01-15 12:00:00+00:00
        '502':
          description: Bad gateway. The server acting as a gateway received an invalid response from an upstream server.
          content:
            application/json:
              schema:
                title: APIError
                required:
                - statusCode
                - statusMessage
                type: object
                properties:
                  path:
                    type: string
                    description: API endpoint path where the error occurred
                    example: /api/v1/resource
                  downstreamStatusCode:
                    type: string
                    description: Downstream service error code if applicable
                  sequenceNo:
                    type: string
                    description: Sequence number for request tracking
                    example: '20250115120000001'
                  method:
                    type: string
                    description: HTTP method of the request that caused the error
                    example: POST
                  statusMessage:
                    type: string
                    description: Human-readable error message
                    example: Bad request. Invalid parameters provided.
                  transactionId:
                    type: string
                    description: Transaction identifier for tracking and correlation
                    example: '1234567890'
                  statusCode:
                    type: string
                    description: Error status code
                    example: '400'
                  supportMessage:
                    type: string
                    description: Technical support message or error code for troubleshooting
                    example: VALIDATION_ERROR
                  timestamp:
                    type: string
                    description: Error timestamp in ISO 8601 format
                    format: date-time
                    example: 2025-01-15 12:00:00+00:00
                description: Generic MADAPI error response structure
                example:
                  sequenceNo: '20250115120000001'
                  statusMessage: Bad gateway. The server acting as a gateway received an invalid response from an upstream server.
                  transactionId: '1234567890'
                  statusCode: '502'
                  supportMessage: API_ERROR
                  timestamp: 2025-01-15 12:00:00+00:00
        '503':
          description: Service unavailable. The server is temporarily unable to handle the request due to maintenance or overload.
          content:
            application/json:
              schema:
                title: APIError
                required:
                - statusCode
                - statusMessage
                type: object
                properties:
                  path:
                    type: string
                    description: API endpoint path where the error occurred
                    example: /api/v1/resource
                  downstreamStatusCode:
                    type: string
                    description: Downstream service error code if applicable
                  sequenceNo:
                    type: string
                    description: Sequence number for request tracking
                    example: '20250115120000001'
                  method:
                    type: string
                    description: HTTP method of the request that caused the error
                    example: POST
                  statusMessage:
                    type: string
                    description: Human-readable error message
                    example: Bad request. Invalid parameters provided.
                  transactionId:
                    type: string
                    description: Transaction identifier for tracking and correlation
                    example: '1234567890'
                  statusCode:
                    type: string
                    description: Error status code
                    example: '400'
                  supportMessage:
                    type: string
                    description: Technical support message or error code for troubleshooting
                    example: VALIDATION_ERROR
                  timestamp:
                    type: string
                    description: Error timestamp in ISO 8601 format
                    format: date-time
                    example: 2025-01-15 12:00:00+00:00
                description: Generic MADAPI error response structure
                example:
                  sequenceNo: '20250115120000001'
                  statusMessage: Service unavailable. The server is temporarily unable to handle the request due to maintenance or overload.
                  transactionId: '1234567890'
                  statusCode: '503'
                  supportMessage: API_ERROR
                  timestamp: 2025-01-15 12:00:00+00:00
      deprecated: false
    servers:
    - url: https://api.mtn.com/v1
      description: Production Server
  /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: transactionId
        in: query
        required: false
        schema:
          type: string
      - name: operation
        in: query
        required: false
        schema:
          type: string
      - name: network
        in: query
        required: false
        schema:
          type: string
      - name: x-country-code
        in: header
        required: false
        schema:
          type: string
      - name: targetSystem
        in: header
        required: false
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                title: CustomerTransferResponse
                type: object
                properties:
                  downstreamStatusCode:
                    type: integer
                    format: int32
                  sequenceNo:
                    type: string
                  data:
                    title: CustomerTransferResponseData
                    type: object
                    properties:
                      agentId:
                        type: string
                      productId:
                        type: string
                      localTransactionId:
                        type: string
                      description:
                        type: string
                      productName:
                        type: string
                      notification:
                        type: string
                      unit:
                        type: string
                      productCode:
                        type: string
                      accountBalances:
                        type: array
                        items:
                          title: AccountBalance
                          type: object
                          properties:
                            amount:
             

# --- truncated at 32 KB (91 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/mtn-group/refs/heads/main/openapi/mtn-group-customertransferservice-api-openapi.yml