Processor: Zuora
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).
- Navigate to Configuration > Payments > Process payments > Payment processor onboarding.
- Select Zuora (ZPay Lite).
- Enter the Client ID, Client secret, and Base URL.
- Assign the processor to the centers where online payment is required.
- Select Save.
- 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
- Guest enters card details at checkout (or uses a stored card).
- Zenoti submits the charge to Zuora; on success, Zuora creates / updates the customer account and captures the card.
- 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.