Visa Acceptance Payment Acceptance Workflow

naftiko: "1.0.0-alpha1"

info:
  label: "Visa Acceptance Payment Acceptance Workflow"
  description: >-
    Workflow capability for the complete payment acceptance lifecycle on the Visa Acceptance
    platform. Covers merchant payment processing (authorize, capture, refund, void),
    invoice-based payment collection, and pay-by-link generation for online merchants,
    ISVs, and AI agents.
  tags:
    - Credit Cards
    - E-Commerce
    - Fintech
    - Invoicing
    - Payment Links
    - Payments
    - Visa
  created: "2026-05-03"
  modified: "2026-05-03"

binds:
  - namespace: env
    keys:
      VISA_ACCEPTANCE_JWT_TOKEN: VISA_ACCEPTANCE_JWT_TOKEN

capability:
  consumes:
    - import: visa-acceptance-payments
      location: ./shared/visa-acceptance-payments.yaml

  exposes:
    - type: rest
      port: 8080
      namespace: payment-acceptance-api
      description: "Unified REST API for the Visa Acceptance payment lifecycle."
      resources:
        - path: /v1/payments
          name: payments
          description: "Payment authorization and sale"
          operations:
            - method: POST
              name: authorize-payment
              description: "Authorize a payment transaction"
              call: "visa-acceptance-payments.authorize-payment"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/payments/{paymentId}/captures
          name: payment-captures
          description: "Capture authorized payments"
          operations:
            - method: POST
              name: capture-payment
              description: "Complete a previously authorized payment"
              call: "visa-acceptance-payments.capture-payment"
              with:
                paymentId: "rest.paymentId"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/payments/{paymentId}/refunds
          name: payment-refunds
          description: "Refund captured payments"
          operations:
            - method: POST
              name: refund-payment
              description: "Refund a captured payment (partial or full)"
              call: "visa-acceptance-payments.refund-payment"
              with:
                paymentId: "rest.paymentId"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/payments/{paymentId}/voids
          name: payment-voids
          description: "Void payments before settlement"
          operations:
            - method: POST
              name: void-payment
              description: "Void a payment before it settles"
              call: "visa-acceptance-payments.void-payment"
              with:
                paymentId: "rest.paymentId"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/payments/{paymentId}/reversals
          name: payment-reversals
          description: "Reverse authorization holds"
          operations:
            - method: POST
              name: reverse-authorization
              description: "Release an authorization hold"
              call: "visa-acceptance-payments.reverse-authorization"
              with:
                paymentId: "rest.paymentId"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/invoices
          name: invoices
          description: "Invoice management"
          operations:
            - method: POST
              name: create-invoice
              description: "Create an invoice for a customer"
              call: "visa-acceptance-payments.create-invoice"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: GET
              name: list-invoices
              description: "List invoices"
              call: "visa-acceptance-payments.list-invoices"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/invoices/{invoiceId}
          name: invoice-by-id
          description: "Invoice access by ID"
          operations:
            - method: GET
              name: get-invoice
              description: "Get invoice details"
              call: "visa-acceptance-payments.get-invoice"
              with:
                invoiceId: "rest.invoiceId"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: PATCH
              name: update-invoice
              description: "Update a draft invoice"
              call: "visa-acceptance-payments.update-invoice"
              with:
                invoiceId: "rest.invoiceId"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/pay-by-links
          name: pay-by-links
          description: "Payment link management"
          operations:
            - method: POST
              name: create-pay-by-link
              description: "Generate a shareable payment link"
              call: "visa-acceptance-payments.create-pay-by-link"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: GET
              name: list-pay-by-links
              description: "List payment links"
              call: "visa-acceptance-payments.list-pay-by-links"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/pay-by-links/{linkId}
          name: pay-by-link-by-id
          description: "Payment link access by ID"
          operations:
            - method: GET
              name: get-pay-by-link
              description: "Get payment link details"
              call: "visa-acceptance-payments.get-pay-by-link"
              with:
                linkId: "rest.linkId"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: DELETE
              name: cancel-pay-by-link
              description: "Cancel a payment link"
              call: "visa-acceptance-payments.cancel-pay-by-link"
              with:
                linkId: "rest.linkId"
              outputParameters:
                - type: object
                  mapping: "$."

    - type: mcp
      port: 9090
      namespace: payment-acceptance-mcp
      transport: http
      description: "MCP server for AI-assisted payment acceptance and invoice management."
      tools:
        - name: authorize-payment
          description: "Authorize a payment to place a hold on customer funds"
          hints:
            readOnly: false
            idempotent: false
          call: "visa-acceptance-payments.authorize-payment"
          outputParameters:
            - type: object
              mapping: "$."

        - name: capture-payment
          description: "Complete a payment by capturing previously authorized funds"
          hints:
            readOnly: false
            idempotent: true
          call: "visa-acceptance-payments.capture-payment"
          with:
            paymentId: "tools.paymentId"
          outputParameters:
            - type: object
              mapping: "$."

        - name: refund-payment
          description: "Refund a customer for a captured payment (partial or full)"
          hints:
            readOnly: false
            idempotent: false
          call: "visa-acceptance-payments.refund-payment"
          with:
            paymentId: "tools.paymentId"
          outputParameters:
            - type: object
              mapping: "$."

        - name: void-payment
          description: "Cancel a payment before it settles to release funds back to the customer"
          hints:
            readOnly: false
            destructive: true
            idempotent: true
          call: "visa-acceptance-payments.void-payment"
          with:
            paymentId: "tools.paymentId"
          outputParameters:
            - type: object
              mapping: "$."

        - name: reverse-authorization
          description: "Release an authorization hold without completing the payment"
          hints:
            readOnly: false
            idempotent: true
          call: "visa-acceptance-payments.reverse-authorization"
          with:
            paymentId: "tools.paymentId"
          outputParameters:
            - type: object
              mapping: "$."

        - name: create-invoice
          description: "Create an invoice with line items and due date for a customer"
          hints:
            readOnly: false
            idempotent: false
          call: "visa-acceptance-payments.create-invoice"
          outputParameters:
            - type: object
              mapping: "$."

        - name: list-invoices
          description: "List invoices filtered by status (CREATED, SENT, PAID, etc.)"
          hints:
            readOnly: true
            idempotent: true
          call: "visa-acceptance-payments.list-invoices"
          outputParameters:
            - type: object
              mapping: "$."

        - name: get-invoice
          description: "Get the status and details of a specific invoice"
          hints:
            readOnly: true
            idempotent: true
          call: "visa-acceptance-payments.get-invoice"
          with:
            invoiceId: "tools.invoiceId"
          outputParameters:
            - type: object
              mapping: "$."

        - name: create-pay-by-link
          description: "Generate a shareable payment link to collect a payment"
          hints:
            readOnly: false
            idempotent: false
          call: "visa-acceptance-payments.create-pay-by-link"
          outputParameters:
            - type: object
              mapping: "$."

        - name: list-pay-by-links
          description: "List payment links filtered by status"
          hints:
            readOnly: true
            idempotent: true
          call: "visa-acceptance-payments.list-pay-by-links"
          outputParameters:
            - type: object
              mapping: "$."

        - name: cancel-pay-by-link
          description: "Cancel an active payment link so it can no longer accept payments"
          hints:
            readOnly: false
            destructive: true
            idempotent: true
          call: "visa-acceptance-payments.cancel-pay-by-link"
          with:
            linkId: "tools.linkId"
          outputParameters:
            - type: object
              mapping: "$."