​
Developer playbooks

These playbooks are the shortest path from “something looks wrong” to a concrete next action. They are public, merchant-safe playbooks for Hilt API and webhook workflows.

​
Protect an API endpoint with Hilt Pay API

Use this when an API, agent tool, AI route, dataset, or paid software feature should return 402 Payment Required until Hilt confirms access.

​
Goal

Serve paid work only after Hilt returns has_access: true.

​
Sequence

  1. create a Hilt Pay API app with POST /v1/access/apps
  2. create a product with POST /v1/access/products
  3. configure Solana USDC payout with PUT /v1/access/rail-settings/solana_usdc
  4. call POST /v1/access/entitlements/check before serving the resource
  5. if access is missing, call POST /v1/access/payment-sessions
  6. return HTTP 402 with the returned checkout_url or payment_requirement
  7. retry the entitlement check after payment succeeds
  8. process signed Hilt webhooks for longer-running state updates

​
Useful routes

POST /v1/access/apps
POST /v1/access/products
PUT  /v1/access/rail-settings/solana_usdc
POST /v1/access/entitlements/check
POST /v1/access/payment-sessions
POST /v1/access/webhooks

​
Good outcome

  • your product never trusts a client-side payment claim
  • the 402 body contains Hilt’s current handoff for that product
  • payment, receipt, entitlement, webhook, support, and audit state stay connected in Hilt

​
Create one-off and recurring Hilt Pay API products

Use this when a backend needs stable product setup instead of manually creating each checkout in the dashboard.

​
Goal

Create access products that match the business model your resource actually sells.

​
Sequence

  1. create or reuse an access app boundary
  2. create a one-off product with billing_model: "one_off" for fixed-period access
  3. create a recurring product with billing_model: "recurring" and renewal_mode: "solana_native_subscription" for automatic Solana USDC renewal
  4. set default_rail: "solana_usdc" and keep allowed_rails limited to rails Hilt says are available
  5. include live_mode_confirmed: true only when the workspace owner is ready for live sessions
  6. check setup readiness before real traffic
  7. use sandbox sessions to test entitlement, webhook, and receipt object shapes

​
Useful routes

POST /v1/access/apps
POST /v1/access/products
GET  /v1/access/products/available-rails
GET  /v1/access/setup/readiness
POST /v1/access/sandbox/payment-sessions
POST /v1/access/sandbox/payment-sessions/{sandbox_session_id}/confirm

​
Good outcome

  • one-off products create a paid access period after successful payment
  • recurring products use native Solana subscription setup and extend access after successful collections
  • your UI shows only the payment options returned by Hilt for that product and account

​
1. Launch a webhook endpoint safely

Use this when a backend is moving from polling-first integration to native Hilt events.

​
Goal

Receive signed events for payments, receipts, memberships, delivery failures, and support changes without guessing whether the consumer is really ready.

​
Sequence

  1. create the webhook endpoint in the dashboard or with POST /v1/webhooks/endpoints
  2. subscribe only to the event types you are ready to process
  3. if the consumer is product-specific, filter the endpoint to the relevant product ids
  4. send a signed test event
  5. verify the signature against the raw body
  6. make sure your consumer is idempotent on event.id
  7. after sandbox validation, optionally complete one low-value live settlement check and confirm the real payment.confirmed event lands

​
Useful routes

POST /v1/webhooks/endpoints
POST /v1/webhooks/endpoints/{endpoint_id}/test
GET  /v1/webhooks/deliveries
GET  /v1/webhooks/timeline
POST /v1/webhooks/deliveries/{delivery_id}/replay

​
Good outcome

  • test event returns 2xx
  • delivery log shows a clean first success
  • the first real buyer payment or optional low-value live settlement check reaches payment.confirmed
  • your consumer unlocks access only after Hilt confirms the payment

​
2. Recover a failed delivery

Use this when payment succeeded but Telegram, Discord, or another delivery path did not complete cleanly.

