Licensing Operations

The Payment Gateway operates under a commercial license verification system. The backend licensing engine continuously evaluates signed JWT claims against your active subscription and heartbeat cadence to derive a runtime state.

Understanding these states is critical for system operators to ensure uninterrupted service.

License Tiers

Three commercial tiers are available:

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

[!TIP] Use a non-production licensing environment to validate activation, heartbeat, and update flows before going live. In the first-party deployment that environment is exposed at https://staging-dashboard.payment-gateway.app/.

Runtime States

• 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. Payment processing, data access, and scheduled jobs continue normally, 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. Payment processing, data access, and scheduled jobs still continue. This is an informational state surfaced on the admin dashboard for visibility. Updates and support remain paused.
• READ_ONLY: Heartbeat gap 45+ days, or never heartbeated. Payment processing, data access, and scheduled jobs still continue. This is also an informational state. Updates and support remain paused.
• BLOCKED: The license has been revoked or suspended by the licensing authority, 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. All protected endpoints return 403 Forbidden. This is the only state that restricts runtime access.
• NOT_ACTIVATED: No license key is configured for the installation. All protected endpoints return 403 Forbidden until a license key is activated. This state is shown immediately on a fresh install; it is not treated as GRACE.

[!IMPORTANT] Operations continue normally through GRACE, SOFT_LOCK, and READ_ONLY. These states only affect update eligibility and support access — they do not degrade or restrict your running system. Only BLOCKED and NOT_ACTIVATED prevent runtime access. BLOCKED is never caused by an expired heartbeat alone, but it can be applied manually by the licensing authority or automatically when the installation reports an out-of-entitlement product version.

Operator Actions

If your system enters a non-active state, follow these procedures to recover:

1. Verify Connectivity: The Admin Backend must be able to make outbound HTTPS requests to the License Authority. Check your firewall and NAT configurations.
2. NTP Drift: Keep the host clock synchronized using NTP (Network Time Protocol). Severe clock drift will cause the JWT verification to fail prematurely or appear expired.
3. Manual Heartbeat: If the state drops to GRACE, SOFT_LOCK, or READ_ONLY, navigate to the Admin UI and trigger a manual heartbeat to force a synchronization. This will restore the license to ACTIVE and resume update/support eligibility.
4. Runtime Block (BLOCKED): If the state becomes BLOCKED, confirm whether the licensing authority revoked or suspended the license, or whether the installation reported a version newer than the maximum version allowed by that license's support window. Resolve the account or version issue, downgrade if necessary, then trigger a manual heartbeat to restore the system to ACTIVE.
5. Initial Activation (NOT_ACTIVATED): As a global administrator, open the Admin UI at System → Licensing (/system/licensing), enter the license key, and activate. This page remains accessible to global admins even when the installation is unlicensed so you can recover from NOT_ACTIVATED / BLOCKED states. A successful activation also updates the operator-facing license workspace managed by your licensing authority. In the first-party deployment that workspace is hosted at payment-gateway.app.