API Evangelist conversational phrasing for Punchh Payments API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Punchh Payments API
  version: 1.0.0
extends: openapi/punchh-payments-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-10-01'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 9
- target: $.paths['/api2/mobile/secure_tokens/{service}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a secure client token for a service
      effect: read
      questions:
      - How does the app get a secure token for gift card or online ordering services?
      - Which services can the secure client token be requested for?
      instructions:
      - text: Fetch a secure client token for the {service} service.
        slots:
          service: path.service
      - text: Get a {service} token so I can buy a gift card in the app.
        slots:
          service: path.service
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api2/mobile/payments/client_token'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a payment gateway client token
      effect: read
      questions:
      - Where does the app get a client token to start a card payment?
      - Can I request a client token for a particular payment gateway?
      instructions:
      - text: Get a payment client token for gateway {gateway}.
        slots:
          gateway: requestBody.payment_gateway_name
      - text: Request a checkout client token for app client {client}.
        slots:
          client: requestBody.client
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api2/mobile/payments'].post
  update:
    x-apievangelist-phrasing:
      intent: Record an in-app payment
      effect: write
      questions:
      - How does the app record a payment after the guest enters their card?
      - Can a payment be tied to a membership program?
      instructions:
      - text: Record a payment using nonce {nonce}.
        slots:
          nonce: requestBody.payment_method_nonce
      - text: Pay for membership program {program} with payment nonce {nonce}.
        slots:
          program: requestBody.membership_program_id
          nonce: requestBody.payment_method_nonce
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api2/mobile/iframe_payments/new'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a PAR Pay card entry page for a token
      effect: read
      questions:
      - How does a guest save a payment card to buy or reload gift cards?
      - What does the PAR Pay token page return to the app?
      instructions:
      - text: Open the PAR Pay card entry page for app client {client}.
        slots:
          client: requestBody.client
      - text: Generate a PAR Pay token form so I can add my card.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/pos/payments'].put
  update:
    x-apievangelist-phrasing:
      intent: Mark a POS payment's status
      effect: write
      questions:
      - How does the POS tell the loyalty platform a payment is complete?
      - Which statuses can a POS set on a payment?
      instructions:
      - text: Set payment {payment_reference_id} to status {status}.
        slots:
          payment_reference_id: requestBody.payment_reference_id
          status: requestBody.status
      - text: Mark the {payment_type} payment for {email} as {status}.
        slots:
          payment_type: requestBody.payment_type
          email: requestBody.email
          status: requestBody.status
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/pos/payments'].post
  update:
    x-apievangelist-phrasing:
      intent: Charge a payment at the POS via single scan
      effect: write
      questions:
      - How does the POS charge a guest who scanned a single scan code?
      - Which receipt details must the POS send to create a payment?
      instructions:
      - text: Charge {amount} {currency_code} using single scan code {single_scan_code}.
        slots:
          amount: requestBody.amount
          currency_code: requestBody.currency_code
          single_scan_code: requestBody.single_scan_code
      - text: Create a {payment_type} payment for transaction {transaction_no}.
        slots:
          payment_type: requestBody.payment_type
          transaction_no: requestBody.transaction_no
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/pos/payments'].delete
  update:
    x-apievangelist-phrasing:
      intent: Void or cancel a POS payment
      effect: destructive
      questions:
      - How do I cancel a payment request that hasn't settled yet?
      - Can I void a payment by its transaction number?
      instructions:
      - text: Void payment {payment_reference_id}.
        slots:
          payment_reference_id: requestBody.payment_reference_id
      - text: Cancel the payment on transaction {transaction_no}.
        slots:
          transaction_no: requestBody.transaction_no
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/pos/payments/status'].get
  update:
    x-apievangelist-phrasing:
      intent: Check a POS payment's status
      effect: read
      questions:
      - Did the guest's payment succeed, or was it cancelled?
      - What should the POS do next based on a payment's status?
      instructions:
      - text: Get the status of payment {payment_reference_id}.
        slots:
          payment_reference_id: requestBody.payment_reference_id
      - text: Check payments from {payment_date} for reference {payment_reference_id}.
        slots:
          payment_date: requestBody.payment_date
          payment_reference_id: requestBody.payment_reference_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/pos/payments/refund'].post
  update:
    x-apievangelist-phrasing:
      intent: Refund a processed POS payment
      effect: destructive
      questions:
      - How do I refund a guest after their payment was accepted?
      - What identifiers are required to refund a POS payment?
      instructions:
      - text: Refund {payment_type} payment {payment_reference_id} on transaction {transaction_no}.
        slots:
          payment_type: requestBody.payment_type
          payment_reference_id: requestBody.payment_reference_id
          transaction_no: requestBody.transaction_no
      - text: Give the guest their money back for payment {payment_reference_id}.
        slots:
          payment_reference_id: requestBody.payment_reference_id
      method: generated
      generated: '2026-10-01'