MTN Payments V1

openapi: 3.0.1
info:
  title: Payments v1
  description: "This is the Payment API for MADAPI. Handles payment use cases such\
    \ as spTransfer, Debit request, Payment request, and related financial transactions.\
    \ Provides comprehensive payment processing capabilities including merchant payments,\
    \ customer payments, transaction status queries, payment history, and reverse\
    \ payment operations."
  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: Payment
- name: Consent
paths:
  /payment-link:
    post:
      tags:
      - Payment
      summary: Provides the ability for a consumer to generate a payment link for
        account payment
      description: Provides the ability for a consumer to get the payment link for
        the requesting MSISDN so as to enable the customer to make payment to the
        service providers.
      operationId: Payment_post_generatePaymentLink_paymentlink
      parameters:
      - name: transactionId
        in: header
        required: false
        schema:
          type: string
      - name: offerMenuId
        in: query
        required: false
        schema:
          type: string
      - name: countryCode
        in: header
        required: false
        schema:
          type: string
      - name: targetSystem
        in: header
        required: false
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              title: PaymentRequest
              type: object
              properties:
                statusDate:
                  type: string
                extension:
                  title: Extension
                  type: object
                  properties:
                    bundleCode:
                      type: string
                    awufu:
                      type: string
                    bundleInput:
                      type: string
                    networkOperator:
                      type: string
                    channel:
                      type: string
                    language:
                      type: string
                    additionalInformation1:
                      type: string
                    additionalInformation2:
                      type: string
                    amountUnit:
                      type: string
                    transactionId:
                      type: string
                    iname:
                      type: string
                    communicationChannel:
                      type: string
                    notification:
                      type: string
                    receivingCustomerId:
                      type: string
                    benmsisdn:
                      type: string
                    serviceGroupCode:
                      type: string
                    lineNumber:
                      type: string
                    rechargeType:
                      type: string
                redirectURL:
                  type: string
                authorizationCode:
                  type: string
                deliveryMethod:
                  type: string
                scheduled:
                  title: Scheduledtransactiondate
                  type: object
                  properties:
                    date:
                      type: string
                    frequency:
                      title: Frequency
                      type: object
                      properties:
                        duration:
                          type: string
                        frequencyType:
                          title: FrequencyType
                          type: object
                          properties:
                            type:
                              type: string
                        durationType:
                          title: DurationType
                          type: object
                          properties:
                            plural:
                              type: string
                            singular:
                              type: string
                            type:
                              type: string
                channel:
                  type: string
                description:
                  type: string
                payer:
                  title: Payer
                  type: object
                  properties:
                    payerRef:
                      type: string
                    payerSurname:
                      type: string
                    includePayerCharges:
                      type: boolean
                    payerIdType:
                      type: string
                    payerId:
                      type: string
                    payerName:
                      type: string
                    payerNote:
                      type: string
                paymentmethods:
                  type: array
                  items:
                    type: string
                frequency:
                  title: Frequency
                  type: object
                  properties:
                    duration:
                      type: string
                    frequencyType:
                      title: FrequencyType
                      type: object
                      properties:
                        type:
                          type: string
                    durationType:
                      title: DurationType
                      type: object
                      properties:
                        plural:
                          type: string
                        singular:
                          type: string
                        type:
                          type: string
                payee:
                  type: array
                  items:
                    title: Payee
                    type: object
                    properties:
                      totalAmount:
                        title: MoneyType
                        type: object
                        properties:
                          amount:
                            type: string
                          units:
                            type: string
                      payeeName:
                        type: string
                      amount:
                        title: MoneyType
                        type: object
                        properties:
                          amount:
                            type: string
                          units:
                            type: string
                      payeeNote:
                        type: string
                      payeeId:
                        type: string
                      taxAmount:
                        title: MoneyType
                        type: object
                        properties:
                          amount:
                            type: string
                          units:
                            type: string
                      payeeIdType:
                        type: string
                prefLang:
                  type: string
                merchantId:
                  type: string
                countryCode:
                  type: string
                segment:
                  type: string
                callbackURL:
                  type: string
                externalTransactionId:
                  type: string
                additionalInformation:
                  type: array
                  items:
                    title: AdditionalInformation
                    type: object
                    properties:
                      name:
                        type: string
                      description:
                        type: string
                amount:
                  title: MoneyType
                  type: object
                  properties:
                    amount:
                      type: string
                    units:
                      type: string
                coupon:
                  type: string
                includePayerCharges:
                  type: string
                itemDetails:
                  type: array
                  items:
                    title: ItemDetail
                    type: object
                    properties:
                      additionalInformation:
                        type: array
                        items:
                          title: AdditionalInformation
                          type: object
                          properties:
                            name:
                              type: string
                            description:
                              type: string
                      itemName:
                        type: string
                      quantity:
                        type: string
                      itemValue:
                        type: string
                      currency:
                        type: string
                      itemDescription:
                        type: string
                transactionId:
                  type: string
                targetSystem:
                  type: string
                quoteId:
                  type: string
                referenceid:
                  type: string
                IdType:
                  type: string
                transactionType:
                  type: string
                totalAmount:
                  title: MoneyType
                  type: object
                  properties:
                    amount:
                      type: string
                    units:
                      type: string
                name:
                  type: string
                transferType:
                  type: string
                paymentMethod:
                  title: PaymentMethod
                  type: object
                  properties:
                    name:
                      type: string
                    description:
                      type: string
                    details:
                      title: PaymentMethodTypeDetails
                      type: object
                      properties:
                        bankAccountTransfer:
                          title: BankAccountTransfer
                          type: object
                          properties:
                            owner:
                              type: string
                            bank:
                              type: string
                            accountNumberType:
                              type: string
                            accountNumber:
                              type: string
                            BIC:
                              type: string
                        bucket:
                          title: Account
                          type: object
                          properties:
                            name:
                              type: string
                            description:
                              type: string
                            id:
                              type: string
                        tokenizedCard:
                          title: TokenizedCard
                          type: object
                          properties:
                            lastFourDigits:
                              type: string
                            type:
                              type: string
                            tokenType:
                              type: string
                            brand:
                              type: string
                            issuer:
                              type: string
                            token:
                              type: string
                        digitalWallet:
                          title: DigitalWallet
                          type: object
                          properties:
                            walletUri:
                              type: string
                            walletId:
                              type: string
                            service:
                              type: string
                        bankCard:
                          title: BankCard
                          type: object
                          properties:
                            cvv:
                              type: string
                            bank:
                              type: string
                            pin:
                              type: string
                            lastFourDigits:
                              type: string
                            nameOnCard:
                              type: string
                            type:
                              type: string
                            brand:
                              type: string
                            cardNumber:
                              type: string
                            expirationDate:
                              type: string
                        voucher:
                          title: Voucher
                          type: object
                          properties:
                            code:
                              type: string
                            description:
                              type: string
                            campaign:
                              type: string
                            value:
                              type: string
                            expirationDate:
                              type: string
                        bankAccountDebit:
                          title: BankAccountDebit
                          type: object
                          properties:
                            owner:
                              type: string
                            bank:
                              type: string
                            accountNumberType:
                              type: string
                            accountNumber:
                              type: string
                            BIC:
                              type: string
                        invoice:
                          title: Invoice
                          type: object
                          properties:
                            deactivateOnFail:
                              type: boolean
                            retryFrequency:
                              type: string
                            endDate:
                              type: string
                            callbackUrl:
                              type: string
                            id:
                              type: string
                            type:
                              type: string
                            retryOnFail:
                              type: boolean
                            startDate:
                              type: string
                            frequency:
                              type: string
                            retryRun:
                              type: string
                        account:
                          title: Account
                          type: object
                          properties:
                            name:
                              type: string
                            description:
                              type: string
                            id:
                              type: string
                        loyaltyAccount:
                          title: Account
                          type: object
                          properties:
                            name:
                              type: string
                            description:
                              type: string
                            id:
                              type: string
                    validFrom:
                      type: string
                    type:
                      title: PaymentMethodType
                      type: object
                      properties:
                        value:
                          type: string
                    validTo:
                      type: string
                siteId:
                  type: string
                correlatorId:
                  type: string
                callingSystem:
                  type: string
                authenticationType:
                  type: string
                partnerId:
                  type: string
                paymentDate:
                  type: string
                taxAmount:
                  title: TaxMoneyType
                  type: object
                  properties:
                    amount:
                      type: string
                    taxId:
                      type: string
                    units:
                      type: string
                status:
                  type: string
        required: true
      responses:
        "200":
          description: "Payment link generated successfully. Returns payment link\
            \ details including URL, expiration time, and payment configuration."
          content:
            application/json:
              schema:
                type: string
        "400":
          description: "Bad request. Invalid MSISDN, missing required parameters,\
            \ or malformed payment request."
          content:
            application/json:
              schema:
                title: APIError
                type: object
                properties:
                  path:
                    type: string
                  downstreamStatusCode:
                    type: integer
                    format: int32
                  sequenceNo:
                    type: string
                  method:
                    type: string
                  statusMessage:
                    type: string
                  transactionId:
                    type: string
                  supportMessage:
                    type: string
                  timestamp:
                    type: string
                  statusCode:
                    type: string
        "500":
          description: "Internal server error. Payment link generation failure, system\
            \ error, or service unavailable."
          content:
            application/json:
              schema:
                title: APIError
                type: object
                properties:
                  path:
                    type: string
                  downstreamStatusCode:
                    type: integer
                    format: int32
                  sequenceNo:
                    type: string
                  method:
                    type: string
                  statusMessage:
                    type: string
                  transactionId:
                    type: string
                  supportMessage:
                    type: string
                  timestamp:
                    type: string
                  statusCode:
                    type: string
        "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
        "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
  /payment-agreement:
    post:
      tags:
      - Payment
      summary: Generate payment agreement (Promise to Pay)
      description: "Provides the ability for a consumer to generate a payment agreement\
        \ (Promise to Pay). This endpoint allows customers to set up payment promise\
        \ agreements with service providers, enabling deferred payment arrangements\
        \ and payment scheduling functionality. It handles the creation of payment\
        \ agreements with appropriate validation, terms and conditions, and integration\
        \ with payment processing systems."
      operationId: Payment_post_setPaymentPromise_paymentagreement
      parameters:
      - name: transactionId
        in: header
        re

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