# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Square Payments API
  version: 1.0.0
extends: openapi/square-payments-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-09-26'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 7
- target: $.paths['/v2/payments'].get
  update:
    x-apievangelist-phrasing:
      intent: List payments
      effect: read
      questions:
      - How do I see all card payments taken in a date range?
      - Can I filter payments by card brand or last four digits?
      - Is it possible to list only offline payments?
      instructions:
      - text: List payments between {begin_time} and {end_time}.
        slots:
          begin_time: query.begin_time
          end_time: query.end_time
      - text: Find payments at location {location_id} on a card ending in {last_4}.
        slots:
          location_id: query.location_id
          last_4: query.last_4
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/payments'].post
  update:
    x-apievangelist-phrasing:
      intent: Charge a card or record a payment
      effect: write
      questions:
      - Can I charge a card or gift card from my own app?
      - What's the way to record a cash or external payment taken outside Square?
      - Can I authorize a payment now and capture it later?
      instructions:
      - text: Charge {amount_money} to source {source_id}.
        slots:
          amount_money: requestBody.amount_money
          source_id: requestBody.source_id
      - text: Take a payment of {amount_money} from {source_id} for order {order_id}.
        slots:
          amount_money: requestBody.amount_money
          source_id: requestBody.source_id
          order_id: requestBody.order_id
      - text: Authorize {amount_money} on {source_id} without completing it, autocomplete {autocomplete}.
        slots:
          amount_money: requestBody.amount_money
          source_id: requestBody.source_id
          autocomplete: requestBody.autocomplete
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/payments/cancel'].post
  update:
    x-apievangelist-phrasing:
      intent: Void a payment by its idempotency key
      effect: destructive
      questions:
      - What should I do if I never got a response to a create payment request?
      - Can I void a payment when I only know the idempotency key I used?
      instructions:
      - text: Cancel the payment created with idempotency key {idempotency_key}.
        slots:
          idempotency_key: requestBody.idempotency_key
      - text: Void whatever payment used key {idempotency_key} after the timeout.
        slots:
          idempotency_key: requestBody.idempotency_key
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/payments/{payment_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a payment
      effect: read
      questions:
      - What is the status and card detail of a specific payment?
      - Can I look up one payment by its ID?
      instructions:
      - text: Get payment {payment_id}.
        slots:
          payment_id: path.payment_id
      - text: Show the details of payment {payment_id}.
        slots:
          payment_id: path.payment_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/payments/{payment_id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Adjust amount or tip on an approved payment
      effect: write
      questions:
      - Can I change the tip on a payment before it's captured?
      - Which payments can have their amount updated?
      instructions:
      - text: Update payment {payment_id} with {payment}.
        slots:
          payment_id: path.payment_id
          payment: requestBody.payment
      - text: Change the tip on approved payment {payment_id} per {payment} using key {idempotency_key}.
        slots:
          payment_id: path.payment_id
          payment: requestBody.payment
          idempotency_key: requestBody.idempotency_key
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/payments/{payment_id}/cancel'].post
  update:
    x-apievangelist-phrasing:
      intent: Void an approved payment
      effect: destructive
      questions:
      - How do I void an authorized payment that hasn't been captured?
      - Can I cancel a payment that is already completed?
      instructions:
      - text: Cancel payment {payment_id}.
        slots:
          payment_id: path.payment_id
      - text: Void the approved payment {payment_id}.
        slots:
          payment_id: path.payment_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/payments/{payment_id}/complete'].post
  update:
    x-apievangelist-phrasing:
      intent: Capture an approved payment
      effect: write
      questions:
      - How do I capture a delayed payment I authorized earlier?
      - When do I need to complete a payment manually?
      instructions:
      - text: Complete payment {payment_id}.
        slots:
          payment_id: path.payment_id
      - text: Capture approved payment {payment_id} at version {version_token}.
        slots:
          payment_id: path.payment_id
          version_token: requestBody.version_token
      method: generated
      generated: '2026-09-26'