How It Works

Paygent connects your AI application to billing in six stages. This page is the integration map — follow it top to bottom when onboarding a new product or customer.

Architecture overview

Your Application                    Paygent                           Customer
─────────────────                  ───────                           ────────
SDK: send_usage /                  Agents + Indicators               Invoice PDF
      send_indicator /             Plans + Pricing                   Payment link
      send_external_cost    →      Orders + Billing run       →      Wallet balance
                                   Invoices + Taxes

Step 1 — Define your product (dashboard)

Before writing code, configure what you sell:

Step 2 — Integrate the SDK (your app)

Install the SDK and send events as your AI runs:

1
import paygent_sdk
2
paygent_sdk.init(api_key="your-api-key")
3
4
# Automatic LLM tracking
5
response = client.chat.completions.create(
6
    model="gpt-4o",
7
    messages=[...],
8
    paygent_agent_id="support-bot",
9
    paygent_customer_id="cust_123",
10
    paygent_indicator="message-sent",
11
)
12
13
# Or explicit indicator / external cost
14
paygent_sdk.send_indicator("support-bot", "cust_123", "ticket-resolved")

Every event includes agent ID, customer ID, and indicator. Paygent resolves pricing, credits, and custom rates server-side.

SDK Installation →

Step 3 — Register customers (dashboard or API)

Create customers with an external ID matching your database primary key:

externalId: "cust_123"  ← pass this as customer_id in SDK calls

Add billing address and tax defaults for invoice PDFs.

Customers API →

Step 4 — Create an order (contract)

An order ties a customer to agents, plans, seat counts, taxes, and billing schedule:

1. Orders → Create Order
2. Pick customer, billing day, payment terms
3. Add agent lines — select a Plan or default pricing
4. Configure wallet settings if the plan includes credit benefits
5. Attach taxes if needed
6. Activate the order

Draft orders do not bill. Only active orders generate invoices.

Orders & Invoicing →

Step 5 — Usage accumulates (automatic)

As your app sends events:

• Activity/outcome indicators → metered for usage billing
• Billable metrics → aggregate meta_tags into quantities
• Credit indicators → debit prepaid wallets or accrue postpaid usage
• External costs → match dashboard configs → invoice lines
• Voice/video → minutes, tokens, resolution tiers via custom pricing

Monitor real-time usage in Dashboard → Agent Analytics.

Step 6 — Billing runs → invoices (automatic)

On each customer’s billing day, Paygent:

1. Aggregates usage for the billing period
2. Adds setup, platform, and seat fees (see Subscription Fees)
3. Applies external cost and wallet conversions
4. Calculates taxes
5. Creates an invoice (PDF + line items)

You can send email, generate a Stripe payment link, or mark as paid to release pending wallet credits.

Common integration paths

Path A — Simple usage billing

Agent + indicator + FLAT price → SDK → order → invoice.
Best for: MVP, single product, pay-per-call.

Path B — SaaS subscription + usage

Plan with platform fee + seat fee + activity indicators.
Best for: B2B AI tools with base subscription and overage.

Path C — Prepaid credits

Credit currency → platform fee credit benefits → prepaid wallet → CREDITS indicators.
Best for: API marketplaces, developer platforms.

Path D — Voice agent

Voice SDK + custom per-minute pricing + external telephony costs.
Best for: AI phone agents, speech-to-speech products.

Why this works

• Real-time tracking — no lost billable events between billing cycles
• Server-side pricing — change rates in dashboard without redeploying
• Automatic invoicing — eliminates spreadsheet reconciliation
• Flexible models — combine fees, credits, taxes, and pass-through costs on one invoice

Quick Start →