openapi: 3.1.0
info:
  title: Watenga Merchant API
  version: 2026-01-01
  description: Merchant integration API for payments, payouts, customers,
    invoices, and account data. All paths use the `/v1/` prefix.
servers:
  - url: https://api.watenga.africa
tags:
  - name: Checkout
  - name: Account
  - name: Transactions
  - name: Refunds
  - name: Payment Links
  - name: Payouts
  - name: Invoices
  - name: Subscriptions
  - name: Payment Methods
  - name: Customers
  - name: Disputes
  - name: Bank Accounts
  - name: Splits
  - name: Capital
  - name: Virtual Terminal
  - name: Terminals
  - name: Platform Billing
  - name: Agent
paths:
  /v1/checkout/create:
    post:
      tags:
        - Checkout
      summary: Create checkout session
      security:
        - bearerAuth: []
      parameters:
        - name: Watenga-Version
          in: header
          required: false
          schema:
            type: string
            example: 2026-01-01
          description: API version date header
      responses:
        "201":
          description: Created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        "400":
          description: Validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /v1/checkout/{id}/status:
    get:
      tags:
        - Checkout
      summary: Get checkout status
      security:
        - bearerAuth: []
      parameters:
        - name: Watenga-Version
          in: header
          required: false
          schema:
            type: string
            example: 2026-01-01
          description: API version date header
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        "400":
          description: Validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /v1/account/balance:
    get:
      tags:
        - Account
      summary: Get account balance
      security:
        - bearerAuth: []
      parameters:
        - name: Watenga-Version
          in: header
          required: false
          schema:
            type: string
            example: 2026-01-01
          description: API version date header
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        "400":
          description: Validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /v1/account/profile:
    get:
      tags:
        - Account
      summary: Get merchant profile
      security:
        - bearerAuth: []
      parameters:
        - name: Watenga-Version
          in: header
          required: false
          schema:
            type: string
            example: 2026-01-01
          description: API version date header
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        "400":
          description: Validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /v1/transactions:
    get:
      tags:
        - Transactions
      summary: List transactions
      security:
        - bearerAuth: []
      parameters:
        - name: Watenga-Version
          in: header
          required: false
          schema:
            type: string
            example: 2026-01-01
          description: API version date header
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        "400":
          description: Validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /v1/transactions/{id}:
    get:
      tags:
        - Transactions
      summary: Retrieve a transaction
      security:
        - bearerAuth: []
      parameters:
        - name: Watenga-Version
          in: header
          required: false
          schema:
            type: string
            example: 2026-01-01
          description: API version date header
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        "400":
          description: Validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /v1/transactions/{id}/refund:
    post:
      tags:
        - Refunds
      summary: Refund a transaction
      security:
        - bearerAuth: []
      parameters:
        - name: Watenga-Version
          in: header
          required: false
          schema:
            type: string
            example: 2026-01-01
          description: API version date header
      responses:
        "201":
          description: Created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        "400":
          description: Validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /v1/transactions/{id}/mobile-status:
    get:
      tags:
        - Transactions
      summary: Poll mobile money status
      security:
        - bearerAuth: []
      parameters:
        - name: Watenga-Version
          in: header
          required: false
          schema:
            type: string
            example: 2026-01-01
          description: API version date header
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        "400":
          description: Validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /v1/payment-links:
    post:
      tags:
        - Payment Links
      summary: Create a payment link
      security:
        - bearerAuth: []
      parameters:
        - name: Watenga-Version
          in: header
          required: false
          schema:
            type: string
            example: 2026-01-01
          description: API version date header
      responses:
        "201":
          description: Created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        "400":
          description: Validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
    get:
      tags:
        - Payment Links
      summary: List payment links
      security:
        - bearerAuth: []
      parameters:
        - name: Watenga-Version
          in: header
          required: false
          schema:
            type: string
            example: 2026-01-01
          description: API version date header
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        "400":
          description: Validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /v1/payment-links/{id}:
    patch:
      tags:
        - Payment Links
      summary: Update a payment link
      security:
        - bearerAuth: []
      parameters:
        - name: Watenga-Version
          in: header
          required: false
          schema:
            type: string
            example: 2026-01-01
          description: API version date header
      responses:
        "201":
          description: Created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        "400":
          description: Validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
    delete:
      tags:
        - Payment Links
      summary: Deactivate a payment link
      security:
        - bearerAuth: []
      parameters:
        - name: Watenga-Version
          in: header
          required: false
          schema:
            type: string
            example: 2026-01-01
          description: API version date header
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        "400":
          description: Validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /v1/payouts/request:
    post:
      tags:
        - Payouts
      summary: Request a withdrawal
      security:
        - bearerAuth: []
      parameters:
        - name: Watenga-Version
          in: header
          required: false
          schema:
            type: string
            example: 2026-01-01
          description: API version date header
      responses:
        "201":
          description: Created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        "400":
          description: Validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /v1/payouts:
    get:
      tags:
        - Payouts
      summary: List payouts
      security:
        - bearerAuth: []
      parameters:
        - name: Watenga-Version
          in: header
          required: false
          schema:
            type: string
            example: 2026-01-01
          description: API version date header
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        "400":
          description: Validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /v1/invoices:
    get:
      tags:
        - Invoices
      summary: List invoices
      security:
        - bearerAuth: []
      parameters:
        - name: Watenga-Version
          in: header
          required: false
          schema:
            type: string
            example: 2026-01-01
          description: API version date header
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        "400":
          description: Validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
    post:
      tags:
        - Invoices
      summary: Create an invoice
      security:
        - bearerAuth: []
      parameters:
        - name: Watenga-Version
          in: header
          required: false
          schema:
            type: string
            example: 2026-01-01
          description: API version date header
      responses:
        "201":
          description: Created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        "400":
          description: Validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /v1/subscriptions:
    get:
      tags:
        - Subscriptions
      summary: List subscriptions
      security:
        - bearerAuth: []
      parameters:
        - name: Watenga-Version
          in: header
          required: false
          schema:
            type: string
            example: 2026-01-01
          description: API version date header
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        "400":
          description: Validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
    post:
      tags:
        - Subscriptions
      summary: Create a subscription
      security:
        - bearerAuth: []
      parameters:
        - name: Watenga-Version
          in: header
          required: false
          schema:
            type: string
            example: 2026-01-01
          description: API version date header
      responses:
        "201":
          description: Created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        "400":
          description: Validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /v1/payment_methods:
    post:
      tags:
        - Payment Methods
      summary: Vault a card-on-file
      description: Save a card as a reusable pm_… token from a registration_id minted
        by the Mobile SDK or hosted widget. Token-only — never a raw PAN.
      security:
        - bearerAuth: []
      parameters:
        - name: Watenga-Version
          in: header
          required: false
          schema:
            type: string
            example: 2026-01-01
          description: API version date header
      responses:
        "201":
          description: Created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        "400":
          description: Validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
    get:
      tags:
        - Payment Methods
      summary: List saved cards
      security:
        - bearerAuth: []
      parameters:
        - name: Watenga-Version
          in: header
          required: false
          schema:
            type: string
            example: 2026-01-01
          description: API version date header
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        "400":
          description: Validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /v1/payment_methods/{id}:
    get:
      tags:
        - Payment Methods
      summary: Retrieve a saved card
      security:
        - bearerAuth: []
      parameters:
        - name: Watenga-Version
          in: header
          required: false
          schema:
            type: string
            example: 2026-01-01
          description: API version date header
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        "400":
          description: Validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
    delete:
      tags:
        - Payment Methods
      summary: Delete a saved card
      security:
        - bearerAuth: []
      parameters:
        - name: Watenga-Version
          in: header
          required: false
          schema:
            type: string
            example: 2026-01-01
          description: API version date header
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        "400":
          description: Validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /v1/payment_methods/{id}/charge:
    post:
      tags:
        - Payment Methods
      summary: Charge a saved card (merchant-initiated)
      security:
        - bearerAuth: []
      parameters:
        - name: Watenga-Version
          in: header
          required: false
          schema:
            type: string
            example: 2026-01-01
          description: API version date header
      responses:
        "201":
          description: Created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        "400":
          description: Validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /v1/merchant/customers:
    get:
      tags:
        - Customers
      summary: List customers
      security:
        - bearerAuth: []
      parameters:
        - name: Watenga-Version
          in: header
          required: false
          schema:
            type: string
            example: 2026-01-01
          description: API version date header
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        "400":
          description: Validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
    post:
      tags:
        - Customers
      summary: Create a customer
      security:
        - bearerAuth: []
      parameters:
        - name: Watenga-Version
          in: header
          required: false
          schema:
            type: string
            example: 2026-01-01
          description: API version date header
      responses:
        "201":
          description: Created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        "400":
          description: Validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /v1/merchant/customers/{id}:
    get:
      tags:
        - Customers
      summary: Retrieve a customer
      security:
        - bearerAuth: []
      parameters:
        - name: Watenga-Version
          in: header
          required: false
          schema:
            type: string
            example: 2026-01-01
          description: API version date header
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        "400":
          description: Validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
    patch:
      tags:
        - Customers
      summary: Update a customer
      security:
        - bearerAuth: []
      parameters:
        - name: Watenga-Version
          in: header
          required: false
          schema:
            type: string
            example: 2026-01-01
          description: API version date header
      responses:
        "201":
          description: Created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        "400":
          description: Validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
    delete:
      tags:
        - Customers
      summary: Delete a customer
      security:
        - bearerAuth: []
      parameters:
        - name: Watenga-Version
          in: header
          required: false
          schema:
            type: string
            example: 2026-01-01
          description: API version date header
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        "400":
          description: Validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /v1/merchant/disputes:
    get:
      tags:
        - Disputes
      summary: List chargeback disputes
      security:
        - bearerAuth: []
      parameters:
        - name: Watenga-Version
          in: header
          required: false
          schema:
            type: string
            example: 2026-01-01
          description: API version date header
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        "400":
          description: Validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /v1/merchant/disputes/{id}:
    get:
      tags:
        - Disputes
      summary: Retrieve a dispute
      security:
        - bearerAuth: []
      parameters:
        - name: Watenga-Version
          in: header
          required: false
          schema:
            type: string
            example: 2026-01-01
          description: API version date header
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        "400":
          description: Validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /v1/merchant/disputes/{id}/evidence:
    post:
      tags:
        - Disputes
      summary: Submit dispute evidence
      security:
        - bearerAuth: []
      parameters:
        - name: Watenga-Version
          in: header
          required: false
          schema:
            type: string
            example: 2026-01-01
          description: API version date header
      responses:
        "201":
          description: Created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        "400":
          description: Validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /v1/merchant/bank-accounts:
    get:
      tags:
        - Bank Accounts
      summary: List bank accounts
      security:
        - bearerAuth: []
      parameters:
        - name: Watenga-Version
          in: header
          required: false
          schema:
            type: string
            example: 2026-01-01
          description: API version date header
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        "400":
          description: Validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
    post:
      tags:
        - Bank Accounts
      summary: Add a bank account
      security:
        - bearerAuth: []
      parameters:
        - name: Watenga-Version
          in: header
          required: false
          schema:
            type: string
            example: 2026-01-01
          description: API version date header
      responses:
        "201":
          description: Created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        "400":
          description: Validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /v1/transactions/stats:
    get:
      tags:
        - Transactions
      summary: Aggregate transaction statistics
      security:
        - bearerAuth: []
      parameters:
        - name: Watenga-Version
          in: header
          required: false
          schema:
            type: string
            example: 2026-01-01
          description: API version date header
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        "400":
          description: Validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /v1/transactions/export:
    get:
      tags:
        - Transactions
      summary: Export transactions CSV
      security:
        - bearerAuth: []
      parameters:
        - name: Watenga-Version
          in: header
          required: false
          schema:
            type: string
            example: 2026-01-01
          description: API version date header
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        "400":
          description: Validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /v1/merchant/splits:
    get:
      tags:
        - Splits
      summary: List transaction splits
      security:
        - bearerAuth: []
      parameters:
        - name: Watenga-Version
          in: header
          required: false
          schema:
            type: string
            example: 2026-01-01
          description: API version date header
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        "400":
          description: Validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
    post:
      tags:
        - Splits
      summary: Create a transaction split
      security:
        - bearerAuth: []
      parameters:
        - name: Watenga-Version
          in: header
          required: false
          schema:
            type: string
            example: 2026-01-01
          description: API version date header
      responses:
        "201":
          description: Created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        "400":
          description: Validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /v1/merchant/capital:
    get:
      tags:
        - Capital
      summary: Capital offers and advances
      security:
        - bearerAuth: []
      parameters:
        - name: Watenga-Version
          in: header
          required: false
          schema:
            type: string
            example: 2026-01-01
          description: API version date header
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        "400":
          description: Validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /v1/merchant/virtual-terminal/sessions:
    post:
      tags:
        - Virtual Terminal
      summary: Create virtual terminal session
      security:
        - bearerAuth: []
      parameters:
        - name: Watenga-Version
          in: header
          required: false
          schema:
            type: string
            example: 2026-01-01
          description: API version date header
      responses:
        "201":
          description: Created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        "400":
          description: Validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /v1/terminal/sessions:
    post:
      tags:
        - Terminals
      summary: Create POS terminal session token
      security:
        - bearerAuth: []
      parameters:
        - name: Watenga-Version
          in: header
          required: false
          schema:
            type: string
            example: 2026-01-01
          description: API version date header
      responses:
        "201":
          description: Created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        "400":
          description: Validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /v1/terminal/firmware-allowlist:
    get:
      tags:
        - Terminals
      summary: Signed firmware allowlist for terminal SDK
      security:
        - bearerAuth: []
      parameters:
        - name: Watenga-Version
          in: header
          required: false
          schema:
            type: string
            example: 2026-01-01
          description: API version date header
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        "400":
          description: Validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /v1/merchant/platform-billing/plans:
    get:
      tags:
        - Platform Billing
      summary: List platform billing plans
      security:
        - bearerAuth: []
      parameters:
        - name: Watenga-Version
          in: header
          required: false
          schema:
            type: string
            example: 2026-01-01
          description: API version date header
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        "400":
          description: Validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /v1/merchant/platform-billing/subscription:
    get:
      tags:
        - Platform Billing
      summary: Current plan, usage, and balance
      security:
        - bearerAuth: []
      parameters:
        - name: Watenga-Version
          in: header
          required: false
          schema:
            type: string
            example: 2026-01-01
          description: API version date header
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        "400":
          description: Validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
    post:
      tags:
        - Platform Billing
      summary: Schedule a platform plan change
      security:
        - bearerAuth: []
      parameters:
        - name: Watenga-Version
          in: header
          required: false
          schema:
            type: string
            example: 2026-01-01
          description: API version date header
      responses:
        "201":
          description: Created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        "400":
          description: Validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /v1/merchant/platform-billing/plan:
    get:
      tags:
        - Platform Billing
      summary: Legacy combined subscription and invoices
      security:
        - bearerAuth: []
      parameters:
        - name: Watenga-Version
          in: header
          required: false
          schema:
            type: string
            example: 2026-01-01
          description: API version date header
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        "400":
          description: Validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /v1/merchant/platform-billing/invoices:
    get:
      tags:
        - Platform Billing
      summary: List platform invoices
      security:
        - bearerAuth: []
      parameters:
        - name: Watenga-Version
          in: header
          required: false
          schema:
            type: string
            example: 2026-01-01
          description: API version date header
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        "400":
          description: Validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /v1/auth/login:
    post:
      tags:
        - Agent
      summary: Agent or merchant login
      description: Agents send phone + password; merchants send email + password.
      parameters:
        - name: Watenga-Version
          in: header
          required: false
          schema:
            type: string
            example: 2026-01-01
          description: API version date header
      responses:
        "201":
          description: Created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        "400":
          description: Validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /v1/agent/me:
    get:
      tags:
        - Agent
      summary: Agent profile and today summary
      security:
        - bearerAuth: []
      parameters:
        - name: Watenga-Version
          in: header
          required: false
          schema:
            type: string
            example: 2026-01-01
          description: API version date header
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        "400":
          description: Validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /v1/agent/verify-otp:
    post:
      tags:
        - Agent
      summary: Verify merchant cash-out OTP
      security:
        - bearerAuth: []
      parameters:
        - name: Watenga-Version
          in: header
          required: false
          schema:
            type: string
            example: 2026-01-01
          description: API version date header
      responses:
        "201":
          description: Created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        "400":
          description: Validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /v1/agent/complete-cashout:
    post:
      tags:
        - Agent
      summary: Complete agent cash-out
      security:
        - bearerAuth: []
      parameters:
        - name: Watenga-Version
          in: header
          required: false
          schema:
            type: string
            example: 2026-01-01
          description: API version date header
      responses:
        "201":
          description: Created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        "400":
          description: Validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /v1/agent/transactions:
    get:
      tags:
        - Agent
      summary: List agent cash-out transactions
      security:
        - bearerAuth: []
      parameters:
        - name: Watenga-Version
          in: header
          required: false
          schema:
            type: string
            example: 2026-01-01
          description: API version date header
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        "400":
          description: Validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /v1/agent/transactions/{id}:
    get:
      tags:
        - Agent
      summary: Retrieve agent cash-out transaction
      security:
        - bearerAuth: []
      parameters:
        - name: Watenga-Version
          in: header
          required: false
          schema:
            type: string
            example: 2026-01-01
          description: API version date header
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        "400":
          description: Validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /v1/cashout-qr/sessions/resolve:
    post:
      tags:
        - Agent
      summary: Resolve scanned cash-out QR
      security:
        - bearerAuth: []
      parameters:
        - name: Watenga-Version
          in: header
          required: false
          schema:
            type: string
            example: 2026-01-01
          description: API version date header
      responses:
        "201":
          description: Created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        "400":
          description: Validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Secret API key `sk_test_*` or `sk_live_*`
    adminJwt:
      type: http
      scheme: bearer
      description: Admin dashboard JWT access token
  schemas:
    SuccessResponse:
      type: object
      required:
        - success
        - data
      properties:
        success:
          type: boolean
          enum:
            - true
        data:
          type: object
    ErrorResponse:
      type: object
      required:
        - success
        - error
      properties:
        success:
          type: boolean
          enum:
            - false
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              example: VALIDATION_ERROR
            message:
              type: string
              example: Invalid request
    WebhookEvent:
      type: object
      required:
        - id
        - type
        - created
        - data
      properties:
        id:
          type: string
          example: evt_550e8400-e29b-41d4-a716-446655440000
        object:
          type: string
          example: event
        type:
          type: string
          description: Canonical webhook event id
          enum:
            - payment.capture.completed
            - split.settled
            - payment.capture.declined
            - payment.capture.pending
            - payment.capture.refunded
            - payment.capture.reversed
            - payment.capture.expired
            - payment.authorization.created
            - payment.authorization.voided
            - payment.refund.completed
            - payment.refund.failed
            - payment.refund.cancelled
            - payment.refund.pending
            - payment.refund.created
            - payment.order.created
            - payment.order.cancelled
            - payment.order.approved
            - payment.order.voided
            - payment.payout-item.succeeded
            - payment.payout-item.failed
            - payment.payout-item.blocked
            - payment.payout-item.held
            - payment.payout-item.returned
            - payment.payout-item.unclaimed
            - payment.payout-batch.success
            - payment.payout-batch.processing
            - payment.payout-batch.denied
            - invoicing.invoice.paid
            - invoicing.invoice.cancelled
            - invoicing.invoice.created
            - invoicing.invoice.refunded
            - invoicing.invoice.sent
            - invoicing.invoice.unpaid
            - invoicing.invoice.updated
            - invoicing.invoice.reminder-sent
            - billing.subscription.activated
            - billing.subscription.cancelled
            - billing.subscription.created
            - billing.subscription.expired
            - billing.subscription.payment-failed
            - billing.subscription.re-activated
            - billing.subscription.suspended
            - billing.subscription.updated
            - billing.plan.activated
            - billing.plan.created
            - billing.plan.deactivated
            - billing.plan.updated
            - customer.dispute.created
            - customer.dispute.updated
            - customer.dispute.resolved
        created:
          type: integer
          example: 1717200000
        data:
          type: object
      description: "Additional event types: risk.dispute.created,
        customer.payout.completed, customer.payout.failed,
        merchant.onboarding.completed, merchant.onboarding.submitted,
        merchant.onboarding.kyc-approved, merchant.onboarding.kyc-rejected,
        merchant.onboarding.document-requested,
        customer.managed-account.created,
        customer.managed-account.status-changed,
        customer.managed-account.risk-assessed,
        customer.managed-account.updated, vault.payment-token.created,
        vault.payment-token.deleted, vault.payment-token.updated,
        compliance.process.completed, compliance.process.failed,
        compliance.process.end-user-action-required,
        compliance.screening.completed, identity.consent.granted,
        identity.consent.revoked, reporting.report.available,
        agent.cash-out.completed, agent.cash-out.failed, agent.cash-out.held,
        agent.float.topped-up, agent.float.low, agent.float.depleted,
        agent.suspended, agent.re-activated, merchant.account.balance-updated,
        billing.invoice.payment-failed, billing.invoice.created,
        payment.capture.authorized, payment.capture.cancelled,
        merchant.settings.updated, customer.dispute.evidence-submitted,
        capital.offer_created, capital.disbursed, capital.repayment,
        capital.repaid"
security:
  - bearerAuth: []
