ZenotiHelp

Processor: Stripe

ZTZenoti Docs Team Updated August 20, 2026 5 min readGuide

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

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

  1. Create and verify a Stripe account in the Stripe Dashboard at dashboard.stripe.com.
  2. Complete Stripe's business verification (tax ID, bank account, representative identity). Stripe cannot issue live keys until verification clears.
  3. In Developers > API keys, locate the Publishable key and the Secret key for live mode.
  4. In Developers > Webhooks, register the webhook endpoint provided by Zenoti Support, and subscribe at minimum to charge.*, payment_intent.*, and refund.* events.

Configure Stripe

  1. Navigate to Configuration > Payments > Process payments > Payment processor onboarding.

  2. Select Stripe.

  3. 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.
  4. Assign the Stripe processor to the centers where online payment is required.

  5. Select Save.

  6. 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.

  1. The guest initiates an online booking or prepayment link.
  2. Zenoti presents Stripe's hosted card element; the guest enters card details.
  3. Stripe tokenises the card and returns a token to Zenoti.
  4. Zenoti creates the charge via the Stripe API.
  5. 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

  1. Open the invoice in Zenoti.
  2. Select Refund and confirm the amount (full or partial).
  3. Zenoti calls Stripe's refund API.
  4. 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.

Was this article helpful?
Your feedback helps us improve our documentation.