- SFTP File Delivery
- SFTP File Specification
SFTP File Delivery
SFTP File Specification
Available outbound file types, decryption, and how to consume them.
This guide describes the outbound files Remitian publishes for you through SFTP File Delivery: the rules that apply to every file, and the specification of each file type. To set up your connection and keys, see the SFTP File Delivery guide.
Outbound Files
Remitian can publish different types of outbound files for you. Each file type has its own path, name, and content, described in Available File Types below. All outbound files share the rules in this section.
Location
Your SFTP session opens in your own isolated folder. Every outbound file is published under the /outbound folder, in a path defined by its file type.
Encryption and Signature
Every outbound file is signed with the Remitian signing key and then encrypted with your PGP public key. File names end with .pgp. One gpg command decrypts a file and verifies its signature:
gpg --output <file name without .pgp> --decrypt <file name>.pgp
With the Remitian signing public key imported (see the SFTP File Delivery guide), gpg reports a good signature from Remitian.
- Verification is recommended, not required. If the signature check fails, do not use the file and contact support@remitian.com.
- Check your tool’s exit codes. Some PGP tools return a non-zero exit code when they cannot check a signature, even when decryption succeeds. If your automation stops on non-zero exit codes, import the Remitian signing public key first, and test the full flow in Sandbox before Production.
When Files Are Available
Each file type states when its files are published. There are two ways to know when to download them:
| Option | How it works |
|---|---|
| Polling | Check the expected folder periodically. If the folder or a file is not there yet, poll again later. |
| Webhook | Subscribe to the outboundFile.Published.v1 event in the Webhooks section of the Developer Portal. Remitian notifies your endpoint once for each published file, so you can download it immediately. |
Processing Files
- Files never change. Once published, a file is never replaced or edited. Corrections appear in a later file.
- Process each file once. Keep a record of the files you have processed (for example, the file path), and skip files that are already in it.
- Download within 60 days. Files are kept for 60 days and then removed automatically.
- Read-only access. You can list and download files. You cannot upload, rename, or delete files.
Available File Types
| File Type | Content | Published |
|---|---|---|
| Daily Payment File | The tax payments of one firm for one day | Daily, per firm |
More file types will be added to this list as they become available.
Daily Payment File
One file per firm per day, with that day’s tax payments. Use it to reconcile tax payments in bulk without calling the API for each payment, and to catch up on schedule.* webhook events your system may have missed.
Path and Name
/outbound/{yyyy-mm-dd}/firms/{firm-id}/taxpayments_{firm-id}_{yyyy-mm-dd}.csv.pgp
| Part | Description |
|---|---|
{yyyy-mm-dd} | The date the file covers |
{firm-id} | The id of the firm, as returned by the Manage Firms endpoints |
taxpayments_{firm-id}_{yyyy-mm-dd}.csv.pgp | The file. Its name repeats the firm and the date, so it stays identifiable after you download it. |
Example:
/outbound/2026-11-02/firms/019b2952-c553-7a93-ba57-d3baf8e09cb0/taxpayments_019b2952-c553-7a93-ba57-d3baf8e09cb0_2026-11-02.csv.pgp
Format
| Property | Value |
|---|---|
| Content | The tax payments of one firm for one day |
| Format | CSV with a header row, signed and encrypted (.csv.pgp) |
| Day covered | The calendar day {yyyy-mm-dd} in Eastern time (America/New_York), from 00:00 to 24:00 |
| Published | Early on the following day, Eastern time. Keep polling until the file appears. |
| No activity | A firm with no tax payment created or changed on a date has no file for that date. |
Rows
- One row per tax payment created or changed during the day covered. Any change counts, not only status changes.
- Current state. Each row shows the tax payment as it is when the file is generated, not each change of the day. A tax payment that changed three times appears once.
- All statuses, including
DeletedandDraft. - Same tax payment, many files. A tax payment appears again in the file of every later day on which it changes. Upsert rows by
id. - Order: by
updatedAtascending, then byid.
Columns
A row is the data of the schedule.* webhook events, with the same field names, plus feePullDate, createdAt and updatedAt.
| # | Column | Type | Format and notes |
|---|---|---|---|
| 1 | id | guid | Tax payment identifier |
| 2 | taxpayerId | guid | Taxpayer the payment belongs to |
| 3 | businessId | string | Remitian reference of the tax payment: SC- followed by 12 characters |
| 4 | externalId | string | Your external identifier. Empty when not provided at creation |
| 5 | taxAccountId | guid | Tax account the payment is made against |
| 6 | bankAccountId | guid | Funding bank account. Empty when not set |
| 7 | approverId | guid | Firm user who approved the payment. Empty when not approved |
| 8 | paymentTypeId | integer | See Available Payment Types |
| 9 | status | string | Tax payment status, with the same values as the statuses filter in Schedule Tax Payments |
| 10 | currency | string | ISO 4217 code (USD, CAD) |
| 11 | amount | decimal | 2 decimal places, . as the decimal separator, no thousands separator, no currency symbol. Example: 2300.50 |
| 12 | fee | decimal | Same format as amount |
| 13 | periodEndDate | date | yyyy-MM-dd. Empty when not set |
| 14 | pullDate | date | yyyy-MM-dd. Date the funds are pulled from the bank account |
| 15 | feePullDate | date | yyyy-MM-dd. Date the fee is collected. Empty when not set |
| 16 | submissionDate | date | yyyy-MM-dd. Date the payment is submitted to the tax authority |
| 17 | remitDate | date | yyyy-MM-dd. Date the funds are remitted to the tax authority |
| 18 | paymentDate | date | yyyy-MM-dd. Scheduled payment date |
| 19 | createdAt | timestamp | ISO 8601 in UTC with the Z suffix. Example: 2026-11-02T14:03:21Z |
| 20 | updatedAt | timestamp | ISO 8601 in UTC with the Z suffix. Last change of the tax payment; equals createdAt when it was never changed |
Note: createdAt and updatedAt are in UTC, while the day covered is in Eastern time. A row changed at 2026-11-03T02:48:17Z belongs to the file of 2026-11-02, because that time is still November 2 in Eastern time.
CSV Rules
- RFC 4180: comma delimiter, CRLF line endings, header row always present.
- A field is quoted only when it contains a comma, a double quote or a line break. A double quote inside a field is escaped by doubling it (
""). - UTF-8 without BOM.
- An empty field means no value. The file never contains
NULLor-. - No trailer record, row count or manifest. The PGP signature check fails on a truncated or altered file.
Changes to This File Type
- Read columns by header name, never by position. New columns are added at the end of the row.
- A column is never renamed, removed, retyped or reordered. A breaking change is published as a new file type, with its own name and path.
Template Example
Example of a file with fake data, for one firm and one day:
/outbound/2026-11-02/firms/019b2952-c553-7a93-ba57-d3baf8e09cb0/taxpayments_019b2952-c553-7a93-ba57-d3baf8e09cb0_2026-11-02.csv.pgp
- Template Example (decrypted CSV): Download here
Decrypted content:
id,taxpayerId,businessId,externalId,taxAccountId,bankAccountId,approverId,paymentTypeId,status,currency,amount,fee,periodEndDate,pullDate,feePullDate,submissionDate,remitDate,paymentDate,createdAt,updatedAt
019b3a10-0c6e-7c1a-9d2e-5f1a2b3c4d01,019b2a00-4f21-7b3e-8a9c-1d2e3f4a5b01,SC-7Hk2pQ9vL3mZ,HRB-RT-2026-000123,019b2b00-6a31-7c4f-9b0d-2e3f4a5b6c01,019b2c00-7b41-7d5a-8c1e-3f4a5b6c7d01,019b2d00-8c51-7e6b-9d2f-4a5b6c7d8e01,10101,QueuedForPayment,USD,1250.00,0.00,2025-12-31,2026-11-04,2026-12-07,2026-11-03,2026-11-06,2026-11-06,2026-11-02T14:03:21Z,2026-11-02T14:05:02Z
019b3a10-0c6e-7c1a-9d2e-5f1a2b3c4d05,019b2a00-4f21-7b3e-8a9c-1d2e3f4a5b05,SC-Rt5uJ2kM7xDa,HRB-RT-2026-000140,019b2b00-6a31-7c4f-9b0d-2e3f4a5b6c05,,,10101,PendingClientApproval,USD,900.00,0.00,2025-12-31,2026-11-06,2026-12-10,2026-11-05,2026-11-10,2026-11-10,2026-11-02T19:22:40Z,2026-11-02T19:22:40Z
019b3a10-0c6e-7c1a-9d2e-5f1a2b3c4d02,019b2a00-4f21-7b3e-8a9c-1d2e3f4a5b02,SC-Qm4rT8wX2bNv,HRB-RT-2026-000098,019b2b00-6a31-7c4f-9b0d-2e3f4a5b6c02,019b2c00-7b41-7d5a-8c1e-3f4a5b6c7d02,019b2d00-8c51-7e6b-9d2f-4a5b6c7d8e01,10101,Processed,USD,480.00,0.00,2025-12-31,2026-10-30,2026-12-02,2026-10-29,2026-11-02,2026-11-02,2026-10-28T13:40:07Z,2026-11-02T22:10:45Z
019b3a10-0c6e-7c1a-9d2e-5f1a2b3c4d03,019b2a00-4f21-7b3e-8a9c-1d2e3f4a5b03,SC-Zc9dF1gH5jKs,,019b2b00-6a31-7c4f-9b0d-2e3f4a5b6c03,019b2c00-7b41-7d5a-8c1e-3f4a5b6c7d03,019b2d00-8c51-7e6b-9d2f-4a5b6c7d8e01,10101,Failed,USD,2300.50,2.50,2025-12-31,2026-10-30,2026-12-02,2026-10-29,2026-11-02,2026-11-02,2026-10-27T16:12:55Z,2026-11-02T23:41:09Z
019b3a10-0c6e-7c1a-9d2e-5f1a2b3c4d04,019b2a00-4f21-7b3e-8a9c-1d2e3f4a5b04,SC-Lp3sV6yB8nWq,HRB-RT-2026-000131,019b2b00-6a31-7c4f-9b0d-2e3f4a5b6c04,,,10101,Voided,USD,615.00,0.00,2025-12-31,2026-11-05,2026-12-09,2026-11-04,2026-11-09,2026-11-09,2026-11-01T18:30:12Z,2026-11-03T02:48:17Z
Need Help?
- Email: support@remitian.com
- Response Time: Within 1-2 business days