# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Hilt So Checkout API
  version: 1.0.0
extends: openapi/hilt-so-checkout-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: 12
- target: $.paths['/v1/pay/broadcast'].post
  update:
    x-apievangelist-phrasing:
      intent: Record a broadcast checkout transaction
      effect: write
      questions:
      - How do I tell the checkout that the buyer's transaction was broadcast on-chain?
      - Can I attach the payer wallet when recording a broadcast signature?
      instructions:
      - text: Record that payment {payment_id} was broadcast as transaction {tx_signature}.
        slots:
          payment_id: requestBody.payment_id
          tx_signature: requestBody.tx_signature
      - text: Log broadcast {tx_signature} for payment {payment_id} from wallet {payer_wallet}.
        slots:
          tx_signature: requestBody.tx_signature
          payment_id: requestBody.payment_id
          payer_wallet: requestBody.payer_wallet
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/pay/automatic-renew/setup'].post
  update:
    x-apievangelist-phrasing:
      intent: Set up automatic renewal for a payment
      effect: write
      questions:
      - Can a buyer turn on automatic renewal during checkout?
      - What starts the auto-renew setup for a membership payment?
      instructions:
      - text: Set up automatic renewal for payment {payment_id}.
        slots:
          payment_id: requestBody.payment_id
      - text: Enable auto-renew on checkout payment {payment_id}.
        slots:
          payment_id: requestBody.payment_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/pay/identity/start'].post
  update:
    x-apievangelist-phrasing:
      intent: Start a buyer identity handshake at checkout
      effect: write
      questions:
      - How does a buyer link their wallet to their customer identity before paying?
      - Can I bind a Telegram or Discord handle to a wallet during checkout?
      instructions:
      - text: Start an identity handshake on product {slug} for wallet {wallet_address} as {customer_reference_value}.
        slots:
          slug: requestBody.slug
          wallet_address: requestBody.wallet_address
          customer_reference_value: requestBody.customer_reference_value
      - text: Begin checkout identity verification for {customer_reference_value} using wallet {wallet_address} on {slug}.
        slots:
          customer_reference_value: requestBody.customer_reference_value
          wallet_address: requestBody.wallet_address
          slug: requestBody.slug
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/pay/identity/complete'].post
  update:
    x-apievangelist-phrasing:
      intent: Complete a buyer identity handshake
      effect: write
      questions:
      - What do I submit to finish the checkout identity handshake?
      - Where does the wallet's signed handshake message go to prove ownership?
      instructions:
      - text: Complete identity session {session_id} for wallet {wallet_address} with signature {signed_message_b64}.
        slots:
          session_id: requestBody.session_id
          wallet_address: requestBody.wallet_address
          signed_message_b64: requestBody.signed_message_b64
      - text: Finish the identity handshake {session_id} using the signed message.
        slots:
          session_id: requestBody.session_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/pay/phantom/connect/callback'].post
  update:
    x-apievangelist-phrasing:
      intent: Handle the Phantom mobile connect callback
      effect: write
      questions:
      - Where does Phantom mobile send its encrypted connect response during checkout?
      - How is the Phantom deeplink connect result tied to a payment?
      instructions:
      - text: Process the Phantom connect callback for payment {payment_id} with key {phantom_encryption_public_key}, nonce {nonce} and data {data}.
        slots:
          payment_id: requestBody.payment_id
          phantom_encryption_public_key: requestBody.phantom_encryption_public_key
          nonce: requestBody.nonce
          data: requestBody.data
      - text: Record Phantom's connect response for payment {payment_id}.
        slots:
          payment_id: requestBody.payment_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/pay/phantom/message-url'].post
  update:
    x-apievangelist-phrasing:
      intent: Build a Phantom sign-message deeplink for identity
      effect: write
      questions:
      - Can I get a Phantom mobile link that asks the buyer to sign the identity message?
      - What generates the deeplink for signing the checkout identity message in Phantom?
      instructions:
      - text: Build a Phantom identity sign-message link for payment {payment_id} and identity session {identity_session_id}.
        slots:
          payment_id: requestBody.payment_id
          identity_session_id: requestBody.identity_session_id
      - text: Create the Phantom message URL for payment {payment_id}.
        slots:
          payment_id: requestBody.payment_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/pay/phantom/renewal-message-url'].post
  update:
    x-apievangelist-phrasing:
      intent: Build a Phantom deeplink to sign auto-renew consent
      effect: write
      questions:
      - How does a mobile buyer sign the automatic renewal consent in Phantom?
      - Is there a deeplink for approving auto-renew from the Phantom app?
      instructions:
      - text: Build a Phantom renewal-consent link for payment {payment_id} with setup key {automatic_renew_setup_key}.
        slots:
          payment_id: requestBody.payment_id
          automatic_renew_setup_key: requestBody.automatic_renew_setup_key
      - text: Create the Phantom auto-renew message URL for payment {payment_id}.
        slots:
          payment_id: requestBody.payment_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/pay/phantom/message/callback'].post
  update:
    x-apievangelist-phrasing:
      intent: Handle Phantom's signed identity message callback
      effect: write
      questions:
      - Where does Phantom return the signed identity message after the buyer approves?
      - How is the encrypted identity signature from Phantom decrypted for a payment?
      instructions:
      - text: Process Phantom's identity signature callback for payment {payment_id}, session {identity_session_id}, nonce {nonce}, data {data}.
        slots:
          payment_id: requestBody.payment_id
          identity_session_id: requestBody.identity_session_id
          nonce: requestBody.nonce
          data: requestBody.data
      - text: Record the signed identity message from Phantom for payment {payment_id}.
        slots:
          payment_id: requestBody.payment_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/pay/phantom/renewal-message/callback'].post
  update:
    x-apievangelist-phrasing:
      intent: Handle Phantom's signed auto-renew consent callback
      effect: write
      questions:
      - Where does Phantom return the buyer's signed automatic renewal consent?
      - What records a renewal approval coming back from the Phantom app?
      instructions:
      - text: Process Phantom's renewal-consent callback for payment {payment_id}, setup key {automatic_renew_setup_key}, nonce {nonce}, data {data}.
        slots:
          payment_id: requestBody.payment_id
          automatic_renew_setup_key: requestBody.automatic_renew_setup_key
          nonce: requestBody.nonce
          data: requestBody.data
      - text: Save the signed auto-renew approval from Phantom for payment {payment_id}.
        slots:
          payment_id: requestBody.payment_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/pay/phantom/transaction-url'].post
  update:
    x-apievangelist-phrasing:
      intent: Build a Phantom deeplink to sign the payment transaction
      effect: write
      questions:
      - Can I send a mobile buyer a Phantom link to sign the payment transaction itself?
      - How do I hand a serialized Solana transaction to Phantom mobile for signing?
      instructions:
      - text: Build a Phantom sign-transaction link for payment {payment_id} using transaction {serialized_transaction_b58}.
        slots:
          payment_id: requestBody.payment_id
          serialized_transaction_b58: requestBody.serialized_transaction_b58
      - text: Create the Phantom transaction URL for payment {payment_id}.
        slots:
          payment_id: requestBody.payment_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/pay/phantom/transaction/callback'].post
  update:
    x-apievangelist-phrasing:
      intent: Handle Phantom's signed transaction callback
      effect: write
      questions:
      - Where does Phantom send the signed payment transaction back after approval?
      - What happens when the Phantom app returns the buyer's transaction result?
      instructions:
      - text: Process Phantom's transaction callback for payment {payment_id} with nonce {nonce} and data {data}.
        slots:
          payment_id: requestBody.payment_id
          nonce: requestBody.nonce
          data: requestBody.data
      - text: Record the signed transaction returned by Phantom for payment {payment_id}.
        slots:
          payment_id: requestBody.payment_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/pay/confirm'].post
  update:
    x-apievangelist-phrasing:
      intent: Confirm an on-chain checkout payment
      effect: write
      questions:
      - How do I confirm a buyer's Solana payment so they get access?
      - Can the confirmation also finalize an automatic renewal setup?
      instructions:
      - text: Confirm transaction {tx_signature} paid by wallet {payer_wallet}.
        slots:
          tx_signature: requestBody.tx_signature
          payer_wallet: requestBody.payer_wallet
      - text: Confirm payment {payment_id} with signature {tx_signature} from {payer_wallet}.
        slots:
          payment_id: requestBody.payment_id
          tx_signature: requestBody.tx_signature
          payer_wallet: requestBody.payer_wallet
      method: generated
      generated: '2026-09-26'