Stripe Financial Operations

naftiko: "1.0.0-alpha1"

info:
  label: "Stripe Financial Operations"
  description: >-
    Unified capability for financial operations and treasury workflows. Combines Stripe Payouts,
    Refunds, Disputes, and Balance APIs to support payout management, refund processing, chargeback
    handling, and balance monitoring. Used by finance teams and payment operations engineers.
  tags:
    - Stripe
    - Payouts
    - Refunds
    - Disputes
    - Financial Operations
    - Treasury
  created: "2026-05-02"
  modified: "2026-05-02"

binds:
  - namespace: env
    keys:
      STRIPE_API_KEY: STRIPE_API_KEY

capability:
  consumes:
    - import: stripe-payouts
      location: ./shared/payouts.yaml
    - import: stripe-refunds
      location: ./shared/refunds.yaml
    - import: stripe-disputes
      location: ./shared/disputes.yaml

  exposes:
    - type: rest
      port: 8082
      namespace: stripe-financial-ops-api
      description: "Unified REST API for Stripe financial operations."
      resources:
        - path: /v1/payouts
          name: payouts
          description: "Payout management"
          operations:
            - method: GET
              name: list-payouts
              description: "List payouts"
              call: "stripe-payouts.list-payouts"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: POST
              name: create-payout
              description: "Create a payout"
              call: "stripe-payouts.create-payout"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/payouts/{payout}
          name: payout
          description: "Individual payout"
          operations:
            - method: GET
              name: get-payout
              description: "Get a payout"
              call: "stripe-payouts.get-payout"
              with:
                payout: "rest.payout"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/refunds
          name: refunds
          description: "Refund management"
          operations:
            - method: GET
              name: list-refunds
              description: "List refunds"
              call: "stripe-refunds.list-refunds"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: POST
              name: create-refund
              description: "Create a refund"
              call: "stripe-refunds.create-refund"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/disputes
          name: disputes
          description: "Dispute management"
          operations:
            - method: GET
              name: list-disputes
              description: "List disputes"
              call: "stripe-disputes.list-disputes"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/disputes/{dispute}
          name: dispute
          description: "Individual dispute"
          operations:
            - method: GET
              name: get-dispute
              description: "Get a dispute"
              call: "stripe-disputes.get-dispute"
              with:
                dispute: "rest.dispute"
              outputParameters:
                - type: object
                  mapping: "$."

    - type: mcp
      port: 9082
      namespace: stripe-financial-ops-mcp
      transport: http
      description: "MCP server for AI-assisted Stripe financial operations."
      tools:
        - name: list-payouts
          description: "List Stripe payouts to bank accounts"
          hints:
            readOnly: true
          call: "stripe-payouts.list-payouts"
          outputParameters:
            - type: object
              mapping: "$."
        - name: create-payout
          description: "Create a Stripe payout to a bank account"
          hints:
            readOnly: false
            destructive: false
          call: "stripe-payouts.create-payout"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-payout
          description: "Retrieve a Stripe payout by ID"
          hints:
            readOnly: true
          call: "stripe-payouts.get-payout"
          with:
            payout: "tools.payout"
          outputParameters:
            - type: object
              mapping: "$."
        - name: cancel-payout
          description: "Cancel a pending Stripe payout"
          hints:
            readOnly: false
            destructive: true
          call: "stripe-payouts.cancel-payout"
          with:
            payout: "tools.payout"
          outputParameters:
            - type: object
              mapping: "$."
        - name: reverse-payout
          description: "Reverse a completed Stripe payout"
          hints:
            readOnly: false
            destructive: true
          call: "stripe-payouts.reverse-payout"
          with:
            payout: "tools.payout"
          outputParameters:
            - type: object
              mapping: "$."
        - name: list-refunds
          description: "List Stripe refunds"
          hints:
            readOnly: true
          call: "stripe-refunds.list-refunds"
          outputParameters:
            - type: object
              mapping: "$."
        - name: create-refund
          description: "Issue a refund on a Stripe charge"
          hints:
            readOnly: false
            destructive: false
          call: "stripe-refunds.create-refund"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-refund
          description: "Retrieve a Stripe refund by ID"
          hints:
            readOnly: true
          call: "stripe-refunds.get-refund"
          with:
            refund: "tools.refund"
          outputParameters:
            - type: object
              mapping: "$."
        - name: list-disputes
          description: "List Stripe disputes (chargebacks)"
          hints:
            readOnly: true
          call: "stripe-disputes.list-disputes"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-dispute
          description: "Get details of a Stripe dispute"
          hints:
            readOnly: true
          call: "stripe-disputes.get-dispute"
          with:
            dispute: "tools.dispute"
          outputParameters:
            - type: object
              mapping: "$."
        - name: update-dispute
          description: "Submit evidence for a Stripe dispute to contest a chargeback"
          hints:
            readOnly: false
            destructive: false
          call: "stripe-disputes.update-dispute"
          with:
            dispute: "tools.dispute"
          outputParameters:
            - type: object
              mapping: "$."