Processor: Stripe
Stripe (standard) is an online-only payment processor that supports card saving and account health checks. It does not support card reader terminals, in-store POS (Point of Sale) swipes, or BNPL (Buy Now, Pay Later). For in-store and terminal-based Stripe payments, use Processor: Stripe Connect β a different integration with different capabilities and a different onboarding flow.
Deployment model: this article covers Stripe (standard) β the direct-key integration used for online payments. Stripe Connect (OAuth-based, terminal-capable) is documented separately. Pick the right one before you start configuration; they are not interchangeable.
On this page
- Before you begin
- Stripe capabilities in Zenoti
- Network requirements
- External-system prerequisites
- Configure Stripe
- Process a payment with Stripe
- Refund and void
- Reconciliation
- Handle transaction failures
- Tips
- Related articles
Before you begin
Permission: Organization administrator access is required to configure Stripe.
- You need an active Stripe account in your operating region.
- Stripe (standard) supports online / app-based payments only. If you need terminal support, stop here and use Stripe Connect.
- Confirm the Stripe account is out of test mode and has completed Stripe's identity verification before going live.
Stripe capabilities in Zenoti
| Capability | Supported |
|---|---|
| Online card payments | Yes |
| Card saving (stored accounts) | Yes |
| Recurring payments | Yes |
| Refund | Yes |
| Void (pre-settlement cancel) | Yes |
| Terminal (in-store POS) | No β use Stripe Connect |
| BNPL (Affirm, Afterpay, Klarna) | No β use Stripe Connect Express |
| Pre-authorize and capture | No |
| Manual card add | No |
| Account health check | Yes |
| Automatic card updating | Yes β Stripe's built-in card updater runs proactively outside Zenoti's AccountUpdater batch service |
Network requirements
Stripe (standard) is cloud-to-cloud: Zenoti calls Stripe's API, and the guest's browser posts card details directly to Stripe via the hosted card element. Centers do not need local network configuration for this processor.
| Connection | Direction | Protocol / Port | Notes |
|---|---|---|---|
| Zenoti to Stripe API | Outbound from Zenoti (cloud) | HTTPS / 443 | Managed by Zenoti. |
| Guest browser to Stripe | Outbound from the guest device | HTTPS / 443 | Card details never transit the Zenoti server. |
| Webhook notifications from Stripe | Inbound to Zenoti | HTTPS / 443 | Configured in the Stripe Dashboard once per environment. |
External-system prerequisites
- Create and verify a Stripe account in the Stripe Dashboard at
dashboard.stripe.com. - Complete Stripe's business verification (tax ID, bank account, representative identity). Stripe cannot issue live keys until verification clears.
- In Developers > API keys, locate the Publishable key and the Secret key for live mode.
- In Developers > Webhooks, register the webhook endpoint provided by Zenoti Support, and subscribe at minimum to
charge.*,payment_intent.*, andrefund.*events.
Configure Stripe
Navigate to Configuration > Payments > Process payments > Payment processor onboarding.
Select Stripe.
Enter your Stripe credentials.
Field Source / Owner What to enter Publishable key Stripe Dashboard > Developers > API keys (Stripe account owner) The live-mode publishable key (begins with pk_live_). Used by the card element in the guest browser.Secret key Stripe Dashboard > Developers > API keys (Stripe account owner) The live-mode secret key (begins with sk_live_). Stored encrypted in Zenoti. Never share outside your finance team.Assign the Stripe processor to the centers where online payment is required.
Select Save.
Select Test to verify credentials against Stripe's health check.
Security: The secret key has full API access to your Stripe account. Rotate it if compromised, and re-enter the new value in Payment processor onboarding > Stripe. Zenoti encrypts the key at rest.
Process a payment with Stripe
Stripe (standard) is used for online or app-based payments only.
- The guest initiates an online booking or prepayment link.
- Zenoti presents Stripe's hosted card element; the guest enters card details.
- Stripe tokenises the card and returns a token to Zenoti.
- Zenoti creates the charge via the Stripe API.
- On success, the invoice closes and the token is saved against the guest's profile (for recurring use, if enabled).
Stored cards are charged for membership renewals, package expirations, and other recurring events. The guest's card details never pass through Zenoti's servers.
Refund and void
Refunds and pre-settlement voids both go through Stripe's Refund API; Zenoti exposes them under a single Refund action.
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.
- Stripe confirms the refund synchronously and sends a webhook event for audit.
Dual-perspective behaviour
| System | What it records |
|---|---|
| Zenoti | Refund line on the invoice; payment dashboard shows a negative transaction referencing the original charge ID. |
| Stripe | Separate Refund object linked to the original Charge. For pre-settlement transactions, Stripe records this as refunded with no net capture; post-settlement, the refund appears in the next settlement batch as a negative amount. |
Partial refunds are supported, and multiple partial refunds can be issued up to the original captured amount.
Reconciliation
| Layer | Source | Match key |
|---|---|---|
| Zenoti | Collections by Invoices report filtered to the Stripe payment method | Invoice number + Stripe charge ID (shown in the payment record) |
| Stripe | Stripe Dashboard > Payments | Charge ID (ch_*) or Payment Intent (pi_*) |
| Bank | Stripe Dashboard > Balance > Payouts (per deposit batch) | Zenoti invoice number in the description / metadata |
Recommended cadence: reconcile daily. Stripe settles on a rolling schedule (typically T+2 in the US, varies by region). A Zenoti charge that never appears in Stripe after 10 minutes likely failed silently; check the Zenoti payment log for the webhook event status.
Handle transaction failures
| Failure mode | Symptom | Resolution |
|---|---|---|
| Stripe unreachable | The guest sees a "processing" spinner that times out. | Transient; retry after a moment. If it persists, check Stripe's public status page. |
| Secret key expired / rotated | All charges fail with an authentication error. | Regenerate the key in the Stripe Dashboard and re-enter it in Payment processor onboarding > Stripe. |
| Card declined | Guest-visible decline message on the card element. | Guest retries with a different card. The decline code appears in the Zenoti payment log. |
| Amount out of processor range | Stripe rejects very small amounts (below the regional minimum, typically $0.50 USD). | Combine small charges into a single invoice or collect payment another way. |
| Currency mismatch | Stripe rejects the transaction with "currency not supported". | Each Stripe account is configured for specific currencies. Confirm the center's currency matches the Stripe account's supported currencies, or create a regional Stripe account. |
| Webhook not received | Refund or dispute visible in Stripe Dashboard but not in Zenoti. | Confirm the Zenoti webhook endpoint is subscribed in Developers > Webhooks and that recent deliveries show 2xx responses. Re-drive the event from Stripe if needed. |
| Stored card charge fails | Recurring charge attempt returns "card declined" or "card expired". | If auto-update is enabled, Stripe has already attempted an update β see Update card details automatically. If the card is permanently unusable, collect a new payment method from the guest. |
Tips
- Use the Account Health Check feature on the Zenoti processor configuration to confirm Stripe connectivity before a shift.
- Stripe supports card tokenization for recurring membership and package charges β verify that auto-save is enabled on the Stripe account.
- If your business takes in-store swipes, contactless, or chip payments, switch to Stripe Connect. Stripe (standard) has no terminal support.
- Stripe's built-in card updater keeps stored tokens current between charges without Zenoti intervention. See Update card details automatically for details on what updates, what does not, and how failures surface.