naftiko: 1.0.0-alpha2
info:
  label: Interswitch Bills Payment API — Quickteller
  description: List billers, get payment items, validate customer references, and submit Quickteller bill payment advices.
  tags:
  - Interswitch
  - Bills
  - Quickteller
  created: '2026-05-24'
  modified: '2026-05-24'
binds:
- namespace: env
  keys:
    INTERSWITCH_BEARER_TOKEN: INTERSWITCH_BEARER_TOKEN
    INTERSWITCH_TERMINAL_ID: INTERSWITCH_TERMINAL_ID
capability:
  consumes:
  - type: http
    namespace: bills-payment-quickteller
    baseUri: https://sandbox.interswitchng.com
    resources:
    - name: billers
      path: /api/v2/quickteller/billers
      operations:
      - name: listBillers
        method: GET
        description: List all Quickteller billers.
        outputRawFormat: json
        outputParameters:
        - { name: result, type: array, value: $. }
    - name: biller-payment-items
      path: /api/v2/quickteller/billers/{billerId}/paymentitems
      operations:
      - name: listBillerPaymentItems
        method: GET
        description: List payment items / packages for a biller.
        outputRawFormat: json
        outputParameters:
        - { name: result, type: array, value: $. }
        inputParameters:
        - { name: billerId, in: path, type: integer, required: true }
    - name: customer-validations
      path: /api/v2/quickteller/customers/validations
      operations:
      - name: validateCustomer
        method: POST
        description: Validate a customer identifier with the biller.
        outputRawFormat: json
        outputParameters:
        - { name: result, type: object, value: $. }
        inputParameters:
        - { name: body, in: body, type: object, required: true }
    - name: payment-advices
      path: /api/v2/quickteller/payments/advices
      operations:
      - name: submitBillPaymentAdvice
        method: POST
        description: Submit a bill payment advice.
        outputRawFormat: json
        outputParameters:
        - { name: result, type: object, value: $. }
        inputParameters:
        - { name: body, in: body, type: object, required: true }
    authentication:
      type: apikey
      key: Authorization
      value: 'Bearer {{env.INTERSWITCH_BEARER_TOKEN}}'
      placement: header
  exposes:
  - type: rest
    namespace: bills-payment-quickteller-rest
    port: 8080
    resources:
    - path: /v1/billers
      name: billers
      operations:
      - method: GET
        name: listBillers
        call: bills-payment-quickteller.listBillers
        outputParameters: [{ type: array, mapping: $. }]
    - path: /v1/billers/{billerId}/payment-items
      name: biller-payment-items
      operations:
      - method: GET
        name: listBillerPaymentItems
        call: bills-payment-quickteller.listBillerPaymentItems
        with: { billerId: rest.path.billerId }
        outputParameters: [{ type: array, mapping: $. }]
    - path: /v1/customer-validations
      name: customer-validations
      operations:
      - method: POST
        name: validateCustomer
        call: bills-payment-quickteller.validateCustomer
        with: { body: rest.body }
        outputParameters: [{ type: object, mapping: $. }]
    - path: /v1/payment-advices
      name: payment-advices
      operations:
      - method: POST
        name: submitBillPaymentAdvice
        call: bills-payment-quickteller.submitBillPaymentAdvice
        with: { body: rest.body }
        outputParameters: [{ type: object, mapping: $. }]
  - type: mcp
    namespace: bills-payment-quickteller-mcp
    port: 9090
    transport: http
    tools:
    - name: interswitch-list-billers
      description: List Quickteller billers.
      hints: { readOnly: true, destructive: false, idempotent: true }
      call: bills-payment-quickteller.listBillers
      outputParameters: [{ type: array, mapping: $. }]
    - name: interswitch-list-biller-payment-items
      description: List biller payment items.
      hints: { readOnly: true, destructive: false, idempotent: true }
      call: bills-payment-quickteller.listBillerPaymentItems
      with: { billerId: tools.billerId }
      outputParameters: [{ type: array, mapping: $. }]
    - name: interswitch-validate-customer
      description: Validate a biller customer reference.
      hints: { readOnly: true, destructive: false, idempotent: true }
      call: bills-payment-quickteller.validateCustomer
      with: { body: tools.body }
      outputParameters: [{ type: object, mapping: $. }]
    - name: interswitch-submit-bill-payment-advice
      description: Submit a Quickteller bill payment advice.
      hints: { readOnly: false, destructive: false, idempotent: false }
      call: bills-payment-quickteller.submitBillPaymentAdvice
      with: { body: tools.body }
      outputParameters: [{ type: object, mapping: $. }]