# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Methodfi Payments API
  version: 1.0.0
extends: openapi/methodfi-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: 8
- target: $.paths['/payments'].get
  update:
    x-apievangelist-phrasing:
      intent: List payments
      effect: read
      questions:
      - Can I list only the payments that failed?
      - How do I see every payment made from one account?
      - Which payments belong to a particular holder?
      instructions:
      - text: List payments with status {status}.
        slots:
          status: query.status
      - text: Show payments from source account {source} to destination {destination}.
        slots:
          source: query.source
          destination: query.destination
      - text: List payments for holder {holder} between {from_date} and {to_date}.
        slots:
          holder: query.holder_id
          from_date: query.from_date
          to_date: query.to_date
      method: generated
      generated: '2026-10-01'
- target: $.paths['/payments'].post
  update:
    x-apievangelist-phrasing:
      intent: Send a payment between accounts
      effect: write
      questions:
      - How do I move money from a source account to a destination account?
      - Can I do a dry run of a payment before moving money?
      instructions:
      - text: Pay {amount} from account {source} to account {destination} with description {description}.
        slots:
          amount: requestBody.amount
          source: requestBody.source
          destination: requestBody.destination
          description: requestBody.description
      - text: Dry-run a {amount} payment from {source} to {destination} described as {description}, dry_run {dry_run}.
        slots:
          amount: requestBody.amount
          source: requestBody.source
          destination: requestBody.destination
          description: requestBody.description
          dry_run: requestBody.dry_run
      method: generated
      generated: '2026-10-01'
- target: $.paths['/payments/{paymentId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a payment with expanded details
      effect: read
      questions:
      - Can I fetch a payment and expand its source and destination?
      - What does the versioned payment lookup return by paymentId?
      instructions:
      - text: Get payment {payment} with {expand} expanded.
        slots:
          payment: path.paymentId
          expand: query.expand
      - text: Retrieve payment {payment} on API version {version}.
        slots:
          payment: path.paymentId
          version: header.Method-Version
      method: generated
      generated: '2026-10-01'
- target: $.paths['/payments/{paymentId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Cancel a pending payment (versioned)
      effect: destructive
      questions:
      - How do I cancel a payment that hasn't been processed yet?
      - Can only pending payments be canceled on the current API version?
      instructions:
      - text: Cancel pending payment {payment} on API version {version}.
        slots:
          payment: path.paymentId
          version: header.Method-Version
      - text: Cancel payment {payment} using idempotency key {key}.
        slots:
          payment: path.paymentId
          key: header.Idempotency-Key
      method: generated
      generated: '2026-10-01'
- target: $.paths['/payments/{pmt_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a payment (legacy unversioned path)
      effect: read
      questions:
      - Is there an older payment lookup that takes pmt_id without a version header?
      - Can I still read a payment via the legacy pmt_id endpoint?
      instructions:
      - text: Look up payment {pmt_id} on the legacy unversioned endpoint.
        slots:
          pmt_id: path.pmt_id
      - text: Fetch payment {pmt_id} without sending a Method-Version header.
        slots:
          pmt_id: path.pmt_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/payments/{pmt_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Cancel a pending payment (legacy path)
      effect: destructive
      questions:
      - Can I cancel a pending payment through the older pmt_id endpoint?
      - Does the legacy delete-payment call work without a version header?
      instructions:
      - text: Cancel pending payment {pmt_id} on the legacy unversioned path.
        slots:
          pmt_id: path.pmt_id
      - text: Delete pending payment {pmt_id} without a Method-Version header.
        slots:
          pmt_id: path.pmt_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/payments/{pmt_id}/reversals'].get
  update:
    x-apievangelist-phrasing:
      intent: List reversals for a payment (legacy)
      effect: read
      questions:
      - Can I list a payment's reversals from the payments endpoints using pmt_id?
      - Where are the reversals for a payment on the older path?
      instructions:
      - text: List reversals for payment {pmt_id} on the legacy path.
        slots:
          pmt_id: path.pmt_id
      - text: Show reversals tied to payment {pmt_id}.
        slots:
          pmt_id: path.pmt_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/payments/{pmt_id}/reversals'].post
  update:
    x-apievangelist-phrasing:
      intent: Reverse funds for a failed payment
      effect: write
      questions:
      - How do I balance funds after a payment fails?
      - Can I create a reversal for an unsuccessful payment?
      instructions:
      - text: Create a reversal for unsuccessful payment {pmt_id}.
        slots:
          pmt_id: path.pmt_id
      - text: Rebalance the funds of failed payment {pmt_id}.
        slots:
          pmt_id: path.pmt_id
      method: generated
      generated: '2026-10-01'