crowetic/Qortal-Nextcloud-Integration
1
0
Fork 1
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
nuqloud
Qortal-Nextcloud-Integration/docs/product/paymenter-readonly-setup.md
T

9.0 KiB
Raw Permalink Blame History

Paymenter Connector Setup (Read-Only + Managed)

Start in read_only to validate sync, then move to managed for full in-plugin checkout.

Goal

  • Keep package/payment authority in CHD billing backend.
  • Let the plugin sync entitlements from CHD.
  • Optionally allow direct purchase/upgrade initiation from the plugin in managed mode.

Admin Settings (NuQloud -> Billing + Entitlements)

  1. Managed By CHD = enabled
  2. Billing Provider = Paymenter
  3. Connector Mode:
    • Read-only for sync-only
    • Managed for registration + checkout + entitlements
  4. CHD Billing Base URL = your connector API base URL
  5. CHD Entitlements Sync Path = endpoint path (default: /api/sovereign/v1/entitlements/sync)
  6. CHD Instance ID = unique tenant/instance identifier
  7. CHD Instance Token = bearer token for connector auth
  8. Optional CHD Instance Secret = HMAC signing secret
  9. CHD Catalog Path = endpoint path (default: /api/sovereign/v1/billing/catalog)
  10. Catalog Category ID = Paymenter/connector category id for NuQloud products (optional but recommended)
  11. Catalog Audience Key = audience rule key from CHD Admin catalog config (optional)

Then:

  • Click Save Billing Connectivity
  • Click Test Connector (No Apply)
  • Click Sync Entitlements From CHD
  • For managed checkout: click Connect Installation + Sync once, then Start Buying Services

Connector Request From Plugin

Method: POST

Path: {CHD Billing Base URL}{CHD Entitlements Sync Path}

Headers:

  • Authorization: Bearer <instance token> (if provided)
  • X-SC-Signature: <hmac_sha256(body, instance secret)> (if provided)

Body JSON:

{
  "instanceId": "my-cloud-instance-001",
  "nextcloudPublicUrl": "https://cloud.example.com",
  "sovereignMode": "powered",
  "billingProvider": "paymenter",
  "billingSyncMode": "read_only",
  "appVersion": "v1",
  "source": "nextcloud-plugin"
}

For managed checkout, plugin also sends billing profile fields to connector (billingProfile) so the Paymenter customer record can be updated before checkout link generation.

Catalog Discovery Request (Managed + Read-Only UI)

Method: POST

Path: {CHD Billing Base URL}{CHD Catalog Path}

Body JSON includes:

  1. instanceId
  2. nextcloudPublicUrl
  3. packageTier
  4. billingProvider
  5. billingSyncMode
  6. categoryId (when configured)
  7. catalogContract: "sc.billing.catalog.v1"
  8. optional context: audience, billingScope, billingSubject, catalogContext

Connector Response (Required)

Return either:

  1. Wrapped:
{
  "entitlements": {
    "packageTier": "nuqloud_starter",
    "billingEnabled": true,
    "creditsBalance": 500,
    "monthlyCredits": 500,
    "encryptedCapacityGb": 10,
    "replicationTarget": 2,
    "userPublishingEnabled": true,
    "qappsEnabled": true
  }
}
  1. Flat (same keys at top level).

Keys Applied By Plugin

  • packageTier
  • billingEnabled
  • creditsBalance
  • monthlyCredits
  • encryptedCapacityGb
  • replicationTarget
  • userPublishingEnabled
  • qappsEnabled

Safety

  • Test Connector (No Apply) validates connectivity/shape only.
  • Sync Entitlements From CHD applies values locally.
  • Package/credits entitlement fields remain read-only in admin UI.
  • Local admins do not directly override paid entitlement values.

Next (Post-Sandbox)

When sandbox passes, keep same API shape and switch only base URL/token to production connector.

Canonical catalog schema reference:

  • docs/product/connector-catalog-contract-v1.md

Legacy Env Mapping (Old -> Current)

Use this when migrating older connector .env files.

