MTN Group Customer Bill API

openapi: 3.2.0
info:
  title: Mtn Group Customer Bill API
  version: '1.0'
  description: 'Operations tagged customerBill across 2 of this provider''s published API definitions: mtn-group-mtn-customer-bill-management.yml, mtn-group-tmf-customer-bill-management.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.mtn.com/v1
- url: https://serverRoot/tmf-api/customerBillManagement/v4/
tags:
- name: customerBill
paths:
  /customerBill:
    get:
      tags:
      - customerBill
      summary: List or find CustomerBills
      description: Retrieves list of paid and unpaid bill details.
      operationId: listCustomerBill
      parameters:
      - name: transactionId
        in: header
        required: false
        description: Client generated Id to include for tracing requests.
        x-example: 6f0bece6-7df3-4da4-af02-5e7f16e5e6fc
        schema:
          type: string
      - name: targetSystem
        in: header
        required: false
        description: Provider system name.
        x-example: ZSmart
        schema:
          type: string
          enum:
          - ZSmart
          - CLM
          - DCBS
          - CS
      - name: countryCode
        in: header
        description: Country ISO code. Must be ISO 3166-1 alpha-3 codes (It is a 3 character string)
        required: false
        schema:
          type: string
      - name: customerType
        in: query
        description: This parameter will be used to query the bill information at Service level or Account level or Invoice Level. 1 refers to Service level, 2 refers to Account level and 3 refers to Invoice Level.
        required: true
        schema:
          type: integer
          enum:
          - 1
          - 2
          - 3
      - name: customerId
        in: query
        description: Value of 'customerType'
        required: true
        schema:
          type: string
      - name: queryType
        in: query
        required: true
        description: This will be used to make the specific request. Either the request will be for unpaid bill or paid bill or complete bill. In case of 'unpaidBill', customer bill information along with due amount detail , related party and bill cycle information will be returned. In case of 'paidBill', applied payment information along with unpaid bill details will be returned. In case of 'completeBill', all other information like billing account,financial,taxItem,billDocument etc. will be returned along with paid and unpaid bill details.
        schema:
          type: string
          enum:
          - unpaidBill
          - paidBill
          - completeBill
      - name: offset
        description: Requested index for start of resources to be provided in response
        required: false
        in: query
        schema:
          type: integer
      - name: limit
        description: Requested number of resources to be provided in response
        required: false
        in: query
        schema:
          type: integer
      - name: billingFlag
        in: query
        description: 'This field contains three segments, like 000 or 100 etc.First segment means if include unbilled amount for current month, second segment means if include credit limit and third segment means if include deposit. 1 refers to ''include'' and 0 refers to ''Not include''. Default value will be 0 '
        schema:
          type: string
          default: '000'
      - name: startDate
        in: query
        description: 'Start date of bill information requested for. Date type format: yyyy-mm-dd'
        schema:
          type: string
      - name: endDate
        in: query
        description: 'End date of bill information requested for. Date type format: yyyy-mm-dd'
        schema:
          type: string
      - name: billingCycleId
        in: query
        description: Billing cycle ID
        schema:
          type: string
      - name: custom
        in: query
        description: Reserve for future use. Can hold the additional filter criteria.
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerBill_Complete'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Customer not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '405':
          description: Method Not allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - ApiKeyAuth: []
      - OAuth2: []
    servers:
    - url: https://api.mtn.com/v1
  /customerBill/{id}:
    get:
      tags:
      - customerBill
      summary: Retrieves a CustomerBill by ID
      description: Provides the ability for a consumer to retrieve list of unpaid bill amount, advance payment amount and total due amount
      operationId: getCustomerBillById
      parameters:
      - name: id
        required: true
        in: path
        description: This can be Customer's masisdn with countrycode or Account Number or Invoice Number. Example - 23712345678
        schema:
          type: string
      - name: transactionId
        in: header
        required: false
        description: Client generated Id to include for tracing requests.
        x-example: 6f0bece6-7df3-4da4-af02-5e7f16e5e6fc
        schema:
          type: string
      - name: targetSystem
        in: header
        required: false
        description: Provider system name.
        x-example: ZSmart
        schema:
          type: string
          enum:
          - ZSmart
          - CLM
          - DCBS
          - CS
      - name: countryCode
        in: header
        description: Country ISO code. Must be ISO 3166-1 alpha-3 codes (It is a 3 character string)
        required: false
        schema:
          type: string
      - name: customerType
        in: query
        description: 'This parameter will be used to query the bill information at Service level or Account level or Invoice Level. 1 refers to Service level, 2 refers to Account level and 3 refers to Invoice Level '
        required: true
        schema:
          type: integer
          enum:
          - 1
          - 2
          - 3
      - name: queryType
        in: query
        required: true
        description: This will be used to make the specific request. Either the request will be for unpaid bill or paid bill or complete bill. In case of 'unpaidBill', customer bill information along with due amount detail , related party and bill cycle information will be returned. In case of 'paidBill', applied payment information along with unpaid bill details will be returned. In case of 'completeBill', all other information like billing account,financial,taxItem,billDocument etc. will be returned along with paid and unpaid bill details.
        schema:
          type: string
          enum:
          - unpaidBill
          - paidBill
          - completeBill
      - name: billingFlag
        in: query
        description: 'This field contains three segments, like 000 or 100 etc.First segment means if include unbilled amount for current month, second segment means if include credit limit and third segment means if include deposit. 1 refers to ''include'' and 0 refers to ''Not include''. Default value will be 0 '
        schema:
          type: string
          default: '000'
      - name: startDate
        in: query
        description: 'Start date of bill information requested for. Date type format: yyyy-mm-dd'
        schema:
          type: string
      - name: endDate
        in: query
        description: 'End date of bill information requested for. Date type format: yyyy-mm-dd'
        schema:
          type: string
      - name: billingCycleId
        in: query
        description: Billing cycle ID
        schema:
          type: string
      - name: custom
        in: query
        description: Reserve for future use. Can hold the additional filter criteria.
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerBill_ID'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Customer not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '405':
          description: Method Not allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - ApiKeyAuth: []
      - OAuth2: []
    patch:
      tags:
      - customerBill
      summary: Updates partially a CustomerBill
      description: Provides the ability for a consumer to update postpaid bill balance
      operationId: updateCustomerBill
      parameters:
      - name: id
        in: path
        description: Unique id of the customer it could be service / account id
        required: true
        schema:
          type: string
      - name: transactionId
        in: header
        description: The transaction reference id to be passed by the 3pp for a particular transaction. This will be used for reconciliation
        required: false
        schema:
          type: string
      - name: countryCode
        in: header
        description: Country ISO code. Must be ISO 3166-1 alpha-3 codes (It is a 3 character string)
        required: false
        schema:
          type: string
      - name: targetSystem
        in: header
        required: false
        description: Provider system name.
        x-example: ZSmart
        schema:
          type: string
          enum:
          - ZSmart
          - CLM
          - DCBS
          - CS
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerBill_Update'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Customer not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '405':
          description: Method Not allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerBill_Payment'
        description: Payment Details
        required: true
      security:
      - ApiKeyAuth: []
      - OAuth2: []
    servers:
    - url: https://api.mtn.com/v1
