Shift4 Payment Processing

naftiko: 1.0.0-alpha2
info:
  label: Shift4 Payment Processing
  description: End-to-end payment processing on Shift4. Combines charges, refunds, checkout sessions, and disputes for e-commerce
    and merchant operations workflows.
  tags:
  - Shift4
  - Payments
  - Checkout
  - Refunds
  - Disputes
  - E-Commerce
  created: '2026-05-05'
  modified: '2026-05-06'
binds:
- namespace: env
  keys:
    SHIFT4_API_KEY: SHIFT4_API_KEY
capability:
  consumes:
  - type: http
    namespace: shift4-charges
    baseUri: https://api.shift4.com
    description: Shift4 Charges API for processing card and payment-method charges.
    authentication:
      type: basic
      username: '{{SHIFT4_API_KEY}}'
      password: ''
    resources:
    - name: charges
      path: /charges
      description: Charges collection.
      operations:
      - name: list-charges
        method: GET
        description: List charges.
        inputParameters:
        - name: limit
          in: query
          type: integer
          required: false
        - name: startingAfter
          in: query
          type: string
          required: false
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: create-charge
        method: POST
        description: Create a new charge.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        body:
          type: json
          data:
            amount: '{{tools.amount}}'
            currency: '{{tools.currency}}'
            card: '{{tools.card}}'
            description: '{{tools.description}}'
    - name: charge
      path: /charges/{charge}
      description: Individual charge resource.
      operations:
      - name: get-charge
        method: GET
        description: Retrieve a charge by ID.
        inputParameters:
        - name: charge
          in: path
          type: string
          required: true
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: update-charge
        method: POST
        description: Update a charge.
        inputParameters:
        - name: charge
          in: path
          type: string
          required: true
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: charge-capture
      path: /charges/{charge}/capture
      description: Capture an authorized charge.
      operations:
      - name: capture-charge
        method: POST
        description: Capture a previously authorized charge.
        inputParameters:
        - name: charge
          in: path
          type: string
          required: true
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
  - type: http
    namespace: shift4-refunds
    baseUri: https://api.shift4.com
    authentication:
      type: basic
      username: '{{SHIFT4_API_KEY}}'
      password: ''
    resources:
    - name: refunds
      path: /refunds
      operations:
      - name: list-refunds
        method: GET
        description: List refunds.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: create-refund
        method: POST
        description: Refund a charge.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        body:
          type: json
          data:
            chargeId: '{{tools.chargeId}}'
            amount: '{{tools.amount}}'
            reason: '{{tools.reason}}'
    - name: refund
      path: /refunds/{refund}
      operations:
      - name: get-refund
        method: GET
        description: Retrieve a refund by ID.
        inputParameters:
        - name: refund
          in: path
          type: string
          required: true
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
  - type: http
    namespace: shift4-checkout
    baseUri: https://api.shift4.com
    authentication:
      type: basic
      username: '{{SHIFT4_API_KEY}}'
      password: ''
    resources:
    - name: checkout-sessions
      path: /checkout/sessions
      operations:
      - name: create-checkout-session
        method: POST
        description: Create a checkout session.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: checkout-session
      path: /checkout/sessions/{session}
      operations:
      - name: get-checkout-session
        method: GET
        description: Retrieve a checkout session by ID.
        inputParameters:
        - name: session
          in: path
          type: string
          required: true
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: payment-links
      path: /payment-links
      operations:
      - name: create-payment-link
        method: POST
        description: Create a payment link.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: payment-link
      path: /payment-links/{link}
      operations:
      - name: get-payment-link
        method: GET
        description: Retrieve a payment link by ID.
        inputParameters:
        - name: link
          in: path
          type: string
          required: true
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
  - type: http
    namespace: shift4-disputes
    baseUri: https://api.shift4.com
    authentication:
      type: basic
      username: '{{SHIFT4_API_KEY}}'
      password: ''
    resources:
    - name: disputes
      path: /disputes
      operations:
      - name: list-disputes
        method: GET
        description: List disputes.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: dispute
      path: /disputes/{dispute}
      operations:
      - name: get-dispute
        method: GET
        description: Retrieve a dispute by ID.
        inputParameters:
        - name: dispute
          in: path
          type: string
          required: true
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: fraud-warnings
      path: /fraud-warnings
      operations:
      - name: list-fraud-warnings
        method: GET
        description: List fraud warnings.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
  exposes:
  - type: rest
    port: 8080
    namespace: shift4-payment-processing-api
    description: Unified REST surface for Shift4 payment workflows.
    resources:
    - path: /charges
      name: charges
      operations:
      - method: GET
        name: list-charges
        call: shift4-charges.list-charges
        outputParameters:
        - type: object
          mapping: $.
      - method: POST
        name: create-charge
        call: shift4-charges.create-charge
        outputParameters:
        - type: object
          mapping: $.
    - path: /charges/{charge}/capture
      name: charge-capture
      operations:
      - method: POST
        name: capture-charge
        call: shift4-charges.capture-charge
        with:
          charge: rest.charge
        outputParameters:
        - type: object
          mapping: $.
    - path: /refunds
      name: refunds
      operations:
      - method: POST
        name: create-refund
        call: shift4-refunds.create-refund
        outputParameters:
        - type: object
          mapping: $.
    - path: /checkout/sessions
      name: checkout-sessions
      operations:
      - method: POST
        name: create-checkout-session
        call: shift4-checkout.create-checkout-session
        outputParameters:
        - type: object
          mapping: $.
    - path: /disputes
      name: disputes
      operations:
      - method: GET
        name: list-disputes
        call: shift4-disputes.list-disputes
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    port: 9080
    namespace: shift4-payment-processing-mcp
    transport: http
    description: MCP surface for AI-assisted Shift4 payment workflows.
    tools:
    - name: create-charge
      description: Create a Shift4 charge against a card or token.
      hints:
        readOnly: false
        destructive: false
      call: shift4-charges.create-charge
      outputParameters:
      - type: object
        mapping: $.
    - name: capture-charge
      description: Capture a previously authorized Shift4 charge.
      hints:
        readOnly: false
        destructive: false
      call: shift4-charges.capture-charge
      with:
        charge: tools.charge
      outputParameters:
      - type: object
        mapping: $.
    - name: create-refund
      description: Refund a Shift4 charge.
      hints:
        readOnly: false
        destructive: false
      call: shift4-refunds.create-refund
      outputParameters:
      - type: object
        mapping: $.
    - name: create-checkout-session
      description: Create a Shift4 hosted checkout session.
      hints:
        readOnly: false
        destructive: false
      call: shift4-checkout.create-checkout-session
      outputParameters:
      - type: object
        mapping: $.
    - name: list-disputes
      description: List Shift4 disputes.
      hints:
        readOnly: true
      call: shift4-disputes.list-disputes
      outputParameters:
      - type: object
        mapping: $.