​
Sequence

  1. inspect the membership by membership_id
  2. load provider diagnostics
  3. if the problem is transient, retry delivery
  4. if the issue is still unclear, open or reuse the linked delivery support ticket
  5. if proof is part of the recovery conversation, send the receipt proof link directly

​
Useful routes

GET  /v1/memberships/{membership_id}
GET  /v1/memberships/{membership_id}/delivery-diagnostics
POST /v1/memberships/{membership_id}/retry-delivery
POST /v1/memberships/{membership_id}/delivery-support-ticket
POST /v1/receipt/{receipt_id}/send-proof

​
Good outcome

  • provider state is visible before you retry
  • the retry result stays tied to the same membership trail
  • support history stays attached to the recovery path

​
3. Prove a payment and send buyer-safe proof

Use this when a buyer or merchant teammate needs verifiable proof instead of a screenshot.

​
Sequence

  1. list or search receipts
  2. load the exact receipt
  3. open the public proof page if a human needs to inspect it
  4. send the proof link or PDF directly when support needs a clean buyer-facing artifact

​
Useful routes

GET  /v1/receipts
GET  /v1/receipt/{receipt_id}
GET  /v1/receipt/{receipt_id}/public
GET  /v1/receipt/{receipt_id}/pdf
POST /v1/receipt/{receipt_id}/send-proof

​
Good outcome

  • the merchant teammate sees the same payment trail as the workspace
  • the buyer gets a stable proof URL and PDF
  • the support action is tied to the receipt instead of separate email history

​
4. Recover a recurring member

Use this when a buyer needs the next approval path, collection check, or recovery action for the next period. Native automatic renewal products use Solana subscription setup evidence, collection evidence, cancellation state, and post-period cleanup state.

​
Sequence

  1. read renewal intelligence for the cohort view
  2. inspect the member, paid-through date, cancellation state, and subscription detail
  3. choose the correct buyer-safe next action from the product and membership state
  4. for native automatic renewal products, inspect native authorization, collection, cancellation, and revoke-due state before asking the buyer to do anything
  5. keep the membership and support trail attached to that recovery step

​
Useful routes

GET /v1/memberships/renewal-intelligence

​
Good outcome

  • the buyer gets the right next action quickly
  • the merchant sees paid-through dates, grace, expiry, and subscription status clearly
  • support does not need to explain recurring operations from scratch

​
5. Validate an integration before live traffic

Hilt has a sandbox for pre-live API testing. It simulates Hilt lifecycle objects and signed webhooks, but it does not pretend to be a separate Solana settlement rail.

​
Use the sandbox for

  • webhook consumer testing
  • SDK and Postman flows
  • receipt and membership object-shape validation
  • delivery-failure and recurring-grace run-throughs

​
Use an optional low-value live settlement check for

  • final end-to-end launch validation
  • wallet flow
  • chain confirmation
  • real merchant payout path

​
Useful routes

POST /v1/access/sandbox/payment-sessions
POST /v1/access/sandbox/payment-sessions/{sandbox_session_id}/confirm
POST /v1/access/entitlements/check
POST /v1/access/webhooks

​
Good outcome

  • your webhook consumer accepts livemode=false test traffic correctly
  • you can replay the same representative Hilt object flow safely
  • any live settlement check is the last step, not the first step

​
Common questions

​
What are Hilt developer playbooks for?

They are repeatable technical guides for endpoint protection, product setup, webhook launch, delivery recovery, receipt proof, subscription recovery, and sandbox validation.

​
Which playbook should a new integration run first?

Start with the product setup playbook, then protect one endpoint, then run webhook launch and sandbox validation. After that, decide whether an optional low-value live settlement check is useful before real traffic.

​
Why are these playbooks conservative?

They protect payment, access, receipt, and support state from duplicate side effects, unverified webhook payloads, and untested recovery paths.