Core (typically keep)

  • PORT -> unchanged. Runtime listen port.
  • HOST -> unchanged. Runtime bind host.
  • LOG_LEVEL -> unchanged. Connector logging level.
  • CONNECTOR_MODE -> unchanged (paymenter for production).
  • INSTANCE_REGISTRY_PATH -> unchanged. Where instance state is stored.
  • ALLOW_UNKNOWN_INSTANCES -> unchanged. Security toggle for unknown instance requests.
  • ADMIN_API_TOKEN -> unchanged. Required for CHD admin endpoints.
  • CHD_ADMIN_API_TOKEN -> alias for ADMIN_API_TOKEN.
  • SOVEREIGN_ADMIN_API_TOKEN -> alias for ADMIN_API_TOKEN.
  • REGISTRATION_TOKEN -> unchanged. Protects install/register endpoint.
  • PAYMENTER_BASE_URL -> unchanged.
  • PAYMENTER_API_TOKEN -> unchanged.
  • PAYMENTER_TIMEOUT_MS -> unchanged.
  • PAYMENTER_TRUST_SCOPED_QUERY_RESULTS -> unchanged. Keep false in production unless you intentionally trust upstream scoped list responses.

Domain verification (keep if used)

  • CHD_DOMAIN_VERIFY_REQUIRED -> unchanged.
  • CHD_DOMAIN_VERIFY_TTL_SECONDS -> unchanged.
  • CHD_DOMAIN_VERIFY_PATH_TEMPLATE -> unchanged.
  • CHD_DOMAIN_VERIFY_TIMEOUT_MS -> unchanged.

Catalog/product mapping

These are still valid, but CHD Admin JSON can override product maps.

  • PAYMENTER_PACKAGE_PRODUCT_MAP -> unchanged.
  • PAYMENTER_ONE_TIME_PRODUCT_MAP -> unchanged.
  • PAYMENTER_ADDON_PRODUCT_MAP -> unchanged (new split naming for monthly add-ons).
  • PAYMENTER_ONE_TIME_LABEL_MAP -> unchanged.
  • PAYMENTER_ADDON_LABEL_MAP -> unchanged.
  • PAYMENTER_PACKAGE_PRICE_MAP -> unchanged (fallback pricing).
  • PAYMENTER_ADDON_PRICE_MAP -> unchanged (fallback pricing for monthly add-ons).
  • PAYMENTER_ONE_TIME_PRICE_MAP -> unchanged (fallback pricing).
  • PAYMENTER_PACKAGE_CHECKOUT_PATH_MAP -> unchanged (public checkout path fallback).
  • PAYMENTER_ONE_TIME_CHECKOUT_PATH_MAP -> unchanged (public checkout path fallback).
  • PAYMENTER_ADDON_CHECKOUT_PATH_MAP -> unchanged.
  • PAYMENTER_CATALOG_CATEGORY_ID -> unchanged.
  • PAYMENTER_CHECKOUT_CATEGORY_SLUG -> optional storefront category slug used to generate public checkout links from product/category data.
  • PAYMENTER_CHECKOUT_PATH_TEMPLATE -> optional storefront template, example /products/{category}/{productSlug}/checkout.

Precedence:

  1. ADMIN_CATALOG_CONFIG_PATH JSON (CHD Admin plugin-managed) for product maps/audience rules
  2. CHD Admin fallback price maps (packagePriceMap, addonPriceMap, oneTimePriceMap) are used when live Paymenter catalog data does not provide a price label.
  3. .env map values above as fallback defaults

Paymenter endpoint overrides (optional)

Still supported and unchanged:

  • PAYMENTER_USERS_ENDPOINT
  • PAYMENTER_ORDERS_ENDPOINT
  • PAYMENTER_SERVICES_ENDPOINT
  • PAYMENTER_CREDITS_ENDPOINT
  • PAYMENTER_INVOICES_ENDPOINT
  • PAYMENTER_INVOICE_ITEMS_ENDPOINT_TEMPLATE
  • PAYMENTER_PRODUCTS_ENDPOINT
  • PAYMENTER_ADDONS_ENDPOINT
  • PAYMENTER_PROPERTIES_ENDPOINT
  • PAYMENTER_CREATE_USER_ENDPOINT
  • PAYMENTER_CREATE_ORDER_ENDPOINT
  • PAYMENTER_CHECKOUT_LINK_ENDPOINT

