Stripe & Razorpay Payments

KaiVox supports two payment gateways: Stripe for global users and Razorpay for Indian users. Both are used exclusively for wallet top-ups. Subscription billing is tracked internally — no recurring charges via Stripe/Razorpay yet.

Environment Variables

# Stripe (test mode — use pk_test / sk_test for local dev)
STRIPE_KEY=pk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxx
STRIPE_SECRET=sk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

# Razorpay (test mode)
RAZORPAY_KEY=rzp_test_xxxxxxxxxxxxxxxxxxxx
RAZORPAY_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxx

Wallet Top-Up Flow

Stripe Flow

1. Tenant selects Stripe and enters amount At Billing → Top Up Wallet, they choose an amount (e.g. $50) and select "Pay with Card (Stripe)".
2. Stripe Checkout Session created BillingController::topupStripe() creates a Stripe Checkout Session via the Stripe API. The session has success_url and cancel_url pointing back to KaiVox.
3. Tenant completes payment on Stripe's hosted page They are redirected to Stripe's secure checkout. On success, Stripe redirects to /billing/topup/stripe/success?session_id=....
4. KaiVox verifies and credits wallet BillingController::stripeSuccess() retrieves the session from Stripe API, verifies payment_status = paid, then credits the tenant's wallet and creates a wallet_transactions record.

Razorpay Flow

1. Tenant selects Razorpay and enters amount At Billing → Top Up Wallet, they choose an amount (in INR) and select "Pay with Razorpay".
2. Razorpay order created BillingController::topupRazorpay() creates a Razorpay order via the Razorpay API. The order ID is returned to the frontend.
3. Razorpay JS checkout modal opens The tenant completes payment in Razorpay's modal (UPI, net banking, card, etc.).
4. KaiVox verifies signature and credits wallet On payment success, Razorpay returns razorpay_payment_id, razorpay_order_id, and razorpay_signature. KaiVox verifies the HMAC signature using RAZORPAY_SECRET, then credits the wallet.

Wallet System Architecture

How Calls Deduct from Wallet

// Called at call hangup (VobizService + TwilioService):
BillingService::chargeForCall($tenant, $durationSeconds);

// Logic inside BillingService::chargeForCall():
1. Convert seconds to minutes (round up)
2. Check tenant's remaining monthly quota
3. If quota remaining → deduct from quota (free)
4. If quota exhausted → deduct from wallet at tenant's plan per-minute rate
5. If wallet insufficient → log failure, flag account
6. Record wallet_transaction entry

Subscription Plan Management

Plans are created and managed by the Super Admin at Super Admin → Subscription Plans. Each plan has:

• Name — Starter / Pro / Enterprise
• Monthly price — charged manually or via future Stripe subscription
• Monthly call quota — free minutes per billing cycle
Per-minute rate — rate charged from wallet after quota
• Features list — shown on pricing page

Tenants can upgrade or downgrade at Billing → Change Plan. The subscriptions table records the current plan, start date, and status.

Invoice / Billing History

Tenants can view their billing history at Billing → History. This shows all wallet top-ups, call charges, and phone number billing deductions from wallet_transactions and phone_number_billing.

Super Admin Billing Controls

Super Admins can at Super Admin → Tenants → [Tenant] → Billing:

• Manually adjust wallet balance (add/deduct with a reason note)
• View all wallet transactions for the tenant
• Override plan assignment
• See low-balance alerts (flagged tenants whose wallet is below threshold)

Troubleshooting Payments