VTex Payments Gateway API — Transaction Process

naftiko: 1.0.0-alpha2
info:
  label: VTex Payments Gateway API — Transaction Process
  description: 'VTex Payments Gateway API — Transaction Process. 9 operations. Lead operation: VTex 2.1 Send payments information
    public. Self-contained Naftiko capability covering one Vtex business surface.'
  tags:
  - Vtex
  - Transaction Process
  created: '2026-05-19'
  modified: '2026-05-19'
binds:
- namespace: env
  keys:
    VTEX_API_KEY: VTEX_API_KEY
capability:
  consumes:
  - type: http
    namespace: payments-gateway-transaction-process
    baseUri: https://{accountName}.vtexpayments.com.br
    description: VTex Payments Gateway API — Transaction Process business capability. Self-contained, no shared references.
    resources:
    - name: api-pub-transactions-transactionId-payments
      path: /api/pub/transactions/{transactionId}/payments
      operations:
      - name: 2sendpaymentspublic
        method: POST
        description: VTex 2.1 Send payments information public
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: orderId
          in: query
          type: string
          description: Order identification.
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
    - name: api-pvt-transactions
      path: /api/pvt/transactions
      operations:
      - name: 1createanewtransaction
        method: POST
        description: VTex 1. Start a new transaction
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
    - name: api-pvt-transactions-transactionId
      path: /api/pvt/transactions/{transactionId}
      operations:
      - name: transactiondetails
        method: GET
        description: VTex Get transaction details
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: api-pvt-transactions-transactionId-additional-data
      path: /api/pvt/transactions/{transactionId}/additional-data
      operations:
      - name: 3sendadditionaldata
        method: POST
        description: VTex 3. Send additional data
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
      - name: 31updateadditionaldata
        method: PATCH
        description: VTex 3.1 Update additional data (optional)
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
    - name: api-pvt-transactions-transactionId-authorization-request
      path: /api/pvt/transactions/{transactionId}/authorization-request
      operations:
      - name: 4doauthorization
        method: POST
        description: VTex 4. Authorize new transaction
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
    - name: api-pvt-transactions-transactionId-payments
      path: /api/pvt/transactions/{transactionId}/payments
      operations:
      - name: 2sendpaymentswithsavedcreditcard
        method: POST
        description: VTex 2.2 Send payments with saved credit card
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
    - name: api-pvt-transactions-transactionId-payments-paymentId
      path: /api/pvt/transactions/{transactionId}/payments/{paymentId}
      operations:
      - name: paymentdetails
        method: GET
        description: VTex Get payment details
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: paymentId
          in: path
          type: string
          description: Payment identification.
          required: true
    - name: api-pvt-transactions-transactionId-settlements
      path: /api/pvt/transactions/{transactionId}/settlements
      operations:
      - name: transactionsettlementdetails
        method: GET
        description: VTex Get transaction settlement details
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    authentication:
      type: apikey
      key: X-VTEX-API-AppKey
      value: '{{env.VTEX_API_KEY}}'
      placement: header
  exposes:
  - type: rest
    namespace: payments-gateway-transaction-process-rest
    port: 8080
    description: REST adapter for VTex Payments Gateway API — Transaction Process. One Spectral-compliant resource per consumed
      operation, prefixed with /v1.
    resources:
    - path: /v1/api/pub/transactions/{transactionid}/payments
      name: api-pub-transactions-transactionid-payments
      description: REST surface for api-pub-transactions-transactionId-payments.
      operations:
      - method: POST
        name: 2sendpaymentspublic
        description: VTex 2.1 Send payments information public
        call: payments-gateway-transaction-process.2sendpaymentspublic
        with:
          orderId: rest.orderId
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/pvt/transactions
      name: api-pvt-transactions
      description: REST surface for api-pvt-transactions.
      operations:
      - method: POST
        name: 1createanewtransaction
        description: VTex 1. Start a new transaction
        call: payments-gateway-transaction-process.1createanewtransaction
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/pvt/transactions/{transactionid}
      name: api-pvt-transactions-transactionid
      description: REST surface for api-pvt-transactions-transactionId.
      operations:
      - method: GET
        name: transactiondetails
        description: VTex Get transaction details
        call: payments-gateway-transaction-process.transactiondetails
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/pvt/transactions/{transactionid}/additional-data
      name: api-pvt-transactions-transactionid-additional-data
      description: REST surface for api-pvt-transactions-transactionId-additional-data.
      operations:
      - method: POST
        name: 3sendadditionaldata
        description: VTex 3. Send additional data
        call: payments-gateway-transaction-process.3sendadditionaldata
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
      - method: PATCH
        name: 31updateadditionaldata
        description: VTex 3.1 Update additional data (optional)
        call: payments-gateway-transaction-process.31updateadditionaldata
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/pvt/transactions/{transactionid}/authorization-request
      name: api-pvt-transactions-transactionid-authorization-request
      description: REST surface for api-pvt-transactions-transactionId-authorization-request.
      operations:
      - method: POST
        name: 4doauthorization
        description: VTex 4. Authorize new transaction
        call: payments-gateway-transaction-process.4doauthorization
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/pvt/transactions/{transactionid}/payments
      name: api-pvt-transactions-transactionid-payments
      description: REST surface for api-pvt-transactions-transactionId-payments.
      operations:
      - method: POST
        name: 2sendpaymentswithsavedcreditcard
        description: VTex 2.2 Send payments with saved credit card
        call: payments-gateway-transaction-process.2sendpaymentswithsavedcreditcard
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/pvt/transactions/{transactionid}/payments/{paymentid}
      name: api-pvt-transactions-transactionid-payments-paymentid
      description: REST surface for api-pvt-transactions-transactionId-payments-paymentId.
      operations:
      - method: GET
        name: paymentdetails
        description: VTex Get payment details
        call: payments-gateway-transaction-process.paymentdetails
        with:
          paymentId: rest.paymentId
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/pvt/transactions/{transactionid}/settlements
      name: api-pvt-transactions-transactionid-settlements
      description: REST surface for api-pvt-transactions-transactionId-settlements.
      operations:
      - method: GET
        name: transactionsettlementdetails
        description: VTex Get transaction settlement details
        call: payments-gateway-transaction-process.transactionsettlementdetails
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    namespace: payments-gateway-transaction-process-mcp
    port: 9090
    transport: http
    description: MCP adapter for VTex Payments Gateway API — Transaction Process. One tool per consumed operation, routed
      inline through this capability's consumes block.
    tools:
    - name: vtex-2-1-send-payments-information
      description: VTex 2.1 Send payments information public
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: payments-gateway-transaction-process.2sendpaymentspublic
      with:
        orderId: tools.orderId
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: vtex-1-start-new-transaction
      description: VTex 1. Start a new transaction
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: payments-gateway-transaction-process.1createanewtransaction
      with:
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: vtex-get-transaction-details
      description: VTex Get transaction details
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: payments-gateway-transaction-process.transactiondetails
      outputParameters:
      - type: object
        mapping: $.
    - name: vtex-3-send-additional-data
      description: VTex 3. Send additional data
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: payments-gateway-transaction-process.3sendadditionaldata
      with:
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: vtex-3-1-update-additional-data
      description: VTex 3.1 Update additional data (optional)
      hints:
        readOnly: false
        destructive: false
        idempotent: true
      call: payments-gateway-transaction-process.31updateadditionaldata
      with:
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: vtex-4-authorize-new-transaction
      description: VTex 4. Authorize new transaction
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: payments-gateway-transaction-process.4doauthorization
      with:
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: vtex-2-2-send-payments-saved
      description: VTex 2.2 Send payments with saved credit card
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: payments-gateway-transaction-process.2sendpaymentswithsavedcreditcard
      with:
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: vtex-get-payment-details
      description: VTex Get payment details
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: payments-gateway-transaction-process.paymentdetails
      with:
        paymentId: tools.paymentId
      outputParameters:
      - type: object
        mapping: $.
    - name: vtex-get-transaction-settlement-details
      description: VTex Get transaction settlement details
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: payments-gateway-transaction-process.transactionsettlementdetails
      outputParameters:
      - type: object
        mapping: $.