# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for stax-api Terminal API
  version: 1.0.0
extends: openapi/stax-terminal-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: 13
- target: $.paths['/terminal/charge/queue'].post
  update:
    x-apievangelist-phrasing:
      intent: Queue a card-present sale on a terminal
      effect: write
      questions:
      - Can I stage a terminal sale while the device is busy with another customer?
      - Is there a way to line up several card-present charges on one register during a rush?
      instructions:
      - text: Queue a {total} card-present sale on register {register}.
        slots:
          total: requestBody.total
          register: requestBody.register
      - text: Stage a queued {total} terminal sale on register {register} for invoice {invoiceId}.
        slots:
          total: requestBody.total
          register: requestBody.register
          invoiceId: requestBody.invoiceId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/terminal/charge'].post
  update:
    x-apievangelist-phrasing:
      intent: Run a card-present sale on a terminal now
      effect: write
      questions:
      - How do I take an in-person card payment on a paired terminal?
      - Can the terminal prompt the customer for a tip during an immediate sale?
      - Why does a terminal charge first come back as waiting, and how do I get the final result?
      instructions:
      - text: Charge {total} on terminal register {register} right now.
        slots:
          total: requestBody.total
          register: requestBody.register
      - text: 'Start an immediate {total} sale on register {register} with a tip prompt: {promptTipInput}.'
        slots:
          total: requestBody.total
          register: requestBody.register
          promptTipInput: requestBody.promptTipInput
      - text: 'Run a {total} in-person sale on register {register} for customer {customerId} and print a receipt: {printReceipt}.'
        slots:
          total: requestBody.total
          register: requestBody.register
          customerId: requestBody.customerId
          printReceipt: requestBody.printReceipt
      method: generated
      generated: '2026-09-26'
- target: $.paths['/terminal/credit'].post
  update:
    x-apievangelist-phrasing:
      intent: Give a standalone credit on a terminal
      effect: write
      questions:
      - Can I return money to a customer at the terminal without an original sale?
      - Does a general credit on the terminal work if my gateway does not support it?
      instructions:
      - text: Issue a standalone {total} credit on register {register}.
        slots:
          total: requestBody.total
          register: requestBody.register
      - text: Give customer {customerId} a general credit of {total} at register {register}.
        slots:
          customerId: requestBody.customerId
          total: requestBody.total
          register: requestBody.register
      method: generated
      generated: '2026-09-26'
