Remitian Tax Payment Automation

naftiko: "1.0.0-alpha1"

info:
  label: Remitian Tax Payment Automation
  description: >-
    Workflow capability for embedding automated tax payment processing into
    tax software and accounting platforms. Combines payment lifecycle management
    (initiation, validation, confirmation), jurisdiction lookup, account
    management, audit logging, and webhook configuration into a single
    integration. Used by tax software providers, accounting firms, and ERP
    integrators to replace manual government portal logins with automated
    payment infrastructure.
  tags:
    - Remitian
    - Tax
    - Payments
    - Fintech
    - Accounting
    - Embedded Payments
    - Automation
  created: "2026-05-02"
  modified: "2026-05-02"

binds:
  - namespace: env
    keys:
      REMITIAN_API_KEY: REMITIAN_API_KEY

capability:
  consumes:
    - import: remitian-tax
      location: ./shared/tax-payment.yaml

  exposes:
    - type: rest
      port: 8080
      namespace: remitian-automation-api
      description: "Unified REST API for embedded tax payment automation."
      resources:
        - path: /v1/payments
          name: payments
          description: Tax payment lifecycle management
          operations:
            - method: GET
              name: list-payments
              description: List tax payments with filtering
              call: "remitian-tax.list-payments"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: POST
              name: initiate-payment
              description: Initiate a new tax payment
              call: "remitian-tax.initiate-payment"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/payments/{paymentId}
          name: payment
          description: Individual tax payment
          operations:
            - method: GET
              name: get-payment
              description: Get full payment details and status
              call: "remitian-tax.get-payment"
              with:
                paymentId: "rest.paymentId"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/payments/{paymentId}/validate
          name: payment-validation
          description: Payment validation
          operations:
            - method: POST
              name: validate-payment
              description: Validate payment against jurisdiction rules
              call: "remitian-tax.validate-payment"
              with:
                paymentId: "rest.paymentId"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/payments/{paymentId}/confirm
          name: payment-confirmation
          description: Payment confirmation
          operations:
            - method: POST
              name: confirm-payment
              description: Confirm payment for processing
              call: "remitian-tax.confirm-payment"
              with:
                paymentId: "rest.paymentId"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/jurisdictions
          name: jurisdictions
          description: Supported tax jurisdictions
          operations:
            - method: GET
              name: list-jurisdictions
              description: Browse supported tax jurisdictions
              call: "remitian-tax.list-jurisdictions"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/accounts
          name: accounts
          description: Client tax payment accounts
          operations:
            - method: GET
              name: list-accounts
              description: List registered client accounts
              call: "remitian-tax.list-accounts"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: POST
              name: create-account
              description: Register a new client account
              call: "remitian-tax.create-account"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/audit-logs
          name: audit-logs
          description: Bank-grade payment audit logs
          operations:
            - method: GET
              name: list-audit-logs
              description: List payment audit log entries
              call: "remitian-tax.list-audit-logs"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/webhooks
          name: webhooks
          description: Payment event webhook subscriptions
          operations:
            - method: GET
              name: list-webhooks
              description: List webhook subscriptions
              call: "remitian-tax.list-webhooks"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: POST
              name: create-webhook
              description: Create a webhook subscription
              call: "remitian-tax.create-webhook"
              outputParameters:
                - type: object
                  mapping: "$."

    - type: mcp
      port: 9090
      namespace: remitian-automation-mcp
      transport: http
      description: "MCP server for AI-assisted tax payment automation and reconciliation."
      tools:
        - name: list-payments
          description: List tax payments filtered by jurisdiction, status, and date range for reconciliation
          hints:
            readOnly: true
            openWorld: false
          call: "remitian-tax.list-payments"
          with:
            jurisdictionId: "tools.jurisdictionId"
            status: "tools.status"
            dateFrom: "tools.dateFrom"
            dateTo: "tools.dateTo"
          outputParameters:
            - type: object
              mapping: "$."
        - name: initiate-payment
          description: Initiate a tax payment to a jurisdiction from a client account
          hints:
            readOnly: false
            destructive: false
          call: "remitian-tax.initiate-payment"
          with:
            amount: "tools.amount"
            currency: "tools.currency"
            taxType: "tools.taxType"
            taxPeriod: "tools.taxPeriod"
            jurisdictionId: "tools.jurisdictionId"
            accountId: "tools.accountId"
            taxIdentifier: "tools.taxIdentifier"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-payment
          description: Get complete payment details including validation results and status
          hints:
            readOnly: true
            openWorld: false
          call: "remitian-tax.get-payment"
          with:
            paymentId: "tools.paymentId"
          outputParameters:
            - type: object
              mapping: "$."
        - name: validate-payment
          description: Run jurisdiction-specific validation to check payment readiness
          hints:
            readOnly: true
            openWorld: false
          call: "remitian-tax.validate-payment"
          with:
            paymentId: "tools.paymentId"
          outputParameters:
            - type: object
              mapping: "$."
        - name: confirm-payment
          description: Confirm a validated payment — irreversible, routes to tax authority
          hints:
            readOnly: false
            destructive: true
            idempotent: false
          call: "remitian-tax.confirm-payment"
          with:
            paymentId: "tools.paymentId"
          outputParameters:
            - type: object
              mapping: "$."
        - name: cancel-payment
          description: Cancel a payment that has not yet been confirmed or processed
          hints:
            readOnly: false
            destructive: true
            idempotent: true
          call: "remitian-tax.cancel-payment"
          with:
            paymentId: "tools.paymentId"
          outputParameters:
            - type: object
              mapping: "$."
        - name: list-jurisdictions
          description: Browse supported tax jurisdictions by country and type
          hints:
            readOnly: true
            openWorld: true
          call: "remitian-tax.list-jurisdictions"
          with:
            country: "tools.country"
            type: "tools.type"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-jurisdiction
          description: Get payment requirements, accepted tax types, and routing for a jurisdiction
          hints:
            readOnly: true
            openWorld: true
          call: "remitian-tax.get-jurisdiction"
          with:
            jurisdictionId: "tools.jurisdictionId"
          outputParameters:
            - type: object
              mapping: "$."
        - name: list-accounts
          description: List client accounts registered for tax payment processing
          hints:
            readOnly: true
            openWorld: false
          call: "remitian-tax.list-accounts"
          outputParameters:
            - type: object
              mapping: "$."
        - name: create-account
          description: Register a new client account with bank connection for tax payments
          hints:
            readOnly: false
            destructive: false
          call: "remitian-tax.create-account"
          with:
            name: "tools.name"
            email: "tools.email"
            taxIdentifier: "tools.taxIdentifier"
          outputParameters:
            - type: object
              mapping: "$."
        - name: list-audit-logs
          description: Retrieve bank-grade audit logs for payment compliance and reconciliation
          hints:
            readOnly: true
            openWorld: false
          call: "remitian-tax.list-audit-logs"
          with:
            paymentId: "tools.paymentId"
            accountId: "tools.accountId"
            eventType: "tools.eventType"
          outputParameters:
            - type: object
              mapping: "$."
        - name: list-webhooks
          description: List active webhook subscriptions for payment event notifications
          hints:
            readOnly: true
            openWorld: false
          call: "remitian-tax.list-webhooks"
          outputParameters:
            - type: object
              mapping: "$."
        - name: create-webhook
          description: Register a webhook endpoint to receive real-time payment status events
          hints:
            readOnly: false
            destructive: false
          call: "remitian-tax.create-webhook"
          with:
            url: "tools.url"
            events: "tools.events"
          outputParameters:
            - type: object
              mapping: "$."