naftiko: 1.0.0-alpha2
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-06'
binds:
- namespace: env
  keys:
    VTEX_APP_KEY: VTEX_APP_KEY
    VTEX_APP_TOKEN: VTEX_APP_TOKEN
capability:
  consumes:
  - type: http
    namespace: vtex-checkout
    baseUri: https://{accountName}.vtexcommercestable.com.br
    description: VTEX Checkout API for cart management and order placement.
    authentication:
      type: apikey
      key: X-VTEX-API-AppKey
      value: '{{VTEX_APP_KEY}}'
      placement: header
    resources:
    - name: cart
      path: /api/checkout/pub/orderForm
      description: Cart and order form management
      operations:
      - name: create-cart
        method: POST
        description: Create a New Cart
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: get-cart
        method: GET
        description: Get Cart by ID
        inputParameters:
        - name: orderFormId
          in: path
          type: string
          required: true
          description: Cart (order form) identifier
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: simulation
      path: /api/checkout/pub/orderForms/simulation
      description: Order simulation for price and availability checks
      operations:
      - name: simulate-order
        method: POST
        description: Order Simulation
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        body:
          type: json
          data:
            items: '{{tools.items}}'
            country: '{{tools.country}}'
            postalCode: '{{tools.postalCode}}'
  - type: http
    namespace: vtex-payments
    baseUri: https://{accountName}.vtexpayments.com.br
    description: VTEX Payments Gateway API for managing payment transactions and conditions.
    authentication:
      type: apikey
      key: X-VTEX-API-AppKey
      value: '{{VTEX_APP_KEY}}'
      placement: header
    resources:
    - name: transactions
      path: /api/pvt/transactions
      description: Payment transaction management
      operations:
      - name: list-transactions
        method: GET
        description: List Transactions
        inputParameters:
        - name: page
          in: query
          type: integer
          required: false
          description: Page number
        - name: size
          in: query
          type: integer
          required: false
          description: Page size
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: get-transaction
        method: GET
        description: Get Transaction by ID
        inputParameters:
        - name: transactionId
          in: path
          type: string
          required: true
          description: Transaction identifier
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: refunds
      path: /api/pvt/transactions/{transactionId}/refunds
      description: Payment refund management
      operations:
      - name: create-refund
        method: POST
        description: Create Refund
        inputParameters:
        - name: transactionId
          in: path
          type: string
          required: true
          description: Transaction identifier
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        body:
          type: json
          data:
            value: '{{tools.amount}}'
  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: $.