- target: $.paths['/terminal/register'].get
  update:
    x-apievangelist-phrasing:
      intent: List terminal devices
      effect: read
      questions:
      - Which Wi-Fi card terminals are connected to my merchant account?
      - What register IDs can I send in-person payments to?
      instructions:
      - text: List all my terminal devices.
      - text: Show the registers paired with my account.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/terminal/{registerId}/status/{transactionId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Check a terminal transaction's status
      effect: read
      questions:
      - Did the customer finish paying on the terminal yet?
      - Can I poll the live status of a card-present transaction I started?
      instructions:
      - text: Check status of transaction {transactionId} on register {registerId}.
        slots:
          transactionId: path.transactionId
          registerId: path.registerId
      - text: Poll register {registerId} for the result of terminal transaction {transactionId}.
        slots:
          registerId: path.registerId
          transactionId: path.transactionId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/terminal/print'].post
  update:
    x-apievangelist-phrasing:
      intent: Print a custom message on a terminal
      effect: write
      questions:
      - Can I print a custom note or receipt add-on from the card terminal's printer?
      - Is it possible to print multiple lines of text on a register?
      instructions:
      - text: Print {message} on register {register}.
        slots:
          message: requestBody.message
          register: requestBody.register
      - text: 'Send this receipt supplement to the printer on register {register}: {message}.'
        slots:
          register: requestBody.register
          message: requestBody.message
      method: generated
      generated: '2026-09-26'
- target: $.paths['/terminal/promptChoice'].post
  update:
    x-apievangelist-phrasing:
      intent: Prompt a multiple-choice question on a terminal
      effect: write
      questions:
      - Can I show the customer a list of options to pick from on the terminal screen?
      - Is it possible to put a title above a choice prompt on the device?
      instructions:
      - text: Show choices {choices} on register {register}.
        slots:
          choices: requestBody.choices
          register: requestBody.register
      - text: Ask the customer on register {register} to pick one of {choices} under the title {title}.
        slots:
          register: requestBody.register
          choices: requestBody.choices
          title: requestBody.title
      method: generated
      generated: '2026-09-26'
- target: $.paths['/terminal/promptInput'].post
  update:
    x-apievangelist-phrasing:
      intent: Prompt for free-text input on a terminal
      effect: write
      questions:
      - Can the terminal ask for a table number or PO reference typed in by the customer?
      - Is it possible to collect free-form text on the card reader screen?
      instructions:
      - text: Prompt for text input on register {register}.
        slots:
          register: requestBody.register
      - text: Ask for free-form entry titled {title} on register {register}.
        slots:
          title: requestBody.title
          register: requestBody.register
      method: generated
      generated: '2026-09-26'
- target: $.paths['/terminal/prompt/signature'].post
  update:
    x-apievangelist-phrasing:
      intent: Capture a signature on a terminal
      effect: write
      questions:
      - Can I collect a customer's signature on the card terminal?
      - When would a terminal need to capture a digital signature for a sale?
      instructions:
      - text: Capture a signature on register {register}.
        slots:
          register: requestBody.register
      - text: Ask the customer to sign on the screen of register {register}.
        slots:
          register: requestBody.register
      method: generated
      generated: '2026-09-26'
- target: $.paths['/terminal/refund'].post
  update:
    x-apievangelist-phrasing:
      intent: Refund a sale by re-presenting the card
      effect: destructive
      questions:
      - Can I refund an in-person sale by having the customer tap or insert their card again?
      - What do I need to do a card-present refund of a prior transaction?
      instructions:
      - text: Refund {total} of transaction {transactionId} with the card present on register {register}.
        slots:
          total: requestBody.total
          transactionId: requestBody.transactionId
          register: requestBody.register
      - text: Run a card-present refund for sale {transactionId} of {total} at register {register}.
        slots:
          transactionId: requestBody.transactionId
          total: requestBody.total
          register: requestBody.register
      method: generated
      generated: '2026-09-26'
- target: $.paths['/terminal/tokenize'].post
  update:
    x-apievangelist-phrasing:
      intent: Save a card from the terminal to a customer
      effect: write
      questions:
      - Can I read a card on the terminal and store it for future online charges?
      - Is it possible to attach a card swiped at the counter to a customer profile?
      instructions:
      - text: Tokenize a card on register {register} for customer {customerId} with tokenize {tokenize}.
        slots:
          register: requestBody.register
          customerId: requestBody.customerId
          tokenize: requestBody.tokenize
      - text: Read and save a card at register {register} to customer {customerId}, tokenize set to {tokenize}.
        slots:
          register: requestBody.register
          customerId: requestBody.customerId
          tokenize: requestBody.tokenize
      method: generated
      generated: '2026-09-26'
- target: $.paths['/terminal/void-or-refund'].post
  update:
    x-apievangelist-phrasing:
      intent: Void a terminal sale or refund it if batched
      effect: destructive
      questions:
      - Can I reverse an in-person sale without knowing whether it has batched yet?
      - What happens to a terminal transaction that's past the open batch when I try to cancel it?
      instructions:
      - text: Void or refund terminal transaction {transactionId} for {total} on register {register}.
        slots:
          transactionId: requestBody.transactionId
          total: requestBody.total
          register: requestBody.register
      - text: Reverse card-present sale {transactionId} ({total}) at register {register}, voiding if still open.
        slots:
          transactionId: requestBody.transactionId
          total: requestBody.total
          register: requestBody.register
      method: generated
      generated: '2026-09-26'
- target: $.paths['/terminal/void'].post
  update:
    x-apievangelist-phrasing:
      intent: Void an unbatched terminal sale
      effect: destructive
      questions:
      - Can I cancel an in-person card sale before it settles in the batch?
      - Is a terminal void only possible while the transaction is still in the open batch?
      instructions:
      - text: Void the {total} open-batch terminal sale on register {register}.
        slots:
          total: requestBody.total
          register: requestBody.register
      - text: Void the unbatched {total} card-present charge for invoice {invoiceId} on register {register}.
        slots:
          total: requestBody.total
          invoiceId: requestBody.invoiceId
          register: requestBody.register
      method: generated
      generated: '2026-09-26'