killbill · reshmabidikar · Sep 24, 2026 · Sep 22, 2026 · Sep 24, 2026
diff --git a/README.md b/README.md
@@ -17,14 +17,14 @@ Authentication on every call:
 | `X-Killbill-ApiKey` | Kill Bill tenant API key (must match your Kintsugi Kill Bill connection) |
 | `X-Killbill-Kintsugi-Signature` | HMAC-SHA256 hex digest of the **raw JSON body** |
 
-The HMAC secret must match on both the Kill Bill plugin config and your Kintsugi Kill Bill connection.
+The HMAC secret is stored on both the Kill Bill plugin config (`hmacSecret`) and the Kintsugi connection. In the product flow Kintsugi generates it and uploads plugin config when you **Enable Tax Collection** — you do not paste a secret by hand.
 
 ## Prerequisites
 
 - JDK 11+
 - Maven 3.9+ (build from source) or a release JAR
 - Kill Bill **0.24.x** with invoice plugin support
-- A Kintsugi account with Kill Bill connected and the tax engine enabled
+- A Kintsugi account with Kill Bill connected and tax collection enabled
 
 ### Kill Bill compatibility
 
@@ -65,51 +65,32 @@ See [Kill Bill plugin installation](https://docs.killbill.io/latest/plugin_insta
 
 ## Tenant configuration
 
-### 1. Enable the invoice plugin
+After the plugin JAR is installed and running on Kill Bill, configure the tenant from Kintsugi (no manual `uploadPluginConfig` / `uploadPerTenantConfig` curls):
 
-Kill Bill 0.24+ expects JSON for per-tenant config:
+1. In Kintsugi, **Connect Kill Bill** (base URL, tenant API key/secret, admin username/password).
+2. Click **Enable Tax Collection** on the connection.
 
-```bash
-curl -u '<killbill-admin-user>:<killbill-admin-password>' \
-  -H 'X-Killbill-ApiKey: <tenant-api-key>' \
-  -H 'X-Killbill-ApiSecret: <tenant-api-secret>' \
-  -H 'Content-Type: text/plain' \
-  -H 'X-Killbill-CreatedBy: setup' \
-  -d '{"org.killbill.invoice.plugin":"killbill-kintsugi"}' \
-  'https://<killbill-host>/1.0/kb/tenants/uploadPerTenantConfig'
-```
-
-### 2. Upload plugin config
+Kintsugi then generates an HMAC secret (if needed), uploads plugin config (`kintsugiUrl` + `hmacSecret`), and enables `killbill-kintsugi` as the tenant invoice plugin. You do not paste secrets by hand.
 
-```bash
-curl -u '<killbill-admin-user>:<killbill-admin-password>' \
-  -H 'X-Killbill-ApiKey: <tenant-api-key>' \
-  -H 'X-Killbill-ApiSecret: <tenant-api-secret>' \
-  -H 'Content-Type: text/plain' \
-  -H 'X-Killbill-CreatedBy: setup' \
-  -d 'kintsugiUrl: https://api.trykintsugi.com
-hmacSecret: <shared-hmac-secret>' \
-  'https://<killbill-host>/1.0/kb/tenants/uploadPluginConfig/killbill-kintsugi'
-```
-
-YAML POJO form is also supported — see `KintsugiConfigurationHandler` in this repo.
+For local docker / maintainer smoke tests that talk to Kill Bill without the product UI, see [docker/README.md](docker/README.md).
 
 | Config key | Required | Description |
 |------------|----------|-------------|
-| `kintsugiUrl` | Yes | Kintsugi API base URL (no trailing slash), e.g. `https://api.trykintsugi.com` |
-| `hmacSecret` | Yes | Shared secret; must match the HMAC secret on your Kintsugi Kill Bill connection |
+| `kintsugiUrl` | Yes | Kintsugi API base URL (no trailing slash), e.g. `https://api.trykintsugi.com` — set by Enable Tax |
+| `hmacSecret` | Yes | Shared secret for request signatures — generated and uploaded by Enable Tax |
 | `killbillUrl` | No | Kill Bill base URL for optional Aviate billing-account lookup (default `http://127.0.0.1:8080`) |
 | `aviateIdToken` | No | Aviate JWT ([Aviate auth](https://docs.killbill.io/latest/aviate-authentication)). When set, the plugin reads [billing accounts](https://docs.killbill.io/latest/aviate-billing-account) before falling back to custom fields. Omit for non-Aviate deployments. |
 
 `kintsugiUrl` must be reachable from the Kill Bill JVM (network/firewall/DNS).
 
-## Kintsugi setup
-
-In your Kintsugi account:
+To **inspect** the stored tenant plugin config (not the healthcheck):
 
-1. Connect Kill Bill (base URL, tenant API key/secret, admin credentials).
-2. Set the connection HMAC secret to the same value as plugin `hmacSecret`.
-3. Enable the tax engine on the connection.
+```bash
+curl -u '<killbill-admin-user>:<killbill-admin-password>' \
+  -H 'X-Killbill-ApiKey: <tenant-api-key>' \
+  -H 'X-Killbill-ApiSecret: <tenant-api-secret>' \
+  'https://<killbill-host>/1.0/kb/tenants/uploadPluginConfig/killbill-kintsugi'
+```
 
 See [Kintsugi documentation](https://trykintsugi.com/docs) for the full setup guide.
 
@@ -128,7 +109,13 @@ curl -u '<killbill-admin-user>:<killbill-admin-password>' \
   'https://<killbill-host>/plugins/killbill-kintsugi/healthcheck'
 ```
 
-Returns healthy when the plugin is loaded and tenant config is present.
+Healthy response (plugin loaded and tenant config present):
+
+```json
+{"message":"Kintsugi plugin configured"}
+```
+
+The healthcheck does **not** return `kintsugiUrl` or `hmacSecret`. To read those values, use `GET .../uploadPluginConfig/killbill-kintsugi` (see above).
 
 ## Local development
 
@@ -145,11 +132,12 @@ See [docker/README.md](docker/README.md) for step-by-step scripts, configuration
 
 | Symptom | Likely cause |
 |---------|----------------|
-| No `TAX` lines on invoice | Tax engine not enabled in Kintsugi, or ship-to address has no tax obligation |
-| `401` / `403` from Kintsugi | HMAC mismatch — verify the same secret on plugin config and Kintsugi connection |
-| `Kintsugi plugin not configured` in logs | Missing `uploadPluginConfig/killbill-kintsugi` for the tenant |
+| No `TAX` lines on invoice | Tax collection not enabled in Kintsugi, or ship-to address has no tax obligation |
+| `401` / `403` from Kintsugi | HMAC mismatch — re-run **Enable Tax Collection** (re-uploads matching secret) |
+| `Kintsugi plugin not configured` in logs | Tenant plugin config missing — re-run **Enable Tax Collection** |
 | Connection timeout | Kill Bill cannot reach `kintsugiUrl` (DNS, firewall, or Docker networking) |
-| Healthcheck unhealthy | Plugin config missing `kintsugiUrl` or `hmacSecret` for the tenant |
+| Healthcheck unhealthy | Plugin config missing `kintsugiUrl` or `hmacSecret` for the tenant — re-run **Enable Tax Collection** |
+| Expected config keys in healthcheck body | Wrong endpoint — healthcheck only returns `{"message":"..."}`; use `GET .../uploadPluginConfig/killbill-kintsugi` to inspect |
 
 ## Behavior notes
 

diff --git a/docker/README.md b/docker/README.md
@@ -14,7 +14,9 @@ against a local Kill Bill stack. No dependency on the Kintsugi platform repo.
 
 ```bash
 cp docker/.env.example docker/.env
-# Edit KINTSUGI_HMAC_SECRET (must match Kintsugi Kill Bill connection)
+# Edit KINTSUGI_HMAC_SECRET for this local stack (setup-tenant.sh uploads it)
+# For a real Kintsugi connection, Enable Tax Collection provisions HMAC instead —
+# only set this env when using the manual docker scripts below.
 # Edit KILLBILL_API_KEY / KILLBILL_API_SECRET for your tenant
 
 docker compose -f docker/docker-compose.yml up -d
@@ -58,14 +60,13 @@ Kintsugi provisions a **test org** for Kill Bill maintainers. You do not put `or
 |----------|-------------|
 | `KILLBILL_API_KEY` / `KILLBILL_API_SECRET` | Kill Bill tenant credentials (create in Kaui). **Must equal** the Kintsugi Kill Bill connection `external_id`. |
 | `KINTSUGI_URL` | Kintsugi API base URL reachable **from the Kill Bill container** |
-| `KINTSUGI_HMAC_SECRET` | HMAC secret from the Kintsugi Kill Bill connection (not an API key) |
+| `KINTSUGI_HMAC_SECRET` | Secret uploaded by `setup-tenant.sh` as plugin `hmacSecret`. Product path: Kintsugi **Enable Tax Collection** generates this; for docker smoke, put the same value on the test connection (or let enable-tax overwrite Kill Bill and skip re-running setup with a different secret). |
 | `SMOKE_TAX_STATE` | US state for smoke ship-to (default `TX`; needs tax registration in the test org) |
 
 **Test org checklist (Kintsugi side):**
 
-1. Kill Bill connection created with tax engine enabled
-2. Connection HMAC secret → `KINTSUGI_HMAC_SECRET`
-3. Connection tenant API key → `KILLBILL_API_KEY` (and matching Kill Bill tenant in Kaui)
+1. Kill Bill connection created with tax collection enabled (provisions HMAC + plugin config), **or** connection + matching `KINTSUGI_HMAC_SECRET` for manual docker setup
+2. Connection tenant API key → `KILLBILL_API_KEY` (and matching Kill Bill tenant in Kaui)
 
 For a Kintsugi API running on the host machine:
 

diff --git a/docs/killbill-docs-pr.md b/docs/killbill-docs-pr.md
@@ -12,12 +12,6 @@ Install:
 kpm install_java_plugin kintsugi --from-source-file=target/kintsugi-plugin-0.1.0.jar
 ```
 
-Per-tenant configuration:
+Per-tenant configuration is provisioned from Kintsugi: connect Kill Bill, then **Enable Tax Collection** (sets the invoice plugin and uploads `kintsugiUrl` / `hmacSecret`). See the plugin README for setup and verification steps.
 
-```properties
-org.killbill.invoice.plugin=killbill-kintsugi
-```
-
-Upload plugin config via `uploadPluginConfig/killbill-kintsugi` with `kintsugiUrl` and `hmacSecret`. See the plugin README for setup and verification steps.
-
-Healthcheck: `GET /plugins/killbill-kintsugi/healthcheck`
+Healthcheck: `GET /plugins/killbill-kintsugi/healthcheck` → `{"message":"Kintsugi plugin configured"}` (does not return config keys; use `GET .../uploadPluginConfig/killbill-kintsugi` to inspect).