ZenotiHelp

SFTP configuration

ZTZenoti Docs Team Updated August 20, 2026 7 min readGuide

Configure SFTP (Secure File Transfer Protocol) connections when a third-party system exchanges files with Zenoti by depositing to or picking up from an SFTP server. SFTP is a transport channel, not an integration of its own β€” it is typically used by batch-oriented payment processors, accounting-adjacent reconciliation feeds, and specific regional compliance exports.

Audience: Organization administrators setting up a file-exchange channel where a third party has provided SFTP credentials or asked for a public key.

Note: For conceptual background on how integrations are organized in Zenoti, see Integrations Overview.


On this page


Before you begin

Permission: You need organization administrator access to configure SFTP connections.

  • Obtain SFTP credentials (host, port, username, and either password or SSH key material) from the external system that requires SFTP file exchange. Zenoti does not own the SFTP server β€” your counter-party does.
  • Agree with the counter-party on directory paths, file naming conventions, and processing cadence before configuring. SFTP fails quietly if Zenoti writes to an unexpected path.

Network requirements

SFTP traffic originates from Zenoti (outbound) to the counter-party's SFTP server. The counter-party does not connect to Zenoti.

The following table describes the network legs involved:

Leg Direction Protocol Port What to configure
Zenoti β†’ SFTP server Outbound from Zenoti SSH / SFTP 22 (or the custom port provided by the counter-party) Counter-party allows inbound SSH from Zenoti's egress IP range
Administrator β†’ Zenoti Outbound from admin browser HTTPS 443 Standard Zenoti URL access

Because the counter-party must allow inbound SSH from Zenoti, they need Zenoti's current egress IP range. Get this from your Zenoti Support contact β€” the list is environment-specific and can change. Zenoti does not support SFTP over plain FTP or FTPS.


External-system prerequisites

  1. SFTP server provisioned by the counter-party. Zenoti does not host an SFTP server for inbound customer files.
  2. Account and credentials issued. The counter-party creates an account on their SFTP server for Zenoti's use and shares the host, port, username, and either a password or the expected SSH key fingerprint.
  3. SSH key exchange (recommended). If using key authentication:
    • Decide which side generates the key pair. The common pattern is that Zenoti generates the key pair and provides the public key to the counter-party; the counter-party registers it against the Zenoti user on their SFTP server.
    • If the counter-party provides a key, paste the private key material exactly β€” do not edit line endings or re-wrap.
  4. Directory structure agreed. Confirm the exact remote directory for uploads, downloads, and the archive or done folder. Many counter-parties move processed files into an archive; writing to the archive folder directly causes silent reprocessing loops.
  5. File naming conventions agreed. Many counter-parties require a specific prefix, extension, or timestamp format β€” mismatches cause the file to be ignored without error.
  6. Test file exchange. Run a pilot file in both directions (upload and download) before enabling the dependent integration.

If you do not have access to the counter-party's SFTP administrator, open a ticket with Zenoti Support in parallel β€” Support can confirm which values are required and walk through a test exchange, but cannot obtain credentials from the counter-party on your behalf.


Steps

Add an SFTP connection

Important: Confirm all external-system prerequisites above are complete before saving a connection. Saving an incomplete configuration does not cause an immediate error, but the dependent integration will fail silently at runtime.

  1. Navigate to Configuration > Integrations > Integration settings, then expand the SFTP accordion.

  2. Select Create New to open the connection form.

  3. Enter the SFTP connection details:

    Field Source What to enter
    Connection name Zenoti administrator (you choose) A descriptive name that identifies the counter-party and purpose β€” for example, "Reconciliation feed β€” Provider X".
    Host Counter-party SFTP administrator Hostname or IP address of the counter-party's SFTP server.
    Port Counter-party SFTP administrator Typically 22; confirm if the counter-party has changed it.
    Username Counter-party SFTP administrator The account the counter-party created for Zenoti's use.
    Authentication method Zenoti administrator (you choose) Password or SSH key. Use SSH key when the counter-party supports it.
    Password / SSH private key Counter-party SFTP administrator or Zenoti-generated key pair Secret material for the chosen authentication method. Do not reuse a password across connections.
    Remote directory Counter-party SFTP administrator The exact path Zenoti should use for uploads or downloads.
  4. Click Save.

  5. Click Verify to confirm Zenoti can authenticate and reach the configured directory.

