AI Agents

You are implementing Osuvox Payments API (live-only). Build a working integration in this codebase.
Choose ONE integration path:
- Hosted Checkout (recommended for fastest integration):
  1) Create payment with success_url and cancel_url.
  2) Redirect the customer to payment_url.
  3) Treat redirects as UX only; fulfill orders from webhooks.
  4) On return, show a receipt page that waits for webhook confirmation (or polls /payments/{id} only for reconciliation).
- Full Integration:
  1) Create payment and render address/amount/QR yourself.
  2) Keep the customer on your site and rely on webhooks for status changes.

Before implementing, read https://www.osuvox.net/docs/payments for full endpoint specs, params, examples, errors, and webhook payloads.

Critical details from /docs/payments to enforce:
- If OSUVOX_API_BASE is set, use it (do not hard-code).
- If OSUVOX_WEBHOOK_URL is set, use it as the default webhook_url unless explicitly overridden per payment.
- Fulfillment: choose payment.confirmed OR payment.completed; if you rely on split payout finality, use payment.completed.
- Webhook dedupe must be persistent (DB table of event ids), not in-memory.
- external_id must be the canonical linkage for fulfillment and reconciliation across all flows (treat as required).
- Any polling endpoint (GET /payments or verify endpoints) is for reconciliation only; webhooks are primary.

Constraints:
- Server-side only. Never expose secrets to client.
- No public monitoring endpoint exists; all payment status changes are delivered via webhooks.
- Use OSUVOX_API_BASE if set, else https://www.osuvox.net/api/v1

Environment variables (server-only):
OSUVOX_API_KEY = sk_live_...
OSUVOX_WEBHOOK_SECRET = webhook signing secret from dashboard
OSUVOX_WEBHOOK_URL = your public webhook endpoint
OSUVOX_API_BASE = optional base URL
If OSUVOX_WEBHOOK_URL is set, pass it as webhook_url when creating payments unless you intentionally want a different per-payment URL.

Steps:
1) Create payment endpoint (server):
   - POST {amount, coin, external_id?, description?, metadata?, webhook_url?} to ${OSUVOX_API_BASE}/payments
   - Header: Authorization: Bearer ${OSUVOX_API_KEY}
   - Content-Type: application/json
   - On success, persist the returned payment object and expose to frontend: payment id, receiving address, amount/coin, and payment_url if provided.
   - Render a payment page or modal using the response fields; if a QR is needed and not provided, generate QR from the payment address/URI.

2) Webhook handler (server):
   - Endpoint: OSUVOX_WEBHOOK_URL (POST)
   - Read raw request body (no JSON middleware before signature verification).
   - Verify X-Osuvox-Signature header:
     - header format: "t=TIMESTAMP,v1=HMAC"
     - signed_payload = "${TIMESTAMP}.${raw_body}"
     - expected = HMAC_SHA256(OSUVOX_WEBHOOK_SECRET, signed_payload) hex
     - Reject if HMAC mismatch or timestamp is older than 5 minutes.
   - Parse JSON, dedupe by event id, then update order status.
   - Fulfillment trigger: use payment.confirmed or payment.completed (prefer completed if you need split payout completion).
   - txid: payment.confirmed/payment.completed should include data.payment.txid; if missing, defer fulfillment and reconcile via GET /payments/{id}. If multiple UTXOs are involved, data.payment.metadata.txids may include the full list.

3) Optional reconciliation (server):
   - GET ${OSUVOX_API_BASE}/payments/{id} or /payments?external_id=... to reconcile if needed.
   - Do NOT poll as a primary mechanism.

4) Error handling:
   - Handle 401/403 (bad key), 429 (rate limits), 4xx validation errors.
   - Log response body for debugging (server logs only).

Deliverables:
- Server endpoint to create payment using OSUVOX_API_BASE and OSUVOX_API_KEY.
- Persist full Osuvox payment response (or at least payment_id, status, payment_url, address, expires_at, external_id).
- Webhook endpoint with signature verification + persistent dedupe (DB).
- Fulfillment logic keyed by external_id and driven by webhook events.
- Optional reconcile endpoint for admins only (never primary).

Notes:
- This is live-only: use small amounts during setup.
- Webhooks are the only external signal of monitoring; there is no public monitoring endpoint.