Billing

curl -X POST "https://api.talkturo.com/api/billing/webhook" \
  -H "Content-Type: application/json" \
  -H "stripe-signature: t=1725624600,v1=8f3b53d5c0e5f9dfc44cb7ec9885f38baf3d66ea9c77f1a0dcb2b2f4c3be8f25" \
  -d '{
    "id": "evt_1Qx9Ab2Lk8fR3mN7pY4sT6uV",
    "object": "event",
    "type": "checkout.session.completed",
    "data": {
      "object": {
        "id": "cs_test_b1m7Wq4sZ9k2Lx8nP3r5T6uV",
        "object": "checkout.session",
        "mode": "payment",
        "client_reference_id": "acct_9f3c2b7d",
        "customer": "cus_R8s2Kj3Lm5Np7Q",
        "payment_status": "paid",
        "metadata": {
          "planId": "credits_500",
          "customAmount": "250",
          "customCredits": "500"
        }
      }
    }
  }'

{
  "received": true
}

curl "https://api.talkturo.com/api/billing/invoices" \
  -H "Cookie: sb-access-token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.session_example"

{
  "success": true,
  "invoices": [
    {
      "id": "in_1Qx9Nf2Lk8fR3mN7sA4dE6gH",
      "status": "paid",
      "currency": "usd",
      "amount_due": 25000,
      "amount_paid": 25000
    }
  ]
}

Billing endpoints

Use these endpoints to receive Stripe billing events, inspect invoice history, and troubleshoot billing state. The webhook endpoint is the source of truth for credits purchases, subscription changes, desktop seat top-ups, and payment-link flows.

POST /api/billing/webhook

Stripe sends billing events to this endpoint. Talkturo verifies the stripe-signature header with STRIPE_WEBHOOK_SECRET before processing the payload.

Authentication and headers

Event types

The webhook processes all Stripe billing events through a single endpoint. Use the event type to understand which billing workflow Talkturo will run.

Special handling paths

Some Stripe events follow specialized billing logic instead of the default purchase or subscription path.

Credit recharge strategy cascade

Talkturo resolves credits for recharge and payment events through a fallback chain. The system tries the most specific source first, then falls back until it finds a usable value.

This cascade matters most for invoice.paid, but related checkout and payment flows can also rely on the same mapping logic. If you debug unexpected credit totals, inspect session or invoice metadata first before checking downstream mapping tables.

Response

The webhook acknowledges successfully processed events with a 200 response.

Notes

• External callers do not authenticate with a session or API key for this endpoint.
• Internal trust comes from Stripe signature verification, not from the request origin alone.
• Successful webhook handling returns 200 with received: true.

GET /api/billing/invoices

List invoices for the authenticated session account.

Authentication

This endpoint requires session authentication.

Response example

Response fields

GET /api/debug/billing

Inspect billing state for debugging. This endpoint is intended for admin users and should not be used as a customer-facing billing integration endpoint.

Authentication

This endpoint requires:

• Session authentication
• Admin access

What to use it for

Use the debug endpoint when you need to verify billing state after webhook delivery, subscription changes, invoice payment, or credit provisioning. It is most useful during support investigations and internal billing diagnostics.

Response shape

The repository context confirms this endpoint exists and requires admin session access, but it does not define a stable public response schema. Treat the payload as diagnostic output rather than a contract for external integrations.

Common integration guidance

Billing integrations fail most often at the webhook boundary. Verify these points before debugging downstream credit logic:

• Preserve the raw Stripe request body for signature verification.
• Send the exact stripe-signature header that Stripe generated.
• Include metadata consistently for plan, payment-link, or desktop seat workflows.
• Check whether the event is a checkout session, subscription update, invoice payment, or payment intent before tracing billing behavior.
• If credits look wrong, walk the recharge strategy cascade from metadata to fallback mapping.

Related billing behaviors

Billing state often affects adjacent parts of the platform, especially credits purchases and subscription-backed recharges.