Overview This feature connects your Stripe account to Luminous so the B2B customer portal can securely collect and store credit card payments using Stripe Elements. Set this up before onboarding customers to the portal — without it, the card entry form will not load.
How It Works (Step-by-Step)
Step 1 — Open Payment Gateway Settings
- Log in to Luminous.
- Click your user name at the top right of the screen and select Settings.
- Under the General group, select General (first item in the list).
- Click the Payment Gateway tab at the top of the settings panel.
Step 2 — Select Stripe as the Active Gateway
- In the Payment Gateway Setting section, open the Currently Used Gateway dropdown.
- Choose Stripe. (The other options are CyberSource, Authorize.Net, and None.)
- A Stripe credentials section expands directly below the dropdown, with the note: "Enter your Stripe Connect account id (acct_...) and your Stripe API keys. Charges will be processed on your connected Stripe account via Luminous's platform."
Step 3 — Enter Your Stripe Credentials All five fields are present and required:
| Field | Where to Find It | What to Expect |
|---|---|---|
| Connect account id | Stripe Dashboard → Settings → Business Details → Account ID | Field placeholder is acct_... |
| Publishable key | Stripe Dashboard → Developers → API Keys | pk_live_... for live, pk_test_... for test mode |
| Secret key | Stripe Dashboard → Developers → API Keys | sk_live_... for live, sk_test_... for test mode. Entered as a masked/password field in Luminous. |
| Webhook signing secret | Generated in Step 4 below | Starts with whsec_. Entered as a masked/password field in Luminous. |
| Test mode | — | Dropdown with values true / false. true = test/validation mode; false = live charges |
⚠ Important: Your Publishable Key, Secret Key, and Test Mode setting must all be consistent — don't mix test keys with live mode or vice versa.
Step 4 — Register the Webhook in Stripe. This step is what allows Stripe to notify Luminous when a payment succeeds or fails; skipping it means orders won't update to a paid status automatically.
- In your Stripe Dashboard, go to Developers → Webhooks → Add Endpoint.
- In the endpoint URL field, enter:
https://<your-luminous-api-host>/api/webhooks/stripe. ⚠ Important — this is NOT your normal Luminous login URL (theyourtenant.joinluminous.comaddress you use to sign in). Login domain doesn't route this path to the backend at all — it silently returns the app's front-end page with a 200 status, which Stripe would treat as a successful delivery even though nothing happened.- Contact Luminous Support or your account manager for the correct API host to use here before setting this up.
- Under Events to send, select at minimum:
payment_intent.succeeded,payment_intent.payment_failed. - Click Add Endpoint.
- On the endpoint detail page, click to reveal the Signing Secret and copy the whsec_... value.
- Paste it into the Webhook Signing Secret field back in Luminous.
Step 5 — Save Click Save Settings at the top right of the General settings page header. Luminous stores all credentials securely in your tenant settings (the Secret Key and Webhook Signing Secret fields are masked in the UI, consistent with encrypted storage).
Note: The application fee rate (Luminous's platform take rate on card charges) is not exposed anywhere on this settings screen — consistent with it being managed on Luminous's side rather than by the account admin, though I don't have a source confirming who specifically manages it.
- Open the B2B portal as a customer and attempt to add a payment method — the Stripe card-entry form should appear.
- In test mode, charge using Stripe's test card: 4242 4242 4242 4242, any future expiry date, any 3-digit CVC.
- In your Stripe Dashboard under Developers → Webhooks, confirm events are arriving and returning 200 responses.
- Once validated, set Test Mode to false, save again, and switch your API keys to pk_live_ / sk_live_.
Key Features & Options
- Test Mode lets you run the full payment flow using fake card numbers without processing real charges. Always complete a full test cycle before switching to live.
- Stripe Connect means Luminous acts as the platform and your Stripe account is the connected merchant. Charges flow through Luminous's platform on your behalf — confirmed live: the settings panel's own helper text says exactly this ("Charges will be processed on your connected Stripe account via Luminous's platform"), which is why the acct_ Connect Account ID is required and is different from your standard Stripe login ID.
- Switching Gateways — Luminous currently supports three gateways plus None: CyberSource, Authorize.Net, and Stripe.
Tips & Best Practices
- Always complete test mode verification before going live — use Stripe's test cards to simulate both successful and failed payments.
- If you ever regenerate the webhook signing secret in Stripe, immediately update it in Luminous and re-save, or webhook events will start failing silently.
- Confirm your acct_ Connect Account ID with your Luminous account manager before starting — it's easy to confuse this with a regular Stripe account ID.
- Keep a copy of your credentials somewhere secure before saving. The Secret Key and Webhook Signing Secret are entered as masked fields and are not visibly retrievable from Luminous after saving.
- Only one payment gateway can be active at a time (Currently Used Gateway is a single-select). Plan your switchover if you're migrating from another gateway.
FAQs & Troubleshooting
Q: The Stripe card form doesn't appear in the B2B portal.
A: Stripe may not be saved as the active gateway, or credentials are incomplete. Go back to Settings → General → Payment Gateway, confirm all fields are filled, and click Save Settings again.
Q: Webhook events are not arriving in Stripe.
A: The endpoint URL likely has a typo. Even a small mismatch in the hostname will cause all events to fail. Double-check against your actual Luminous domain.
Q: I'm getting a webhook signature mismatch error.
A: The signing secret in Luminous doesn't match Stripe's current value. Re-copy the whsec_ value from Stripe Dashboard → Developers → Webhooks → [your endpoint] → Signing Secret and paste it fresh into Luminous.
Q: Test payments work but live payments fail.
A: Confirm that Test Mode is set to false and that your keys are the pk_live_ and sk_live_ versions — not the test keys.
Q: I don't have a Connect Account ID.
A: This is provided by your Luminous account manager, not something you create yourself in Stripe. Contact your account manager if you haven't received it.
Additional Help If you're unable to complete setup or encounter an error not covered here, contact the Luminous support team. Have your Stripe Connect Account ID and the exact error message ready.