Integrations

The Integrations page is where you connect the outside tools your business already uses to Kribana.

What this does for you

Integrations are organized into four groups:

• Payments & Accounting — Stripe and Razorpay (payment gateways, so invoices and checkouts can collect real payments) and Avalara (automatic sales tax/VAT calculation). QuickBooks is listed here too, marked Coming soon.
• CRM & Sales — HubSpot, marked Coming soon.
• Developer & Checkouts — Wix, Webflow, and Custom Website: embed a lightweight script on your own site's pricing page so visitors can sign up and pay through a Kribana-powered checkout.
• Data Sources — MongoDB, MySQL, and Google Sheets: connect a database or spreadsheet as a usage data source (used by Usage Metering).

Who can use it

This is an admin/team-facing feature. Access is controlled by a single permission on your role: integration.view. There isn't a separate permission for connecting, editing, or disconnecting an integration today — anyone whose role can see the Integrations page can also connect, reconfigure, or disconnect anything on it.

Where to find it

Go to Settings → Integrations.

How to use it

Connect a payment gateway (Stripe or Razorpay)

1. Click Connect on the card.
2. Enter the keys requested — for Stripe: Publishable key, Secret key, and an optional Webhook signing secret; for Razorpay: API key, API secret, and an optional Webhook signing secret — then click Validate & connect. Kribana checks the keys live before saving.
3. Open the connected card's details view to toggle Active and Default payment gateway (used for checkout when more than one gateway is connected).
4. Update keys later with Change keys → Revalidate. Remove a gateway with Disconnect (confirm "Yes, disconnect"), or pause it without losing saved keys by turning off Active (confirm "Make inactive") — turning it back on requires re-entering and re-validating keys.

Set up the payment status webhook (Stripe)

Card payments in the checkout modal confirm instantly, so Kribana already knows the result the moment the customer clicks Pay. US bank account (ACH) payments don't — Stripe has to clear the debit with the customer's bank first, which usually takes a few days. Without a webhook telling Kribana when that clearing finishes, an ACH-paid invoice can sit showing "processing" indefinitely even after Stripe has actually settled it. Setting up the webhook is what closes that loop, and it also feeds Kribana's failed-payment retry emails (see below) the moment a payment is declined, disputed, or refunded.

