openapi: 3.0.1
info:
  title: Payment Methods Management
  description: "A comprehensive suite of APIs designed for customer payment method\
    \ details management, including associated data types. This service enables payment\
    \ method registration, validation, retrieval, and management operations. It provides\
    \ secure handling of payment method information including card details, bank accounts,\
    \ mobile money accounts, and other payment instruments across various payment\
    \ providers and systems."
  license:
    name: MADAPI
    url: https://developers.mtn.com/
  version: 3.0.0 - Last updated date:2026-09-11 15:03:13
servers:
- url: https://api.mtn.com/v1
  description: Production Server
security:
- OAuth2: []
tags:
- name: PaymentMethodsManagement
paths:
  /paymentMethod:
    get:
      tags:
      - PaymentMethodsManagement
      summary: Retrieves the list of payment methods.
      description: "This uses the customer number and optional filters to return a\
        \ list of banks, cards, or tokenized cards that are available."
      operationId: PaymentMethodsManagementService_get_fetchCustomerPaymentMethods_paymentMethod
      parameters:
      - name: customerId
        in: query
        required: false
        schema:
          type: string
      - name: description
        in: query
        required: false
        schema:
          type: string
      - name: limit
        in: query
        required: false
        schema:
          type: string
      - name: offset
        in: query
        required: false
        schema:
          type: string
      - name: providerId
        in: query
        required: false
        schema:
          type: string
      - name: sequenceNumber
        in: header
        required: false
        schema:
          type: string
      - name: transactionId
        in: query
        required: false
        schema:
          type: string
      - name: type
        in: query
        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
      responses:
        "200":
          description: HTTP 200 indicating the request succeeded; the response body
            follows the documented schema for this operation and includes correlation
            identifiers where applicable for traceability across MTN MADAPI payment
            methods management flows.
          content:
            application/json:
              schema:
                title: PaymentMethodResponse
                type: object
                properties:
                  statusCode:
                    type: string
                  statusMessage:
                    type: string
                  transactionId:
                    type: string
                  data:
                    title: ResponseData
                    type: object
                    properties:
                      id:
                        type: string
                      type:
                        type: string
                      details:
                        title: Details
                        type: object
                        properties:
                          tokenizedCard:
                            type: array
                            items:
                              title: TokenizedCardDetails
                              type: object
                              properties:
                                brand:
                                  type: string
                                value:
                                  type: string
                                tokenType:
                                  type: string
                                token:
                                  type: string
                                issuer:
                                  type: string
                                expiry:
                                  type: string
                                expired:
                                  type: boolean
                                recurring:
                                  type: boolean
                          bank:
                            type: array
                            items:
                              title: BankDetails
                              type: object
                              properties:
                                bankName:
                                  type: string
                                accountNumber:
                                  type: string
                                accountHolderName:
                                  type: string
                                bankAccountType:
                                  type: string
                                bankBranchCode:
                                  type: string
                                bankAccountNumber:
                                  type: string
                                bankAccountHolderName:
                                  type: string
                                value:
                                  type: string
                                issuer:
                                  type: string
                                logoUrl:
                                  type: string
                                recurring:
                                  type: boolean
                                paymentDay:
                                  type: string
                          account:
                            type: array
                            items:
                              title: AccountDetails
                              type: object
                              properties:
                                id:
                                  type: string
                                name:
                                  type: string
                                description:
                                  type: string
                                type:
                                  type: string
                  _links:
                    title: Links
                    type: object
                    properties:
                      self:
                        title: Self
                        type: object
                        properties:
                          href:
                            type: string
                  sequenceNumber:
                    type: string
        "400":
          description: "Bad request. Invalid request parameters, missing required\
            \ fields, or validation errors."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
              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
        "401":
          description: "Unauthorized. Invalid or missing authorization credentials,\
            \ insufficient permissions, or authentication failure."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
              example:
                statusCode: "401"
                statusMessage: "Unauthorized. Invalid or missing authorization credentials,\
                  \ insufficient permissions, or authentication failure."
                supportMessage: API_ERROR
                transactionId: "1234567890"
                sequenceNo: "20250115120000001"
                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:
                $ref: '#/components/schemas/APIError'
              example:
                statusCode: "403"
                statusMessage: Forbidden. Access denied. The request is valid but
                  the server refuses to perform it.
                supportMessage: API_ERROR
                transactionId: "1234567890"
                sequenceNo: "20250115120000001"
                timestamp: 2025-01-15T12:00:00Z
        "404":
          description: Not found. The requested resource was not found or does not
            exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
              example:
                statusCode: "404"
                statusMessage: Not found. The requested resource was not found or
                  does not exist.
                supportMessage: API_ERROR
                transactionId: "1234567890"
                sequenceNo: "20250115120000001"
                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:
                $ref: '#/components/schemas/APIError'
              example:
                statusCode: "500"
                statusMessage: "Internal server error. Unexpected system failure,\
                  \ database connectivity issues, or external service integration\
                  \ problems."
                supportMessage: API_ERROR
                transactionId: "1234567890"
                sequenceNo: "20250115120000001"
                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:
                $ref: '#/components/schemas/APIError'
              example:
                statusCode: "502"
                statusMessage: Bad gateway. The server acting as a gateway received
                  an invalid response from an upstream server.
                supportMessage: API_ERROR
                transactionId: "1234567890"
                sequenceNo: "20250115120000001"
                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:
                $ref: '#/components/schemas/APIError'
              example:
                statusCode: "503"
                statusMessage: Service unavailable. The server is temporarily unable
                  to handle the request due to maintenance or overload.
                supportMessage: API_ERROR
                transactionId: "1234567890"
                sequenceNo: "20250115120000001"
                timestamp: 2025-01-15T12:00:00Z
      deprecated: false
  /paymentMethod/{paymentMethodId}:
    put:
      tags:
      - PaymentMethodsManagement
      summary: Update a payment method
      description: Updates an existing payment method using its unique identifier
        and customer-related parameters for validation and processing.
      operationId: PaymentMethodsManagementService_put_paymentMethodUpdate_paymentMethodpayment
      parameters:
      - name: billingAccountNumber
        in: query
        required: false
        schema:
          type: string
      - name: customerMsisdn
        in: query
        required: false
        schema:
          type: string
      - name: idNumber
        in: query
        required: false
        schema:
          type: string
      - name: idType
        in: query
        required: false
        schema:
          type: string
      - name: paymentDay
        in: query
        required: false
        schema:
          type: string
      - name: paymentMethodId
        in: path
        required: true
        schema:
          type: string
      - name: providerId
        in: query
        required: false
        schema:
          type: string
      - name: sequenceNumber
        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:
              $ref: '#/components/schemas/com_mtn_aggregator_models_response_BankDetails'
        required: true
      responses:
        "200":
          description: HTTP 200 indicating the request succeeded; the response body
            follows the documented schema for this operation and includes correlation
            identifiers where applicable for traceability across MTN MADAPI payment
            methods management flows.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/com_mtn_aggregator_models_response_PaymentMethodResponse'
        "400":
          description: "Bad request. Invalid request parameters, missing required\
            \ fields, or validation errors."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
              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
        "401":
          description: "Unauthorized. Invalid or missing authorization credentials,\
            \ insufficient permissions, or authentication failure."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
              example:
                statusCode: "401"
                statusMessage: "Unauthorized. Invalid or missing authorization credentials,\
                  \ insufficient permissions, or authentication failure."
                supportMessage: API_ERROR
                transactionId: "1234567890"
                sequenceNo: "20250115120000001"
                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:
                $ref: '#/components/schemas/APIError'
              example:
                statusCode: "403"
                statusMessage: Forbidden. Access denied. The request is valid but
                  the server refuses to perform it.
                supportMessage: API_ERROR
                transactionId: "1234567890"
                sequenceNo: "20250115120000001"
                timestamp: 2025-01-15T12:00:00Z
        "404":
          description: Not found. The requested resource was not found or does not
            exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
              example:
                statusCode: "404"
                statusMessage: Not found. The requested resource was not found or
                  does not exist.
                supportMessage: API_ERROR
                transactionId: "1234567890"
                sequenceNo: "20250115120000001"
                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:
                $ref: '#/components/schemas/APIError'
              example:
                statusCode: "500"
                statusMessage: "Internal server error. Unexpected system failure,\
                  \ database connectivity issues, or external service integration\
                  \ problems."
                supportMessage: API_ERROR
                transactionId: "1234567890"
                sequenceNo: "20250115120000001"
                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:
                $ref: '#/components/schemas/APIError'
              example:
                statusCode: "502"
                statusMessage: Bad gateway. The server acting as a gateway received
                  an invalid response from an upstream server.
                supportMessage: API_ERROR
                transactionId: "1234567890"
                sequenceNo: "20250115120000001"
                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:
                $ref: '#/components/schemas/APIError'
              example:
                statusCode: "503"
                statusMessage: Service unavailable. The server is temporarily unable
                  to handle the request due to maintenance or overload.
                supportMessage: API_ERROR
                transactionId: "1234567890"
                sequenceNo: "20250115120000001"
                timestamp: 2025-01-15T12:00:00Z
      deprecated: false
