---
openapi: 3.0.1
info:
  title: RizPay API
  version: 1.0.0
  description: |
    The RizPay API enables businesses to integrate bill payment services into their applications.

    ## Features
    - **Airtime**: Purchase airtime for MTN, Airtel, Glo, 9mobile
    - **Data Plans**: Buy data bundles for all networks
    - **Electricity**: Pay electricity bills for all Nigerian distributors
    - **Cable TV**: Subscribe to DSTV, GOTV, Startimes

    ## Authentication
    All requests require a Bearer token in the Authorization header:
    ```
    Authorization: Bearer sk_live_your_secret_key
    ```

    ## Rate Limiting
    - Standard: 60 requests/minute
    - Burst: 10 requests/10 seconds
    Response headers include rate limit info.
  contact:
    name: RizPay Support
    email: support@rizpay.app
    url: https://www.rizpay.app/partners
servers:
  - url: https://my.rizpay.app/api/partners/v1
    description: Production
  - url: https://my.rizpay.app/api/partners/sandbox/v1
    description: Sandbox (test environment)
  - url: http://localhost:3000/api/partners/v1
    description: Development
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description:
        Use your secret key (sk_live_xxx or sk_test_xxx) as the bearer
        token
  schemas:
    Status:
      type: object
      description: Response status information
      properties:
        code:
          oneOf:
            - type: integer
            - type: string
          description: HTTP status code or error code
          example: 200
        message:
          type: string
          description: Human-readable status message
          example: Success
      required:
        - code
        - message
    Error:
      type: object
      description: Error response format
      properties:
        status:
          type: object
          properties:
            code:
              type: string
              description: Error code identifier
              example: VALIDATION_ERROR
              enum:
                - AUTHENTICATION_REQUIRED
                - INVALID_CREDENTIALS
                - TOKEN_REVOKED
                - TOKEN_EXPIRED
                - INSUFFICIENT_SCOPE
                - API_DISABLED
                - IP_NOT_ALLOWED
                - ENVIRONMENT_MISMATCH
                - VALIDATION_ERROR
                - MISSING_PARAMETER
                - INVALID_PARAMETER
                - INVALID_PHONE_NUMBER
                - INVALID_AMOUNT
                - DUPLICATE_REFERENCE
                - INSUFFICIENT_BALANCE
                - PRODUCT_UNAVAILABLE
                - VERIFICATION_REQUIRED
                - VERIFICATION_FAILED
                - PROVIDER_ERROR
                - PROVIDER_TIMEOUT
                - PROVIDER_UNAVAILABLE
                - PRODUCT_NOT_FOUND
                - TRANSACTION_NOT_FOUND
                - PURCHASE_NOT_FOUND
                - INVALID_STATUS
                - RATE_LIMIT_EXCEEDED
            message:
              type: string
              description: Human-readable error description
              example: Validation failed
        data:
          type: object
          nullable: true
          example:
    SuccessResponse:
      type: object
      properties:
        status:
          "$ref": "#/components/schemas/Status"
        data:
          type: object
    Account:
      type: object
      description: Partner account information
      properties:
        id:
          type: string
          description: Unique account identifier
          example: acc_abc123
        type:
          type: string
          example: account
        attributes:
          type: object
          properties:
            name:
              type: string
              description: Account/business name
              example: Acme Corp
            email:
              type: string
              format: email
              description: Account email
              example: api@acme.com
            business_name:
              type: string
              description: Business name
              example: Acme Corp
            role:
              type: string
              description: Account type
              example: business
            created_at:
              type: string
              format: date-time
              description: Account creation time
              example: "2024-01-15T10:30:00Z"
    Balance:
      type: object
      description: Wallet balance information
      properties:
        balance:
          type: string
          description: Current available balance
          example: "50000.00"
        currency:
          type: string
          description: Currency code (always NGN)
          example: NGN
        updated_at:
          type: string
          format: date-time
          description: Last balance update time
          example: "2024-01-15T10:30:00Z"
    ProductCategory:
      type: object
      description: Product category information
      properties:
        id:
          type: string
          description: Category identifier
          example: airtimes
          enum:
            - airtimes
            - dataplans
            - cabletv
            - electricity
        name:
          type: string
          description: Display name
          example: Airtime
        description:
          type: string
          description: Category description
          example: Mobile airtime top-up
        endpoint:
          type: string
          description: API endpoint for this category
          example: "/api/partners/v1/products/airtimes"
    VariablePrice:
      type: object
      description:
        Variable-basis price for products where the partner chooses the
        amount (airtime, electricity). The partner can pick any amount in [min_amount,
        max_amount].
      properties:
        currency:
          type: string
          example: NGN
        basis:
          type: string
          example: face_value
          enum:
            - face_value
        min_amount:
          type: string
          example: "50.00"
        max_amount:
          type: string
          example: "50000.00"
    FixedPrice:
      type: object
      description:
        Fixed catalog price the partner will be billed for one unit of
        the product (data plans, cable TV). Matches Product#buyer_discounted_amount
        for the requesting partner account.
      properties:
        amount:
          type: string
          example: "320.00"
        currency:
          type: string
          example: NGN
        basis:
          type: string
          example: fixed
          enum:
            - fixed
    TransactionPrice:
      type: object
      description:
        Per-transaction price breakdown. product_amount is the resolved
        product cost, fee_amount is any partner-tier markup (zero today), total_debit
        is what was actually taken from the partner wallet.
      properties:
        product_amount:
          type: string
          example: "320.00"
        fee_amount:
          type: string
          example: "0.00"
        total_debit:
          type: string
          example: "320.00"
        currency:
          type: string
          example: NGN
        basis:
          type: string
          example: fixed
          enum:
            - fixed
            - face_value
    AirtimeProduct:
      type: object
      description: Airtime product details
      properties:
        id:
          type: string
          description: Product ID with prd_ prefix
          example: prd_mtn_airtime
        type:
          type: string
          example: airtime
        attributes:
          type: object
          properties:
            network:
              type: string
              description: Mobile network operator
              example: MTN
              enum:
                - MTN
                - AIRTEL
                - GLO
                - 9MOBILE
            min_amount:
              type: string
              description: Minimum purchase amount
              example: "50.00"
            max_amount:
              type: string
              description: Maximum purchase amount
              example: "50000.00"
            price:
              "$ref": "#/components/schemas/VariablePrice"
    DataPlanProduct:
      type: object
      description: Data plan product details
      properties:
        id:
          type: string
          description: Product ID with prd_ prefix
          example: prd_mtn_1gb_daily
        type:
          type: string
          example: data_plan
        attributes:
          type: object
          properties:
            network:
              type: string
              description: Mobile network operator
              example: MTN
              enum:
                - MTN
                - AIRTEL
                - GLO
                - 9MOBILE
            name:
              type: string
              description: Plan name
              example: 1GB Daily Plan
            duration:
              type: string
              description: Plan validity period
              example: 1 day
            bundle_size:
              type: string
              description: Data bundle size
              example: 1GB
            bundle_type:
              type: string
              description: Bundle category
              example: daily
              enum:
                - daily
                - weekly
                - monthly
            price:
              "$ref": "#/components/schemas/FixedPrice"
    CableTvProduct:
      type: object
      description: Cable TV subscription product
      properties:
        id:
          type: string
          description: Product ID with prd_ prefix
          example: prd_dstv_compact
        type:
          type: string
          example: cable_tv
        attributes:
          type: object
          properties:
            service:
              type: string
              description: Cable TV provider
              example: DSTV
              enum:
                - DSTV
                - GOTV
                - STARTIMES
            name:
              type: string
              description: Subscription name
              example: DStv Compact
            package:
              type: string
              description: Package details
              example: Compact
            price:
              "$ref": "#/components/schemas/FixedPrice"
    ElectricityProduct:
      type: object
      description: Electricity payment product
      properties:
        id:
          type: string
          description: Product ID with prd_ prefix
          example: prd_ikedc_prepaid
        type:
          type: string
          example: electricity
        attributes:
          type: object
          properties:
            distributor:
              type: string
              description: Electricity distribution company
              example: IKEDC
            meter_type:
              type: string
              description: Meter type
              example: prepaid
              enum:
                - prepaid
                - postpaid
            min_amount:
              type: string
              description: Minimum payment amount
              example: "500.00"
            max_amount:
              type: string
              description: Maximum payment amount
              example: "100000.00"
            price:
              "$ref": "#/components/schemas/VariablePrice"
    Product:
      type: object
      description: Generic product (see specific product types for details)
      properties:
        id:
          type: string
          description: Product ID with prd_ prefix
          example: prd_123
        type:
          type: string
          description: Product type
          example: airtime
          enum:
            - airtime
            - data_plan
            - cable_tv
            - electricity
        attributes:
          type: object
          description: Product-specific attributes
    Transaction:
      type: object
      description: Purchase transaction details
      properties:
        id:
          type: string
          description: Transaction ID with txn_ prefix
          example: txn_abc123
        type:
          type: string
          example: transaction
        attributes:
          type: object
          properties:
            amount:
              type: string
              description: Transaction amount
              example: "1000.00"
            currency:
              type: string
              description: Currency code
              example: NGN
            status:
              type: string
              description: Transaction status
              example: successful
              enum:
                - pending
                - successful
                - failed
                - reversed
            category:
              type: string
              description: Product category
              example: airtime
            description:
              type: string
              description: Transaction description
              example: MTN Airtime purchase
            reference:
              type: string
              description: RizPay internal reference
              example: RIZ-ABCD-1234
            external_reference:
              type: string
              nullable: true
              description: Your external reference
              example: order-12345
            product_type:
              type: string
              nullable: true
              description: Type of product purchased
              example: Airtime
            phone_number:
              type: string
              nullable: true
              description: Phone number (for airtime/data)
              example: "08012345678"
            meter_number:
              type: string
              nullable: true
              description: Meter number (for electricity)
              example: "12345678901"
            price:
              "$ref": "#/components/schemas/TransactionPrice"
            created_at:
              type: string
              format: date-time
              description: Transaction creation time
              example: "2024-01-15T10:30:00Z"
            updated_at:
              type: string
              format: date-time
              description: Last update time
              example: "2024-01-15T10:30:02Z"
    Purchase:
      "$ref": "#/components/schemas/Transaction"
    ElectricityVerification:
      type: object
      description: Electricity meter verification result
      properties:
        verified:
          type: boolean
          description: Whether verification was successful
          example: true
        product_id:
          type: string
          description: Product ID
          example: prd_ikedc_prepaid
        product_type:
          type: string
          example: electricity
        price:
          "$ref": "#/components/schemas/VariablePrice"
        customer:
          type: object
          properties:
            meter_number:
              type: string
              description: Verified meter number
              example: "12345678901"
            meter_type:
              type: string
              description: Meter type
              example: prepaid
            customer_name:
              type: string
              description: Customer name on account
              example: John Doe
            address:
              type: string
              description: Customer address
              example: 123 Main Street, Lagos
            distributor:
              type: string
              description: Electricity distributor
              example: IKEDC
    CableTvVerification:
      type: object
      description: Cable TV decoder verification result
      properties:
        verified:
          type: boolean
          description: Whether verification was successful
          example: true
        product_id:
          type: string
          description: Product ID
          example: prd_dstv_compact
        product_type:
          type: string
          example: cable_tv
        price:
          "$ref": "#/components/schemas/FixedPrice"
        customer:
          type: object
          properties:
            smart_number:
              type: string
              description: Decoder/smart card number
              example: "1234567890"
            customer_name:
              type: string
              description: Customer name on account
              example: Jane Doe
            current_bouquet:
              type: string
              description: Current subscription package
              example: Compact
            due_date:
              type: string
              description: Subscription expiry date
              example: "2024-02-15"
    Verification:
      type: object
      description: Verification result (structure varies by product type)
      properties:
        verified:
          type: boolean
          description: Whether verification was successful
        product_id:
          type: string
          description: Product ID
        product_type:
          type: string
          description: Product type
        price:
          oneOf:
            - "$ref": "#/components/schemas/FixedPrice"
            - "$ref": "#/components/schemas/VariablePrice"
          description:
            Price tuple for the verified product (fixed for cable TV, variable
            face_value for electricity/airtime).
        customer:
          type: object
          description: Customer information (varies by product type)
    Pagination:
      type: object
      description: Pagination metadata
      properties:
        page:
          type: integer
          description: Current page number
          example: 1
        per_page:
          type: integer
          description: Items per page
          example: 20
        total_pages:
          type: integer
          description: Total number of pages
          example: 10
        total_count:
          type: integer
          description: Total number of items
          example: 195
    AccountResponse:
      type: object
      description: Account details response
      properties:
        status:
          "$ref": "#/components/schemas/Status"
        data:
          "$ref": "#/components/schemas/Account"
      example:
        status:
          code: 200
          message: Success
        data:
          id: acc_abc123
          type: account
          attributes:
            name: Acme Corp
            email: api@acme.com
            business_name: Acme Corp
            role: business
            created_at: "2024-01-15T10:30:00Z"
    BalanceResponse:
      type: object
      description: Balance response
      properties:
        status:
          "$ref": "#/components/schemas/Status"
        data:
          "$ref": "#/components/schemas/Balance"
      example:
        status:
          code: 200
          message: Success
        data:
          balance: "50000.00"
          currency: NGN
          updated_at: "2024-01-15T10:30:00Z"
    TransactionResponse:
      type: object
      description: Single transaction response
      properties:
        status:
          "$ref": "#/components/schemas/Status"
        data:
          "$ref": "#/components/schemas/Transaction"
      example:
        status:
          code: 200
          message: Success
        data:
          id: txn_abc123
          type: transaction
          attributes:
            amount: "1000.00"
            currency: NGN
            status: successful
            category: purchase
            description: MTN Airtime purchase
            reference: RIZ-ABCD-1234
            external_reference: order-12345
            product_type: Airtime
            phone_number: "08012345678"
            price:
              product_amount: "1000.00"
              fee_amount: "0.00"
              total_debit: "1000.00"
              currency: NGN
              basis: face_value
            created_at: "2024-01-15T10:30:00Z"
            updated_at: "2024-01-15T10:30:02Z"
    TransactionListResponse:
      type: object
      description: Transaction list response
      properties:
        status:
          "$ref": "#/components/schemas/Status"
        data:
          type: array
          items:
            "$ref": "#/components/schemas/Transaction"
        pagination:
          "$ref": "#/components/schemas/Pagination"
      example:
        status:
          code: 200
          message: Success
        data:
          - id: txn_abc123
            type: transaction
            attributes:
              amount: "1000.00"
              currency: NGN
              status: successful
              category: purchase
              description: MTN Airtime purchase
              reference: RIZ-ABCD-1234
              phone_number: "08012345678"
              price:
                product_amount: "1000.00"
                fee_amount: "0.00"
                total_debit: "1000.00"
                currency: NGN
                basis: face_value
              created_at: "2024-01-15T10:30:00Z"
        pagination:
          page: 1
          per_page: 20
          total_pages: 5
          total_count: 95
    ProductResponse:
      type: object
      description: Single product response
      properties:
        status:
          "$ref": "#/components/schemas/Status"
        data:
          "$ref": "#/components/schemas/Product"
      example:
        status:
          code: 200
          message: Success
        data:
          id: prd_mtn_airtime
          type: airtime
          attributes:
            network: MTN
            min_amount: "50.00"
            max_amount: "50000.00"
            price:
              currency: NGN
              basis: face_value
              min_amount: 50
              max_amount: 50000
    ProductListResponse:
      type: object
      description: Product list response
      properties:
        status:
          "$ref": "#/components/schemas/Status"
        data:
          type: array
          items:
            "$ref": "#/components/schemas/Product"
        pagination:
          "$ref": "#/components/schemas/Pagination"
      example:
        status:
          code: 200
          message: Success
        data:
          - id: prd_mtn_airtime
            type: airtime
            attributes:
              network: MTN
              min_amount: "50.00"
              max_amount: "50000.00"
              price:
                currency: NGN
                basis: face_value
                min_amount: 50
                max_amount: 50000
          - id: prd_airtel_airtime
            type: airtime
            attributes:
              network: AIRTEL
              min_amount: "50.00"
              max_amount: "50000.00"
              price:
                currency: NGN
                basis: face_value
                min_amount: 50
                max_amount: 50000
        pagination:
          page: 1
          per_page: 20
          total_pages: 1
          total_count: 4
    ProductCategoryListResponse:
      type: object
      description: Product category list response
      properties:
        status:
          "$ref": "#/components/schemas/Status"
        data:
          type: array
          items:
            "$ref": "#/components/schemas/ProductCategory"
      example:
        status:
          code: 200
          message: Success
        data:
          - id: airtimes
            name: Airtime
            description: Mobile airtime top-up
            endpoint: "/api/partners/v1/products/airtimes"
          - id: dataplans
            name: Data Plans
            description: Mobile data bundles
            endpoint: "/api/partners/v1/products/dataplans"
          - id: electricity
            name: Electricity
            description: Electricity bill payments
            endpoint: "/api/partners/v1/products/electricity"
          - id: cabletv
            name: Cable TV
            description: Cable TV subscriptions
            endpoint: "/api/partners/v1/products/cabletv"
    VerificationResponse:
      type: object
      description: Verification response
      properties:
        status:
          "$ref": "#/components/schemas/Status"
        data:
          "$ref": "#/components/schemas/Verification"
      example:
        status:
          code: 200
          message: Verification successful
        data:
          verified: true
          product_id: prd_ikedc_prepaid
          product_type: electricity
          price:
            currency: NGN
            basis: face_value
            min_amount: 500
            max_amount: 100000
          customer:
            meter_number: "12345678901"
            meter_type: prepaid
            customer_name: John Doe
            address: 123 Main Street, Lagos
    HealthResponse:
      type: object
      description: Health check response
      required:
        - status
        - data
      properties:
        status:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: integer
              example: 200
            message:
              type: string
              example: API is healthy
        data:
          type: object
          required:
            - status
            - version
            - timestamp
          properties:
            status:
              type: string
              example: ok
            version:
              type: string
              example: 1.0.0
            timestamp:
              type: string
              format: date-time
      example:
        status:
          code: 200
          message: API is healthy
        data:
          status: ok
          version: 1.0.0
          timestamp: "2024-01-15T10:30:00Z"
    PurchaseRequest:
      type: object
      description: Create purchase request
      required:
        - product_id
      properties:
        product_id:
          type: string
          description: Product ID
          example: prd_mtn_airtime
        amount:
          type: number
          description: Amount for airtime/electricity
          example: 1000
        phone_number:
          type: string
          description: Phone number for airtime/data
          example: "08012345678"
        meter_number:
          type: string
          description: Meter number for electricity
          example: "12345678901"
        smart_number:
          type: string
          description: Smart card number for cable TV
          example: "1234567890"
        external_reference:
          type: string
          description:
            "Your unique reference for duplicate prevention (16 chars:
            10-digit timestamp + 6 alphanumeric)"
          example: 1736234400A1B2C3
      example:
        product_id: prd_mtn_airtime
        amount: 1000
        phone_number: "08012345678"
        external_reference: 1736234400A1B2C3
    VerifyRequest:
      type: object
      description: Verify meter/decoder request
      required:
        - product_id
      properties:
        product_id:
          type: string
          description: Product ID
          example: prd_ikedc_prepaid
        meter_number:
          type: string
          description: Meter number for electricity
          example: "12345678901"
        smart_number:
          type: string
          description: Smart card number for cable TV
          example: "1234567890"
      example:
        product_id: prd_ikedc_prepaid
        meter_number: "12345678901"
