MTN Group Usage Management API

openapi: 3.2.0
info:
  title: Mtn Group Usage Management API
  version: 3.0.0 - Last updated date:2026-06-26 09:07:34
  license:
    name: MADAPI
    url: https://developers.mtn.com/
  description: 'Operations tagged UsageManagement across 2 of this provider''s published API definitions: mtn-group-tmf-usage-management-tmf635.yml, mtn-group-usage-management.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.mtn.com/v1
  description: Production Server
security:
- OAuth2: []
tags:
- name: UsageManagement
paths:
  /agent/loanhistory:
    get:
      tags:
      - UsageManagement
      summary: Retrieves agent loan history with paging and country-specific DAASAGENT routing support.
      description: Retrieves agent loan history with pagination, supported country validation, date filtering, and downstream DAASAGENT routing for Banktech reconciliation, audit requirements, and agent financial workflows.
      operationId: UsageManagement_get_getAgentDataBanktech_agentloanhistory
      parameters:
      - name: country
        in: header
        required: false
        schema:
          type: string
      - name: customerIdHash
        in: query
        required: true
        schema:
          type: string
      - name: endDate
        in: query
        required: false
        schema:
          type: string
      - name: maxResults
        in: query
        required: false
        schema:
          type: string
      - name: momoPartnerId
        in: query
        required: false
        schema:
          type: string
      - name: pageNumber
        in: query
        required: false
        schema:
          type: integer
          format: int32
      - name: partnerName
        in: header
        required: false
        schema:
          type: string
      - name: startDate
        in: query
        required: false
        schema:
          type: string
      - name: transactionId
        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 usage management flows.
          content:
            application/json:
              schema:
                title: BankTechAgentResponse
                type: object
                properties:
                  statusCode:
                    type: string
                  statusMessage:
                    type: string
                  transactionId:
                    type: string
                  customerId:
                    type: string
                  timestamp:
                    type: string
                  data:
                    title: BankTechAgentData
                    type: object
                    properties:
                      accountBalance1m:
                        type: number
                        format: double
                      accountBalance3m:
                        type: number
                        format: double
                      accountBalance6m:
                        type: number
                        format: double
                      activatedAt:
                        type: string
                      agentProfile:
                        type: string
                      averageBalance1m:
                        type: number
                        format: double
                      averageBalance3m:
                        type: number
                        format: double
                      averageBalance6m:
                        type: number
                        format: double
                      cashInLast1m:
                        type: string
                      cashInLast3m:
                        type: string
                      cashInLast6m:
                        type: string
                      cashInPeers1m:
                        type: integer
                        format: int32
                      cashInPeers3m:
                        type: integer
                        format: int32
                      cashInPeers6m:
                        type: integer
                        format: int32
                      cashInValue1m:
                        type: number
                        format: double
                      cashInValue3m:
                        type: number
                        format: double
                      cashInValue6m:
                        type: number
                        format: double
                      cashInVolume1m:
                        type: integer
                        format: int32
                      cashInVolume3m:
                        type: integer
                        format: int32
                      cashInVolume6m:
                        type: integer
                        format: int32
                      cashOutLast1m:
                        type: string
                      cashOutLast3m:
                        type: string
                      cashOutLast6m:
                        type: string
                      cashOutPeers1m:
                        type: integer
                        format: int32
                      cashOutPeers3m:
                        type: integer
                        format: int32
                      cashOutPeers6m:
                        type: integer
                        format: int32
                      cashOutValue1m:
                        type: string
                      cashOutValue3m:
                        type: string
                      cashOutValue6m:
                        type: string
                      cashOutVolume1m:
                        type: integer
                        format: int32
                      cashOutVolume3m:
                        type: integer
                        format: int32
                      cashOutVolume6m:
                        type: integer
                        format: int32
                      commission1m:
                        type: number
                        format: double
                      commission3m:
                        type: number
                        format: double
                      commission6m:
                        type: number
                        format: double
                      commissionCashIn1m:
                        type: number
                        format: double
                      commissionCashIn3m:
                        type: number
                        format: double
                      commissionCashIn6m:
                        type: number
                        format: double
                      commissionCashOut1m:
                        type: number
                        format: double
                      commissionCashOut3m:
                        type: number
                        format: double
                      commissionCashOut6m:
                        type: number
                        format: double
                      COMMISSIONING_EXTERNAL_PAYMENT_1m:
                        type: number
                        format: double
                      COMMISSIONING_EXTERNAL_PAYMENT_3m:
                        type: number
                        format: double
                      COMMISSIONING_EXTERNAL_PAYMENT_6m:
                        type: number
                        format: double
                      commissioningVoucher1m:
                        type: number
                        format: double
                      commissioningVoucher3m:
                        type: number
                        format: double
                      commissioningVoucher6m:
                        type: number
                        format: double
                      credit_limit:
                        type: integer
                        format: int32
                      credit_limit_date:
                        type: string
                      cumulative_payments_30dy:
                        type: number
                        format: double
                      date_key:
                        type: integer
                        format: int32
                      dateOfBirth:
                        type: string
                      EXTERNAL_PAYMENT_last:
                        type: string
                      EXTERNAL_PAYMENT_peers_1m:
                        type: integer
                        format: int32
                      EXTERNAL_PAYMENT_peers_3m:
                        type: integer
                        format: int32
                      EXTERNAL_PAYMENT_peers_6m:
                        type: integer
                        format: int32
                      EXTERNAL_PAYMENT_value_1m:
                        type: number
                        format: double
                      EXTERNAL_PAYMENT_value_3m:
                        type: number
                        format: double
                      EXTERNAL_PAYMENT_value_6m:
                        type: number
                        format: double
                      EXTERNAL_PAYMENT_volume_1m:
                        type: integer
                        format: int32
                      EXTERNAL_PAYMENT_volume_3m:
                        type: integer
                        format: int32
                      EXTERNAL_PAYMENT_volume_6m:
                        type: integer
                        format: int32
                      Number_Of_Customers_Served_1m:
                        type: integer
                        format: int32
                      Number_Of_Customers_Served_3m:
                        type: integer
                        format: int32
                      Number_Of_Customers_Served_6m:
                        type: integer
                        format: int32
                      Optional_Parameter_1:
                        type: integer
                        format: int32
                      Optional_Parameter_2:
                        type: integer
                        format: int32
                      Optional_Parameter_3:
                        type: integer
                        format: int32
                      Optional_Parameter_4:
                        type: integer
                        format: int32
                      Optional_Parameter_5:
                        type: integer
                        format: int32
                      Optional_Parameter_6:
                        type: integer
                        format: int32
                      Optional_Parameter_7:
                        type: integer
                        format: int32
                      Optional_Parameter_8:
                        type: integer
                        format: int32
                      Optional_Parameter_9:
                        type: integer
                        format: int32
                      Optional_Parameter_10:
                        type: integer
                        format: int32
                      overdraft_fees_balance:
                        type: integer
                        format: int32
                      overdraft_interest_balance:
                        type: integer
                        format: int32
                      overdraft_principle_balance:
                        type: integer
                        format: int32
                      days_past_due:
                        type: integer
                        format: int32
                      drawdown_number:
                        type: number
                        format: double
                      revenue1m:
                        type: number
                        format: double
                      revenue3m:
                        type: number
                        format: double
                      revenue6m:
                        type: number
                        format: double
                      Transaction_Values_1m:
                        type: number
                        format: double
                      Transaction_Values_3m:
                        type: number
                        format: double
                      Transaction_Values_6m:
                        type: number
                        format: double
                      Transaction_Volumes_1m:
                        type: number
                        format: double
                      Transaction_Volumes_3m:
                        type: number
                        format: double
                      Transaction_Volumes_6m:
                        type: number
                        format: double
                      voucherLast1m:
                        type: string
                      voucherLast3m:
                        type: string
                      voucherLast6m:
                        type: string
                      voucherPeers1m:
                        type: integer
                        format: int32
                      voucherPeers3m:
                        type: integer
                        format: int32
                      voucherPeers6m:
                        type: integer
                        format: int32
                      voucherValue1m:
                        type: number
                        format: double
                      voucherValue3m:
                        type: number
                        format: double
                      voucherValue6m:
                        type: number
                        format: double
                      voucherVolume1m:
                        type: integer
                        format: int32
                      voucherVolume3m:
                        type: integer
                        format: int32
                      voucherVolume6m:
                        type: integer
                        format: int32
        '400':
          description: Bad request. Invalid request parameters, missing required fields, or validation errors.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        '401':
          description: Unauthorized. Invalid or missing authorization credentials, insufficient permissions, or authentication failure.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        '403':
          description: Forbidden. Access denied. The request is valid but the server refuses to perform it.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        '404':
          description: Not found. The requested resource was not found or does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        '500':
          description: Internal server error. Unexpected system failure, database connectivity issues, or external service integration problems.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        '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'
        '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'
      deprecated: false
    servers:
    - url: https://api.mtn.com/v1
      description: Production Server
  /customer/crbRecord:
    get:
      tags:
      - UsageManagement
      summary: Retrieves a Banktech customer CRB (credit bureau) snapshot via GET /customer/crbRecord when the loan-history response did not include bureau data, typically because the subscriber had no qualifying transactions in the configured look-back window.
      description: Retrieves customer CRB record. This endpoint will be called if the CRB record was not returned in the LoanHistory endpoint due to that the customer has not transacted in the past 30 days
      operationId: UsageManagement_get_getCrbRecord_customercrbRecord
      parameters:
      - name: country
        in: header
        required: false
        schema:
          type: string
      - name: customerIdHash
        in: query
        required: true
        schema:
          type: string
      - name: partnerId
        in: query
        required: true
        schema:
          type: string
      - name: providerId
        in: query
        required: true
        schema:
          type: string
      - name: transactionId
        in: header
        required: true
        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 usage management flows.
          content:
            application/json:
              schema:
                title: CrbRecordResponse
                type: object
                properties:
                  Header:
                    title: Header
                    type: object
                    properties:
                      crbName:
                        type: string
                      reportDate:
                        type: string
                      reportType:
                        type: string
                      productDisplayName:
                        type: string
                      requester:
                        type: string
                      requestNo:
                        type: integer
                        format: int32
                  PersonalProfile:
                    title: PersonalProfile
                    type: object
                    properties:
                      crn:
                        type: integer
                        format: int32
                      salutation:
                        type: string
                      surname:
                        type: string
                      otherNames:
                        type: string
                      fullName:
                        type: string
                      nationalID:
                        type: string
                      passportNo:
                        type: string
                      drivingLicenseNo:
                        type: string
                      serviceID:
                        type: string
                      alienID:
                        type: string
                  AccountList:
                    type: array
                    items:
                      title: AccountList
                      type: object
                      properties:
                        Account:
                          title: Account
                          type: object
                          properties:
                            accountStatus:
                              type: string
                  Summary:
                    title: Summary
                    type: object
                    properties:
                      creditHistory:
                        title: CreditHistory
                        type: object
                        properties:
                          mySector:
                            type: integer
                            format: int32
                          allSectors:
                            type: integer
                            format: int32
                      npaAccounts:
                        title: NpaAccounts
                        type: object
                        properties:
                          mySector:
                            type: integer
                            format: int32
                          allSectors:
                            type: integer
                            format: int32
                      npaClosedAccounts:
                        title: NpaClosedAccounts
                        type: object
                        properties:
                          mySector:
                            type: integer
                            format: int32
                          allSectors:
                            type: integer
                            format: int32
                      npaOpenAccounts:
                        title: NpaOpenAccounts
                        type: object
                        properties:
                          mySector:
                            type: integer
                            format: int32
                          allSectors:
                            type: integer
                            format: int32
                      paAccounts:
                        title: PaAccounts
                        type: object
                        properties:
                          mySector:
                            type: integer
                            format: int32
                          allSectors:
                            type: integer
                            format: int32
                      paClosedAccounts:
                        title: PaClosedAccounts
                        type: object
                        properties:
                          mySector:
                            type: integer
                            format: int32
                          allSectors:
                            type: integer
                            format: int32
                      paOpenAccounts:
                        title: PaOpenAccounts
                        type: object
                        properties:
                          mySector:
                            type: integer
                            format: int32
                          allSectors:
                            type: integer
                            format: int32
                  ScoreOutput:
                    title: ScoreOutput
                    type: object
                    properties:
                      positiveScore:
                        type: integer
                        format: int32
                      probability:
                        type: string
                      grade:
                        type: string
                      reasonCodeAARC1:
                        type: string
                      reasonCodeAARC2:
                        type: string
                      reasonCodeAARC3:
                        type: string
                      reasonCodeAARC4:
                        type: string
                  statusCode:
                    type: string
                  statusMessage:
                    type: string
                  customerIdHash:
                    type: string
                  partnerId:
                    type: string
                  transactionId:
                    type: string
                  supportMessage:
                    type: string
                  customerId:
                    type: string
                  timestamp:
                    type: string
        '400':
          description: Bad request. Invalid request parameters, missing required fields, or validation errors.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        '401':
          description: Unauthorized. Invalid or missing authorization credentials, insufficient permissions, or authentication failure.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        '403':
          description: Forbidden. Access denied. The request is valid but the server refuses to perform it.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        '404':
          description: Not found. The requested resource was not found or does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        '500':
          description: Internal server error. Unexpected system failure, database connectivity issues, or external service integration problems.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        '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'
        '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'
      deprecated: false
    servers:
    - url: https://api.mtn.com/v1
      description: Production Server
  /customer/loanhistory:
    get:
      tags:
      - UsageManagement
      summary: Retrieves Banktech loan history with paging and country-specific backend routing support.
      description: Retrieves customer loan history including disbursement and repayment details with paging, partner identifiers, and routing to DAAS, DASS_MFS, or EVA backends for Banktech operations and financial tracking.
      operationId: UsageManagement_get_getCustomerDataBanktech_customerloanhistory
      parameters:
      - name: appName
        in: query
        required: false
        schema:
          type: string
      - name: country
        in: header
        required: false
        schema:
          type: string
      - name: customerIdHash
        in: query
        required: true
        schema:
          type: string
      - name: endDate
        in: query
        required: false
        schema:
          type: string
      - name: hostName
        in: query
        required: false
        schema:
          type: string
      - name: maxResults
        in: query
        required: false
        schema:
          type: string
      - name: momoPartnerId
        in: query
        required: false
        schema:
          type: string
      - name: pageNumber
        in: query
        required: false
        schema:
          type: integer
          format: int32
      - name: pageSize
        in: query
        required: false
        schema:
          type: string
      - name: startDate
        in: query
        required: false
        schema:
          type: string
      - name: transactionId
        in: header
        required: false
        schema:
          type: string
      - name: userID
        in: query
        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 usage management flows.
          content:
            application/json:
              schema:
                title: BankTechResponse
                type: object
                properties:
                  statusCode:
                    type: string
                  statusMessage:
                    type: string
                  transactionId:
                    type: string
                  sequenceNumber:
                    type: string
                  customerId:
                    type: string
                  timestamp:
                    type: string
                  data:
                    title: BanktechUserData
                    type: object
                    properties:
                      kyc_momo_id:
                        type: string
                      kyc_msisdn:
                        type: string
                      account_status:
                        type: string
                      activation_date:
                        type: integer
                        format: int32
                      atc_loans_amt_tot:
                        type: integer
                        format: int32
                      atc_loans_first_date:
                        type: integer
                        format: int32
                      atc_loans_last_date:
                        type: integer
                        format: int32
                      atc_loans_last_overdue:
                        type: integer
                        format: int32
                      atc_loans_max_term:
                        type: integer
                        format: int32
                      atc_loans_overdue:
                        type: integer
                        format: int32
                      atc_loans_qty_1m:
                        type: integer
                        format: int32
                      atc_loans_qty_3m:
                        type: integer
                        format: int32
                      atc_loans_qty_6m:
                        type: integer
                        format: int32
                      atc_loans_tot_term:
                        type: integer
                        format: int32
                      batch_id:
                        type: integer
                        format: int32
                      behavioural_category:
                        type: string
                      behavioural_score:
                        type: integer
                        format: int32
                      block_code_1:
                        type: string
                      block_code_1_date:
                        type: integer
                        format: int32
                      block_code_2:
                        type: string
                      block_code_2_date:
                        type: integer
                        format: int32
                      create_dt:
                        type: integer
                        format: int32
                      credit_limit:
                        type: integer
                        format: int32
                      customer_type:
                        type: string
                      date_key:
                        type: string
                      date_opened:
                        type: integer
                        format: int32
                      dw_cpart:
                        type: integer
                        format: int32
                      dw_part:
                        type: integer
                        format: int32
                      end_of_day_balance:
                        type: number
                        format: double
                      ewp_account_holder_type_cd:
                        type: string
                      gsm_active_days_qty_1m:
                        type: integer
                        format: int32
                      gsm_active_days_qty_3m:
                        type: integer
                        format: int32
                      gsm_active_days_qty_6m:
                        type: integer
                        format: int32
                      gsm_avg_bund_size_1m:
                        type: string
                      gsm_avg_bund_size_3m:
                        type: string
                      gsm_avg_bund_size_6m:
                        type: string
                      gsm_avg_topup_amt_1m:
                        type: number
                        format: double
                      gsm_avg_topup_amt_3m:
                        type: number
                        format: double
                      gsm_avg_topup_amt_6m:
                        type: number
                        format: double
                      gsm_dab_qty_1m:
                        type: integer
                        format: int32
                      gsm_dab_qty_3m:
            

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