Credit System — Credits and subscriptions for your own site

§ 01 — Two ways money arrives

Top-ups and recurring plans, from one integration

Most credit businesses need both: customers who buy a bundle when they need it, and customers who want it handled automatically every month. Both run through the same API and produce the same webhook vocabulary.

Pay as you go

Top-ups

The customer picks an amount and a payment method on your site. You create one order; we take it from there and tell you when the money is genuinely final — not merely promised.

Any amount you set, in any currency you price in
Crypto deposits get their own address per order, so reconciliation is never ambiguous
Card and wallet payments can run on a page we host, keeping the processor off your domain
Re-running the same request never charges twice — orders are idempotent by key

payment.paid → credit the balance

Recurring

Subscriptions

Plans that renew on their own schedule, with the provider handling billing retries and tax. You get told when a subscription starts, renews, lapses or is cancelled.

Runs on your own Lemon Squeezy account, or the platform's FastSpring account
The provider acts as Merchant of Record — they handle VAT and sales tax
Subscription state is mirrored locally, so entitlement checks need no API round-trip
Entitlement is granted from signed webhooks, never from a buyer landing on a success page

subscription.* → grant or revoke access

§ 02 — How it works

From your customer's click to their new balance

Your site stays the source of truth for the balance itself. This platform's job is the part in the middle: collecting the money, confirming it is final, and telling you exactly once.

Step 04 is the one that matters: you credit a customer on a signed webhook or a confirmed order status — never on a redirect back to your site, which anyone can forge by typing a URL.

§ 03 — Payment rails

Seven ways to take a top-up

Switch any of them on or off from your dashboard. The column that usually goes unsaid is the one that matters most — whose account the money actually lands in.

Rail	What the customer sees	Where the money lands
Crypto	A deposit address and exact amount, on whichever chain they hold	Platform wallets, swept to cold storage. Custodial.
Cards & wallets	Card fields, Apple Pay and Google Pay, on a page we host so the processor never sees your domain	Your own Stripe account.
PayPal rail	Card, Apple Pay, Google Pay and Trustly bank redirect	Routed to your PayPal at capture.
Hosted checkout	A complete checkout page priced per order, opened without ever revealing your domain	Your own Whop account.
Subscriptions	A hosted plan page that renews on schedule, with tax handled for you	Your own Lemon Squeezy account.
Managed plans	The same recurring or one-off hosted checkout, with no provider account of your own to open	The platform's FastSpring account, as Merchant of Record.
Bank / manual	Your own instructions and a unique reference code, under a name you choose	Straight to you. You confirm receipt.

Each rail is a switch in your dashboard, enforced server-side — turning one off actually refuses the order, it does not merely hide a button.

§ 04 — For developers

Create an order, wait for the webhook, credit the balance

That is the whole integration. One REST call, one handler, and the same event shape no matter which rail the customer chose.

1 · Start a top-up

# POST /v1/payment-orders
curl https://your-domain.example/v1/payment-orders \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "idempotency_key": "topup-8841",
    "external_reference": "user-204:topup",
    "method": "STRIPE_CARD",
    "currency": "USD",
    "expected_amount_atomic": "2500"
  }'

2 · Send them to checkout

// The response carries a page hosted on
// our domain — embed or redirect to it.
window.location =
  order.checkout_payload
       .hosted_checkout_path;

// Processors see our domain, not yours.

3 · Credit on the webhook

# X-Webhook-Event: payment.paid
# X-Webhook-Signature: sha256=...
{
  "external_reference": "user-204:topup",
  "rail": "STRIPE",
  "new_status": "PAID",
  "expected_amount_atomic": "2500"
}

Every event carries your own external_reference, so you map it to a customer without a second lookup. Delivery is at-least-once and signed with HMAC-SHA256 — dedupe on order_id and verify before you trust it.

§ 05 — Security

Handling other people's money

API keys

Hashed with HMAC-SHA256 and a server-side pepper — never stored or logged in plaintext.

Stored credentials

Provider keys and webhook secrets are encrypted at rest with AES-256-GCM, and never shown again after you save them.

Account access

Argon2id password hashing, optional TOTP two-factor, and lockout after repeated failed logins.

Every state change

Recorded in an append-only transition log with the actor and reason — so a paid order can always be explained.

Sell credits on your own site. We handle the money coming in.