Tip: If Verify fails immediately after saving, check for leading or trailing whitespace in the host, username, or key fields. These are the most common causes of an authentication failure on first save.

Worked example

A payment processor requires Zenoti to deposit daily reconciliation files. The processor's SFTP administrator provides the following:

  • Host: sftp.processor-example.com
  • Port: 22
  • Username: zenoti_recon
  • Authentication: SSH key (processor registers Zenoti's public key)
  • Remote directory: /inbound/zenoti/

You enter these values in the connection form, name the connection "Daily reconciliation β€” Processor Example", and click Save. You then click Verify β€” the result shows the connection is active and the directory is reachable. You notify the processor's team that the key is in place and request a test file exchange before enabling the reconciliation feature.


Manage existing connections

  1. Navigate to Configuration > Integrations > Integration settings, then expand the SFTP accordion.
  2. The list shows all configured SFTP connections.
  3. To edit a connection, select its name and update the settings, then click Save.
  4. To remove a connection, select Reset and confirm. Confirm with the counter-party first β€” removing a connection breaks any dependent integration immediately.

Important: Deleting an SFTP connection breaks any Zenoti feature that depends on it at the moment of deletion. There is no grace period or warning at the feature level.


Failure path (SFTP)

The following table lists common failure modes, their symptoms, and how to resolve them:

Failure mode User-visible symptom Resolution
Authentication failed Verify returns "authentication failed" Verify username and password or key exactly as provided by the counter-party. For keys, confirm Zenoti's public key has been registered on the counter-party's server. Leading or trailing whitespace in pasted keys is a frequent cause.
Host unreachable Verify times out Confirm the counter-party allows inbound SSH from Zenoti's current egress IP range. Contact Zenoti Support for the egress range if not already shared with the counter-party.
Path not found Verify authenticates but fails on directory Check the exact remote directory path with the counter-party. Paths are case-sensitive on most SFTP servers.
Permission denied on directory Upload or download fails with "permission denied" Counter-party's SFTP account lacks read or write permission on the target directory. The counter-party administrator must grant it.
File uploaded but counter-party did not pick it up File visible on the server but never processed Check naming convention (prefix, extension, timestamp). Many counter-parties filter by file pattern. Confirm the exact pattern in writing.
Duplicate files processed twice Counter-party reports duplicate reconciliation entries Zenoti is writing into the archive or "done" folder rather than the drop folder. Verify the remote directory path is the inbound folder, not the archive.
Key material corrupted on paste Key looks valid but authentication fails Re-paste the private key from the original source. Do not open the key file in a word processor before pasting β€” line-ending conversions silently corrupt SSH keys.
Port blocked Verify times out on a custom port Confirm the custom port is open on the counter-party's firewall for Zenoti's egress IP range.

Tips

  • Use SSH key authentication rather than passwords for better security and to avoid password expiry breaking the integration.
  • Document which counter-party owns which SFTP connection and which Zenoti feature depends on it. Removing an SFTP connection breaks the feature immediately.
  • Verify the remote directory exists and the SFTP account has the required read and write permissions before saving.
  • Test the connection with a dummy file first in both directions before relying on it for production data.
  • Rotate SFTP credentials at least annually, and immediately when counter-party staff with access leave.
  • Keep a record of the public key you provided to each counter-party. If you need to rotate the key, you must provide the new public key to the counter-party before the old one is removed from their server.

Troubleshooting

The Verify step succeeds but files are not being transferred.

The connection is valid but the dependent integration may not be enabled or scheduled. Confirm that the Zenoti feature using this SFTP connection (for example, a reconciliation export or a compliance feed) is active and that any associated sync schedule is configured. Check the integration's own status screen for errors separate from the SFTP connection itself.

Credentials were rotated by the counter-party and the integration stopped working.

Navigate to Configuration > Integrations > Integration settings, expand the SFTP accordion, select the affected connection, update the password or SSH key with the new credentials, click Save, and then click Verify to confirm the connection is restored.

The counter-party says they received a file but it has the wrong content or format.

SFTP is a transport layer only β€” it does not transform file content. The content and format are controlled by the Zenoti feature that generates the file (for example, a reconciliation export or a compliance module). Contact Zenoti Support and reference the specific integration feature, not the SFTP connection, when reporting a content issue.


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