Clavem

Adding license keys to an existing Stripe setup

If you already take payments in Stripe, you do not need a new checkout. Connect a restricted key to Clavem, map your Stripe products or prices to Clavem products, and every paid checkout starts issuing a key, an order page and a download. Your Checkout, Payment Links and Billing stay as they are.

What you already have, and what is missing

Stripe takes the payment and records it: Checkout sessions, Payment Links, subscriptions, invoices, refunds. What none of that gives you is the thing a software buyer needs after paying: a key to type into the app, a limit on how many computers use it, a place to download the file, and an answer from your app to “is this customer still entitled?” Clavem adds those, and nothing about how you take money changes.

The pieces:

  • Stripe sends events to a webhook endpoint that Clavem registers in your account.
  • Clavem checks each event’s signature and, when a mapped purchase is paid, issues the licenses, creates the order and a private order page, and emails the buyer the keys.
  • Your app calls the License API with the key.

Clavem never touches the payment and does not process card data.

Set it up in six steps

  1. Create a product in Clavem. Set the device limit and validity: perpetual, a number of days, or following the Stripe subscription. Clavem generates the signing key pair.
  2. Create a restricted key in Stripe. It needs read access to Products, Prices, Checkout Sessions, Subscriptions, Customers, Invoices, and Charges and Refunds, and write access to Webhook Endpoints. Everything else stays at None. Start with a test-mode key, which starts with rk_test_.
  3. Paste it into Clavem’s settings. Clavem checks the key can list products and Checkout Sessions, then creates its webhook endpoint in your account, subscribed to six events, pinned to a fixed Stripe API version.
  4. Map Stripe to Clavem. Open the Clavem product and add a mapping: a whole Stripe product, or one price of it. A price mapping wins over a product mapping.
  5. Test. Buy with Stripe’s test card 4242 4242 4242 4242, any future expiry date and any CVC. The license appears in the dashboard marked as a test. Refund it in full and the license becomes disabled.
  6. Go live. Disconnect, connect a live key (rk_live_) and map the live products again, because Stripe product ids differ between test and live mode.

Which of your setups issues what

How you sell in Stripe What to map What happens
A Payment Link for one price The price The paid checkout issues a license
Checkout sessions created by your site The product or price in the line items Each mapped line item issues licenses; a quantity of 3 issues 3 keys, up to 100
A subscription through Billing The subscription’s price The license follows the subscription: it expires at period end plus three days, and renews with invoice.paid
One Stripe product with monthly and lifetime prices Each price to its own Clavem product Different validity for each price
A checkout with a mapped and an unmapped item Only the mapped ones The unmapped item is left alone
Stripe Managed Payments As above Should work, since it uses Checkout; test it, as Clavem’s docs advise

If nothing in a checkout is mapped, no license is issued, and the event log shows it as unmapped, so you can fix the mapping and see what you missed.

What each Stripe event does to a license

Event Effect
checkout.session.completed, paid, with an email address Creates the order, the licenses and the email
checkout.session.async_payment_succeeded The same, for payment methods that settle later, such as bank debits
invoice.paid A renewal: extends the license, revives an expired one
customer.subscription.updated active, trialing and past_due keep it valid; canceled, unpaid, incomplete_expired and paused expire it
customer.subscription.deleted Expires the subscription’s licenses
charge.refunded, full Disables every license from the order

Events are processed once, by event id, so Stripe’s retries and your own replays are safe. A partial refund changes nothing. Refunding a subscription invoice does not disable its license: cancel the subscription, which expires it, or disable the license yourself. A license you disabled by hand stays disabled whatever Stripe says.

If you use Stripe’s customer portal so subscribers can cancel or update a card, nothing changes in Clavem’s setup: a cancellation reaches Clavem as a subscription event.

Edge cases that cost people an hour

  • No email address. A checkout needs an email address to issue a license. If a Payment Link or session collects none, no license is issued.
  • Two connections. An account has one Stripe connection, test or live. Disconnect to switch.
  • Your own webhook endpoints. Clavem registers its own endpoint and leaves yours alone. Deliveries to it should show 200 in Stripe’s dashboard; a 400 usually means the signing secret was rolled, and you disconnect and reconnect.
  • Plan limits. Purchases issue licenses even above your plan’s limit. Only creating licenses by hand and imports pause.

Customers who bought before

Clavem issues licenses for new purchases only. Bring older customers across with the import screen (CSV or JSON, or from your own database) or the management API, which accepts up to 500 licenses per call. The import keeps key strings as they are, with buyer, limit, expiry and activated devices, so apps in the field keep working. See importing licenses.

Doing this with Clavem

Everything above is on the Connecting Stripe page in full. For your app, pick a guide: Swift, Electron, Python or Node.js. The articles on whether Stripe generates license keys and adding keys to Stripe cover the background.

Clavem is not a merchant of record and does not handle tax, so how you sell in Stripe, and who owns tax, stays your decision.

Guides to follow

Questions

Do I have to change my Stripe Checkout to use Clavem?

No. Clavem listens to events from your Stripe account through a webhook endpoint that it registers itself. Checkout sessions, Payment Links and subscriptions you already have keep working. You map the Stripe products or prices to Clavem products and test one purchase.

What about customers who bought before I connected Clavem?

Clavem only issues licenses for purchases that happen after you connect. For earlier buyers, import their licenses from a CSV or JSON file, or create them with the management API. The import keeps key strings, limits and expiry dates.