Stripe
A Stripe integration links your Sealcord organization to your own Stripe account. Stripe keeps the money; Sealcord keeps the licences. Once connected and mapped, Stripe’s webhooks issue a licence for each paid checkout of a product you mapped, and end it on a refund or when a subscription ends. The rules every provider shares are on How payment integrations work.
You do not need an integration to sell through Stripe: your own backend can issue through the Admin API on Stripe’s webhook instead.
Connect
Section titled “Connect”- Create a restricted key in Stripe: Developers, API keys, Create restricted key. Give it Read on Checkout Sessions, Customers, Invoices, Subscriptions, Prices, Products, Charges and PaymentIntents, and on Connect, Accounts (what Sealcord uses to ask which account the key belongs to). Give it nothing else. Add Customer portal, Write only if your customers should reach Stripe’s customer portal from their licence (how).
- Paste it in the Console, under Payment integrations, in the Connect Stripe form. The key’s prefix decides the mode:
rk_test_…is test mode andrk_live_…is live mode. Only an owner or admin connects an integration. Sealcord stores the key encrypted and never shows it again. - Add the webhook endpoint in Stripe (Workbench, Webhooks, create an event destination for events from your account, with the snapshot payload) with the URL the Console shows for
the integration under Webhooks and events, Incoming,
https://api.sealcord.com/v1/webhooks/stripe/<integration id>, and the events listed on Checkouts, refunds, subscriptions and trials. Create it in the same mode as the key. - Paste the endpoint’s signing secret (
whsec_…) in the Console, under Webhooks and events, Incoming. It is write-only: once saved it is never shown again, and you can replace or remove it. Until it is set, Sealcord answers Stripe’s webhooks with503, and Stripe retries them. - Map your prices or products so a paid checkout knows which licence to issue: Map Stripe prices and products.
Sealcord only reads from your Stripe account, apart from opening a customer portal session when one of your customers asks for one. It never creates a webhook endpoint, product, price or Payment Link for you.
What Sealcord refuses
Section titled “What Sealcord refuses”-
A secret key (
sk_…). It can do anything in your account, so Sealcord refuses it before storing it or sending it anywhere, with “This is a secret key (sk_…), which can do anything in your Stripe account. Create a restricted key with the permissions below and paste that. Nothing was saved.” Create a restricted key. -
A key that lacks a permission. When you connect, and at each check, Sealcord makes one small read for each permission above, and the API names the first one missing (such as Invoices). The Console shows “Stripe refused the key. Check that you copied all of it, and that it is a restricted key from the account you mean. Nothing was saved.”, so check the key against the list above.
-
A Stripe account already connected to a Sealcord organization in the same mode. One account can have a test and a live integration, each with its own key, webhook and mappings.
How a delivery is checked
Section titled “How a delivery is checked”Sealcord checks each delivery’s Stripe-Signature against the endpoint’s signing secret, and
refuses one that is not signed with it or is more than five minutes old. Then it reads the
checkout, subscription, invoice or charge the event names again from Stripe, with your key and an
API version Sealcord fixes, and applies what Stripe says now. So the shape of the event never
depends on the API version of your endpoint, and an event that arrives late is applied as things
stand.
If Stripe does not answer, the delivery fails and Stripe retries it. If Stripe refuses your key
(revoked, expired, a permission removed), the integration shows needs_attention, your members are
alerted and the delivery fails, so Stripe’s retries apply the order once you fix the key.
Test mode and live mode
Section titled “Test mode and live mode”Stripe’s test and live modes are separate, and so are integrations. A test-mode integration takes a test key and test events; a live-mode one takes a live key and live events. Mappings, secrets and portal settings belong to one of them. An event from the other mode is recorded as ignored.
To try it end to end: connect a test-mode integration, create a test-mode webhook endpoint at its URL, create test prices and map them, and pay with one of Stripe’s test cards. A test purchase issues a licence in your Sealcord organization like any other, so revoke test licences you do not need. Repeat with live keys as a second integration when you go live.
Status and upkeep
Section titled “Status and upkeep”Status, Check, Disconnect and the rest of the upkeep are the same for every provider: see
How payment integrations work. On Stripe a
delivery needs your key to read its objects, so while an integration shows needs_attention
deliveries wait until the key works again. Add the missing permission back to the same key and press Check; only a revoked or expired key needs the steps below. To replace a revoked or expired key, create a new restricted key, disconnect
the integration and connect it again with the new key (the same integration comes back, with its
mappings), then set the signing secret again, because disconnecting erases it.
Questions
Section titled “Questions”Do I need a restricted key, or can I use my secret key?
Section titled “Do I need a restricted key, or can I use my secret key?”A restricted key. Sealcord only reads from your account, and a restricted key can be limited to exactly that.
Why does Stripe show 403 for my deliveries?
Section titled “Why does Stripe show 403 for my deliveries?”The endpoint’s signing secret is not the one saved in Sealcord, or you rolled it in Stripe. Paste the current one under Webhooks and events, Incoming.
Why does Stripe show 404?
Section titled “Why does Stripe show 404?”The URL names no connected Stripe integration, or you disconnected it. Check the URL against the one the Console shows.
What if Stripe sends an event before I set the secret?
Section titled “What if Stripe sends an event before I set the secret?”Sealcord answers 503 integration_webhook_not_configured, and Stripe retries it later, so the
order is applied once you set the secret. Stripe retries for up to three days in live mode and a few hours in test mode; after that, resend the events from Stripe’s dashboard.
What if my plan has no room for another licence?
Section titled “What if my plan has no room for another licence?”The order is kept, not lost, and issued once your plan allows it. See When your plan has no room.