Credits & billing

Every billable op has a costCents declared in the contract. Each call debits the caller's credit balance; an empty balance returns 402 Payment Required with a topupUrl.

The 402 body shape (RFC 9457 problem+json):

{
  "type": "https://paymentauth.org/problems/payment-required",
  "title": "Payment Required",
  "status": 402,
  "detail": "Operation librarySearch costs 2 credits; balance is 1.",
  "required": 2,
  "balance": 1,
  "topupUrl": "https://<your-landing>/?account=acc_..."
}

The response also carries WWW-Authenticate: Payment topupUrl="..." (x402-ready seam).

Topping up

curl -X POST https://api.viralquery.com/v1/topup \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"amountCents": 5000}'
# → { "url": "https://checkout.stripe.com/c/pay/cs_..." }

Pay, then either:

• Webhook auto-credits if Stripe webhooks are wired (set STRIPE_WEBHOOK_SECRET), or
• Poll: POST /v1/topup/confirm {"sessionId": "cs_..."} credits on demand.

Both paths route through one idempotent seam — a session credits at most once.

Refunds

If a call debits but then fails downstream, the gateway refunds the cost. You only pay for work that succeeded.