Set up a payment processor
Configure a payment processor in Zenoti to accept card, e-wallet, QR, or BNPL (Buy Now, Pay Later) payments at your centers. Zenoti supports over 35 processors across two configuration frameworks: V1 (center-level setup) and V2 (organization-level setup). This article covers the shared setup flow; processor-specific articles cover credentials, capabilities, and failure paths for each processor.
Audience: Organization administrators and center-level payment configuration staff.
On this page
- Before you begin
- V1 vs V2 processors
- Network requirements
- External-system prerequisites
- Set up a V1 processor
- Set up a V2 processor
- Configure terminal hardware
- Verify the integration
- Reconciliation
- Tips
- Troubleshooting
- Related articles
Before you begin
Permission: You need organization administrator access (for V2 processors) or center-level payment configuration permissions (for V1 processors) to set up a payment processor.
- Obtain your processor credentials (API keys, merchant IDs, terminal IDs) from the processor before starting. Zenoti cannot retrieve these on your behalf.
- Decide which centers will use the processor and in which role (primary for card payments, secondary for BNPL or other specialized methods).
- Only one primary processor is active per center. Secondary processors (BNPL, custom payment agents) supplement the primary processor at checkout.
- Confirm regional availability before beginning β not every processor is available in every country, and within a processor, not every payment method is available in every region.
Note: For conceptual background on how payment processors work within Zenoti, see Payment processing overview.
V1 vs V2 processors
The two frameworks are not interchangeable. Use the framework the processor documents β do not attempt to configure a V2 processor through V1 menus or vice versa.
The following table shows which framework each processor uses and where to configure it.
| Framework | Configuration location | Processors |
|---|---|---|
| V1 | Center level β Configuration > Payments > Settings (the center-scope caption of the Payments row) | FreedomPay, Element/Express (Worldpay), BBVA, Moneris, Payworks, Payment Express, AirPay, JusPay, EBS, QNB, eGHL, EzyPay, ZipPay, and others |
| V2 | Organization level β Configuration > Payments > Process payments > Payment processor onboarding | Adyen, Adyen Direct, Stripe, Stripe Connect, ZPay Lite, ICPlus, Xendit, Sunbit, Walletdoc, CaisseAP |
Important: V2 processors are onboarded only at Configuration > Payments > Process payments > Payment processor onboarding. Do not use the V1 path (Configuration > Payments > Settings at center scope) for any processor listed in the V2 column above.
Network requirements
Most cloud-hosted processors (Adyen API, Stripe API, Xendit API, Sunbit API) require only outbound HTTPS from Zenoti, which Zenoti manages. Centers only need to configure their own network when the processor has a local-network component: terminals, WiFi-connected card readers, or webhook listeners.
The following table describes each connection type and when it applies.
| Connection | Direction | Protocol / Port | When this applies |
|---|---|---|---|
| Zenoti to processor API | Outbound from Zenoti (cloud) | HTTPS / 443 | Always β managed by Zenoti. |
| Terminal / reader to processor cloud | Outbound from center WiFi or Bluetooth | HTTPS / 443 | Card-present processors (Adyen terminals, Stripe Connect terminals, Element Express, FreedomPay, etc.). |
| Guest browser to processor hosted payment page | Outbound from guest device | HTTPS / 443 | Hosted payment page flows (Xendit, Sunbit, Walletdoc, Stripe online). |
| Webhook notifications from processor | Inbound to Zenoti | HTTPS / 443 | Any processor that uses asynchronous webhook confirmations (Xendit virtual accounts, Sunbit, Adyen, Stripe). |
For terminal-based processors, whitelist the processor's published API and terminal hosts on the center WiFi before going live.
External-system prerequisites
The specifics differ per processor, but the common pattern is:
- Open a merchant account with the processor and complete their KYC (Know Your Customer) and KYB (Know Your Business) verification.
- Generate API credentials (API keys, client keys, publishable and secret keys, OAuth credentials) in the processor's dashboard. Scope keys to the minimum access the integration needs.
- Register webhook URLs provided by Zenoti Support in the processor's dashboard, where the processor uses webhooks.
- Order and register terminal hardware where applicable. Pair each reader to the correct merchant account and store code.
- Confirm regional availability β not every processor is available in every country, and within a processor, not every payment method is available in every region.
See the processor-specific article for exact field names and steps.
Set up a V1 processor
Configure processor credentials
At the center level, navigate to Configuration > Payments > Settings (the center-scope caption of the Payments row).
Select your payment processor from the available options.
Enter the processor credentials. Each field has a specific source β consult the processor-specific article for exact mapping.
The following table describes the common credential field types and where to obtain each value.
Field type Typical source / owner Merchant ID Processor's merchant account team API key / Secret key Processor dashboard (account owner) Terminal ID Processor's terminal fleet configuration Hash / provider URL Processor's integration documentation Configure additional settings:
- Accept credit cards β enable card acceptance.
- Accept debit cards β enable debit-card acceptance (if supported by the processor).
- Pre-authorize β enable pre-authorization (if supported by the processor).
Select Save.
Select Verify (where available) to validate credentials against the processor.
Tip: For a worked example using eGHL, the Merchant ID comes from your eGHL merchant account, the Password is the merchant secret configured in the eGHL portal, and the Provider URL is the endpoint published in eGHL's integration guide for your region (for example,
https://payment.ipay88.com.my/epayment/entry.aspfor Malaysia). Enter these three values, select Save, then select Verify to confirm connectivity.
Set up a V2 processor
Start the onboarding flow
- At the organization level, navigate to Configuration > Payments > Process payments > Payment processor onboarding.
- Select your V2 processor.
- Follow the onboarding flow, which varies by processor:
- Sunbit β iframe-based per-center onboarding. Each center submits its own merchant application; Sunbit approves each one independently. Prepare your business registration details, bank account information, and center address before starting. The actual form fields are controlled by Sunbit's hosted application. See Processor: Sunbit.
- Adyen / Adyen Direct β enter API credentials and configure terminal assignments. Adyen Direct uses separate accounts per channel. See Processor: Adyen and Processor: Adyen Direct.
- Stripe (standard) β enter publishable and secret keys. Online only. See Processor: Stripe.
- Stripe Connect β OAuth-based; select the option to connect with Stripe to authorize. Supports terminals and BNPL. See Processor: Stripe Connect.
- Xendit β enter secret and public keys, enable per-method payment options. See Processor: Xendit.
- Walletdoc, CaisseAP, ZPay Lite, ICPlus β enter the credentials provided by the payment provider.
- Assign the processor to the centers where it should be active.
- Select Save.
Important: For processors that use hosted or iframe-based onboarding (such as Sunbit), do not attempt to enter manual credential fields. The onboarding form is controlled by the third-party provider. Gather your business information before starting and follow the prompts in the hosted flow.
Multi-center onboarding
Some V2 processors (including Sunbit) require a separate merchant application per center. After completing onboarding for the first center:
- Return to Configuration > Payments > Process payments > Payment processor onboarding.
- Select the same processor.
- Select the next center and complete the onboarding flow for that center.
- Repeat for each center that will use the processor.
Processors that use a single organization-level merchant account (such as Adyen and Stripe Connect) do not require this step β assign additional centers from the processor's configuration page after the initial onboarding.
Configure terminal hardware
Terminal setup applies to any card-present processor.
- Navigate to the terminal management section for the center (within the V1 or V2 configuration page for the processor).
- Add or select the terminal device. Provide any identifier fields required by the processor (terminal ID, serial number, store code).
- Link the terminal to the configured payment processor.
- To update terminal firmware, run the update from the terminal's own menu and enter the firmware update PIN when prompted. Refer to your payment processor's terminal documentation for the current PIN β Zenoti does not publish PIN values.
For supported terminal models by processor, see Configure payment terminals and card readers.
Verify the integration
After saving configuration and before opening to guests:
- Run the Verify action (or Test Connection) where the processor exposes one.
- Create a small test invoice (for example, a $1 service) and process it through the new processor using a real card. Use a real card rather than a test card because live processor environments typically reject test card numbers.
- Confirm the transaction appears in Zenoti's payment dashboard and the processor's dashboard with matching identifiers.
- Refund or void the test transaction immediately in Zenoti and confirm the reversal on the processor side.
- If the processor uses webhooks, confirm the webhook event was received and applied to the invoice.
- Deactivate or delete the test service item used for the test invoice.
The following table covers common failures during verification and how to resolve them.
| Symptom | Likely cause | Resolution |
|---|---|---|
| "Invalid credentials" or authentication error | API key or merchant ID entered incorrectly | Re-enter credentials exactly as shown in the processor dashboard; check for leading or trailing spaces. |
| Terminal not responding | Terminal not paired to the correct merchant account or store code | Verify the terminal ID and store code in the processor's terminal management portal, then re-enter in Zenoti. |
| Network / connectivity error | Center WiFi does not allow outbound HTTPS to the processor's hosts | Whitelist the processor's API and terminal endpoints on the center network. |
| Card declined on test transaction | Card not enabled for the processor's merchant category code | Use a different card or contact the processor to confirm the merchant category code is correctly configured. |
| Webhook not received | Webhook URL not registered in the processor's dashboard | Register the Zenoti webhook URL in the processor's developer or webhook settings, then retry. |
Reconciliation
Reconciliation is a per-processor concern β each processor has its own report in Zenoti and its own dashboard externally. The shared pattern is:
The following table describes each reconciliation layer and the matching key to use.
| Layer | Where | Match key |
|---|---|---|
| Zenoti | Collections by Invoices, filtered to the relevant payment method | Invoice number + processor transaction or PSP reference |
| Processor | Processor's dashboard (Adyen Customer Area, Stripe Dashboard, Xendit Dashboard, Sunbit merchant dashboard) | Processor transaction reference |
| Bank | Processor's settlement or payout report | Merchant reference carrying the Zenoti invoice number |
Recommended cadence: reconcile daily per processor. Multi-MID (Merchant Identifier) processors (Adyen Direct, Stripe Connect) must be reconciled per merchant account, not in aggregate.
For processing payments at the point of sale after setup is complete, see Payment processing.
Tips
- Always process and refund a small live transaction after setup before opening to guests. This confirms the full payment and refund path is working before real guest transactions occur.
- Only one primary processor can be active per center. BNPL processors (Sunbit, Stripe Connect Express BNPL) and custom agents supplement the primary processor at checkout.
- For Sunbit, each center must complete its own onboarding through the Sunbit iframe before the processor is active at that location. Plan for the approval timeline before scheduling a go-live date.
- Document which processor (and variant) serves each center in your internal runbook. During outages the on-call team needs to know exactly which dashboard to check.
- When switching processors, plan a card migration for guests who have stored payment accounts on the old processor. See Migrate cards between processors for the migration workflow.
Troubleshooting
| Problem | Symptom | Resolution |
|---|---|---|
| Processor not appearing in the onboarding list | The processor name is absent from Configuration > Payments > Process payments > Payment processor onboarding | The processor may be a V1 processor β check the V1 vs V2 table above and configure it at center scope at Configuration > Payments > Settings instead. If the processor should be V2 and is still missing, contact Zenoti Support. |
| Payments failing at checkout after setup | Guests or front-desk staff see a payment error at the point of sale | Confirm the processor is assigned to the center, the credentials are saved correctly, and the center's network allows outbound HTTPS to the processor's endpoints. Run the Verify action again and check the processor's dashboard for error codes. |
| Terminal shows "offline" or "not connected" | The terminal cannot communicate with the processor | Confirm the terminal is on the center WiFi, the processor's terminal hosts are whitelisted, and the terminal firmware is up to date. Re-pair the terminal to the merchant account if needed. |
| Refund declined by processor | A refund initiated in Zenoti is rejected by the processor | Some processors require the original transaction to be within a certain age or amount threshold for refunds. Check the processor-specific article for refund limitations and contact the processor's support if the transaction is within the allowed window. |