components:
  schemas:
    com_mtn_aggregator_models_response_PaymentMethodResponse:
      title: PaymentMethodResponse
      type: object
      properties:
        statusCode:
          type: string
        statusMessage:
          type: string
        transactionId:
          type: string
        data:
          title: ResponseData
          type: object
          properties:
            id:
              type: string
            type:
              type: string
            details:
              title: Details
              type: object
              properties:
                tokenizedCard:
                  type: array
                  items:
                    title: TokenizedCardDetails
                    type: object
                    properties:
                      brand:
                        type: string
                      value:
                        type: string
                      tokenType:
                        type: string
                      token:
                        type: string
                      issuer:
                        type: string
                      expiry:
                        type: string
                      expired:
                        type: boolean
                      recurring:
                        type: boolean
                bank:
                  type: array
                  items:
                    title: BankDetails
                    type: object
                    properties:
                      bankName:
                        type: string
                      accountNumber:
                        type: string
                      accountHolderName:
                        type: string
                      bankAccountType:
                        type: string
                      bankBranchCode:
                        type: string
                      bankAccountNumber:
                        type: string
                      bankAccountHolderName:
                        type: string
                      value:
                        type: string
                      issuer:
                        type: string
                      logoUrl:
                        type: string
                      recurring:
                        type: boolean
                      paymentDay:
                        type: string
                account:
                  type: array
                  items:
                    title: AccountDetails
                    type: object
                    properties:
                      id:
                        type: string
                      name:
                        type: string
                      description:
                        type: string
                      type:
                        type: string
        _links:
          title: Links
          type: object
          properties:
            self:
              title: Self
              type: object
              properties:
                href:
                  type: string
        sequenceNumber:
          type: string
    com_mtn_aggregator_models_response_AccountDetails:
      title: AccountDetails
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
        type:
          type: string
    com_mtn_aggregator_models_response_TokenizedCardDetails:
      title: TokenizedCardDetails
      type: object
      properties:
        brand:
          type: string
        value:
          type: string
        tokenType:
          type: string
        token:
          type: string
        issuer:
          type: string
        expiry:
          type: string
        expired:
          type: boolean
        recurring:
          type: boolean
    com_mtn_aggregator_models_response_Details:
      title: Details
      type: object
      properties:
        tokenizedCard:
          type: array
          items:
            title: TokenizedCardDetails
            type: object
            properties:
              brand:
                type: string
              value:
                type: string
              tokenType:
                type: string
              token:
                type: string
              issuer:
                type: string
              expiry:
                type: string
              expired:
                type: boolean
              recurring:
                type: boolean
        bank:
          type: array
          items:
            title: BankDetails
            type: object
            properties:
              bankName:
                type: string
              accountNumber:
                type: string
              accountHolderName:
                type: string
              bankAccountType:
                type: string
              bankBranchCode:
                type: string
              bankAccountNumber:
                type: string
              bankAccountHolderName:
                type: string
              value:
                type: string
              issuer:
                type: string
              logoUrl:
                type: string
              recurring:
                type: boolean
              paymentDay:
                type: string
        account:
          type: array
          items:
            title: AccountDetails
            type: object
            properties:
              id:
                type: string
              name:
                type: string
              description:
                type: string
              type:
                type: string
    com_mtn_aggregator_models_response_Self:
      title: Self
      type: object
      properties:
        href:
          type: string
    com_mtn_aggregator_models_response_ResponseData:
      title: ResponseData
      type: object
      properties:
        id:
          type: string
        type:
          type: string
        details:
          title: Details
          type: object
          properties:
            tokenizedCard:
              type: array
              items:
                title: TokenizedCardDetails
                type: object
                properties:
                  brand:
                    type: string
                  value:
                    type: string
                  tokenType:
                    type: string
                  token:
                    type: string
                  issuer:
                    type: string
                  expiry:
                    type: string
                  expired:
                    type: boolean
                  recurring:
                    type: boolean
            bank:
              type: array
              items:
                title: BankDetails
                type: object
                properties:
                  bankName:
                    type: string
                  accountNumber:
                    type: string
                  accountHolderName:
                    type: string
                  bankAccountType:
                    type: string
                  bankBranchCode:
                    type: string
                  bankAccountNumber:
                    type: string
                  bankAccountHolderName:
                    type: string
                  value:
                    type: string
                  issuer:
                    type: string
                  logoUrl:
                    type: string
                  recurring:
                    type: boolean
                  paymentDay:
                    type: string
            account:
              type: array
              items:
                title: AccountDetails
                type: object
                properties:
                  id:
                    type: string
                  name:
                    type: string
                  description:
                    type: string
                  type:
                    type: string
    com_mtn_aggregator_models_response_Links:
      title: Links
      type: object
      properties:
        self:
          title: Self
          type: object
          properties:
            href:
              type: string
    APIError:
      title: APIError
      required:
      - statusCode
      - statusMessage
      type: object
      properties:
        statusCode:
          type: string
          description: Error status code
        statusMessage:
          type: string
          description: Human-readable error message
        supportMessage:
          type: string
          description: Technical support message or error code for troubleshooting
        transactionId:
          type: string
          description: Transaction identifier for tracking and correlation
        sequenceNo:
          type: string
          description: Sequence number for request tracking
        timestamp:
          type: string
          description: Error timestamp in ISO 8601 format
          format: date-time
        path:
          type: string
          description: API endpoint path where the error occurred
        method:
          type: string
          description: HTTP method of the request that caused the error
        downstreamStatusCode:
          type: string
          description: Downstream service error code if applicable
      description: Generic MADAPI error response structure
    com_mtn_aggregator_models_response_BankDetails:
      title: BankDetails
      type: object
      properties:
        bankName:
          type: string
        accountNumber:
          type: string
        accountHolderName:
          type: string
        bankAccountType:
          type: string
        bankBranchCode:
          type: string
        bankAccountNumber:
          type: string
        bankAccountHolderName:
          type: string
        value:
          type: string
        issuer:
          type: string
        logoUrl:
          type: string
        recurring:
          type: boolean
        paymentDay:
          type: string
  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