> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fexco.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Build and submit an I-file

> Build a fixed-length I-file, encrypt it, and submit it to Fexco for DCC transaction reporting.

The I-file is a flat text file with fixed-length records that
you create daily to report DCC and foreign currency transaction
data to Fexco for revenue reporting on Fresh Insights. Each field in
the file must be placed at an exact position, with the correct
length, padding, and data type. You encrypt the file with
[GPG](https://docs.fexco.com/dcc/guides/getting-started/security-setup.md#file-encryption-gpg)
and upload it to Fexco's
[SFTP](https://docs.fexco.com/dcc/guides/getting-started/security-setup.md#secure-file-transfer-sftp)
server. The I-file supports sales and refunds only.

You build the I-file by extracting transaction data from your
payment processing systems and formatting it according to the
record structure described on this page. Fexco recommends using a
code editor with column view (such as [UltraEdit](https://www.ultraedit.com/) or [GNU Emacs](https://www.gnu.org/software/emacs/)) to
verify that each field starts at the correct position. Every
field must be at the exact position specified, with the correct
padding (space-fill or zero-fill). Misaligned fields are a
common cause of file rejections.

## Before you start

You need the following before you build and submit an I-file:

* SFTP credentials and GPG encryption keys, configured through
  [security setup](https://docs.fexco.com/dcc/guides/getting-started/security-setup.md).
* A three-character submitter identifier assigned by Fexco
  during onboarding.
* [Boarded merchants](https://docs.fexco.com/dcc/guides/merchant-boarding/how-it-works.md)
  with merchant IDs that match the IDs in your file.

> [!NOTE]
>
> If you do not have your submitter identifier or SFTP location,
> contact Fexco DCC Support at [DCCSupport@fexco.com](mailto:DCCSupport@fexco.com).

## I-file structure overview

Every I-file follows the same record order. Each record occupies
a single line in the file, with fields at fixed positions. The
following table describes the record types in the order they must
appear:

| Order | Record | Description |
| :- | :- | :- |
| 1 | Volume header (VOL1) | First line. Identifies the submitter and contains the file sequence number. |
| 2 | User header (UHL1) | Second line. Contains the file creation date and work code (`1VOUCHERS`). |
| 3 | Transaction records (J1, J2) | Body of the file. One line per transaction: `J1` for sales, `J2` for refunds. |
| 4 | Subrecords (optional) | Additional data lines that follow their parent transaction. Codes: `07` (MCP), `10` (ICC addendum), `26` (authorization network reference). |
| 5 | Net summary records (E4, E5) | One per merchant, terminal, and currency combination. `E4` when sales equal or exceed refunds. `E5` when refunds exceed sales. |
| 6 | Net claim records (E7, E8) | One per merchant. `E8` when total sales equal or exceed total refunds. `E7` when total refunds exceed total sales. |
| 7 | User trailer (UTL1) | Last line. Contains monetary totals and record count for the entire file. |

> [!WARNING]
>
> The I-file is rejected if records are not in this order. Place
> all transaction records and their subrecords before the summary
> records.

The I-file has two levels of integrity checking. A failure in
either check causes the entire file to be rejected.

* **Financial integrity**: transaction records must total into
  summary records, summary records must total into claim
  records, and claim records must total into the trailer.
* **Logical integrity**: every record must have a sequence
  number starting at `0000001` and incrementing by one, and
  the record count in the UTL must equal the highest sequence
  number.

## File naming convention

Name your I-file using the following format (all uppercase):

```
IXXXYYYYMMDDnnnnnn.DAT
```

The following table describes each component:

| Component | Description |
| :- | :- |
| `I` | Fixed prefix. Must be the first character. |
| `XXX` | Three-character submitter identifier assigned by Fexco. Uppercase if alphabetic. |
| `YYYYMMDD` | File creation date. |
| `nnnnnn` | Six-digit file sequence number. Start at `000001`. Increment by one after each accepted or partially accepted file. Do not increment after a fully rejected file. |
| `.DAT` | File extension. Uppercase. |

For example:

```
IJLB20261020000217.DAT
```

## Build the file

Your system must produce each record type in the correct order.
The following sections describe what each record must contain
and how to verify it. To follow along, download the
[sample I-file](https://docs.fexco.com/samples/transaction-i-file-sample.txt) and
open it in a code editor with column view (such as
[UltraEdit](https://www.ultraedit.com/) or
[GNU Emacs](https://www.gnu.org/software/emacs/)) to verify
your field positions against the column ruler.

**Step 1**

### Start with the volume header (line 1)

The volume header (VOL1) is the first line. It identifies
the submitter and contains a six-digit file sequence number
that must match the `nnnnnn` in the filename.

The sequence number is a counter that you maintain. Start
at `000001` for your first file and increment by one each
time Fexco accepts or partially accepts a file. If Fexco
rejects the file entirely, do not increment. Resubmit
with the same sequence number.

Your system must place the following fields at exact
positions. The line must be exactly 90 characters long,
with space-fill or zero-fill in all unused positions:

| Position | Length | Field | Example value |
| :- | :- | :- | :- |
| 1–3 | 3 | Record identifier. Always `VOL`. | `VOL` |
| 4 | 1 | Record number. Always `1`. | `1` |
| 5–10 | 6 | Six-digit sequence number. Must match the filename. | `000001` |
| 11 | 1 | Reserved. Space-fill. | ` ` |
| 12–26 | 15 | File creation date and time. Format: `yyyymmdd:hhmmss`. | `20261020:143000` |
| 27–79 | 53 | Reserved. Space-fill and zero-fill. | |
| 80 | 1 | Format version. Always `3`. | `3` |
| 81–90 | 10 | Reserved. Space-fill. | |

In the example file, line 1 shows `VOL1000001` at the
start (cols 1–10), the date `20261020:143000` at cols
12–26, and `3` at col 80.

**Step 2**

### Add the user header (line 2)

The user header (UHL1) is the second line. It contains the
file creation date and a fixed work code that identifies
this as a submission file.

| Position | Length | Field | Example value |
| :- | :- | :- | :- |
| 1–3 | 3 | Record identifier. Always `UHL`. | `UHL` |
| 4 | 1 | Record number. Always `1`. | `1` |
| 5–10 | 6 | Creation date in `YYMMDD` format. Must match the date in the filename. | `261020` |
| 11–28 | 18 | Reserved. Zero-fill. | `000000000000000000` |
| 29–37 | 9 | Work code. Always `1VOUCHERS`. | `1VOUCHERS` |
| 38–40 | 3 | Shortened sequence number, the last three digits only. Rolls over from `999` to `000`. | `001` |
| 41–90 | 50 | Reserved. Space-fill. | |

In the example file, line 2 shows `UHL1261020` at the
start, followed by zeros, then `1VOUCHERS001`.

> [!NOTE]
>
> When the three-digit sequence number rolls over from
> `999` to `000`, the full six-digit sequence number in
> the filename and volume header is not affected.

**Step 3**

### Add transaction records (lines 3+)

Each transaction occupies one line (173 characters). Your
system must output one line for every card transaction in
the reporting period, including both DCC and domestic
transactions. Use `J1` for sales and `J2` for refunds.

Transaction records are built from two segments that
cover card, merchant, terminal, transaction, and currency
conversion data. For the field-by-field layout, see the
[I-file format specification](https://docs.fexco.com/dcc/developer-resources/file-formats/i-file.md).

Format all monetary amounts in unsigned minor units as
defined by
[ISO 4217](https://www.iso.org/iso-4217-currency-codes.html),
right-justified, and zero-filled with no decimal point.
See the
[currency precision table](https://docs.fexco.com/dcc/developer-resources/codes/currency-precision.md)
for the correct formatting per currency.

> [!WARNING]
>
> Currencies with zero minor units (for example, JPY, KRW,
> CLP) must be right-padded with `00`. This exception
> applies only to currencies where the minor unit is 0.

**Step 4**

### Include subrecords if needed

Some transactions need an additional line of data (90
characters) immediately after the transaction line to
carry type-specific information. The I-file supports
three subrecord types:

* **[MCP](https://docs.fexco.com/dcc/guides/rate-service/mcp-rate.md) (`07`)**:
  offered currency code and detection method for
  Multi-Currency Pricing transactions.
* **[ICC addendum](https://docs.fexco.com/dcc/guides/getting-started/glossary.md#i) (`10`)**:
  the application currency code read from the card's
  chip during a chip transaction (EMV Tag 9F42). Your
  payment terminal captures this value.
* **[Authorization network reference](https://docs.fexco.com/dcc/guides/getting-started/glossary.md#a) (`26`)**:
  the reference date and trace ID returned in the card
  scheme's authorization response. For Mastercard, this
  is DE 16 (date) and DE 48 Subelement 63 (Trace ID).

For the full field layout of each subrecord type, see
the [I-file format specification](https://docs.fexco.com/dcc/developer-resources/file-formats/i-file.md).
If your transactions do not use subrecords, skip this
step.

A subrecord line sits between the transaction it belongs
to and the next transaction. Every subrecord gets its own
sequence number, which shifts the count for all lines that
follow it. For example:

```
Line 3: Transaction A       (seq 0000001)
Line 4: Subrecord for A     (seq 0000002)
Line 5: Transaction B       (seq 0000003)
```

All three subrecord types share the same core fields:

| Position | Length | Field | Example value |
| :- | :- | :- | :- |
| 1–4 | 4 | Subrecord counter. `0001` for the first subrecord on a transaction, `0002` for the second, and so on. Zero-filled. | `0001` |
| 20–21 | 2 | Transaction code. Identifies the subrecord type: `07`, `10`, or `26`. | `07` |
| 84–90 | 7 | Record sequence number. Continues the file-wide count. Zero-filled. | `0000003` |

> [!NOTE]
>
> Only one subrecord of each type is permitted per
> transaction. A transaction can have multiple subrecords
> of different types (for example, both `07` and `10`),
> each on its own line with its own sequence number.

For the complete field-by-field layout of each subrecord
type, see the
[I-file format specification](https://docs.fexco.com/dcc/developer-resources/file-formats/i-file.md).

**Step 5**

### Calculate summary and claim totals

After all transaction lines, your system must output
totals that Fexco uses to verify the file has not been
corrupted or truncated. If the totals do not match the
transactions, the entire file is rejected.

There are two types:

* **Summary records**: one for each combination of
  merchant, terminal, and currency. The record code
  varies depending on whether sales exceed refunds or
  vice versa.
* **Claim records**: one per merchant. The record code
  varies depending on whether the merchant's total
  sales exceed total refunds or vice versa.

For the record codes and field layouts, see the
[I-file format specification](https://docs.fexco.com/dcc/developer-resources/file-formats/i-file.md).

> [!WARNING]
>
> Do not mix short (11 characters or fewer) and long (12–16
> characters) merchant IDs in the same I-file. All merchant
> IDs in a single file must use the same format.

**Step 6**

### Close the file with the user trailer (last line)

The user trailer (UTL1) is the last line (90 characters).
It contains the grand totals of all claim records and a
count of records in the file. Fexco checks this count
against the sequence numbers. If they do not match, the
file is rejected.

Your system must place the following fields at exact
positions:

| Position | Length | Field | Example value |
| :- | :- | :- | :- |
| 1–3 | 3 | Record identifier. Always `UTL`. | `UTL` |
| 4 | 1 | Record number. Always `1`. | `1` |
| 5–17 | 13 | Grand total of all sale claim amounts, in smallest unit. Zero-padded. | `0000004000000` |
| 18–30 | 13 | Grand total of all refund claim amounts. All zeros if no merchant had more refunds than sales. | `0000000000000` |
| 31–37 | 7 | Count of sale claim records in the file. | `0000001` |
| 38–44 | 7 | Count of refund claim records in the file. | `0000000` |
| 45–54 | 10 | Total record count between the UHL and this line. Must equal the highest sequence number. | `0000000004` |
| 55–90 | 36 | Reserved. Space-fill. | |

In the example file, line 7 shows `UTL1` followed by the
totals. The record count `0000000004` matches the four
records between the UHL and UTL (two transactions, one
summary, one claim).

> [!TIP]
>
> The record count in the trailer must match the highest
> sequence number. If it does not, the file is rejected.

## Submit empty files

If no transactions occurred during the reporting period, you must
still submit an I-file. An empty I-file contains only the volume
header (VOL1), user header (UHL1), and user trailer (UTL1) with
all monetary totals and record counts set to zero.

The empty file must follow the same naming convention and sequence
numbering as a regular file.

## Encrypt and submit the file

Follow the steps below to encrypt and upload your file to Fexco:

**Step 1**

### Encrypt with GPG

As a PCI DSS requirement, encrypt the I-file using GPG before
submission. The encrypted file must use the `.gpg` suffix in
lowercase:

```
IJLB20261020000217.DAT.gpg
```

**Step 2**

### Upload to SFTP

Upload the encrypted file to the `Incoming` folder on your
designated Fexco SFTP server. Fexco picks up files
automatically at a scheduled time.

> [!WARNING]
>
> When submitting multiple files on the same day, collect the
> confirmation file from the previous submission before
> sending the next file.

## Check the confirmation files

After Fexco processes your file, three confirmation files appear
in the `Outgoing` folder on your SFTP server. The following table
describes each file:

| File | Filename | Description |
| :- | :- | :- |
| Confirmation text | `CXXXYYYYMMDDnnnnnn.DAT.TXT` | Human-readable report showing whether the file was accepted, rejected, or partially rejected. |
| Confirmation data | `CXXXYYYYMMDDnnnnnn.DAT` | Mirrors the I-file record format. Contains the processed totals or rejection codes. |
| Currency breakdown report | `AXXXYYYYMMDDnnnnnn.DAT` | Breakdown of file values by currency. |

### Read the confirmation text file

Open the confirmation text file to check the result:

* **Completely accepted**: all transactions were processed.
  Increment the file sequence number for your next submission.
* **Rejected entirely**: the entire file was rejected. The UHL
  line contains an `R` followed by a two-digit rejection code.
  Fix the rejection cause and resubmit with the same sequence
  number. Do not increment.
* **Partially rejected**: some transactions were rejected. The
  UHL line contains a `P`. Accepted transactions are processed.
  Fix the rejected transactions and resubmit them in a new
  file with the next sequence number.

> [!TIP]
>
> The confirmation text file shows "completely accepted." If the
> file was rejected or partially rejected, see
> [Troubleshoot transaction import](https://docs.fexco.com/dcc/guides/transaction-import/troubleshoot.md)
> for the full list of rejection codes and resubmission steps.

## Next steps

After you have submitted your I-file and verified the
confirmation, use the following resources for troubleshooting or
to learn more:

* [I-file format specification](https://docs.fexco.com/dcc/developer-resources/file-formats/i-file.md):
  the complete field-by-field reference for all record types.
* [Troubleshoot transaction import](https://docs.fexco.com/dcc/guides/transaction-import/troubleshoot.md):
  file-level and transaction-level rejection codes.
* [Settlement and commission](https://docs.fexco.com/dcc/guides/transaction-import/settlement.md):
  learn how I-files feed into commission calculation.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.