Get Started with Aeion Billing

Aeion stores provider credentials (Stripe, PayPal, Square, Adyen, Razorpay, and 15+ more) in the payment_providers collection. Each row carries the provider type, an isEnabled flag, and the credentials needed to call the provider's API.

Open Settings → Billing → Payment Providers in admin, or create one directly via auto-CRUD:

```bash POST /api/v1/payment_providers Content-Type: application/json

{ "type": "stripe", "isEnabled": true, "config": { "secretKey": "sk_live_xxx", "webhookSecret": "whsec_xxx", "publicKey": "pk_live_xxx" } } ```

Response (auto-CRUD envelope):

json { "data": { "id": "01J...", "type": "stripe", "isEnabled": true, "config": { "secretKey": "...", "webhookSecret": "..." }, "createdAt": "2026-05-20T10:00:00Z" } }

Point your provider's webhooks at:

POST /api/billing/webhooks/stripe POST /api/billing/webhooks/paypal POST /api/billing/webhooks/square POST /api/billing/webhooks/adyen POST /api/billing/webhooks/razorpay

The handler verifies the signature against the webhookSecret you stored, then fans the event out through the platform's event bus (billing.transaction.created, billing.subscription.canceled, etc.) so other modules can react.

> Need an env-var fallback for local dev? If no payment_providers row is enabled, the Stripe routes fall back to STRIPE_SECRET_KEY from the environment.

Once a license has a stripeCustomerId, customers can update their card, change plan, or cancel themselves through Stripe's hosted Customer Portal. Aeion issues short-lived portal session URLs:

bash POST /api/billing/stripe/portal-session { "returnUrl": "https://app.example.com/admin/modules/subscriptions" }

json { "data": { "url": "https://billing.stripe.com/p/session/..." } }

Redirect the user to that URL. Stripe handles the UI; webhooks (Step 1) keep Aeion's module_licenses in sync.

Change plan from inside your app (skips the portal — useful for upsell prompts):

bash POST /api/billing/stripe/change-plan { "moduleId": "crm", "newTier": "enterprise", "newPriceId": "price_xxx" }

Prorated immediately by Stripe. The local license is updated with the new tier and previous tier recorded as upgradedFrom.

Record metered usage for usage-based pricing:

bash POST /api/billing/stripe/usage-record { "subscriptionItemId": "si_xxx", "quantity": 1500, "action": "increment" }

Read current usage across all active licenses:

bash GET /api/billing/stripe/usage GET /api/billing/stripe/usage?moduleId=crm

For one-off charges (deposits, add-ons, marketplace purchases) use the unified charge endpoint. It writes a row to transactions, applies an advisory lock for idempotency, and calls whichever provider you specify (defaults to Stripe).

bash POST /api/billing/charge { "amount": 4999, "currency": "USD", "provider": "stripe", "source": "marketplace", "sourceId": "module:crm:upgrade-addon", "idempotencyKey": "upgrade-2026-05-20-tenant-xyz" }

json { "data": { "id": "txn_01J...", "amount": 4999, "currency": "USD", "status": "succeeded", "provider": "stripe", "providerTransactionId": "pi_xxx", "createdAt": "2026-05-20T10:15:00Z" } }

The same idempotencyKey will return the original transaction instead of double-charging — safe to retry from a flaky network.

Hosted Checkout flow (for subscription signup):

bash POST /api/billing/checkout/sessions { "mode": "subscription", "lineItems": [{ "price": "price_xxx", "quantity": 1 }], "successUrl": "https://app.example.com/billing/success", "cancelUrl": "https://app.example.com/billing/cancel", "trialPeriodDays": 14, "allowPromotionCodes": true }

Returns { "data": { "id": "cs_xxx", "url": "https://checkout.stripe.com/..." } }. Redirect, let Stripe collect the card, and the webhook handler will activate the license.

Cancel a subscription cleanly:

bash POST /api/billing/subscriptions/sub_xxx/cancel { "cancelImmediately": false, "reason": "customer_request" }

Pass cancelImmediately: true for an instant cancel; otherwise it lapses at the period end.

Refunds are a four-state pipeline: pending → approved → processing → succeeded (or failed / canceled / requires_review). Customer-service staff request, finance approves, the system executes.

Request:

bash POST /api/billing/refunds { "transactionId": "txn_01J...", "amount": 4999, "reason": "customer_request", "reasonDetails": "Duplicate charge — first attempt timed out" }

Amount must be ≤ original transaction. currency and metadata are optional. Returns a refund with an auto-generated refundNumber.

Approve (finance admin only):

bash POST /api/billing/refunds/<refundId>/approve

Execute against the provider:

bash POST /api/billing/refunds/<refundId>/process

The handler calls the original provider's refund API, updates the row to succeeded, and emits billing.refund_completed. If the provider succeeds but the local update fails, the row is flagged requires_review for manual reconciliation — no silent loss.

List, inspect, cancel:

bash GET /api/billing/refunds GET /api/billing/refunds?status=pending GET /api/billing/refunds/<refundId> PATCH /api/billing/refunds/<refundId> # notes, metadata, reasonDetails POST /api/billing/refunds/<refundId>/cancel

See your revenue picture:

bash GET /api/billing/analytics/overview GET /api/billing/analytics/recent

overview returns counts (transactions, refunds, invoices), time-series, and money totals in whole units (revenue / refunded / outstanding / netRevenue) — pulled directly from the database, not cached.