MTN TMF Payment Management - TMF676

openapi: 3.0.1
info:
  title: TMF676 Payment Management
  description: "TMF676 Payment Management Aggregator API provides comprehensive payment\
    \ management capabilities following TM Forum TMF676 standards. This service enables\
    \ payment processing, payment method management, payment status tracking, and\
    \ payment reconciliation operations. It serves as the central aggregator for all\
    \ payment-related operations, integrating with various payment systems and providers\
    \ across the MTN ecosystem."
  license:
    name: MADAPI
    url: https://developers.mtn.com/
  version: 3.0.0
servers:
- url: https://api.mtn.com/v1
  description: Production Server
security:
- OAuth2: []
tags:
- name: TMF676 Payment Management Aggregator
paths:
  /payment:
    get:
      tags:
      - TMF676 Payment Management Aggregator
      summary: Retrieve OTT tax status details
      description: "Fetches the OTT tax status details for a specific customer from\
        \ the configured CIS system, forwarding the request to downstream services\
        \ while preserving the optional transaction identifier."
      operationId: TMF676PaymentManagementAggregatorService_get_getOTTStatus_payment
      parameters:
      - name: ottTaxStatus
        in: query
        required: true
        schema:
          type: string
      - name: customerId
        in: query
        required: true
        schema:
          type: string
      - name: clientTransactionId
        in: header
        required: false
        schema:
          type: string
      responses:
        "200":
          description: Success
        "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-15T12:00:00Z
                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-15T12:00:00Z
        "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-15T12:00:00Z
                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-15T12:00:00Z
        "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-15T12:00:00Z
                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-15T12:00:00Z
        "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-15T12:00:00Z
                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-15T12:00:00Z
        "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-15T12:00:00Z
                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-15T12:00:00Z
        "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-15T12:00:00Z
                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-15T12:00:00Z
        "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-15T12:00:00Z
                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-15T12:00:00Z
      deprecated: false
    post:
      tags:
      - TMF676 Payment Management Aggregator
      summary: Process customer payment via MoMo
      description: "Initiates a customer payment using MTN MoMo channels, generating\
        \ or reusing a transaction reference, logging the full request payload, and\
        \ delegating downstream payment execution with comprehensive response auditing."
      operationId: TMF676PaymentManagementAggregatorService_post_payViaMomo_payment
      parameters:
      - name: transactionId
        in: header
        required: false
        schema:
          type: string
      - name: countryCode
        in: header
        required: false
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              title: Payment
              type: object
              properties:
                statusDate:
                  type: string
                reason:
                  type: string
                amount:
                  title: Amount
                  type: object
                  properties:
                    unit:
                      type: string
                    amount:
                      type: integer
                      format: int32
                    units:
                      type: string
                    value:
                      type: integer
                      format: int32
                code:
                  type: string
                authorizationCode:
                  type: string
                '@type':
                  type: string
                channel:
                  title: Channel
                  type: object
                  properties:
                    '@referredType':
                      type: string
                    role:
                      type: string
                    '@baseType':
                      type: string
                    '@type':
                      type: string
                    name:
                      type: string
                    id:
                      type: string
                    href:
                      type: string
                    '@schemaLocation':
                      type: string
                description:
                  type: string
                message:
                  type: string
                referenceError:
                  type: string
                payer:
                  title: Account
                  type: object
                  properties:
                    '@referredType':
                      type: string
                    entityLevel:
                      type: string
                    role:
                      type: string
                    '@baseType':
                      type: string
                    '@type':
                      type: string
                    name:
                      type: string
                    description:
                      type: string
                    id:
                      type: string
                    href:
                      type: string
                    '@schemaLocation':
                      type: string
                totalAmount:
                  title: Amount
                  type: object
                  properties:
                    unit:
                      type: string
                    amount:
                      type: integer
                      format: int32
                    units:
                      type: string
                    value:
                      type: integer
                      format: int32
                paymentItem:
                  type: array
                  items:
                    title: PaymentItem
                    type: object
                    properties:
                      totalAmount:
                        title: Amount
                        type: object
                        properties:
                          unit:
                            type: string
                          amount:
                            type: integer
                            format: int32
                          units:
                            type: string
                          value:
                            type: integer
                            format: int32
                      amount:
                        title: Amount
                        type: object
                        properties:
                          unit:
                            type: string
                          amount:
                            type: integer
                            format: int32
                          units:
                            type: string
                          value:
                            type: integer
                            format: int32
                      item:
                        title: Item
                        type: object
                        properties:
                          request:
                            title: Request
                            type: object
                            properties:
                              '@referredType':
                                type: string
                              '@baseType':
                                type: string
                              id:
                                type: string
                              href:
                                type: string
                              '@schemaLocation':
                                type: string
                          '@referredType':
                            type: string
                          orderItem:
                            type: array
                            items:
                              title: OrderItem
                              type: object
                              properties:
                                productSpecification:
                                  title: ProductSpecification
                                  type: object
                                  properties:
                                    '@referredType':
                                      type: string
                                    '@baseType':
                                      type: string
                                    '@type':
                                      type: string
                                    name:
                                      type: string
                                    id:
                                      type: string
                                    href:
                                      type: string
                                    technology:
                                      type: array
                                      items:
                                        type: string
                                    '@schemaLocation':
                                      type: string
                                    version:
                                      type: string
                                product:
                                  title: Product
                                  type: object
                                  properties:
                                    productSpecification:
                                      title: ProductSpecification
                                      type: object
                                      properties:
                                        '@referredType':
                                          type: string
                                        '@baseType':
                                          type: string
                                        '@type':
                                          type: string
                                        name:
                                          type: string
                                        id:
                                          type: string
                                        href:
                                          type: string
                                        technology:
                                          type: array
                                          items:
                                            type: string
                                        '@schemaLocation':
                                          type: string
                                        version:
                                          type: string
                                    xDir:
                                      type: string
                                    '@referredType':
                                      type: string
                                    customFields:
                                      title: CustomFields
                                      type: object
                                      properties:
                                        registrationType:
                                          type: string
                                        productOrderGroup:
                                          type: array
                                          items:
                                            type: string
                                        moMoFlag:
                                          type: boolean
                                        assignType:
                                          type: string
                                    '@type':
                                      type: string
                                    channel:
                                      type: array
                                      items:
                                        title: Channel
                                        type: object
                                        properties:
                                          '@referredType':
                                            type: string
                                          role:
                                            type: string
                                          '@baseType':
                                            type: string
                                          '@type':
                                            type: string
                                          name:
                                            type: string
                                          id:
                                            type: string
                                          href:
                                            type: string
                                          '@schemaLocation':
                                            type: string
                                    productOrder:
                                      type: array
                                      items:
                                        title: ProductOrder
                                        type: object
                                        properties:
                                          '@referredType':
                                            type: string
                                          orderItemActionSubType:
                                            type: string
                                          orderItemId:
                                            type: string
                                          id:
                                            type: string
                                          href:
                                            type: string
                                          '@schemaLocation':
                                            type: string
                                          orderItemAction:
                                            type: string
                                    isPrimaryMSISDN:
                                      type: boolean
                                    '@baseType':
                                      type: string
                                    id:
                                      type: string
                                    href:
                                      type: string
                                    place:
                                      type: array
                                      items:
                                        title: Place
                                        type: object
                                        properties:
                                          role:
                                            type: string
                                          '@type':
                                            type: string
                                    '@schemaLocation':
                                      type: string
                                    publicIdentifier:
                                      type: string
                                    simNumber:
                                      type: string
                                    productOffering:
                                      title: ProductOffering
                                      type: object
                                      properties:
                                        code:
                                          type: string
                                        '@type':
     

# --- truncated at 32 KB (94 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/mtn-group/refs/heads/main/openapi/mtn-group-tmf-payment-management-tmf676.yml