components:
  schemas:
    CustomerBill_Complete:
      required:
      - resultCode
      - resultDescription
      - data
      type: object
      properties:
        result:
          type: object
          properties:
            resultCode:
              type: string
              description: Result code. Example- '0000'
            resultDescription:
              type: string
              description: Result message. Example- 'Successfully processed'
            transactionId:
              type: string
              description: Transaction id returned by the provider system.
        data:
          type: array
          items:
            $ref: '#/components/schemas/CustomerBill'
            properties:
              relatedParty:
                type: object
                $ref: '#/components/schemas/RelatedParty'
              billCycle:
                type: object
                $ref: '#/components/schemas/BillCycle'
              appliedPayment:
                $ref: '#/components/schemas/AppliedPayment'
              billDocument:
                $ref: '#/components/schemas/BillDocument'
              billingAccount:
                $ref: '#/components/schemas/BillingAccount'
              financialAccount:
                $ref: '#/components/schemas/FinancialAccount'
              taxItem:
                $ref: '#/components/schemas/TaxItem'
    RelatedParty:
      type: array
      items:
        type: object
        properties:
          id:
            type: string
          customerType:
            type: string
            description: Type of customer. Example-Individual or Corporate etc.
          customerName:
            type: string
          href:
            type: string
            description: Hyperlink reference
    AppliedPayment:
      description: Payment associated with the bill. There may be a partial payment, then there should be several applied payments available. On the other hand, more than one bill could be payed by one payment
      type: object
      properties:
        idType:
          type: string
          description: Identifier of the level against which bill has been paid.
          example: Account Number
        id:
          type: string
          description: Value of 'idType'
          example: '45632145'
        totalPaidAmount:
          description: Total amount paid. This should be summation of amounts paid against multiple bill number (aka invoice number)
          type: object
          $ref: '#/components/schemas/Money'
        payment:
          type: array
          items:
            type: object
            $ref: '#/components/schemas/PaymentRef'
    CustomerBill_ID:
      required:
      - result
      - data
      type: object
      properties:
        result:
          type: object
          properties:
            resultCode:
              type: string
              description: Result code. Example- '0000'
            resultDescription:
              type: string
              description: Result message. Example- 'Successfully processed'
            transactionId:
              type: string
              description: Transaction id returned by the provider system.
        data:
          type: object
          $ref: '#/components/schemas/CustomerBill'
          properties:
            relatedParty:
              type: object
              $ref: '#/components/schemas/RelatedParty'
            billCycle:
              type: object
              $ref: '#/components/schemas/BillCycle'
            appliedPayment:
              type: object
              $ref: '#/components/schemas/AppliedPayment'
            billDocument:
              $ref: '#/components/schemas/BillDocument'
            billingAccount:
              $ref: '#/components/schemas/BillingAccount'
            financialAccount:
              $ref: '#/components/schemas/FinancialAccount'
            taxItem:
              $ref: '#/components/schemas/TaxItem'
    ATM:
      description: Detailed information of the  ATM through which bill payment has done.
      properties:
        bankName:
          type: string
          description: Name or Code of the bank.
        branchCode:
          type: string
          description: Branch code.
        atmCode:
          type: string
          description: ATM center code.
      required:
      - atmCode
    Bank:
      description: Detailed information of the  Bank through which bill payment has done.
      properties:
        bankName:
          type: string
          description: Name of the bank.
        bankCode:
          type: string
          description: Code of the bank.
        branchCode:
          type: string
          description: Branch code or Bank Code in case branch code is not available.
        paymentMode:
          type: string
          description: It can be EFT, Internet Banking,Cash
          enum:
          - Transfer
          - EFT
          - Cash
          - Autodebit
          - InternetBanking
      required:
      - branchCode
      - paymentMode
    CustomerBill_Payment:
      type: object
      $ref: '#/components/schemas/AppliedPayment'
    TokenizedCard:
      description: Detailed information for a stored tokenized card.
      properties:
        brand:
          type: string
          description: Card brand. Might be used for display purposes.
        type:
          type: string
          description: Card type. Might be used for display purposes.
        lastFourDigits:
          type: string
          description: Last four digits of the credit card. Might be used for display purposes.
        tokenType:
          type: string
          description: Token type. e.g emv.
        token:
          type: string
          description: The token itself.
        issuer:
          type: string
          description: Whoever issued the token.
    DueDetail:
      type: array
      items:
        type: object
        properties:
          id:
            type: string
            description: Unique identifier. It can be customer id or account id or invoice number etc.
          description:
            type: string
            description: Description of the due detail
          validFor:
            $ref: '#/components/schemas/TimePeriod'
          dueDate:
            type: string
            format: date-time
          unpaidAmount:
            $ref: '#/components/schemas/Money'
            description: Unpaid bill amount.
          advanceAmount:
            $ref: '#/components/schemas/Money'
            description: Advance payment of the customer.
          taxExcludedAmount:
            $ref: '#/components/schemas/Money'
            description: Tax exempted amount.
          taxIncludedAmount:
            $ref: '#/components/schemas/Money'
            description: Taxable amount.
          totalDueAmount:
            $ref: '#/components/schemas/Money'
            description: total payable amount,i.e. unpaidAmount plus advance amount after taxable amount
    PaymentRef:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier
        paymentRef:
          type: array
          items:
            $ref: '#/components/schemas/Reference'
        billNumber:
          type: string
        transactionDate:
          type: string
          description: format- 'yyyy-mm-dd'
          example: '2020-07-24'
        paidAmount:
          type: object
          $ref: '#/components/schemas/Money'
        paymentMethod:
          type: object
          $ref: '#/components/schemas/PaymentMethodRef'
      required:
      - referenceId
    Error:
      type: object
      title: Error
      required:
      - status
      - message
      properties:
        timestamp:
          type: string
          format: date-time
          description: Time stamp of the error
        status:
          type: string
          description: Status code returned by provider system
        error:
          type: string
          description: Status description
        message:
          type: string
          description: More error details and corrective measures
        path:
          type: string
          description: The path that caused the error
    FinancialAccount:
      type: array
      items:
        type: object
        properties:
          name:
            type: string
            description: Name of the related entity
          id:
            type: string
            description: unique identifier
          href:
            type: string
            description: Hyperlink reference
          type:
            type: string
            description: The actual type of the target instance when needed for disambiguation.
    PaymentMethodRef:
      type: object
      description: Reference or value of the method used for payment.
      properties:
        name:
          type: string
          description: Friendly name assigned to the payment method.
          example: Manual Boost for RWC
        description:
          type: string
          description: Description of the associated payment method.
          example: Manual Boost for RWC
        type:
          $ref: '#/components/schemas/PaymentMethodTypeEnum'
        details:
          $ref: '#/components/schemas/PaymentMethodTypeDetails'
    TimePeriod:
      type: object
      properties:
        startDate:
          type: string
        endDate:
          type: string
    Cash:
      description: Detailed information of the  service center/shop where bill paid through cash
      properties:
        centerName:
          type: string
          description: Name  of the service center where bill paid.
        centerCode:
          type: string
          description: Code of the service center where bill paid.
      required:
      - centerCode
    BankCard:
      description: Detailed information for a bank card.
      properties:
        brand:
          type: string
          description: Card brand. e.g. Visa, MasterCard, AmericanExpress.
          example: Visa
        type:
          type: string
          description: Type of card. e.g. Credit, Debit.
          example: Credit
        cardNumber:
          type: string
          description: Credit card number.
          example: xxxx xxxx xxx xxx
        expirationDate:
          type: string
          format: date-time
          description: Expiration date of the card.
          example: 10/2020
        cvv:
          type: string
          description: Security Code of the card. e.g. CCV, CCV2.
          example: '123'
        lastFourDigits:
          type: string
          description: Last four digits of the credit card.
          example: '1234'
        nameOnCard:
          type: string
          description: Name on the card.
          example: Bruce Wayne
        bank:
          type: string
          description: Bank that issued the card.
          example: Bank of Gotham
    BillingAccount:
      type: array
      items:
        type: object
        properties:
          accountType':
            type: string
            description: The actual type of the target instance when needed for disambiguation
          accountId:
            type: string
          accountname:
            type: string
          href:
            type: string
    BillCycle:
      type: array
      items:
        type: object
        properties:
          href:
            type: string
          billingCycleId:
            type: string
            description: Billing cycle ID.
          billingName:
            type: string
          billingType:
            type: string
            description: Type of billing.
          startDate:
            type: string
            description: format- 'yyyy-mm-dd'
          endDate:
            type: string
            description: format- 'yyyy-mm-dd'`
          creditLimit:
            $ref: '#/components/schemas/CreditLimit'
    Cheque:
      description: Detailed information of cheque.
      properties:
        chequeNumber:
          type: string
          description: Cheque Number
        issueDate:
          type: string
          description: Issue date of the cheque.
        expiryDate:
          type: string
          description: Expiry date of the cheque
        accountNumber:
          type: string
        bankCode:
          type: string
          description: Code of the bank.
      required:
      - chequeNumber
    TaxItem:
      type: array
      items:
        type: object
        properties:
          taxAmount:
            $ref: '#/components/schemas/Money'
          taxCategory:
            type: string
          taxRate:
            type: string
          type:
            type: string
    PaymentMethodTypeDetails:
      type: object
      description: Definition of the payment method. Its content depends on the type field.
      properties:
        bank:
          $ref: '#/components/schemas/Bank'
        cash:
          $ref: '#/components/schemas/Cash'
        atm:
          $ref: '#/components/schemas/ATM'
        cheque:
          $ref: '#/components/schemas/Cheque'
        bankCard:
          $ref: '#/components/schemas/BankCard'
        tokenizedCard:
          $ref: '#/components/schemas/TokenizedCard'
    CustomerBill_Update:
      type: object
      required:
      - resultCode
      - resultDescription
      - data
      properties:
        resultCode:
          type: string
          description: Result code. Example- '0000'
        resultDescription:
          type: string
          description: Result message. Example- 'Successfully processed'
        transactionId:
          type: string
          description: Transaction id returned by the provider system.
        data:
          type: object
          properties:
            idType:
              type: string
              description: This field refers the information against which bill has been paid, i.e. Account Number or Invoice Number or Service Number or Bill Number etc.
              example: Account Number
            id:
              type: string
              description: Value of the chosen 'idType'
              example: '4567123'
            paymentRef:
              type: array
              items:
                $ref: '#/components/schemas/Reference'
            amountPaid:
              $ref: '#/components/schemas/Money'
            advancePayment:
              $ref: '#/components/schemas/Money'
    BillDocument:
      type: array
      items:
        type: object
        properties:
          id:
            type: string
            description: Unique identifier for this particular attachment
          description:
            type: string
            description: A narrative text describing the content of the attachment
          href:
            type: string
            description: URI for this Attachment
          attachmentType:
            type: string
            description: Attachment type such as video, picture
          content:
            type: string
            description: The actual contents of the attachment object, if embedded, encoded as base64
          mimeType:
            type: string
            description: Attachment mime type such as extension file for video, picture and document
          size:
            type: string
            description: The size of the attachment
          validFor:
            type: string
            description: The period of time for which the attachment is valid
          '@referredType':
            type: string
            description: The actual type of the target instance when needed for disambiguation
    Money:
      required:
      - amount
      - unit
      type: object
      properties:
        amount:
          type: string
        unit:
          type: string
    PaymentMethodTypeEnum:
      type: string
      title: PaymentMethodTypeEnum
      enum:
      - Bank
      - Cash
      - Cheque
      - ATM
      - BankCard
      - TokenizedCard
    CustomerBill:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier of the bill. It can be account number or service number or invoice number etc. Service number must be of format countrcode + msisdn, example- 250786456732
        href:
          type: string
        billType:
          type: string
          description: Identifier of the bill type. Example -'Customer Bill'
        billNo:
          type: string
          description: Bill reference known by the customer or the party and displayed on the bill. Could be different from the id.
        billDate:
          type: string
          description: Bill date, external customer view (in consequence - different to the production date of the bill).
        category:
          type: string
          enum:
          - normal
          - duplicate
          - interim
          - last
          - trail customer
          - credit note
          description: Category of the bill produced - normal, duplicate, interim, last, trial customer or credit note for example
        billRunType:
          type: string
          enum:
          - onCycle
          - offCycle
          description: onCycle (a bill can be created as a result of a cycle run) or offCycle (a bill can be created as a result of other events such as customer request or account close)
        lastUpdate:
          type: string
          format: date-time
          description: Date of bill last update.
        nextBillDate:
          type: string
          format: date-time
          description: Approximate date of the next bill production given for information (only used/meaningful for on cycle / regular bills)
        paymentDueDate:
          type: string
          format: date-time
          description: Date at which the amount due should have been paid.
        state:
          type: string
          description: Status of the bill.
        amountDue:
          $ref: '#/components/schemas/Money'
          description: A base / value business entity used to represent money
        amountDueDetail:
          $ref: '#/components/schemas/DueDetail'
          description: Detail of the due amount.
    Reference:
      type: object
      properties:
        referenceId:
          type: string
          description: Holds reference value . It can be payment reference number or slip number or transcation number etc.
          example: PAY-9876
        referenceType:
          type: string
          description: Holds reference type . It can be 'PaymentRef' or 'Slip Number' or 'RefTransactionNum' etc.
          example: PaymentRefNum
        referenceName:
          description: Holds reference name.
          example: csp-bill
      required:
      - referenceId
      - referenceType
    CreditLimit:
      type: array
      items:
        type: object
        properties:
          idType:
            type: string
            description: Credit limit object flag. Whether this  is for Account or for Subscriber
          id:
            type: string
            description: Credit limit Object value
          creditLimitType:
            type: string
            description: Credit limit type
          creditLimitName:
            type: string
            description: Credit limit type name
          creditLimit:
            type: string
            description: Credit limit value of customer
          effectiveDate:
            type: string
            description: Effective date，Date type format:yyyy-mm-dd
          expiryDate:
            type: string
            description: Expire date，Date type format:yyyy-mm-dd
    PaymentMethodRef_2:
      type: object
      description: PaymentMethod reference. A payment method defines a specific mean of payment (e.g direct debit).
      properties:
        id:

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