> ## 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 a V-file

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

The V-file is a flat text file with fixed-length records that you
create daily to submit DCC and domestic transactions to Fexco for
processing and settlement. 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.

You build the V-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 a V-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 and terminal 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).

## V-file structure overview

Every V-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 file and contains the sequence number. |
| 2 | User header (UHL1) | Second line. Contains the file creation date and work code (`1VOUCHERS`). |
| 3 | Transaction records | Body of the file. One line per transaction. Magnetic swipe sales use `J1`, refunds use `J2`. Chip card sales use `P1`, refunds use `P2`. Airline sales use `K1`, refunds use `K2`. Cash advances use `J3`. |
| 4 | Subrecords (optional) | Additional data lines that follow their parent transaction. Codes include `05` (integrated terminal), `06` (UPI/JCB), `07` (MCP), `10` (ICC addendum), `17` (AMEX hospitality), `18` (credentials on file), `39` (contactless), `40` (pay by instalment), `41` (3D Secure). |
| 5 | Net summary records (E4, E5, E6) | One per merchant, terminal, and currency combination. `E4` when sales equal or exceed refunds. `E5` when refunds exceed sales. `E6` for cash advance summaries. |
| 6 | Net claim records (E7, E8) | One per merchant. `E8` when total sales and cash advance summaries equal or exceed refund summaries. `E7` when refund summaries exceed sales and cash advance summaries. |
| 7 | User trailer (UTL1) | Last line. Contains monetary totals and record count for the entire file. |

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

The V-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 V-file using the following format (all uppercase):

```
VXXXYYYYMMDDnnnnnn.DAT
```

The following table describes each component:

| Component | Description |
| :- | :- |
| `V` | 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:

```
VJLB20260920000217.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 V-file](https://docs.fexco.com/samples/transaction-v-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 file 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. | `000217` |
| 11 | 1 | Reserved. Space-fill. | ` ` |
| 12–37 | 26 | Reserved. Space-fill. | |
| 38–47 | 10 | Owner identification. First 10 positions: zero-fill. | `0000000000` |
| 48–51 | 4 | Owner identification (continued). Space-fill. | |
| 52–79 | 28 | Reserved. Space-fill. | |
| 80 | 1 | Format version. Always `3`. | `3` |
| 81–90 | 10 | Reserved. Space-fill. | |

**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. | `260920` |
| 11–28 | 18 | Reserved. Space-fill. | |
| 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`. | `217` |
| 41–90 | 50 | Reserved. Space-fill. | |

> [!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 a single line in the body of the
file. Your system must produce one line for every card
transaction in the reporting period, including both DCC and
domestic transactions.

### Transaction codes

The transaction code at positions 20–21 identifies the card
type and whether the transaction is a sale or refund. The
following table lists the supported codes:

| Card type | Sale | Refund |
| :- | :- | :- |
| Magnetic swipe card | `J1` | `J2` |
| Integrated chip card (ICC) | `P1` | `P2` |
| Airline transaction | `K1` | `K2` |
| Cash advance | `J3` | n/a |

> [!NOTE]
>
> DCC is not permitted on cash advance (`J3`) transactions
> per compliance requirements.

Transaction records are built from segments that vary by
transaction type. For the segment combinations and
field-by-field layouts, see the
[V-file format specification](https://docs.fexco.com/dcc/developer-resources/file-formats/v-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
immediately after the transaction line to carry
type-specific information. Common subrecord types
include:

* **[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.
* **Contactless (`39`)**: contactless-specific data
  captured by the payment terminal during a tap
  transaction.

The V-file supports additional subrecord types. For the full
list and field layouts, see the
[V-file format specification](https://docs.fexco.com/dcc/developer-resources/file-formats/v-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 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 (for example, `05`, `07`, `10`). | `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 `39`),
> each on its own line with its own sequence number.

**Step 5**

### Calculate summary and claim totals

After all transaction lines, your system must produce
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, and whether the summary covers cash
  advances.
* **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
[V-file format specification](https://docs.fexco.com/dcc/developer-resources/file-formats/v-file.md).

> [!WARNING]
>
> Do not mix short (11 characters or fewer) and long (12–16
> characters) merchant IDs in the same V-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–80 | 26 | Reserved. Space-fill. | |
| 81–90 | 10 | Reserved. Space-fill. | |

> [!TIP]
>
> The record count in the trailer must match the highest
> sequence number. If it does not, the file is rejected.
> See
> [Troubleshoot transaction import](https://docs.fexco.com/dcc/guides/transaction-import/troubleshoot.md)
> for rejection codes and resubmission steps.

## Submit empty files

If no transactions occurred during the reporting period, you must
still submit a V-file. An empty V-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 V-file using GPG
before submission. The encrypted file must use the `.gpg`
suffix in lowercase:

```
VJLB20260920000217.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 V-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 V-file and verified the
confirmation, use the following resources for troubleshooting or
to learn more:

* [V-file format specification](https://docs.fexco.com/dcc/developer-resources/file-formats/v-file.md):
  the complete field-by-field reference for all segments and
  subrecords.
* [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 V-file data feeds into settlement and commission
  calculation.


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