Processor: Stripe connect
Stripe Connect is a V2 payment processor that supports in-store card terminals (BBPOS / Stripe Reader), online payments, multi-MID (Merchant Identifier) configurations, BNPL (Buy Now, Pay Later) options (Affirm, Afterpay, Klarna, Clearpay), manual card add, and card migration. It is configured at the organization level via OAuth-based account connection and is the right choice for any business that needs terminal or BNPL support.
Deployment model: This article covers Stripe Connect β OAuth-connected, terminal-capable, multi-MID-capable. It is distinct from Stripe (standard) (direct-key, online-only). Do not mix the two. Pick one and document which is active for each center.
On this page
- Before you begin
- Stripe Connect variants
- Stripe Connect capabilities in Zenoti
- Network requirements
- External-system prerequisites
- Configure Stripe Connect
- BNPL with Stripe Connect
- Automatic card updating
- Feature-toggle interactions
- Refund and void
- Reconciliation
- Handle transaction failures
- Tips
- Related articles
Before you begin
Permission: Organization administrator access is required to configure Stripe Connect.
- You need a Stripe Connect account in a supported region.
- You need Stripe Dashboard access for the account owner to complete the OAuth authorization.
- For terminal payments, identify the reader model per center (BBPOS Chipper 2X BT, BBPOS WisePOS E, Stripe Reader M2) and confirm the region supports it.
- BNPL eligibility depends on your Stripe contract and region. Confirm which BNPL providers Stripe has enabled on your account before offering them at checkout.
Stripe Connect variants
Work with your Zenoti implementation team to choose the variant that matches your region and onboarding model. Each variant corresponds to a different Stripe Connect product in the Stripe Dashboard.
| Variant | Region | Onboarding style |
|---|---|---|
| US | United States | Full Stripe Connect |
| CA | Canada | Full Stripe Connect |
| AUS | Australia | Full Stripe Connect |
| ExpressUS | United States | Express (hosted onboarding) |
| ExpressUK | United Kingdom | Express |
| ExpressAUS | Australia | Express |
| ExpressCA | Canada | Express |
| ExpressUAE | UAE | Express |
| MultiMid | United States | Multi-merchant-ID (separate MIDs per center) |
| MultiMidUK | United Kingdom | Multi-merchant-ID |
If your organisation operates centers in multiple Stripe regions, each region is configured as a separate variant.
Stripe Connect capabilities in Zenoti
| Capability | Supported |
|---|---|
| Sale (POS (Point of Sale) terminal) | Yes |
| Sale (online) | Yes |
| Refund | Yes |
| Void (pre-settlement cancel) | Yes |
| Pre-authorize and capture | Yes |
| Recurring payments | Yes |
| Stored accounts (tokenization) | Yes |
| Manual card add | Yes |
| Automatic card updating | Yes β Stripe's built-in card updater (proactive, not Zenoti's AccountUpdater) |
| BNPL (Affirm, Afterpay, Klarna, Clearpay) | Yes β 5.9% fee per BNPL transaction |
| Multi-MID routing | Yes (MultiMid / MultiMidUK variants) |
| Dispute management | Yes |
| Card migration (from another processor) | Yes |
Network requirements
Stripe Connect handles cloud-to-cloud payments the same way as Stripe (standard), but terminal payments add a local-network requirement at each center.
| Connection | Direction | Protocol / Port | Notes |
|---|---|---|---|
| Zenoti to Stripe API | Outbound from Zenoti (cloud) | HTTPS / 443 | Managed by Zenoti. |
| Terminal (WiFi) to Stripe | Outbound from the center WiFi | HTTPS / 443 | WisePOS E, WisePOS E Cloud. Terminal must reach *.stripe.com over WiFi. |
| Terminal (Bluetooth) to POS device | Local Bluetooth pairing | N/A | Chipper 2X BT, Stripe Reader M2. The POS device itself must then reach Stripe over HTTPS. |
| Webhook notifications from Stripe | Inbound to Zenoti | HTTPS / 443 | Configured once in the Stripe Dashboard for each connected account. |
Wired-only networks and WiFi networks that block outbound HTTPS to Stripe will fail terminal transactions. Whitelist Stripe's documented API and terminal hosts.
External-system prerequisites
- Create a Stripe account and apply for Stripe Connect in the Stripe Dashboard. Express onboarding is handled through Stripe's hosted flow; full Connect requires direct configuration in the Stripe Dashboard.
- For multi-MID variants, provision the individual merchant IDs in Stripe before starting Zenoti configuration. Each MID maps to a separate bank account.
- For terminal support, order certified readers through Stripe or an approved distributor. Register each reader against the correct Stripe account in the Stripe Dashboard.
- Confirm BNPL provider availability with Stripe β not every region or account has Affirm / Afterpay / Klarna enabled by default.
Configure Stripe Connect
Navigate to Configuration > Payments > Process payments > Payment processor onboarding.
Select Stripe Connect and the appropriate regional variant (see above).
Select Connect with Stripe.
Zenoti redirects to Stripe's OAuth authorization flow. Sign in with the Stripe account owner's credentials and authorize Zenoti.
After authorization, Stripe returns you to Zenoti. The connection status shows Connected and the Stripe account ID is recorded.
Field Source / Owner Notes Stripe account ID Stripe (returned by OAuth) Populated automatically after Connect. Variant Zenoti configuration (admin) Must match the regional Stripe product used. Publishable key (sub-account) Stripe Dashboard (for each sub-account under a multi-MID variant) Required per MID when using MultiMid. Configure terminal assignments for each center that takes card-present payments. Pair each reader to a Stripe location and the matching Zenoti center.
Assign Stripe Connect to the centers where it should be active.
Select Save.
BNPL with Stripe Connect
Stripe Connect Express supports Buy Now Pay Later through Affirm, Afterpay, Klarna, and Clearpay, with availability by region. A flat 5.9% fee applies per BNPL transaction.
To enable BNPL:
- In the Stripe Connect configuration, enable Buy Now Pay Later.
- Select which BNPL providers to offer at checkout. Only providers enabled on the underlying Stripe account appear here.
- Select Save.
BNPL is offered to guests during online checkout; it is not presented on in-store terminals. Stripe Express BNPL is a separate integration from Sunbit BNPL β see Processor: Sunbit β with different commercial terms and onboarding.
Automatic card updating
Stripe Connect includes Stripe's own built-in card updating service. When a card network reissues a guest's card (new expiry or new card number), Stripe pushes the new token details to Zenoti in the background β before any charge is attempted. This is a proactive, push-based mechanism and is separate from Zenoti's AccountUpdater batch service.
Stripe's card updater supports Visa and Mastercard. Amex is not supported. For full detail on how this works, supported networks, and what to do when updates fail, see Update card details automatically.
Feature-toggle interactions
Several feature toggles on Stripe Connect can be enabled independently, but the combinations that matter most are BNPL and auto-save. Document your center's intended behaviour before turning them on.
| Auto-save card | BNPL enabled | Resulting behaviour |
|---|---|---|
| Off | Off | One-time card payments only; no token stored, no BNPL offered. |
| On | Off | Card tokens saved for recurring use; no BNPL offered. |
| Off | On | Guests can choose BNPL at online checkout. Card payments do not store a token. |
| On | On | Recurring card billing via stored tokens AND BNPL available at online checkout. BNPL transactions are never auto-saved β they are single loan events. |
Auto-save does not apply to BNPL purchases (each BNPL transaction is an independent loan between the guest and the BNPL provider), so the two toggles do not conflict; they apply to different payment methods at checkout.
Refund and void
Refunds and pre-settlement voids both go through Stripe's Refund API. Zenoti exposes them under a single Refund action; whether a transaction is voided (no net movement) or refunded (post-settlement reversal) depends on the original charge's state in Stripe.
Process a refund or void
- Open the invoice in Zenoti.
- Select Refund and confirm the amount (full or partial).
- Zenoti calls Stripe's refund API against the original
ChargeorPaymentIntent. - Stripe confirms the refund synchronously and sends a webhook for audit.
Dual-perspective behaviour
| System | What it records |
|---|---|
| Zenoti | Refund line on the invoice; payment dashboard shows a negative transaction with the Stripe charge ID. |
| Stripe | A Refund object linked to the original Charge. For pre-settlement transactions, no net capture shows in settlement reports. For post-settlement, the refund appears as a negative amount in the next payout batch. |
Partial refunds and multiple partial refunds are supported up to the captured amount. BNPL refunds follow the same flow β Stripe reverses the loan on the guest's side and settles the merchant for the negative amount.
Reconciliation
| Layer | Source | Match key |
|---|---|---|
| Zenoti | Collections by Invoices report filtered to the Stripe Connect payment method | Invoice number + Stripe charge ID |
| Stripe | Stripe Dashboard > Payments (per connected account) | Charge ID (ch_*) or Payment Intent (pi_*) |
| Bank | Stripe Dashboard > Balance > Payouts | Zenoti invoice number in the metadata |
Recommended cadence: reconcile daily. For multi-MID variants, reconcile each MID separately β payouts land in different bank accounts.
Handle transaction failures
| Failure mode | Symptom | Resolution |
|---|---|---|
| Stripe unreachable | Terminal or POS times out. | Confirm WiFi connectivity at the center and check Stripe's status page. Do not re-charge blindly β check Stripe Dashboard first to confirm whether the charge went through. |
| OAuth token revoked | All charges return an authentication error. | Re-authorize Stripe in Payment processor onboarding > Stripe Connect > Connect with Stripe. |
| Terminal offline | Terminal shows "disconnected" or does not wake. | For WisePOS E, confirm WiFi. For Bluetooth readers, re-pair to the POS device. Check battery on Chipper 2X BT / M2. |
| Card declined | Guest-visible decline on the reader or HPP (Hosted Payment Page). | Ask for an alternative card or payment method. Decline code is in the Zenoti payment log. |
| Amount out of processor range | Stripe rejects below-minimum amounts (regional minimum, typically $0.50 USD). | Aggregate or collect the small amount via another method. |
| Currency mismatch | "Currency not supported for this account". | Stripe accounts are provisioned for specific currencies. Use the variant matching the center's region or add the currency in Stripe. |
| BNPL provider declined | Guest-visible "not approved for financing". | The BNPL provider rejected the application. Offer a different BNPL provider or a regular card. |
| Webhook not received | Refund or dispute in Stripe but not in Zenoti. | Confirm the webhook endpoint is subscribed in Stripe Dashboard > Developers > Webhooks for the connected account. Re-drive the event if needed. |
Tips
- For multi-location businesses with separate bank accounts per location, use the MultiMid variant to route payments to the correct merchant account.
- Card migration from another processor to Stripe Connect is supported. See Migrate cards between processors.
- After the first configuration, run a small test charge on a BBPOS reader at each center and refund it immediately to validate both the connection and the reconciliation path.
- Keep the OAuth session owner's Stripe login active β re-authorizing is the quickest fix if the connection drops.