Licensing Operations

The Payment Gateway operates under a commercial license verification system. The backend licensing engine evaluates signed license claims, the license support window, entitlement policy, and heartbeat cadence to derive a runtime state.

Understanding these states helps system operators keep service uninterrupted.

License Tiers

Three commercial tiers are available:

Additional organizations beyond the tier allowance can be added for 250 EUR per organization per year on any tier.

[!TIP] Use a non-production licensing environment to validate activation, heartbeat, and update flows before going live.

Runtime States

Heartbeat age is computed locally from the last successful heartbeat timestamp. A missing or zero heartbeat is treated as GRACE, not READ_ONLY.

• ACTIVE: Normal operations. Heartbeat received within 14 days. All reads, writes, and scheduled background workers function as expected.
• GRACE: Heartbeat not received for 14+ days, or no heartbeat recorded yet. Payment processing, data access, and scheduled jobs continue normally on both backends, but administrators will see warnings in the Admin Panel. Updates and support are paused until a successful heartbeat restores the license to ACTIVE.
• SOFT_LOCK: Heartbeat gap 31+ days. The Main Backend keeps full read/write access for payment processing and scheduled jobs. The Admin Backend allows reads but blocks create, update, and delete requests (POST, PUT, PATCH, DELETE return 403 Forbidden with code LICENSE_READ_ONLY). Updates and support remain paused.
• READ_ONLY: Heartbeat gap 45+ days. Service behavior matches SOFT_LOCK: the Main Backend continues normally; the Admin Backend is read-only for mutating API calls. Updates and support remain paused.
• BLOCKED: The license has been revoked or suspended, or the installation has been blocked for a policy violation such as reporting a product version newer than the highest version entitled by its support window. Protected endpoints return 403 Forbidden. Together with NOT_ACTIVATED, this state restricts runtime access.
• NOT_ACTIVATED: No license key is configured for the installation. Protected endpoints return 403 Forbidden until a license key is activated. The Admin Backend shows this state immediately on a fresh install; the Main Backend may report a short startup GRACE for up to one hour while a new host is being activated.

[!IMPORTANT] GRACE does not restrict runtime on either backend. SOFT_LOCK and READ_ONLY restrict Admin Backend writes only; checkout, webhooks, and worker jobs on the Main Backend continue with full access. These heartbeat-derived states also pause update eligibility and support access. Only BLOCKED and NOT_ACTIVATED block protected runtime access broadly. BLOCKED is never caused by an expired heartbeat alone, but it can be applied manually by the vendor or automatically when the installation reports an out-of-entitlement product version.

Operator Runbook

Use System > Licensing as the source of truth for local runtime state, activation, Sync License Now, support window, and last synchronization time. Only global administrators can open this page. Organization administrators using the Admin UI can still open Notifications, Geolocation, Invoicing, Checkout, and Tax settings for recovery while runtime access is blocked. Portal, templates, encryption, API-key settings, and API-key-authenticated requests remain license-gated.

First checks

1. Confirm the Admin Backend can make outbound HTTPS requests to the Licensing Authority. Official self-hosted deployments use https://payment-gateway.app; do not point production hosts at local or arbitrary endpoints.
2. Keep host time synchronized with NTP. Clock drift can make signed license tokens appear invalid or expired.
3. Use System > Licensing > Sync License Now after any payment-gateway.app account portal or operator workspace change that should affect the self-hosted host immediately.

Blocked, suspended, or revoked

BLOCKED covers manual blocks, suspended licenses, revoked licenses, and policy blocks such as a product version that is newer than the license support window allows. Protected runtime endpoints return 403 Forbidden; activation and sync stay reachable for global administrators.

1. In the payment-gateway.app account portal or operator workspace, confirm whether the remote status is manual BLOCKED, SUSPENDED, REVOKED, or a version/support policy block.
2. Clear the remote cause first. Sync cannot override a manual block, suspension, or revocation while it remains set in the Licensing Authority.
3. If the block is caused by version entitlement, either renew support so the running version is covered or downgrade to a covered release.
4. On the self-hosted host, run System > Licensing > Sync License Now. If sync still reports BLOCKED, wait briefly for the portal update to propagate and retry once before escalating with the request IDs shown in the UI.

Support renewed but the host still shows blocked

Saving a future support end date can auto-clear an automatic policy BLOCKED state in the Licensing Authority. The self-hosted installation does not refresh instantly on its own.

1. Verify the support end date is in the future on the license Instances view.
2. Verify the running product version is within that support window.
3. Run Sync License Now on the affected self-hosted admin.
4. If the host remains blocked, check whether the license also has a manual block, suspension, revocation, or registry access problem.

Deactivation and re-activation

Use deactivation when the local installation identity is wrong, the host was rebuilt with stale license state, or support asks you to reset the binding.

1. From System > Licensing, deactivate/reset the local license state.
2. Confirm the intended license is usable in the payment-gateway.app account portal or operator workspace.
3. Activate again from the same deployed host and public egress IP that pulled the licensed images.
4. After activation, run Sync License Now if the portal status changed during the reset.

Registry IP binding issues

Registry access credentials are bound to the public IP used by the first successful registry token request. License activation is expected to come from the same deployment environment.

1. If image pulls fail after a host move, NAT change, or new egress IP, rotate the license access secret in the license workspace before the next deploy or update.
2. Update the deploy environment with the new REGISTRY_ACCESS_SECRET.
3. Run the deploy or update from the target host so the registry token flow binds the current public IP.
4. Activate or sync the license from that same host.