security:
  - bearerAuth: []
paths:
  "/account":
    get:
      summary: Get account details
      tags:
        - Account
      operationId: getAccount
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Account details retrieved
          content:
            application/json:
              example:
                status:
                  code: 200
                  message: Account details retrieved
                data:
                  id: acc_e6a0f87e-fa49-462d-8bdb-79334f18a65d
                  type: account
                  attributes:
                    name: Acme Technologies Ltd
                    email: 700f5766@rizpay.app
                    business_name: Acme Technologies Ltd
                    role: regular
                    created_at: "2026-05-18T11:39:48+01:00"
              schema:
                "$ref": "#/components/schemas/AccountResponse"
        "401":
          description: Unauthorized
  "/account/balance":
    get:
      summary: Get wallet balance
      tags:
        - Account
      operationId: getBalance
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Balance retrieved
          content:
            application/json:
              example:
                status:
                  code: 200
                  message: Balance retrieved
                data:
                  balance: "25750.00"
                  currency: NGN
                  updated_at: "2026-05-18T11:39:49+01:00"
              schema:
                "$ref": "#/components/schemas/BalanceResponse"
  "/account/transactions":
    get:
      summary: List transactions
      tags:
        - Account
      operationId: listTransactions
      security:
        - bearerAuth: []
      parameters:
        - name: status
          in: query
          required: false
          description: Filter by status (pending, successful, failed, reversed)
          schema:
            type: string
        - name: category
          in: query
          required: false
          description:
            Filter by category (funding, purchase, withdrawal, transfer,
            commission, promo)
          schema:
            type: string
        - name: reference
          in: query
          required: false
          description: Filter by external_reference
          schema:
            type: string
        - name: from
          in: query
          required: false
          description: Filter transactions from this date (ISO8601)
          schema:
            type: string
            format: date-time
        - name: to
          in: query
          required: false
          description: Filter transactions to this date (ISO8601)
          schema:
            type: string
            format: date-time
        - name: page
          in: query
          required: false
          schema:
            type: integer
        - name: per_page
          in: query
          required: false
          schema:
            type: integer
      responses:
        "200":
          description: Transactions listed
          content:
            application/json:
              example:
                status:
                  code: 200
                  message: Transactions retrieved
                data:
                  - id: txn_86bdbeb6-7b63-46f2-bbdc-82e9b55f018d
                    type: transaction
                    attributes:
                      amount: "15000.0"
                      currency: NGN
                      status: pending
                      category: purchase
                      description: DSTV Compact Subscription
                      reference: 53ec0a81cd2c4c418787
                      external_reference:
                      product_type:
                      phone_number:
                      meter_number:
                      price:
                        product_amount: "15000.00"
                        fee_amount: "0.00"
                        total_debit: "15000.00"
                        currency: NGN
                        basis: fixed
                      created_at: "2026-05-18T11:39:49+01:00"
                      updated_at: "2026-05-18T11:39:49+01:00"
                  - id: txn_02982aa2-0a95-450d-9a48-85e10035606a
                    type: transaction
                    attributes:
                      amount: "2500.0"
                      currency: NGN
                      status: successful
                      category: purchase
                      description: GLO 1.5GB Data Plan - 08098765432
                      reference: aed27b19d6d37ac73a7c
                      external_reference:
                      product_type:
                      phone_number:
                      meter_number:
                      price:
                        product_amount: "2500.00"
                        fee_amount: "0.00"
                        total_debit: "2500.00"
                        currency: NGN
                        basis: fixed
                      created_at: "2026-05-18T11:39:49+01:00"
                      updated_at: "2026-05-18T11:39:49+01:00"
                  - id: txn_471d34e1-8a85-44a7-a9db-4706fb3765d9
                    type: transaction
                    attributes:
                      amount: "1000.0"
                      currency: NGN
                      status: successful
                      category: purchase
                      description: MTN Airtime - 08012345678
                      reference: 183e2b14e05622581d74
                      external_reference:
                      product_type:
                      phone_number:
                      meter_number:
                      price:
                        product_amount: "1000.00"
                        fee_amount: "0.00"
                        total_debit: "1000.00"
                        currency: NGN
                        basis: fixed
                      created_at: "2026-05-18T11:39:49+01:00"
                      updated_at: "2026-05-18T11:39:49+01:00"
                pagination:
                  page: 1
                  per_page: 20
                  total_pages: 1
                  total_count: 3
              schema:
                "$ref": "#/components/schemas/TransactionListResponse"
        "400":
          description: Invalid filter parameters
  "/account/transactions/{id}":
    get:
      summary: Get transaction details
      tags:
        - Account
      operationId: getTransaction
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          description:
            "Transaction ID (with or without txn_ prefix) OR external_reference
            (16 chars: 10 digits + 6 alphanumeric)"
          schema:
            type: string
      responses:
        "200":
          description: Transaction retrieved by external_reference
          content:
            application/json:
              example:
                status:
                  code: 200
                  message: Transaction details retrieved
                data:
                  id: txn_0fcae366-33d6-456a-81c3-a8c65f039d8e
                  type: transaction
                  attributes:
                    amount: "500.0"
                    currency: NGN
                    status: successful
                    category: purchase
                    description: Airtel Airtime - 08055512345
                    reference: 2e1cc4616ac60cd80a23
                    external_reference:
                    product_type:
                    phone_number:
                    meter_number:
                    price:
                      product_amount: "500.00"
                      fee_amount: "0.00"
                      total_debit: "500.00"
                      currency: NGN
                      basis: fixed
                    created_at: "2026-05-18T11:39:49+01:00"
                    updated_at: "2026-05-18T11:39:49+01:00"
              schema:
                "$ref": "#/components/schemas/TransactionResponse"
        "404":
          description: Transaction not found
  "/health":
    get:
      summary: Check API health status
      tags:
        - Health
      operationId: getHealth
      security: []
      responses:
        "200":
          description: API is healthy
          content:
            application/json:
              example:
                status:
                  code: 200
                  message: API is healthy
                data:
                  status: ok
                  version: 1.0.0
                  timestamp: "2026-05-18T11:39:50+01:00"
              schema:
                "$ref": "#/components/schemas/HealthResponse"
  "/products":
    get:
      summary: List product categories
      tags:
        - Products
      operationId: listProductCategories
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Product categories listed
          content:
            application/json:
              example:
                status:
                  code: 200
                  message: Product categories retrieved
                data:
                  - id: airtimes
                    type: product_category
                    attributes:
                      name: Airtime
                      description: Mobile airtime top-up
                      endpoint: "/api/partners/v1/products/airtimes"
                  - id: dataplans
                    type: product_category
                    attributes:
                      name: Data Plans
                      description: Mobile data bundles
                      endpoint: "/api/partners/v1/products/dataplans"
                  - id: cabletv
                    type: product_category
                    attributes:
                      name: Cable TV
                      description: Cable TV subscriptions
                      endpoint: "/api/partners/v1/products/cabletv"
                  - id: electricity
                    type: product_category
                    attributes:
                      name: Electricity
                      description: Electricity bill payments
                      endpoint: "/api/partners/v1/products/electricity"
              schema:
                "$ref": "#/components/schemas/ProductCategoryListResponse"
  "/products/airtimes":
    get:
      summary: List airtime products
      tags:
        - Products
      operationId: listAirtimes
      security:
        - bearerAuth: []
      parameters:
        - name: network
          in: query
          required: false
          description: Filter by network (MTN, Airtel, Glo, 9mobile)
          schema:
            type: string
        - name: page
          in: query
          required: false
          description: "Page number (default: 1)"
          schema:
            type: integer
        - name: per_page
          in: query
          required: false
          description: "Items per page (default: 20, max: 100)"
          schema:
            type: integer
      responses:
        "200":
          description: Airtime products listed
          content:
            application/json:
              example:
                status:
                  code: 200
                  message: Airtime products retrieved
                data:
                  - id: prd_364
                    type: airtime
                    attributes:
                      display_name: 9MOBILE Airtime
                      network: 9MOBILE
                      min_amount: "50.0"
                      max_amount: "50000.0"
                      price:
                        currency: NGN
                        basis: face_value
                        min_amount: "50.00"
                        max_amount: "50000.00"
                  - id: prd_361
                    type: airtime
                    attributes:
                      display_name: MTN Airtime
                      network: MTN
                      min_amount: "50.0"
                      max_amount: "100000.0"
                      price:
                        currency: NGN
                        basis: face_value
                        min_amount: "50.00"
                        max_amount: "100000.00"
                  - id: prd_362
                    type: airtime
                    attributes:
                      display_name: AIRTEL Airtime
                      network: AIRTEL
                      min_amount: "50.0"
                      max_amount: "50000.0"
                      price:
                        currency: NGN
                        basis: face_value
                        min_amount: "50.00"
                        max_amount: "50000.00"
                  - id: prd_363
                    type: airtime
                    attributes:
                      display_name: GLO Airtime
                      network: GLO
                      min_amount: "50.0"
                      max_amount: "100000.0"
                      price:
                        currency: NGN
                        basis: face_value
                        min_amount: "50.00"
                        max_amount: "100000.00"
                  - id: prd_17
                    type: airtime
                    attributes:
                      display_name: AIRTEL Airtime
                      network: AIRTEL
                      min_amount: "50.0"
                      max_amount: "50000.0"
                      price:
                        currency: NGN
                        basis: face_value
                        min_amount: "50.00"
                        max_amount: "50000.00"
                  - id: prd_18
                    type: airtime
                    attributes:
                      display_name: 9MOBILE Airtime
                      network: 9MOBILE
                      min_amount: "50.0"
                      max_amount: "50000.0"
                      price:
                        currency: NGN
                        basis: face_value
                        min_amount: "50.00"
                        max_amount: "50000.00"
                  - id: prd_19
                    type: airtime
                    attributes:
                      display_name: GLO Airtime
                      network: GLO
                      min_amount: "50.0"
                      max_amount: "100000.0"
                      price:
                        currency: NGN
                        basis: face_value
                        min_amount: "50.00"
                        max_amount: "100000.00"
                  - id: prd_20
                    type: airtime
                    attributes:
                      display_name: MTN Airtime
                      network: MTN
                      min_amount: "50.0"
                      max_amount: "100000.0"
                      price:
                        currency: NGN
                        basis: face_value
                        min_amount: "50.00"
                        max_amount: "100000.00"
                pagination:
                  page: 1
                  per_page: 20
                  total_pages: 1
                  total_count: 8
              schema:
                "$ref": "#/components/schemas/ProductListResponse"
  "/products/dataplans":
    get:
      summary: List data plan products
      tags:
        - Products
      operationId: listDataPlans
      security:
        - bearerAuth: []
      parameters:
        - name: network
          in: query
          required: false
          schema:
            type: string
        - name: bundle_type
          in: query
          required: false
          description: Filter by bundle type (daily, weekly, monthly)
          schema:
            type: string
        - name: page
          in: query
          required: false
          description: "Page number (default: 1)"
          schema:
            type: integer
        - name: per_page
          in: query
          required: false
          description: "Items per page (default: 20, max: 100)"
          schema:
            type: integer
      responses:
        "200":
          description: Data plans listed
          content:
            application/json:
              example:
                status:
                  code: 200
                  message: Data plans retrieved
                data:
                  - id: prd_367
                    type: data_plan
                    attributes:
                      display_name: MTN 1.5GB / 30 Days (SME)
                      network: MTN
                      bundle_size: 1.5GB
                      duration: 30 Days
                      bundle_type: SME
                      price:
                        amount: "292.00"
                        currency: NGN
                        basis: fixed
                  - id: prd_368
                    type: data_plan
                    attributes:
                      display_name: AIRTEL 500MB / 7 Days (GIFTING)
                      network: AIRTEL
                      bundle_size: 500MB
                      duration: 7 Days
                      bundle_type: GIFTING
                      price:
                        amount: "292.00"
                        currency: NGN
                        basis: fixed
                pagination:
                  page: 1
                  per_page: 20
                  total_pages: 1
                  total_count: 2
              schema:
                "$ref": "#/components/schemas/ProductListResponse"
  "/products/cabletv":
    get:
      summary: List cable TV products
      tags:
        - Products
      operationId: listCableTv
      security:
        - bearerAuth: []
      parameters:
        - name: provider
          in: query
          required: false
          description: Filter by provider (DSTV, GOTV, Startimes)
          schema:
            type: string
        - name: page
          in: query
          required: false
          description: "Page number (default: 1)"
          schema:
            type: integer
        - name: per_page
          in: query
          required: false
          description: "Items per page (default: 20, max: 100)"
          schema:
            type: integer
      responses:
        "200":
          description: Cable TV products listed
          content:
            application/json:
              example:
                status:
                  code: 200
                  message: Cable TV products retrieved
                data:
                  - id: prd_371
                    type: cable_tv
                    attributes:
                      display_name: Compact
                      service: DSTV
                      package: Compact
                      price:
                        amount: "20992.00"
                        currency: NGN
                        basis: fixed
                  - id: prd_372
                    type: cable_tv
                    attributes:
                      display_name: GOtv Max
                      service: GOTV
                      package: GOtv Max
                      price:
                        amount: "15692.00"
                        currency: NGN
                        basis: fixed
                pagination:
                  page: 1
                  per_page: 20
                  total_pages: 1
                  total_count: 2
              schema:
                "$ref": "#/components/schemas/ProductListResponse"
  "/products/electricity":
    get:
      summary: List electricity products
      tags:
        - Products
      operationId: listElectricity
      security:
        - bearerAuth: []
      parameters:
        - name: distributor
          in: query
          required: false
          description: Filter by electricity distributor
          schema:
            type: string
        - name: page
          in: query
          required: false
          description: "Page number (default: 1)"
          schema:
            type: integer
        - name: per_page
          in: query
          required: false
          description: "Items per page (default: 20, max: 100)"
          schema:
            type: integer
      responses:
        "200":
          description: Electricity products listed
          content:
            application/json:
              example:
                status:
                  code: 200
                  message: Electricity products retrieved
                data:
                  - id: prd_375
                    type: electricity
                    attributes:
                      display_name: Ikeja Electric (PRE)
                      distributor: Ikeja Electric
                      meter_type: PRE
                      min_amount: "500.0"
                      max_amount: "100000.0"
                      price:
                        currency: NGN
                        basis: face_value
                        min_amount: "500.00"
                        max_amount: "100000.00"
                  - id: prd_376
                    type: electricity
                    attributes:
                      display_name: Eko Electric (POST)
                      distributor: Eko Electric
                      meter_type: POST
                      min_amount: "1000.0"
                      max_amount: "100000.0"
                      price:
                        currency: NGN
                        basis: face_value
                        min_amount: "1000.00"
                        max_amount: "100000.00"
                  - id: prd_23
                    type: electricity
                    attributes:
                      display_name: Benin Electricity - BEDC
                      distributor: Benin Electricity - BEDC
                      meter_type:
                      min_amount: "500.0"
                      max_amount: "100000.0"
                      price:
                        currency: NGN
                        basis: face_value
                        min_amount: "500.00"
                        max_amount: "100000.00"
                  - id: prd_24
                    type: electricity
                    attributes:
                      display_name: Eko Electric Payment - EKEDC
                      distributor: Eko Electric Payment - EKEDC
                      meter_type:
                      min_amount: "1000.0"
                      max_amount: "100000.0"
                      price:
                        currency: NGN
                        basis: face_value
                        min_amount: "1000.00"
                        max_amount: "100000.00"
                  - id: prd_25
                    type: electricity
                    attributes:
                      display_name: Enugu Electric - EEDC
                      distributor: Enugu Electric - EEDC
                      meter_type:
                      min_amount: "500.0"
                      max_amount: "100000.0"
                      price:
                        currency: NGN
                        basis: face_value
                        min_amount: "500.00"
                        max_amount: "100000.00"
                  - id: prd_26
                    type: electricity
                    attributes:
                      display_name: IBEDC - Ibadan Electricity Distribution Company
                      distributor: IBEDC - Ibadan Electricity Distribution Company
                      meter_type:
                      min_amount: "2000.0"
                      max_amount: "100000.0"
                      price:
                        currency: NGN
                        basis: face_value
                        min_amount: "2000.00"
                        max_amount: "100000.00"
                  - id: prd_27
                    type: electricity
                    attributes:
                      display_name: Ikeja Electric Payment - IKEDC
                      distributor: Ikeja Electric Payment - IKEDC
                      meter_type:
                      min_amount: "100.0"
                      max_amount: "100000.0"
                      price:
                        currency: NGN
                        basis: face_value
                        min_amount: "100.00"
                        max_amount: "100000.00"
                  - id: prd_21
                    type: electricity
                    attributes:
                      display_name: Aba Electric Payment - ABEDC
                      distributor: Aba Electric Payment - ABEDC
                      meter_type:
                      min_amount: "100.0"
                      max_amount: "100000.0"
                      price:
                        currency: NGN
                        basis: face_value
                        min_amount: "100.00"
                        max_amount: "100000.00"
                  - id: prd_29
                    type: electricity
                    attributes:
                      display_name: Kaduna Electric - KAEDCO
                      distributor: Kaduna Electric - KAEDCO
                      meter_type:
                      min_amount: "1100.0"
                      max_amount: "100000.0"
                      price:
                        currency: NGN
                        basis: face_value
                        min_amount: "1100.00"
                        max_amount: "100000.00"
                  - id: prd_30
                    type: electricity
                    attributes:
                      display_name: KEDCO - Kano Electric
                      distributor: KEDCO - Kano Electric
                      meter_type:
                      min_amount: "500.0"
                      max_amount: "100000.0"
                      price:
                        currency: NGN
                        basis: face_value
                        min_amount: "500.00"
                        max_amount: "100000.00"
                  - id: prd_31
                    type: electricity
                    attributes:
                      display_name: PHED - Port Harcourt Electric
                      distributor: PHED - Port Harcourt Electric
                      meter_type:
                      min_amount: "200.0"
                      max_amount: "100000.0"
                      price:
                        currency: NGN
                        basis: face_value
                        min_amount: "200.00"
                        max_amount: "100000.00"
                  - id: prd_32
                    type: electricity
                    attributes:
                      display_name: Yola Electric Disco Payment - YEDC
                      distributor: Yola Electric Disco Payment - YEDC
                      meter_type:
                      min_amount: "500.0"
                      max_amount: "100000.0"
                      price:
                        currency: NGN
                        basis: face_value
                        min_amount: "500.00"
                        max_amount: "100000.00"
                  - id: prd_28
                    type: electricity
                    attributes:
                      display_name: Jos Electric - JED
                      distributor: Jos Electric - JED
                      meter_type:
                      min_amount: "1000.0"
                      max_amount: "100000.0"
                      price:
                        currency: NGN
                        basis: face_value
                        min_amount: "1000.00"
                        max_amount: "100000.00"
                  - id: prd_22
                    type: electricity
                    attributes:
                      display_name: Abuja Electricity Distribution Company- AEDC
                      distributor: Abuja Electricity Distribution Company- AEDC
                      meter_type:
                      min_amount: "900.0"
                      max_amount: "100000.0"
                      price:
                        currency: NGN
                        basis: face_value
                        min_amount: "900.00"
                        max_amount: "100000.00"
                pagination:
                  page: 1
                  per_page: 20
                  total_pages: 1
                  total_count: 14
              schema:
                "$ref": "#/components/schemas/ProductListResponse"
  "/products/{id}":
    get:
      summary: Get product details
      tags:
        - Products
      operationId: getProduct
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          description: Product ID (with or without prd_ prefix)
          schema:
            type: string
      responses:
        "200":
          description: Product details retrieved
          content:
            application/json:
              example:
                status:
                  code: 200
                  message: Product details retrieved
                data:
                  id: prd_377
                  type: airtime
                  attributes:
                    display_name: MTN Airtime
                    network: MTN
                    min_amount: "50.0"
                    max_amount: "100000.0"
                    price:
                      currency: NGN
                      basis: face_value
                      min_amount: "50.00"
                      max_amount: "100000.00"
              schema:
                "$ref": "#/components/schemas/ProductResponse"
        "404":
          description: Product not found
  "/purchases/verify":
    post:
      summary: Verify meter/decoder before purchase
      tags:
        - Purchases
      operationId: verifyPurchase
      security:
        - bearerAuth: []
      parameters: []
      responses:
        "200":
          description: Verification successful
          content:
            application/json:
              example:
                status:
                  code: 200
                  message: Verification successful
                data:
                  verified: true
                  product_id: prd_378
                  product_type: electricity
                  price:
                    currency: NGN
                    basis: face_value
                    min_amount: "1000.00"
                    max_amount: "100000.00"
                  customer:
                    meter_number: "45012345678"
                    meter_type:
                    customer_name: Adebayo Johnson
                    address: 15 Adeola Odeku Street, Victoria Island, Lagos
                    distributor: Ikeja Electric
              schema:
                "$ref": "#/components/schemas/VerificationResponse"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/VerifyRequest"
  "/purchases":
    post:
      summary: Create a purchase
      tags:
        - Purchases
      operationId: createPurchase
      security:
        - bearerAuth: []
      parameters: []
      responses:
        "201":
          description: Purchase created
          content:
            application/json:
              example:
                status:
                  code: 201
                  message: Purchase created successfully
                data:
                  id: txn_7f46356f-815a-4372-9cb5-49e7ab80a966
                  type: transaction
                  attributes:
                    amount: "2000.0"
                    currency: NGN
                    status: pending
                    category: purchase
                    description: MTN Airtime - 08012345678
                    reference: 0a417ec43fbc54d21788
                    external_reference: 1780315200ABC123
                    product_type:
                    phone_number:
                    meter_number:
                    price:
                      product_amount: "2000.00"
                      fee_amount: "0.00"
                      total_debit: "2000.00"
                      currency: NGN
                      basis: fixed
                    created_at: "2026-06-01T13:00:00+01:00"
                    updated_at: "2026-06-01T13:00:00+01:00"
              schema:
                "$ref": "#/components/schemas/TransactionResponse"
        "400":
          description: Validation error
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/PurchaseRequest"
  "/purchases/{id}":
    get:
      summary: Get purchase details
      tags:
        - Purchases
      operationId: getPurchase
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          description: Purchase ID (with or without txn_ prefix)
          schema:
            type: string
      responses:
        "200":
          description: Purchase details retrieved
          content:
            application/json:
              example:
                status:
                  code: 200
                  message: Purchase details retrieved
                data:
                  id: txn_4162fdd7-e293-413b-a3f6-ebcd4a473efb
                  type: transaction
                  attributes:
                    amount: "5000.0"
                    currency: NGN
                    status: successful
                    category: purchase
                    description: DSTV Compact Plus Subscription
                    reference: fb98d1b3b6d703ee6532
                    external_reference: 1780315200ABC123
                    product_type:
                    phone_number:
                    meter_number:
                    price:
                      product_amount: "5000.00"
                      fee_amount: "0.00"
                      total_debit: "5000.00"
                      currency: NGN
                      basis: fixed
                    created_at: "2026-06-01T13:00:00+01:00"
                    updated_at: "2026-06-01T13:00:00+01:00"
              schema:
                "$ref": "#/components/schemas/TransactionResponse"
  "/purchases/{id}/query":
    post:
      summary: Requery transaction status from provider
      tags:
        - Purchases
      operationId: queryPurchase
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          description: Purchase ID (with or without txn_ prefix)
          schema:
            type: string
      responses:
        "200":
          description: Query initiated
          content:
            application/json:
              example:
                status:
                  code: 200
                  message: Purchase details retrieved
                data:
                  id: txn_1cf51bb5-4319-4a89-bd91-4109e076b5c6
                  type: transaction
                  attributes:
                    amount: "10000.0"
                    currency: NGN
                    status: pending
                    category: purchase
                    description: IKEDC Electricity - 45012345678
                    reference: "0298dff35b39e8b155e8"
                    external_reference: 1780315200ABC123
                    product_type:
                    phone_number:
                    meter_number:
                    price:
                      product_amount: "10000.00"
                      fee_amount: "0.00"
                      total_debit: "10000.00"
                      currency: NGN
                      basis: fixed
                    created_at: "2026-06-01T13:00:00+01:00"
                    updated_at: "2026-06-01T13:00:00+01:00"
              schema:
                "$ref": "#/components/schemas/TransactionResponse"
        "400":
          description: Invalid status - only pending purchases can be requeried