Connector checkout resolution order:

  1. explicit mapped checkoutPath
  2. generated storefront path from PAYMENTER_CHECKOUT_CATEGORY_SLUG + PAYMENTER_CHECKOUT_PATH_TEMPLATE
  3. custom PAYMENTER_CHECKOUT_LINK_ENDPOINT
  4. order creation
  5. invoice + invoice-item fallback

Customer + property mapping

  • PAYMENTER_CUSTOMER_EXTERNAL_FIELD -> unchanged.
  • PAYMENTER_QORTAL_ADDRESS_PROPERTY_KEY -> unchanged.
  • PAYMENTER_QORTAL_ADDRESS_PROPERTY_NAME -> unchanged.
  • PAYMENTER_QORTAL_ADDRESS_MODEL_TYPE -> unchanged.
  • PAYMENTER_QORTAL_ADDRESS_UPSERT_ENDPOINT -> unchanged.
  • PAYMENTER_QORTAL_ADDRESS_UPSERT_TOKEN -> unchanged.
  • QORTAL_ADDRESS_UPSERT_ENDPOINT -> legacy alias (still accepted).
  • QORTAL_ADDRESS_UPSERT_TOKEN -> legacy alias (still accepted).

SSO bridge keys

  • SSO_BRIDGE_ENABLED -> unchanged.
  • SSO_BRIDGE_PAYMENTER_SSO_URL -> unchanged.
  • SSO_BRIDGE_VERIFY_TOKEN -> unchanged.
  • SSO_BRIDGE_VERIFY_PATH -> unchanged.
  • SSO_BRIDGE_TOKEN_TTL_SECONDS -> unchanged.
  • SSO_BRIDGE_REDIRECT_ALLOWLIST -> unchanged.
  • SSO_PAYMENTER_URL -> alias for SSO_BRIDGE_PAYMENTER_SSO_URL.
  • SSO_VERIFY_TOKEN -> alias for SSO_BRIDGE_VERIFY_TOKEN.
  • SSO_VERIFY_PATH -> alias for SSO_BRIDGE_VERIFY_PATH.

No longer used (safe to remove)

  • SOVEREIGN_CONNECTOR_BASE_URL
  • SOVEREIGN_SSO_VERIFY_PATH
  • SOVEREIGN_SSO_VERIFY_TOKEN
  • SOVEREIGN_SSO_TIMEOUT_SECONDS

Mock-mode defaults (optional in production)

Only relevant when CONNECTOR_MODE=mock:

  • DEFAULT_PACKAGE_TIER
  • DEFAULT_BILLING_ENABLED
  • DEFAULT_CREDITS_BALANCE
  • DEFAULT_MONTHLY_CREDITS
  • DEFAULT_ENCRYPTED_CAPACITY_GB
  • DEFAULT_REPLICATION_TARGET
  • DEFAULT_USER_PUBLISHING_ENABLED
  • DEFAULT_QAPPS_ENABLED

Webhook Clarification

Connector endpoint:

  • POST /api/sovereign/v1/events/paymenter/post-payment

Purpose:

  • Trigger entitlement refresh immediately after payment events.
  • Update instance state fields such as lastPaymentEventAt, lastPaymentEventType, and lastResolvedEntitlements.

Auth:

  • If PAYMENTER_WEBHOOK_TOKEN is set, Paymenter must send header X-SC-Webhook-Token with that value.
  • If token is empty, endpoint is still callable (not recommended for production).

Recommended Paymenter webhook target:

  • https://<connector-domain>/api/sovereign/v1/events/paymenter/post-payment

If you are unsure whether Paymenter is calling it, check connector logs for:

  • payment webhook processed
  • missing_webhook_token
  • invalid_webhook_token
Reference in New Issue View Git Blame Copy Permalink