​
Testing and going live

Start with Developer quickstart if you have not already created a product, webhook endpoint, and API key. This page is about the final confidence pass:
  1. prove your Hilt API handling in sandbox
  2. confirm the product, webhook, payout wallet, and live settings are ready
For Hilt Pay API, the same principle applies:
  1. prove the denied -> x402 HTTP 402 -> sandbox payment/proof -> entitlement check loop
  2. confirm Solana USDC settlement settings before real traffic
  3. verify receipt, entitlement, webhook, support context, and audit state after the first real buyer payment or optional live settlement check

​
30-second sandbox proof

If you only want to prove the testing surface exists before you do anything heavier, run: 
curl https://api.hilt.so/v1/testing/scenarios \
  -H "X-Hilt-Key: hk_sandbox_..."
Success looks like:
  • a 200 response
  • a scenarios list
  • the scenario ids you can use later in this page
Representative response: 
{
  "count": 4,
  "scenarios": [
    { "id": "confirmed_access", "title": "Confirmed access" },
    { "id": "payment_failed", "title": "Payment failed" },
    { "id": "delivery_failed", "title": "Delivery failed" },
    { "id": "renewal_grace", "title": "Renewal grace" }
  ]
}
Hilt’s sandbox is an API testing tool, not a fake Solana chain. That means it is excellent for:
  • webhook consumers
  • SDK and Postman workflows
  • receipt and membership handling
  • delivery recovery logic
  • recurring access grace handling
It does not prove:
  • wallet UX
  • real chain confirmation
  • merchant payout routing

​
Hilt Pay API sandbox path

Use this when you are protecting an API, bot, dataset, private product, or software feature. 
curl -X POST "$HILT_API_URL/v1/access/sandbox/payment-sessions" \
  -H "X-Hilt-Key: $HILT_SANDBOX_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: sandbox-session-cust-123-pro-ai-api-001" \
  -d '{
    "external_product_id": "pro-ai-api",
    "external_customer_id": "cust_123",
    "rail": "solana_usdc",
    "confirm_sandbox_mode": true
  }'
The response includes a one-time sandbox proof. Confirm it: 
curl -X POST "$HILT_API_URL/v1/access/sandbox/payment-sessions/SANDBOX_SESSION_ID/confirm" \
  -H "X-Hilt-Key: $HILT_SANDBOX_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: sandbox-confirm-cust-123-pro-ai-api-001" \
  -d '{ "proof": "hilt_sandbox_v1..." }'
Then call: 
curl -X POST "$HILT_API_URL/v1/access/entitlements/check" \
  -H "X-Hilt-Key: $HILT_SANDBOX_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_product_id": "pro-ai-api",
    "external_customer_id": "cust_123",
    "rail": "solana_usdc"
  }'
Expected result: has_access: true for the sandbox entitlement only. This does not create a live receipt and does not prove wallet settlement. The TypeScript and Python SDKs expose the same route pair as createSandboxPaymentSession / confirmSandboxPaymentSession and create_sandbox_payment_session / confirm_sandbox_payment_session. Use this order every time:
  1. create or choose one product
  2. create one webhook endpoint
  3. send one signed test event
  4. run one sandbox session
  5. confirm live readiness
  6. verify payment, membership, receipt, and delivery state after the first real buyer payment or optional live settlement check

​
Sandbox routes

GET  /v1/testing/scenarios
POST /v1/testing/sessions
GET  /v1/testing/sessions
GET  /v1/testing/sessions/{session_id}

​
Supported scenarios

Current public scenarios include:
  • confirmed_access
  • payment_failed
  • delivery_failed
  • renewal_grace

​
10-minute sandbox validation

​
1. List the scenarios

curl "$HILT_API_URL/v1/testing/scenarios" \
  -H "X-Hilt-Key: $HILT_SANDBOX_KEY"
You should see the scenario ids, titles, and emitted event list.

​
2. Create one confirmed-access session

