How payment integrations work

A payment integration links your Sealcord organization to your own account at a payment provider. The provider keeps the money and Sealcord keeps the licences. When someone pays for a product you mapped, the provider tells Sealcord, and Sealcord issues a licence. When the order is refunded or the subscription ends, Sealcord ends it. Sealcord supports Polar and Stripe, and both follow the rules on this page.

You do not need an integration to sell through a provider: your own backend can issue through the Admin API from the provider’s webhook instead.

The steps, for any provider

1. Connect in the Console, under Payment integrations. Only an owner or admin connects one; an admin API key cannot. You give Sealcord a credential for your provider account (Polar also asks you to choose sandbox or production; a Stripe key’s prefix says test or live). Sealcord asks the provider which account it belongs to, and refuses a credential the provider does not accept.
2. Add a webhook endpoint at the provider, with the URL the Console shows for the integration under Webhooks and events, Incoming, and the events your provider’s page lists.
3. Paste the endpoint’s secret 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 the provider’s webhooks with 503 and the provider retries them, so no order is lost.
4. Map your products so a paid order knows which licence to issue. An order for a product without a mapping issues nothing, and Sealcord tells you.

Sealcord only reads from your provider account, apart from opening a customer portal session when one of your customers asks for one. It never creates the webhook endpoint for you, and never changes or deletes anything in your account.

What a payment does to a licence

What happens at the provider	What Sealcord does
A customer pays for a mapped one-time product	Issues a licence, once, however often the provider repeats the event
A customer pays for a mapped subscription	Issues a licence on the first payment
A subscription renews	Nothing: the same key keeps working, since renewals need no new key
A customer cancels a subscription	Nothing yet: access runs to the end of the paid period
The subscription ends	Applies the mapping’s choice: expires the licence (the default) or revokes it
A full refund of the order that issued a licence	Applies the mapping’s choice: revokes the licence (the default) or leaves it
A partial refund, or a refunded renewal	Records it and changes nothing
An order or subscription for an unmapped product	Issues nothing, records it as ignored and emails your owners and admins

The events behind each row are on the provider’s own page: Polar and Stripe.

• A subscription’s key carries no expiry unless the mapping sets key_valid_days. An embedded expiry would force a new key at every renewal, so the subscription’s end is enforced online, through the verdict.
• A licence that you or a refund ended is never brought back by a later subscription event. Sealcord reinstates only a licence that ended because its subscription ended, when the subscription becomes active again.
• A paid order with no customer email issues nothing and is recorded as ignored: look into it by hand.

Renewals and the 30-day hold

A subscription licence whose subscription just ended keeps its place in your plan’s count for 30 days. If the customer renews in that time, the licence is reinstated whatever your plan allows. After it, the renewal counts like any new licence.

When your plan has no room

If an order or subscription would take your organization past its plan’s number of active licences, Sealcord does not lose it. It records the event as deferred (Webhooks and events, Incoming shows it with the detail “deferred: plan limit reached”), and issues the licence once your plan allows it, after you upgrade or revoke or expire licences you no longer need. Licences already issued keep working.

Repeats and order

Providers deliver an event at least once, sometimes twice at the same time and not always in order. Sealcord applies each delivery once and keeps one licence for each order or subscription, so a repeat issues nothing new. An event older than the last one it applied to a licence is recorded and changes nothing, so a late event cannot undo a conversion.

Trials

A subscription that starts with a trial issues a trial licence at once: an active licence with a trial end. Your app sees an ordinary active licence, and the key does not change.

• While it is a trial, a verdict is valid at most a day past the trial’s end (why).
• When the customer pays for the first time after the trial, it converts: the trial end is cleared and the key stays the same. The licence’s audit log says it was converted.
• If the provider moves the trial’s end, the licence follows.
• If the subscription ends during the trial, the licence ends as for any subscription.
• If the conversion never reaches Sealcord, Sealcord asks the provider about every trial two hours after its end and settles it, so a paying customer is not locked out.

A trial issued by hand ends with its key, and is never checked with a provider.

Status and upkeep

An integration is in one of three states:

Status	Meaning
active	The provider accepts the credential
needs_attention	The provider stopped accepting the credential, or it now belongs to another account
disconnected	You erased its credentials. Its webhook answers 404

• Check asks the provider again. A working credential sets the status back to active.
• Disconnect erases the credential and the webhook secret. Licences and mappings stay. Delete the endpoint at the provider yourself. Connecting the same provider account again from the same Sealcord organization brings the same integration back, with its webhook URL and mappings, and without a secret.
• Each integration is yours alone. Your webhook route reads only your mappings and issues only your organization’s products. A provider account can be connected to one Sealcord organization at a time, in each environment.

Your plan decides how many integrations you may connect, and every plan allows at least one. You can list your integrations and manage their mappings with the Admin API (scopes payments:read and payments:write) or an AI assistant; connecting, the credential and the webhook secret stay in the Console.

Alerts

Sealcord emails your organization’s owners and admins, and members who turned it on, when an event was ignored because the product is not mapped, the order had no customer email or the event could not be read, or when your plan deferred an order or a subscription. It sends at most one such email a day for each integration and reason. Each member chooses their alerts in the Console.

What customers can open

Customers get their key, receipt, renewal link and, if you turn it on, your provider’s customer portal from their licence. All of it happens at your provider, never Sealcord’s. Setting it up is on each provider’s page: Polar and Stripe. With the portal on, every live licence from the integration whose customer the provider knows shows it: Manage subscription on a subscription’s licence, Your orders on a one-time purchase’s.