> ## 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.

# Board merchants via XML

> Build a Boarding File Upload XML file to create merchants and submit it to Fexco via SFTP.

The Boarding File Upload utility lets you board merchants by
submitting an XML file to Fexco via [Secure File Transfer Protocol
(SFTP)](https://docs.fexco.com/dcc/guides/getting-started/security-setup.md#secure-file-transfer-sftp). Fexco processes the file automatically and returns a response
file with the results.

This guide covers how to build a Boarding File Upload XML file for creating new
merchants. For updating, deactivating, or reactivating existing merchants, see
[Update a boarded merchant](https://docs.fexco.com/dcc/guides/merchant-boarding/update-merchant.md),
[Deactivate a merchant](https://docs.fexco.com/dcc/guides/merchant-boarding/deactivate-merchant.md),
and [Reactivate a merchant](https://docs.fexco.com/dcc/guides/merchant-boarding/reactivate-merchant.md).

## Before you start

You need the following before you can build and submit a Boarding File Upload XML
file.

* [Secure connectivity setup](https://docs.fexco.com/dcc/guides/getting-started/security-setup.md#secure-file-transfer-sftp)
  completed, including SFTP credentials.
* An acquirer ID assigned by Fexco.
* A file group ID and rate margin group name for your merchant
  template.
* The Boarding File Upload XSD schema file provided by Fexco for validation.

> [!NOTE]
>
> If you do not yet have your acquirer ID, file group ID, or rate
> margin group name, contact your Fexco project manager.

## Boarding File Upload XML file structure

An Boarding File Upload XML file has the following structure:

* A `merchantBulkUpload` root element containing one or more
  `acquirer` elements.
* Each `acquirer` element contains `createMerchant`, `updateMerchant`,
  `deleteMerchant`, and `reactivateMerchant` child elements.
* Each `createMerchant` element defines a single merchant record
  with its name, address, originator configuration, and optional
  terminal definitions.

All element and attribute names are case-sensitive and use camelCase
exactly as shown in the example below.

```xml theme={null}
<?xml version="1.0" encoding="UTF-8"?>
<merchantBulkUpload
  xmlns="http://www.fexco.com"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://www.fexco.com
    https://reporting.fexcodcc.com/dais/schema/VanillaMBU_V26.1.xsd">

  <acquirer id="128">
    <createMerchant mcc="7314" id="10000001">
      <name>Cafe Berlin</name>
      <address>
        <line1>Friedrichstrasse 43</line1>
        <line2>Berlin</line2>
        <countryCode>DE</countryCode>
        <postalCode>10117</postalCode>
      </address>
      <originator
        tag="10000001"
        fileGroupId="10154">
        <baseCurrency>978</baseCurrency>
        <rateMarginGroupName>Standard</rateMarginGroupName>
      </originator>
    </createMerchant>
  </acquirer>
</merchantBulkUpload>
```

In most cases the merchant `id` and originator `tag` are the same
value. The example above uses matching values to reflect this.

A merchant can have multiple terminals. Terminals are entirely
optional. See the
[Build the XML file](#build-the-xml-file) step for a more detailed
example.

## File naming convention

Fexco uses the filename to identify the source acquirer and match the
file to the correct processing pipeline. Name your Boarding File Upload XML file using
the following format:

```
MBUXXXYYYYMMDD.hhmmss.XML
```

The table below describes the components of this filename.

| Component | Description |
| :- | :- |
| `MBU` | Fixed prefix (mandatory). |
| `XXX` | Three-letter merchant identifier assigned by Fexco. |
| `YYYYMMDD.hhmmss` | File creation timestamp. `YYYY` = year, `MM` = month, `DD` = day, `hh` = hour, `mm` = minute, `ss` = second. |
| `.XML` | File extension (uppercase). |

For example, a file created on September 20, 2026, at 14:30:00 for
the identifier `ACQ` would be named `MBUACQ20260920.143000.XML`.

## Build and submit the file

Follow the steps below to build your Boarding File Upload XML file, validate it, and
submit it to Fexco.

**Step 1**

### Build the XML file

Create an XML file with one `createMerchant` block per merchant
you want to board. Add multiple `createMerchant` blocks within
the same `acquirer` element to board several merchants at once.
Each merchant is processed independently, so a data error in one
does not affect the others.

The key parts of each `createMerchant` block are:

* `id`: your unique merchant identifier (mandatory).
* `name`: the merchant display name (mandatory).
* `originator`: the DCC configuration for this merchant
  (mandatory). The `tag` attribute is the Merchant ID (MID)
  used for rate service queries and settlement files.
* `address`, `contact`, `bankAccount`, and `terminal` are
  optional.

> [!NOTE]
>
> The `baseCurrency` element uses an [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) numeric currency
> code instead of a three-letter code. For example, `978` is EUR
> and `826` is GBP. See [Currency codes](https://docs.fexco.com/dcc/developer-resources/codes/currency.md) for a reference.

The following example boards a single merchant under acquirer
`128` with one originator and one terminal.

```xml theme={null}
<?xml version="1.0" encoding="UTF-8"?>
<merchantBulkUpload
  xmlns="http://www.fexco.com"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://www.fexco.com
    https://reporting.fexcodcc.com/dais/schema/VanillaMBU_V26.1.xsd">

  <acquirer id="128">
    <createMerchant mcc="7314" id="10000001">
      <name>Cafe Berlin</name>
      <address>
        <line1>Friedrichstrasse 43</line1>
        <line2>Berlin</line2>
        <countryCode>DE</countryCode>
        <postalCode>10117</postalCode>
      </address>
      <originator
        tag="10000001"
        fileGroupId="10154">
        <baseCurrency>978</baseCurrency>
        <rateMarginGroupName>Standard</rateMarginGroupName>
      </originator>
    </createMerchant>
  </acquirer>
</merchantBulkUpload>
```

A merchant can have multiple terminals, but terminals are entirely
optional.

Child elements must appear in the order shown. Use XML entity
references for special characters (for example, `&amp;` for
`&`).

For the full list of elements, attributes, and validation rules,
see
[XML Boarding File Upload format](https://docs.fexco.com/dcc/developer-resources/file-formats/xml-boarding-file-upload.md).

> [!TIP]
>
> Download the [sample Boarding File Upload XML template](https://docs.fexco.com/samples/boarding-xml-template.xml)
> to see the expected file structure. It includes two example
> merchants with different levels of detail.

**Step 2**

### Validate the XML file

Validate your XML file against the Boarding File Upload XSD schema before
submission. Structural or syntactical errors cause the entire
file to be rejected.

See
[Validate an XML file before submission](https://docs.fexco.com/dcc/guides/merchant-boarding/validate-xml.md)
for detailed validation instructions and common schema errors.

**Step 3**

### Submit the file via SFTP

Upload the validated XML file to your dedicated Fexco
[SFTP folder](https://docs.fexco.com/dcc/guides/getting-started/security-setup.md#secure-file-transfer-sftp).
Fexco picks up files from this folder automatically at
a scheduled time.

> [!WARNING]
>
> Submit create requests before update requests. If you need to
> create and update the same merchants, use separate files and
> submit the creation file first.

**Step 4**

### Check the response file

After Fexco processes your file, a response file is placed in
your [SFTP folder](https://docs.fexco.com/dcc/guides/getting-started/security-setup.md#secure-file-transfer-sftp). The response file is named using the same
prefix as your input file, with a `.csv` extension. It is in
CSV format.

The following table describes the key fields in the response
file.

| Field | Description |
| :- | :- |
| `Status Code` | Result code. `200` means success. `400` means a data error. `500` means an internal error. |
| `Merchant Identifier` | The merchant `id` from your XML file. |
| `Merchant Originator` | The originator `tag` from your XML file. |
| `Warning List` | Warning messages separated by `#`, each in `Code\|Title\|Message` format. |
| `Error List` | Error messages separated by `#`, each in `Code\|Title\|Message` format. |

A `200` status code with an empty error list means the merchant
was boarded successfully. A `200` status with warnings means
the merchant was boarded, but some data may be incomplete (for
example, an unrecognized account manager name).

A `400` status means the merchant record was rejected. Correct
the errors and resubmit only the failed records in a new Boarding File Upload
file.

> [!TIP]
>
> Each merchant in the response file has a `200` status code and
> an empty error list. If any merchants failed, correct the data
> and resubmit only the failed records in a new Boarding File Upload file. Do not
> resubmit records that were processed successfully.

## Next steps

* [Validate an XML file before submission](https://docs.fexco.com/dcc/guides/merchant-boarding/validate-xml.md):
  learn how to validate your file against the XSD and resolve
  common schema errors.
* [Update a boarded merchant](https://docs.fexco.com/dcc/guides/merchant-boarding/update-merchant.md):
  modify an existing merchant's configuration using the
  `updateMerchant` element.
* [Deactivate a merchant](https://docs.fexco.com/dcc/guides/merchant-boarding/deactivate-merchant.md):
  deactivate merchants using the `deleteMerchant` element.


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