Skip to content

Circuit KYC Network

Billing

circuit-kyc/circuit

Billing API¶

Manage credits, subscriptions, and payment methods programmatically.

Endpoints Overview¶

Endpoint	Method	Description
`/billing/credits`	GET	Get current credit balance
`/billing/overview`	GET	Full billing dashboard
`/billing/usage`	GET	Usage history
`/billing/transactions`	GET	Credit transactions
`/billing/checkout/credits`	POST	Purchase credits
`/billing/checkout/subscription`	POST	Upgrade subscription
`/billing/auto-recharge`	POST	Configure auto-recharge
`/billing/pricing`	GET	Get pricing info (public)

Authentication¶

All endpoints except /billing/pricing require X-API-Key header.

Get Credit Balance¶

GET /billing/credits

Response¶

{
  "credits": 8500,
  "tier": "starter",
  "auto_recharge_enabled": false
}

Get Billing Overview¶

GET /billing/overview

Response¶

{
  "credits": {
    "balance": 8500,
    "used_this_month": 1500,
    "included_monthly": 0
  },
  "subscription": {
    "tier": "starter",
    "price_monthly": 99,
    "started_at": "2024-01-01T00:00:00Z",
    "renews_at": "2024-02-01T00:00:00Z"
  },
  "auto_recharge": {
    "enabled": false,
    "threshold": null,
    "amount": null
  }
}

Get Usage History¶

GET /billing/usage?days=30

Query Parameters¶

Parameter	Type	Default	Description
`days`	integer	30	Number of days to retrieve

Response¶

{
  "usage": [
    {
      "date": "2024-01-15",
      "check_eligibility": 150,
      "assess_risk": 45,
      "issue_credential": 20,
      "verify_credential": 80,
      "total_credits": 595
    }
  ],
  "totals": {
    "check_eligibility": 4500,
    "assess_risk": 1350,
    "issue_credential": 600,
    "verify_credential": 2400,
    "total_credits": 17850
  }
}

Purchase Credits¶

POST /billing/checkout/credits

Request Body¶

{
  "package": "large",
  "success_url": "https://yourapp.com/success",
  "cancel_url": "https://yourapp.com/cancel"
}

Field	Type	Required	Description
`package`	string	Yes	`small` (1,000 credits) or `large` (10,000 credits)
`success_url`	string	Yes	Redirect URL after successful payment
`cancel_url`	string	Yes	Redirect URL if payment cancelled

Response¶

{
  "checkout_url": "https://checkout.stripe.com/c/pay/cs_live_..."
}

Credit Packages¶

Package	Credits	Price
`small`	1,000	$120
`large`	10,000	$1,000

Upgrade Subscription¶

POST /billing/checkout/subscription

Request Body¶

{
  "tier": "growth",
  "success_url": "https://yourapp.com/success",
  "cancel_url": "https://yourapp.com/cancel"
}

Subscription Tiers¶

Tier	Monthly Price	Rate Limit Multiplier
`starter`	$99	1x
`growth`	$499	5x
`enterprise`	Custom	20x

Configure Auto-Recharge¶

POST /billing/auto-recharge

Request Body¶

{
  "enabled": true,
  "threshold": 500,
  "package": "small"
}

Field	Type	Description
`enabled`	boolean	Enable/disable auto-recharge
`threshold`	integer	Recharge when credits fall below this
`package`	string	Package to purchase: `small` or `large`

Response¶

{
  "status": "configured",
  "auto_recharge": {
    "enabled": true,
    "threshold": 500,
    "package": "small"
  }
}

Get Pricing (Public)¶

GET /billing/pricing

No authentication required.

Response¶

{
  "operations": {
    "check_eligibility": 1,
    "assess_risk": 5,
    "issue_credential": 10,
    "verify_credential": 1,
    "ingest": 0
  },
  "packages": {
    "small": {
      "credits": 1000,
      "price": 120
    },
    "large": {
      "credits": 10000,
      "price": 1000
    }
  },
  "subscriptions": {
    "starter": {
      "price": 99,
      "rate_multiplier": 1
    },
    "growth": {
      "price": 499,
      "rate_multiplier": 5
    },
    "enterprise": {
      "price": "custom",
      "rate_multiplier": 20
    }
  }
}

Webhooks¶

Configure Stripe webhooks to receive billing events:

checkout.session.completed - Payment successful
invoice.paid - Subscription renewed
invoice.payment_failed - Payment failed
customer.subscription.deleted - Subscription cancelled

Webhook URL: https://api.circuitkyc.com/webhooks/stripe