VTEX Payment Processing

naftiko: "1.0.0-alpha1"

info:
  label: "VTEX Payment Processing"
  description: >-
    Workflow capability for VTEX financial and payment operations teams.
    Combines checkout, payments, and customer credit capabilities for finance teams,
    payment operations staff, and developers building payment integrations who need
    to manage transactions, process refunds, and monitor payment flows.
  tags:
    - Checkout
    - Commerce
    - Finance
    - Payments
    - Transactions
    - VTEX
  created: "2026-05-03"
  modified: "2026-05-03"

binds:
  - namespace: env
    keys:
      VTEX_APP_KEY: VTEX_APP_KEY
      VTEX_APP_TOKEN: VTEX_APP_TOKEN

capability:
  consumes:
    - import: vtex-checkout
      location: ./shared/checkout.yaml
    - import: vtex-payments
      location: ./shared/payments.yaml

  exposes:
    - type: rest
      port: 8082
      namespace: vtex-payment-processing-api
      description: "Unified REST API for VTEX payment processing and checkout management."
      resources:
        - path: /v1/carts
          name: carts
          description: "Shopping cart management"
          operations:
            - method: POST
              name: create-cart
              description: "Create a new shopping cart"
              call: "vtex-checkout.create-cart"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/carts/{orderFormId}
          name: cart
          description: "Single cart operations"
          operations:
            - method: GET
              name: get-cart
              description: "Get shopping cart by ID"
              call: "vtex-checkout.get-cart"
              with:
                orderFormId: "rest.orderFormId"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/order-simulation
          name: order-simulation
          description: "Order simulation"
          operations:
            - method: POST
              name: simulate-order
              description: "Simulate order for pricing and availability"
              call: "vtex-checkout.simulate-order"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/transactions
          name: transactions
          description: "Payment transaction management"
          operations:
            - method: GET
              name: list-transactions
              description: "List payment transactions"
              call: "vtex-payments.list-transactions"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/transactions/{transactionId}
          name: transaction
          description: "Single transaction operations"
          operations:
            - method: GET
              name: get-transaction
              description: "Get transaction by ID"
              call: "vtex-payments.get-transaction"
              with:
                transactionId: "rest.transactionId"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/transactions/{transactionId}/refunds
          name: refunds
          description: "Payment refunds"
          operations:
            - method: POST
              name: create-refund
              description: "Create a refund for a transaction"
              call: "vtex-payments.create-refund"
              with:
                transactionId: "rest.transactionId"
              outputParameters:
                - type: object
                  mapping: "$."

    - type: mcp
      port: 9092
      namespace: vtex-payment-processing-mcp
      transport: http
      description: "MCP server for AI-assisted VTEX payment processing and financial operations."
      tools:
        - name: create-cart
          description: "Create a new VTEX shopping cart for a customer"
          hints:
            readOnly: false
            destructive: false
          call: "vtex-checkout.create-cart"
          outputParameters:
            - type: object
              mapping: "$."

        - name: get-cart
          description: "Get current state of a VTEX shopping cart including items, prices, and shipping options"
          hints:
            readOnly: true
            idempotent: true
          call: "vtex-checkout.get-cart"
          with:
            orderFormId: "tools.orderFormId"
          outputParameters:
            - type: object
              mapping: "$."

        - name: simulate-order
          description: "Simulate a VTEX order to check real-time pricing, shipping costs, and item availability"
          hints:
            readOnly: true
            idempotent: false
          call: "vtex-checkout.simulate-order"
          outputParameters:
            - type: object
              mapping: "$."

        - name: list-transactions
          description: "List VTEX payment transactions with pagination"
          hints:
            readOnly: true
            idempotent: true
          call: "vtex-payments.list-transactions"
          outputParameters:
            - type: object
              mapping: "$."

        - name: get-transaction
          description: "Get full details of a VTEX payment transaction including status and amounts"
          hints:
            readOnly: true
            idempotent: true
          call: "vtex-payments.get-transaction"
          with:
            transactionId: "tools.transactionId"
          outputParameters:
            - type: object
              mapping: "$."

        - name: create-refund
          description: "Create a refund for a completed VTEX payment transaction"
          hints:
            readOnly: false
            destructive: false
            idempotent: false
          call: "vtex-payments.create-refund"
          with:
            transactionId: "tools.transactionId"
          outputParameters:
            - type: object
              mapping: "$."