ZenotiHelp

Processor: Zuora

ZTZenoti Docs Team Updated August 20, 2026 4 min readGuide

Zuora (onboarded through Zenoti's ZPay Lite flow, one of the six V2 onboarding options) is an online-only payment gateway with card saving, auto-save, and automatic Zuora-account creation. Terminals and voids are not supported.

Before you begin

Permission: Organization administrator access is required to configure Zuora.

Zuora-side prerequisites

  • Active Zuora tenant provisioned by Zuora.
  • OAuth client / application created in Zuora Central, with permissions to create accounts, take payments, and tokenize cards.
  • Environment selection β€” Zuora offers a sandbox and a production environment; Base URL values differ.

Credentials

Field Source / owner What to enter
Client ID Zuora Central β†’ Settings β†’ Administration β†’ OAuth clients OAuth client ID for the integration.
Client secret Zuora Central β†’ Settings β†’ Administration β†’ OAuth clients OAuth client secret. Shown once at creation; regenerate if lost.
Base URL Zuora Central Production vs sandbox tenant URL. Using the wrong URL causes every transaction to fail.

Network requirements

Direction Port Protocol Why
Outbound from Zenoti to Zuora API 443 HTTPS Authorise, capture, tokenize, account-create calls
Outbound from guest browser to Zuora Payment Page / hosted card form 443 HTTPS HPP (Hosted Payment Page)-style card collection

Zuora (ZPay Lite) capabilities in Zenoti

Capability Supported
Online card payments Yes
Card saving (stored accounts) Yes
Auto-save (store card on first successful payment) Yes
Automatic Zuora-account creation on first payment Yes
Recurring payments Yes
Refund [SOURCE GAP β€” PM VERIFY: no RefundTransaction override in ZuoraProcessor.cs. Refund support may route through a Zuora-side billing action rather than a Zenoti-initiated refund.]
Void No (no VoidTransaction override)
Terminal (POS (Point of Sale)) No

Capability correction (April 2026): Refund support requires the code caveat below. The Zuora processor class does not override RefundTransaction; refunds in the Zuora model typically occur through a Zuora billing adjustment rather than a processor call. Verify with PM before promising a Zenoti-initiated refund.

Configure Zuora

Zuora uses the V2 onboarding flow (ZPay Lite).

  1. Navigate to Configuration > Payments > Process payments > Payment processor onboarding.
  2. Select Zuora (ZPay Lite).
  3. Enter the Client ID, Client secret, and Base URL.
  4. Assign the processor to the centers where online payment is required.
  5. Select Save.
  6. Select Test to verify.

Toggle interactions

Card saving Auto-create Zuora account Behaviour
Off Off Guest card entry required every time; no Zuora account link.
On Off Card stored after first charge; guest must pre-exist in Zuora.
Off On Zuora account created on first charge, but card not stored.
On On Recommended: Zuora account is created on first successful charge and the card is saved against it for recurring billing.

Process a payment

  1. Guest enters card details at checkout (or uses a stored card).
  2. Zenoti submits the charge to Zuora; on success, Zuora creates / updates the customer account and captures the card.
  3. Zenoti closes the invoice.

Manage stored accounts and refunds

Stored cards live in Zuora's vault. Refund and reversal actions typically require a billing adjustment in Zuora Central. Coordinate with your Zuora admin and record the reference in Zenoti.

Edit or reverse a posted payment

Invoice state What you can do
Open Remove the Zuora payment line if the charge has not yet posted in Zuora. If it has posted, coordinate with the Zuora admin to issue a Zuora-side credit and post a compensating refund in Zenoti.
Closed Same as Open β€” Zuora-side credit is the authoritative reversal action; mirror it in Zenoti as a compensating line.

Failure modes

Failure mode User-visible symptom Resolution
Zuora API unreachable Payment fails with communication error. Check HTTPS and Zuora status.
OAuth token expired / wrong client secret All transactions fail with auth error. Re-verify Client ID / secret in Zuora Central; rotate if needed.
Base URL mismatch (sandbox vs production) Every transaction fails with 404 / unknown tenant. Re-enter the correct Base URL.
Card declined Issuer decline. Guest retries.
Amount out of range Rejected at Zuora or underlying acquirer. Check Zuora billing rules.
Currency mismatch Rejected. Confirm center currency matches Zuora tenant.
Account already exists Zuora returns a conflict when auto-creating an account. Link the existing Zuora account manually and re-try.

Settlement and reconciliation

Zuora is a billing platform; settlement timing depends on the underlying acquirer Zuora routes to. [SOURCE GAP β€” PM VERIFY: acquirer relationship and typical T+N for ZPay Lite.]

Source Report / view Match key
Zenoti Collections report (filter: Payment Method = Zuora) Zuora transaction ID + Zenoti invoice number
Zuora Zuora Central β†’ Payments / Transactions Same fields

Recommended cadence: daily during the first month after go-live; weekly thereafter.

Tips

  • Zuora automatically creates a customer account in Zuora when a guest makes their first payment. Verify this behavior aligns with your Zuora account setup and de-duplication rules.
  • Use the sandbox Base URL during testing and switch to the production URL when going live.
  • Refund / reversal paths typically originate on the Zuora side β€” coordinate with your Zuora admin for the first reversal to confirm the workflow.
Was this article helpful?
Your feedback helps us improve our documentation.