Toast Orders API — Payments

naftiko: 1.0.0-alpha2
info:
  label: Toast Orders API — Payments
  description: 'Toast Orders API — Payments. 4 operations. Lead operation: Toast Post Payments. Self-contained Naftiko capability
    covering one Toast business surface.'
  tags:
  - Toast
  - Payments
  created: '2026-05-19'
  modified: '2026-05-19'
binds:
- namespace: env
  keys:
    TOAST_API_KEY: TOAST_API_KEY
capability:
  consumes:
  - type: http
    namespace: orders-payments
    baseUri: https://toast-api-server/orders/v2
    description: Toast Orders API — Payments business capability. Self-contained, no shared references.
    resources:
    - name: orders-orderGuid-checks-checkGuid-payments
      path: /orders/{orderGuid}/checks/{checkGuid}/payments
      operations:
      - name: orderscheckspaymentspost
        method: POST
        description: Toast Post Payments
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: orderGuid
          in: path
          type: string
          description: The Toast platform identifier of the order that you are
          required: true
        - name: checkGuid
          in: path
          type: string
          description: The Toast platform identifier of the check that you are
          required: true
        - name: body
          in: body
          type: array
          description: An array of JSON `Payment` objects containing information about the payments you are adding.
          required: true
    - name: orders-orderGuid-checks-checkGuid-payments-paymentGuid
      path: /orders/{orderGuid}/checks/{checkGuid}/payments/{paymentGuid}
      operations:
      - name: ordersorderguidcheckscheckguidpaymentspaymentguidpatch
        method: PATCH
        description: Toast Update a Tip Amount
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: orderGuid
          in: path
          type: string
          description: The Toast platform identifier of the order that you are
          required: true
        - name: checkGuid
          in: path
          type: string
          description: The Toast platform identifier of the check that you are
          required: true
        - name: paymentGuid
          in: path
          type: string
          description: The Toast platform identifier of the payment that you are
          required: true
        - name: body
          in: body
          type: string
          description: A JSON `Payment` object
          required: true
    - name: payments
      path: /payments
      operations:
      - name: paymentsget
        method: GET
        description: Toast Get Payment Identifiers
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: Toast-Restaurant-External-ID
          in: header
          type: string
          description: The GUID of the restaurant used as the context of the request.
          required: true
        - name: paidBusinessDate
          in: query
          type: string
          description: Returns a list of the payments that were made during
        - name: refundBusinessDate
          in: query
          type: string
          description: Returns a list of the payments that were refunded
        - name: voidBusinessDate
          in: query
          type: string
          description: Returns a list of the payments that were voided during
    - name: payments-guid
      path: /payments/{guid}
      operations:
      - name: paymentsguidget
        method: GET
        description: Toast Get a Payment
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: Toast-Restaurant-External-ID
          in: header
          type: string
          description: The GUID of the restaurant used as the context of the request.
          required: true
        - name: guid
          in: path
          type: string
          description: The GUID for the payment you want to return.
          required: true
  exposes:
  - type: rest
    namespace: orders-payments-rest
    port: 8080
    description: REST adapter for Toast Orders API — Payments. One Spectral-compliant resource per consumed operation, prefixed
      with /v1.
    resources:
    - path: /v1/orders/{orderguid}/checks/{checkguid}/payments
      name: orders-orderguid-checks-checkguid-payments
      description: REST surface for orders-orderGuid-checks-checkGuid-payments.
      operations:
      - method: POST
        name: orderscheckspaymentspost
        description: Toast Post Payments
        call: orders-payments.orderscheckspaymentspost
        with:
          orderGuid: rest.orderGuid
          checkGuid: rest.checkGuid
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/orders/{orderguid}/checks/{checkguid}/payments/{paymentguid}
      name: orders-orderguid-checks-checkguid-payments-paymentguid
      description: REST surface for orders-orderGuid-checks-checkGuid-payments-paymentGuid.
      operations:
      - method: PATCH
        name: ordersorderguidcheckscheckguidpaymentspaymentguidpatch
        description: Toast Update a Tip Amount
        call: orders-payments.ordersorderguidcheckscheckguidpaymentspaymentguidpatch
        with:
          orderGuid: rest.orderGuid
          checkGuid: rest.checkGuid
          paymentGuid: rest.paymentGuid
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/payments
      name: payments
      description: REST surface for payments.
      operations:
      - method: GET
        name: paymentsget
        description: Toast Get Payment Identifiers
        call: orders-payments.paymentsget
        with:
          Toast-Restaurant-External-ID: rest.Toast-Restaurant-External-ID
          paidBusinessDate: rest.paidBusinessDate
          refundBusinessDate: rest.refundBusinessDate
          voidBusinessDate: rest.voidBusinessDate
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/payments/{guid}
      name: payments-guid
      description: REST surface for payments-guid.
      operations:
      - method: GET
        name: paymentsguidget
        description: Toast Get a Payment
        call: orders-payments.paymentsguidget
        with:
          Toast-Restaurant-External-ID: rest.Toast-Restaurant-External-ID
          guid: rest.guid
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    namespace: orders-payments-mcp
    port: 9090
    transport: http
    description: MCP adapter for Toast Orders API — Payments. One tool per consumed operation, routed inline through this
      capability's consumes block.
    tools:
    - name: toast-post-payments
      description: Toast Post Payments
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: orders-payments.orderscheckspaymentspost
      with:
        orderGuid: tools.orderGuid
        checkGuid: tools.checkGuid
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: toast-update-tip-amount
      description: Toast Update a Tip Amount
      hints:
        readOnly: false
        destructive: false
        idempotent: true
      call: orders-payments.ordersorderguidcheckscheckguidpaymentspaymentguidpatch
      with:
        orderGuid: tools.orderGuid
        checkGuid: tools.checkGuid
        paymentGuid: tools.paymentGuid
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: toast-get-payment-identifiers
      description: Toast Get Payment Identifiers
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: orders-payments.paymentsget
      with:
        Toast-Restaurant-External-ID: tools.Toast-Restaurant-External-ID
        paidBusinessDate: tools.paidBusinessDate
        refundBusinessDate: tools.refundBusinessDate
        voidBusinessDate: tools.voidBusinessDate
      outputParameters:
      - type: object
        mapping: $.
    - name: toast-get-payment
      description: Toast Get a Payment
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: orders-payments.paymentsguidget
      with:
        Toast-Restaurant-External-ID: tools.Toast-Restaurant-External-ID
        guid: tools.guid
      outputParameters:
      - type: object
        mapping: $.