1. Get your organisation ID. Go to Settings → Organisation Details and copy your org ID (e.g. ORG-015).
2. In your Stripe Dashboard, go to Developers → Webhooks → Add destination. This opens a 3-step wizard:
   • Select events — leave the scope on Your account (not "Connected accounts" — that's only for platforms billing on behalf of other Stripe accounts). Use the search box to find and check each of these four, one at a time (there's no bulk-search for a specific list):
     • payment_intent.succeeded
     • payment_intent.payment_failed
     • charge.dispute.created
     • charge.refunded
       Click Selected events at any point to confirm you've got exactly 4 checked, then Continue.
   • Choose destination type — leave Webhook endpoint selected (the other two, Amazon EventBridge and Azure Event Grid, aren't relevant here) and Continue.
   • Configure destination — give it a Destination name (or keep the auto-generated one), and set Endpoint URL to your Kribana API host plus /api/payments/webhooks/stripe/<your-org-id> — this must be a public https:// URL; Stripe's dashboard will reject http:// or a bare localhost/127.0.0.1 address (ask your engineer for the exact API host if you're not sure — it's not the same as the app URL you log into). The Description field is optional. Click Create destination.
3. Copy the signing secret Stripe shows you right after creating the destination (starts with whsec_) — it's only shown once.
4. Paste it into Kribana. Go to Settings → Integrations → Stripe → Manage API keys & credentials → Change keys, paste the value into Webhook signing secret, and click Revalidate. Do this once per mode — a test-mode endpoint's secret only works with a test-mode endpoint, and likewise for live.

Do this for every org that takes ACH payments — the webhook is org-specific (the URL itself encodes which org it belongs to), not a one-time global setup.

Testing locally, before you have a public URL: the dashboard flow above needs a real https:// address, so it won't work against localhost. For local development, use the Stripe CLI instead — stripe login, then stripe listen --forward-to http://127.0.0.1:5000/api/payments/webhooks/stripe/<your-org-id> --events payment_intent.succeeded,payment_intent.payment_failed,charge.dispute.created,charge.refunded. It prints its own whsec_... secret to paste into step 4 — no dashboard destination needed at all for local testing.

Accept US bank debit (ACH) payments through Stripe

Once Stripe is connected, US customers can pay by linking their bank account directly (ACH direct debit) instead of only by card — usually a lower processing fee, and preferred by some US businesses for larger invoices.

1. Enable it in Stripe. In your Stripe Dashboard, go to Settings → Payment methods and turn on US bank account. Stripe treats test mode and live mode as separate switches — turning it on in test mode lets you try the whole flow with no real money before asking Stripe to activate it on your live account.
2. Check the status in Kribana. Open Settings → Integrations → Stripe and look at the ACH section. A Test mode / Live mode toggle lets you see each mode's status independently — "Enabled" means Stripe will offer US bank account as a payment option in that mode; "Not enabled" means you still need to turn it on in the Stripe Dashboard (step 1) or, for live mode, that Stripe hasn't finished verifying your account for it yet. The same toggle also filters the Billing Methods list below it, so you can see exactly which payment methods are actually live for real customers versus which ones only work in your Stripe test data.
3. Currency requirement. US bank account only applies to USD. A proposal or invoice billed in any other currency will only ever offer card (and whatever other methods you've enabled for that currency).

Where customers see it: on the customer billing portal (the "Pay" step of an invoice), a customer paying a USD invoice will see US bank account as a tab alongside Card and any other enabled methods, and can search for and link their bank the same way they would on Stripe's own checkout pages.

Where it isn't available yet: the proposal "Pay now" flow (a customer accepting and paying for a proposal in one step) is card-only today — this is intentional, not a bug, because that flow provisions a subscription immediately, and bank debits take a few days to clear. Once an invoice exists, its "Pay" step supports US bank account as described above.

Failed payments: automatic retries and customer emails

When a Stripe or Razorpay payment is declined, Kribana doesn't just leave the invoice unpaid and wait — it reads the decline reason and decides what to do next, instead of retrying every failure on the same blind schedule. This runs off the payment status webhook above, so make sure that's set up first.

How the decline is classified:

What the customer sees: at each scheduled retry, Kribana emails the customer a short, reason-specific note — e.g. insufficient funds gets "we'll automatically retry over the next few days, no action needed," while an expired card or a hard decline gets a direct "please update your payment method" ask. These are lightweight nudges, not a re-sent copy of the invoice.

When retries run out: if every scheduled retry has been attempted and the payment still hasn't gone through, Kribana stops retrying and either flags the invoice as needing an alternate payment method (most reasons) or as needing your team to step in directly (fraud/blocked declines). It automatically stops early and marks the payment recovered the moment any payment for that invoice succeeds — through a retry or the customer paying manually — so nobody gets a reminder for something already paid.

Verify it's actually working

Do this in Stripe test mode before relying on it for real customers:

1. Pay a test USD invoice with US bank account, using Stripe's built-in "Test (Non-OAuth)" bank and the Failure or Debit Not Authorized test account instead of "Success" — Stripe's Financial Connections test flow lists these explicitly, no real bank needed.
2. In Stripe Dashboard → Developers → Events, confirm a payment_intent.payment_failed event was generated for that PaymentIntent.
3. In Stripe Dashboard → Developers → Webhooks, open your endpoint and confirm that event shows as delivered (not just generated) — a generated-but-undelivered event means the webhook itself isn't reachable or isn't configured, and nothing below this step will happen.
4. Confirm the decline shows up in Kribana against that invoice, and that the customer received the reason-specific retry email described above.

If step 2 succeeds but step 3 doesn't, revisit Set up the payment status webhook above — the endpoint URL or signing secret is the most common culprit.

Connect Avalara (automatic tax calculation)

1. Click Connect, enter your Account ID, License key, Company code, and choose Sandbox or Production, then Validate & connect.
2. Use the Use Avalara for tax calculation switch to turn Avalara on or off.
3. Fill in and save the Origin address (ship-from) section — required for a valid tax calculation.

Connect a website (Wix, Webflow, Custom Website)

Click Connect to open the setup wizard (6 steps for Wix, 5 for Webflow, 4 for Custom Website). All three wizards cover the same three things — whitelist your pricing page, add button attributes, add the script — with platform-specific instructions for where the script goes.

1. Whitelist your pricing page's origin. The wizard's first step shows an example URL, but doesn't actually take you to where you configure it — that's a separate page: Settings → Configure Self-checkout → Whitelist URLs. Add the exact origin your pricing page is served from (e.g. https://yourwebsite.wixsite.com, not a specific page path). An org that hasn't added any URL here has no enforcement yet; once you add your first entry, only whitelisted origins can complete a checkout.
2. Add both data attributes to every pricing button:

html<button
  data-simplify-plan-id="your-plan-id"
  data-simplify-organisation-id="ORG-015"
>
  Choose Plan
</button>

• data-simplify-organisation-id is filled in automatically by the wizard with your real organisation ID. If it still shows a placeholder, copy the ID from Settings → Organisation Details.
• data-simplify-plan-id has no lookup UI today — it's generated internally as {organisationId}_plan_{number} when the plan is created and isn't shown anywhere on the Plans page. Until that's added, get it from an engineer or the plan's API response.

1. Add the checkout script, placed according to your platform:
   • Wix: Settings → Custom Code → Add Custom Code → paste the script → place in Head → choose pages → Apply → Save.
   • Webflow: Project Settings → Custom Code → paste into Head or Before Body → Save Changes → Publish.
   • Custom Website: paste right after your page's opening <body> tag.

html<script src="https://kribanaloggers.s3.ap-southeast-1.amazonaws.com/logger.js"></script>

Source and deploy: this script (logger.js) is maintained in Simplifyhq/plc, which also has the platform-specific demo pricing pages (Wix, Webflow, Custom Website) used to validate it end-to-end before it's pushed to the kribanaloggers S3 bucket above.

Wix-specific: keep the button and script in the same element

Wix's Settings → Custom Code injects into the parent page document, but a button added through Wix's Add → Embed Code element renders inside its own sandboxed, cross-origin <iframe>. A script injected via Custom Code can't see into that iframe — it finds no button, clicks do nothing, and no checkout request ever fires. This was verified directly on a live Wix site.

Working setup: put the button HTML and the <script src="...logger.js"> tag together inside one Embed Code element (Add → Embed → Embed Code), instead of Custom Code + a separate button. Both then run in the same iframe document, so the script can find and wire up the button.

Change which plans appear on your pricing page

There's no live sync between your Kribana catalog and your embedded page — each button is hard-coded to one data-simplify-plan-id. To change what's offered on your site, edit the buttons directly: add a new button (with that plan's ID and your org ID) to offer a plan, or remove/hide a button to stop offering one.

Separately, Show in self-serve checkout on a plan's Plan Details tab (Catalogue → Plans → open a plan) controls whether that plan appears on Kribana's own hosted checkout/proposal surfaces — it has no effect on buttons already embedded on your own site.

Test your integration end-to-end

Do this on the actual published site, not the platform's editor/preview — some editors (Wix's Site Preview, for example) sandbox iframes in ways that don't reliably match the live page. This checklist mirrors a real run-through we verified working: real org, real plan, real inbox, real redirect to checkout.

1. Confirm the button data is real. Open the button's HTML and check data-simplify-plan-id and data-simplify-organisation-id are an actual plan/org from your Kribana account, not a placeholder left over from setup (a placeholder plan ID surfaces later as a clean "Plan not found" error, not a script failure).
2. Confirm the origin is whitelisted. Settings → Configure Self-checkout → Whitelist URLs must contain the exact origin serving the page (scheme + host, no path). If the button/script run inside a platform-managed iframe with its own separate origin (see the Wix caveat above), whitelist that iframe's origin too, not just the page you see in the browser's address bar — check the iframe's src if the whitelist looks right but you still get "Requests from this origin are not allowed for this organisation."
3. On the live page, click a plan's Choose Plan button — the modal should open with your brand colors, not the default blue.
4. Enter a real email you can check and click Send OTP. A slow first response (several seconds) is expected — the backend retries automatically through cold starts, so this should still resolve to either the OTP-entry screen or a clean inline error banner, never a raw alert() popup or an unstyled browser error.
5. If you get an inline error, it tells you exactly what's wrong: an unwhitelisted origin, an invalid plan/org ID, or a genuine backend issue — fix per steps 1–2 and retry.
6. Check the inbox for the OTP email, then enter the code. You can also paste the whole code into any one of the boxes — it auto-splits across all four and submits automatically.
7. If you didn't get the email, use Resend OTP (enabled 30 seconds after the first send).
8. On success, you're redirected to a real Kribana checkout page (Package details → Billing details → Review & payment) showing the plan you clicked — confirm the plan name and price match what you expected before treating the integration as done.

Connect a data source (MongoDB, MySQL, Google Sheets)

These connect the same way as the equivalent source type on the Usage Sources page — see the Usage Metering & Compilation documentation.

Tips / things to know

• You can only have one default payment gateway at a time — making a second one default automatically un-defaults the previous one, and an inactive gateway can't be made default.
• Disconnecting a gateway removes its saved keys but not the connection record — you'll need to re-enter and re-validate keys to reconnect.
• If Avalara-calculated tax looks wrong or missing, the most common cause is an incomplete origin address.
• QuickBooks and HubSpot are shown today but aren't yet connectable ("Coming soon").
• The payment gateway details view also shows "Allowed payment methods" and "Sync frequency" selects with a Save button — these aren't wired up yet and don't persist a real change. The same is true of the Wix/Webflow/Custom Website integration cards' own "Manage" pages — they show config fields but aren't the source of truth for your embedded checkout (that's the wizard's script/button setup plus the Whitelist URLs page).
• There's no separate permission for editing vs. viewing an integration — anyone with page access can connect, reconfigure, or disconnect anything on it.
• A plan's ID (needed for data-simplify-plan-id) isn't shown anywhere in the Plans UI yet — a known gap, not just an oversight in this doc.
• US bank account (ACH) status in test mode and live mode are genuinely independent in Stripe — enabling it in test mode does not enable it for real customers, and vice versa. Always check both toggles in Kribana's Stripe integration details before assuming it's ready for production.
• The payment status webhook isn't optional if you take ACH payments or want automatic failed-payment retries/emails — without it, Kribana has no way to learn that a bank debit cleared, failed, or was disputed after the customer left the checkout page. A test-mode-only webhook won't do anything for live customers, and vice versa — you need one endpoint (and one signing secret pasted into Kribana) per mode.
• Webflow's free/Starter site plan cannot run the checkout script at all. The Code Embed element, site-wide Custom Code, and page-level Custom Code are all paywalled behind a paid Site plan on that platform — there's no free-tier workaround. Confirm the site has a Site plan with Custom Code unlocked (Project Settings → Custom code) before troubleshooting anything else on a Webflow integration that isn't loading the script.