tags:
  - name: Health
    description: |
      Check API availability and status.

      Use this endpoint to verify the API is operational before making other requests.
  - name: Account
    description: |
      Manage your partner account and view wallet information.

      ## Endpoints
      - **GET /account** - View account details
      - **GET /account/balance** - Check wallet balance
      - **GET /account/transactions** - List transaction history

      ## Required Scopes
      - `read_balance` - For account and balance endpoints
      - `read_transactions` - For transaction endpoints
  - name: Products
    description: |
      Browse available bill payment products.

      ## Categories
      - **Airtime** - Mobile top-up for MTN, Airtel, Glo, 9mobile
      - **Data Plans** - Data bundles (daily, weekly, monthly)
      - **Cable TV** - DSTV, GOTV, Startimes subscriptions
      - **Electricity** - Prepaid/postpaid meter payments

      ## Required Scope
      - `view_products`
  - name: Purchases
    description: |
      Create and manage bill payment transactions.

      ## Workflow
      1. **Verify** (optional) - Validate meter/decoder number before purchase
      2. **Create** - Submit purchase request
      3. **Query** - Check transaction status if pending

      ## Required Scopes
      - `purchase_airtime` - For airtime purchases
      - `purchase_data` - For data plan purchases
      - `purchase_cable_tv` - For cable TV subscriptions
      - `purchase_electricity` - For electricity payments
      - `read_transactions` - For viewing purchase details
