Keyva Platform

Overview

Keyva core is licensing infrastructure: you create products and issue license keys from your own backend. Keyva Platform adds the commercial layer on top of it. Your customers subscribe through a portal you own, and every payment event drives the license key automatically.

Availability

Platform billing is a feature of the paid Keyva plans. Your plan sets how many end customers you can bill:

License keys issued to end customers count towards your normal Keyva license allowance as well.

How the money moves

You can take payment through Stripe, PayPal, or both. Keyva uses Stripe Connect direct charges on a Standard connected account, and PayPal Commerce Platform with you as the payee. Either way:

• Your customers, prices, subscriptions and invoices live in your account, not in Keyva's.
• Payments settle to your account on your own payout schedule. There is no escrow and no reserve hold by Keyva.
• You are the merchant of record. Refunds, chargebacks, tax and customer support for the sale are yours.
• You keep a full Stripe or PayPal dashboard and can leave Keyva without losing your billing data.

Keyva charges no platform fee on end-customer payments. The gateway's own processing fees still apply.

If you connect both, your customers choose which to pay with. A plan can hold a price in both accounts, and the portal then shows a button for each — Stripe or PayPal, the customer's call. You can also keep a plan to one gateway if you prefer, and add the other later without disturbing anyone already subscribed.

Setting up

1. Connect a payment account. Go to Settings → Keyva Platform → Connect and connect Stripe, PayPal, or both. Either way you can use an account you already have. Keyva shows each one's status as onboarding, restricted, active or disabled — only active can take payments. A PayPal account commonly sits at restricted until its primary email address is confirmed, which is worth checking first if payments are not going through.
2. Claim your portal address. In Settings → Keyva Platform → Customer Portal pick a slug. Your portal lives at https://keyva.dev/portal/your-slug.
3. Create your plans. Under Clients → Plans, define what you sell. Each plan creates a real price in your connected account — a Product and Price in Stripe, or a catalog product and billing plan in PayPal. If you have connected both, a plan is created in both by default and your customers choose at checkout; untick one if you would rather it were sold a single way.
4. Send customers to the portal. They sign in, subscribe, and get a key. Add customers up front under Clients if you want to invite them directly.

Plans

A plan is one thing a customer can buy. It ties a price in your Stripe or PayPal account to the licence that gets issued when they pay.

Price and interval are fixed once a plan is created, because prices are immutable at both gateways — editing them would not change what existing subscribers pay. To change pricing, create a new plan and archive the old one. Archiving hides a plan from the portal but keeps it resolvable from old invoices and licences.

The accepted payment methods are not fixed. Adding a gateway to a plan creates a matching price in that account and gives future customers another way to pay; it changes nothing for anyone already subscribed, who keeps being billed through the gateway they signed up with. Use the + Stripe or + PayPal button on the Plans list.

Usage-based pricing

A monthly plan can bill a metered count on top of its base price — “$20/mo including 100 clients, then $0.09/client”. You pick the unit name (clients, seats, devices), how many the base price includes, and the price per unit beyond that. The pricing is shown on the portal's plan card before anyone subscribes.

Your software reports its current count by adding one query parameter to the license validation it already makes:

• The month's peak is what gets billed. Keyva keeps the highest count reported in each calendar month (UTC); when the month closes, anything beyond the included allowance lands on the customer's next renewal invoice as its own line, at the per-unit price. Base in advance, usage in arrears.
• Reporting is passive. No extra endpoint, no schedule to keep — validate as often as your software already does, and the count rides along. A month with no reports simply bills nothing beyond the base price.
• The running total is visible all month. Your Clients page shows the accrued overage across every reporting license, and each customer's page shows their peak, allowance and month-to-date charge.
• Stripe only. PayPal subscriptions bill a fixed amount and cannot carry a metered overage, so a usage-priced plan cannot be sold through PayPal.

The customer portal

Your portal is a public page at /portal/your-slug, branded with your name. Customers sign in with a magic link — they enter their email address and get a single-use link that expires in 15 minutes. There is no password to reset and no Keyva account to create.

Once signed in, a customer can:

• Subscribe to any of your active plans.
• See and copy their license keys.
• Read their payment history, and open Stripe-hosted receipts where the plan bills through Stripe. A PayPal payment's receipt lives in the customer's own PayPal activity.
• Cancel a subscription — and resume it, on Stripe.
• Update their payment method through Stripe's hosted billing portal, so card details never touch Keyva or your servers. PayPal customers manage their funding source in their own PayPal account, where those controls already live.

Portal sessions are entirely separate from Keyva dashboard accounts. An end customer signing in to your portal has no access to Keyva itself, and a session on one developer's portal grants nothing on another's.

License provisioning

Keys are issued from payment events, not from checkout redirects — so a customer who closes the tab still gets what they paid for, and a checkout that never completes never hands out a key.

The moment a key is first issued, the customer is emailed it — including for a free trial and for a licence you issue by hand. Renewals are silent, because the key does not change.

For a subscription, licence expiry tracks the paid period: access lapses exactly when the customer stops paying, without waiting for a revocation. For a one-time purchase, expiry comes from the plan's licence duration, and a perpetual plan issues a key that never lapses.

Failed payments and cancellation

Grace period

When a payment fails, the subscription is marked past due and the customer is emailed with the exact date their access ends. Their key keeps working for the plan's grace period (7 days by default, configurable per plan; 0 revokes immediately). The gateway's own retries do not extend the deadline.

If the customer fixes their card before the deadline, nothing is revoked — the decision is made when the deadline arrives, based on the state at that moment, not when the payment first failed.

Cancellation

Cancelling always takes effect at the end of the current period. The customer has paid through it, so their licence keeps working until it lapses on its own.

On Stripe the cancellation itself is deferred, so the customer can resume any time before the period ends and nothing is reissued. PayPal has no deferred cancellation: the subscription stops at PayPal immediately and cannot be un-cancelled. The customer keeps their licence until the period they have paid for runs out, exactly as on Stripe, but resuming means subscribing again.

Managing customers

Clients lists everyone buying from you. Opening a client shows their subscriptions, licences and payments, and lets you act directly:

• Issue a licence manually against any of your plans — for comped accounts, replacements, or sales you closed off-platform. No payment account is required for this.
• Revoke a licence with a reason. A manual revoke is permanent: unlike a dunning revoke, a later payment will not resurrect the key. Revoking does not cancel the subscription; stopping the billing is a separate decision.
• See why provisioning failed, if a customer paid but their key could not be issued.

Customers can also write to you directly: every Platform plan includes a built-in support desk where they open tickets from the portal and you answer from your dashboard.

Teams

A team shares one connected Stripe account, one PayPal account, one portal and one catalog — the billing setup belongs to the team, not to whoever happens to be its owner today. Use the scope switcher in the sidebar to choose whether you are working in your personal account or in a team; everything you create lands in the scope you picked.

Connecting a payment account and claiming the portal address are owner-only actions. Any member can sell under the team's name, but only an owner decides where the revenue lands.

Validating platform-issued keys

Keys sold through Keyva Platform are ordinary Keyva license keys. Your application validates them exactly as it validates any other key — same endpoint, same signed Ed25519 token, same feature codes. Nothing in your client integration changes when you start selling through the platform.

See the API Reference for the full request and response, and the Integration Guide for code samples.

Already have billing?