curl -X POST "$HILT_API_URL/v1/testing/sessions" \
  -H "X-Hilt-Key: $HILT_SANDBOX_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "scenario": "confirmed_access",
    "product_id": "PRODUCT_ID",
    "identity_display": "@sandboxbuyer"
  }'
Representative response: 
{
  "session": {
    "id": "6f9418d1-cf8e-4fcb-9b0d-90b31f407111",
    "scenario": "confirmed_access",
    "status": "complete",
    "fake_payment_id": "sandbox_pay_0b0fbaf8d8b844b38b",
    "fake_membership_id": "sandbox_mem_76fbb6674f1e4e7d9d",
    "fake_receipt_id": "sandbox_rcpt_4c56f442f8274e7d8f",
    "event_count": 3,
    "delivery_count": 1
  },
  "scenario": {
    "id": "confirmed_access",
    "title": "Confirmed access",
    "events": [
      "payment.confirmed",
      "receipt.created",
      "membership.activated"
    ]
  }
}

​
3. Read the saved session back

curl "$HILT_API_URL/v1/testing/sessions/6f9418d1-cf8e-4fcb-9b0d-90b31f407111" \
  -H "X-Hilt-Key: $HILT_SANDBOX_KEY"
What you should inspect:
  • the fake ids
  • the emitted timeline
  • any webhook delivery results
  • livemode=false on the simulated event trail

​
4. Verify your own system

After the sandbox session, your own application should be able to:
  • verify the webhook signature
  • deduplicate the event id
  • store the fake payment_id
  • handle the fake membership and receipt ids without special-case code

​
What each scenario is for

ScenarioBest use
confirmed_accessclean-path payment, receipt, membership, and webhook handling
payment_failedfailed-payment handling and buyer recovery logic
delivery_failedfailed Telegram or Discord delivery plus support escalation
renewal_gracerecurring access grace and expiry logic

​
Keep the sandbox honest

Treat sandbox data as:
  • representative of the Hilt API
  • safe for repeatable integration work
  • useful for debugging your webhook and object handling
Do not treat it as:
  • proof that wallet UX is correct
  • proof that chain confirmation is correct
  • proof that merchant payout routing is correct

​
Optional live settlement check

After sandbox, some teams complete a low-value live settlement check before opening the product to buyers. This is useful when you want to verify:
  • wallet flow
  • confirmation path
  • payout routing
  • access delivery
  • dashboard alignment

​
What to verify after live settlement

​
Payment

curl "$HILT_API_URL/v1/payments/PAYMENT_ID"

​
Membership

curl "$HILT_API_URL/v1/memberships?product_id=PRODUCT_ID&limit=20" \
  -H "X-Hilt-Key: $HILT_API_KEY"

​
Receipt proof

curl "$HILT_API_URL/v1/receipts?page=1&per_page=20&product_id=PRODUCT_ID" \
  -H "X-Hilt-Key: $HILT_API_KEY"

​
Webhook trail

Use the dashboard or the webhook APIs to confirm:
  • the real event was emitted
  • the endpoint got the event
  • the delivery log matches your own server logs

​
Go-live checklist

Before real traffic:
  • one product is proven
  • Hilt Pay API products have setup readiness with no live blockers
  • payment_session_options.session_creatable_rails[] contains only the rails you intend to expose
  • one signed test event succeeded
  • one sandbox scenario succeeded
  • sandbox validation succeeded
  • live settlement settings are ready
  • payment, membership, receipt, and webhook trails all agree

​
Common questions

​
What does the Hilt sandbox prove?

The sandbox proves your Hilt API handling, webhook consumer behavior, object parsing, and recovery logic. It does not prove real wallet UX or settlement.

​
Do I still need a live test?

Not for SDK or webhook development. Sandbox proves the API behavior. A low-value live settlement check is useful when the merchant wants to verify buyer wallet UX, chain confirmation, payout routing, access delivery, and receipt trail before real buyer traffic.

​
Which sandbox scenario should I run first?

Start with confirmed_access, then add payment_failed, delivery_failed, and renewal_grace when your application needs those recovery paths.

​
Where to go next