# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for PAY.JP Charges API
  version: 1.0.0
extends: openapi/payjp-charges-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: 8
- target: $.paths['/charges'].get
  update:
    x-apievangelist-phrasing:
      intent: List charges
      effect: read
      questions:
      - How do I see all the payments I've charged?
      - Can I page through my charges a few at a time?
      - Which charges came through most recently?
      instructions:
      - text: List my charges.
      - text: Show {limit} charges starting at offset {offset}.
        slots:
          limit: query.limit
          offset: query.offset
      method: generated
      generated: '2026-09-26'
- target: $.paths['/charges'].post
  update:
    x-apievangelist-phrasing:
      intent: Charge a card or customer
      effect: write
      questions:
      - How do I charge a customer's card in yen with PAY.JP?
      - Can I authorize a payment now and capture it later?
      - Is it possible to charge a saved customer instead of a one-time token?
      instructions:
      - text: Charge {amount} {currency} to card token {card}.
        slots:
          amount: requestBody.amount
          currency: requestBody.currency
          card: requestBody.card
      - text: Charge customer {customer} {amount} {currency} for {description}.
        slots:
          customer: requestBody.customer
          amount: requestBody.amount
          currency: requestBody.currency
          description: requestBody.description
      - text: Authorize {amount} {currency} on token {card} without capturing (capture {capture}).
        slots:
          amount: requestBody.amount
          currency: requestBody.currency
          card: requestBody.card
          capture: requestBody.capture
      method: generated
      generated: '2026-09-26'
- target: $.paths['/charges/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a charge
      effect: read
      questions:
      - How do I check the details of one charge?
      - Did a particular charge succeed or get refunded?
      instructions:
      - text: Show charge {id}.
        slots:
          id: path.id
      - text: Get the status of charge {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/charges/{id}'].post
  update:
    x-apievangelist-phrasing:
      intent: Edit a charge's description or metadata
      effect: write
      questions:
      - Can I change the description on a charge after it was created?
      - How do I add metadata to an existing charge?
      instructions:
      - text: Update the description of charge {id}.
        slots:
          id: path.id
      - text: Add metadata to existing charge {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/charges/{id}/refund'].post
  update:
    x-apievangelist-phrasing:
      intent: Refund a charge
      effect: destructive
      questions:
      - How do I refund a payment?
      - Can I refund only part of a charge instead of the whole amount?
      - Can I record a reason when I issue a refund?
      instructions:
      - text: Refund charge {id} in full.
        slots:
          id: path.id
      - text: Refund {amount} of charge {id}.
        slots:
          amount: requestBody.amount
          id: path.id
      - text: Refund charge {id} with reason {refund_reason}.
        slots:
          id: path.id
          refund_reason: requestBody.refund_reason
      method: generated
      generated: '2026-09-26'
- target: $.paths['/charges/{id}/capture'].post
  update:
    x-apievangelist-phrasing:
      intent: Capture an authorized charge
      effect: write
      questions:
      - How do I collect the money on a charge I only authorized?
      - What do I call to capture a held payment?
      instructions:
      - text: Capture authorized charge {id}.
        slots:
          id: path.id
      - text: Collect the funds on held charge {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/charges/{id}/reauth'].post
  update:
    x-apievangelist-phrasing:
      intent: Re-authorize an expiring charge
      effect: write
      questions:
      - My authorization hold is about to expire — can I extend it?
      - How do I renew an uncaptured charge's authorization?
      instructions:
      - text: Re-authorize charge {id} before its hold expires.
        slots:
          id: path.id
      - text: Renew the authorization on uncaptured charge {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/charges/{id}/tds_finish'].post
  update:
    x-apievangelist-phrasing:
      intent: Finish 3D Secure authentication for a charge
      effect: write
      questions:
      - After the cardholder passes 3D Secure, how do I complete the charge that was waiting on it?
      - What call finalizes a charge once its 3D Secure challenge is done?
      instructions:
      - text: Finish the 3D Secure flow for charge {id}.
        slots:
          id: path.id
      - text: Complete 3D Secure on charge {id} so the payment can proceed.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'