> ## 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. # XML Boarding File Upload > Field reference, response file format, error and warning codes, and sample XML for the Boarding File Upload boarding format. This reference covers every element, attribute, and code you need to build or validate a Boarding File Upload XML file. For step-by-step submission instructions, see [Board merchants via XML](https://docs.fexco.com/dcc/guides/merchant-boarding/board-xml.md). Sample XML files are available on the [Sample files](https://docs.fexco.com/dcc/developer-resources/sample-files.md) page. ## File naming Fexco uses the filename prefix to identify the source acquirer and route the file to the correct processing pipeline. Using an incorrect or inconsistent filename will cause the file to be rejected or misrouted. Name every Boarding File Upload file using this format: ``` MBUXXXYYYYMMDD.hhmmss.XML ``` The table below describes each component of the filename. | Component | Description | | :- | :- | | `MBU` | Fixed prefix. Mandatory. | | `XXX` | Three-letter acquirer identifier assigned by Fexco. | | `YYYYMMDD` | File creation date. `YYYY` = year, `MM` = month, `DD` = day. | | `.hhmmss` | File creation time. `hh` = hour, `mm` = minute, `ss` = second. | | `.XML` | File extension. Must be uppercase. | ## Character encoding All Boarding File Upload XML files must use UTF-8 encoding. Declare the encoding in the XML declaration on the first line of every file. ```xml theme={null} ``` Files that omit this declaration or use a different encoding may fail schema validation or produce incorrect data. ## File structure An Boarding File Upload XML file consists of a `merchantBulkUpload` root element containing one or more `acquirer` elements. Each `acquirer` element holds `createMerchant`, `reactivateMerchant`, `updateMerchant`, and `deleteMerchant` operations as child elements. When an `acquirer` element contains more than one type of operation, place them in this order: `createMerchant`, `reactivateMerchant`, `updateMerchant`, then `deleteMerchant`. All element and attribute names are case-sensitive and must be written in camelCase exactly as shown in this reference. For example, `createMerchant` is valid but `CreateMerchant` and `create_merchant` are not. > [!WARNING] > > Submit `createMerchant` operations before `updateMerchant` operations. > If you need to create and update the same merchants, use separate > files and submit the creation file first. The `acquirer` element takes a single `id` attribute. This is a positive integer up to 999, assigned by Fexco. Every operation inside the `acquirer` block is associated with this acquirer ID. ## `createMerchant` fields Use the `createMerchant` element to board a new merchant. Each `createMerchant` block defines one merchant record. Add multiple `createMerchant` elements within the same `acquirer` to board several merchants in one file. Each record is processed independently, so a data error in one does not prevent the others from being processed. > [!NOTE] > > The `id` attribute on `createMerchant` is the merchant's unique > identifier in Mercury (used for reporting). The Merchant ID (MID) > used for rate service queries and transaction import files is the > `tag` attribute on each `originator` element. In most cases both > values are the same. ### Merchant attributes The following attributes apply to the `createMerchant` element. | Attribute | Required | Type | Constraints | Description | | :- | :- | :- | :- | :- | | `id` | Mandatory | String | Max 9 characters | Unique merchant identifier in Mercury. Assigned by you. Must be unique per acquirer. In most cases the same value as the originator `tag`. | | `mcc` | Recommended | Integer | 742–9999 | Merchant Category Code (MCC). | | `distributionType` | Optional | Enum | `Terminal`, `Integrated`, `eCommerce`, `Other` | Distribution channel for the merchant. | ### Merchant elements Child elements must appear inside `createMerchant` in the order shown below. The table lists every supported child element. | Element | Required | Type | Constraints | Description | | :- | :- | :- | :- | :- | | `name` | Mandatory | String | Max 128 characters | Merchant name or description. | | `address` | Optional | Element | See [Address elements](#address-elements) | Physical address of the merchant. | | `pspCode` | Optional | String | Exactly 3 characters | Payment service provider (PSP) code. Must be agreed upon with Fexco before use. | | `groupName` | Optional | String | Max 32 characters | Merchant group name. Must already exist in Mercury. Confirm the value with Fexco. | | `accountManagerName` | Optional | String | Max 50 characters | Must match an existing Fexco account manager name. | | `originator` | Mandatory | Element | 1 or more | DCC configuration per base currency and card scheme. See [Merchant originator fields](#merchant-originator-fields). | | `contact` | Optional | Element | Added in v26.1 | Contact details for the merchant. See [Contact elements](#contact-elements). | | `bankAccount` | Optional | Element | Added in v26.1 | Bank account details for settlement. See [Bank account elements](#bank-account-elements). | | `terminal` | Optional | Element | 0 or more | Point of sale (POS) or Automated Teller Machine (ATM) terminal. See [Terminal fields](#terminal-fields). | ### Merchant originator fields An `originator` element represents the Dynamic Currency Conversion (DCC) configuration for one base currency and card scheme combination. Add one `originator` per base currency and card scheme combination; for example, one for Visa EUR and a separate one for Mastercard GBP. The `tag` attribute on `originator` is the Merchant ID (MID) used in rate service queries and transaction import files. It is provided by the integrator. In most cases it matches the merchant `id` attribute. #### Merchant originator attributes The following attributes apply to the `originator` element. | Attribute | Required | Type | Constraints | Description | | :- | :- | :- | :- | :- | | `tag` | Mandatory | String | 4–16 characters | Merchant Originator Tag. This is the MID used in rate service queries and transaction import files. Provided by the integrator. In most cases the same value as the merchant `id`. | | `fileGroupId` | Mandatory | Integer | 1001–19999 | Identifies the set of DCC currencies for this base currency. Assigned by Fexco. | | `description` | Optional | String | Max 64 characters | Human-readable label for this originator, for example `VISA` or `MasterCard`. | | `fmsProduct` | Optional | Enum | `DCC`, `MCP` | Product type for this originator. | | `omnipayMerchantNumber` | Optional | String | Max 16 characters | Required for OmniPay merchants. | #### Merchant originator elements The table below covers the child elements of `originator`. | Element | Required | Type | Constraints | Description | | :- | :- | :- | :- | :- | | `baseCurrency` | Mandatory | Integer | 001–999 | Three-digit [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) numeric currency code. For example, `978` for EUR and `826` for GBP. See [Currency codes](https://docs.fexco.com/dcc/developer-resources/codes/currency.md). | | `rateMarginGroupName` | Mandatory | String | Max 64 characters | Rate margin group applied to this originator. Must be agreed upon with Fexco before use. | | `commissionSplit` | Optional | Element | See [Commission split fields](#commission-split-fields) | Merchant-specific commission split. | > [!NOTE] > > `baseCurrency` uses the ISO 4217 numeric code, not the three-letter > alpha code. For example, use `978`, not `EUR`. #### Commission split fields The `commissionSplit` element is optional under `originator`. The V26.1 XSD also marks each child element below as optional. The XSD does not define how omitted values or combinations are handled by business validation. Confirm those requirements with Fexco. | Element | Required by V26.1 XSD | Description | | :- | :- | :- | | `acquirerPercent` | No | Acquirer commission percentage. | | `merchantProviderPercent` | No | Merchant provider commission percentage. | | `merchantPercent` | No | Merchant commission percentage. | ### Terminal fields Use the `terminal` element to associate a point of sale (POS) or ATM terminal with a merchant. Terminals are optional, and a merchant can have zero or more terminals. The table below covers the `id` attribute and the `location` child element. | Field | Type | Required | Constraints | Description | | :- | :- | :- | :- | :- | | `id` (attribute) | String | Mandatory | 4–11 alphanumeric characters | Unique terminal identifier. | | `location` (element) | String | Optional | Max 40 characters | Physical location description for the terminal. | ### Address elements The `address` element is optional on `createMerchant`. The table below covers all supported child elements of `address`. All fields are optional. | Element | Type | Constraints | Description | | :- | :- | :- | :- | | `line1` | String | Max 60 characters | First line of the street address. | | `line2` | String | Max 60 characters | Second line of the street address. | | `line3` | String | Max 60 characters | Third line of the street address. | | `countryCode` | String | Exactly 2 uppercase letters (A–Z) | [ISO 3166-1](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) alpha-2 country code. See [Country codes](https://docs.fexco.com/dcc/developer-resources/codes/country.md). | | `postalCode` | String | Max 20 characters | Postal or ZIP code. | | `latitude` | Decimal | Up to 8 fraction digits | Decimal latitude of the merchant location. | | `longitude` | Decimal | Up to 9 fraction digits | Decimal longitude of the merchant location. | ### Contact elements The `contact` element was added in v26.1 and is optional. The table below covers the child elements of `contact`. All fields are optional. | Element | Type | Description | | :- | :- | :- | | `name` | String | Full name of the merchant contact. | | `email` | String | Email address of the merchant contact. Must be a valid email format. | ### Bank account elements The `bankAccount` element was added in v26.1 and is optional. The table below covers the child elements of `bankAccount`. All fields are optional. | Element | Type | Description | | :- | :- | :- | | `accountName` | String | Name on the bank account. | | `accountNumber` | String | Bank account number. | | `sortCode` | String | Sort code or routing number. | | `bankName` | String | Name of the bank. | | `addressLine1` | String | First line of the bank address. | | `city` | String | City of the bank. | | `postalCode` | String | Postal code of the bank. | | `countryName` | String | Country of the bank. | ## `updateMerchant` fields Use the `updateMerchant` element to modify an existing merchant record. You identify the merchant by its `id` attribute. The `id` itself cannot be changed. ### Update attributes The following attribute is required on the `updateMerchant` element. | Attribute | Required | Type | Description | | :- | :- | :- | :- | | `id` | Mandatory | String | Merchant ID of the existing record to update. | ### Update elements All update elements are optional. Include only the elements you want to change. The table below lists every supported update element. | Element | Type | Description | | :- | :- | :- | | `newName` | String, max 128 characters | Replaces the merchant name. | | `newAddress` | AddressType | Replaces the merchant address. Use the structured child elements described in [Address elements](#address-elements). | | `newMCC` | Integer, 742–9999 | Replaces the Merchant Category Code (MCC). Recommended when changing business category. | | `newDistributionType` | String | Replaces the distribution type. Accepts the same values as `distributionType` on `createMerchant`. | | `newCommissionSplit` | CommissionSplitType | Changes the acquirer percentage and recalculates the merchant percentage while preserving their existing total. See [Update a commission split](#update-a-commission-split). | | `addTerminal` | Element | Adds a new terminal. The terminal `id` attribute is mandatory. | | `deleteTerminal` | String | Removes a terminal by its terminal ID. | | `addMerchantOriginator` | Element | Adds a new originator. See [Merchant originator fields](#merchant-originator-fields) for required attributes and elements. | | `deleteMerchantOriginator` | String | Removes an originator by its Merchant Originator Tag (`tag` value). | The `newAddress` element uses the same structured child elements as `address`. This example replaces the address lines and country code: ```xml theme={null} 15 Example Street IE D02 XY12 ``` ### Update a commission split For standard XML boarding updates, supply `acquirerPercent` inside `newCommissionSplit`. The service calculates the merchant percentage as the existing acquirer-plus-merchant total minus the new acquirer percentage. This operation does not change that total. Supplying `merchantPercent` or `merchantProviderPercent` does not independently update those percentages through this operation. The new acquirer percentage must be an allowed value for your acquirer, must be non-negative, and must not exceed the existing total for any affected merchant originator. Confirm the configured allowed values with Fexco. > [!WARNING] > > If you include `newCommissionSplit` but omit `acquirerPercent`, the > standard update flow treats the acquirer percentage as zero. It does > not preserve the previous value. Always supply the intended acquirer > percentage explicitly. Omit the entire `newCommissionSplit` element > when you do not want to change the split. After processing, check the response file for errors before treating the update as successful. The XSD's optional fields alone do not establish whether a commission change will be accepted. ## `deleteMerchant` fields Use the `deleteMerchant` element to deactivate a merchant. This is a soft-delete operation: the merchant record is retained for audit and historical reporting purposes and is not permanently removed. To make the merchant active again, use the `reactivateMerchant` operation. The table below covers the single attribute on `deleteMerchant`. | Attribute | Required | Type | Description | | :- | :- | :- | :- | | `id` | Mandatory | String | Merchant ID of the record to deactivate. | ## `reactivateMerchant` fields Use the `reactivateMerchant` element to make a deactivated merchant active again. The following example reactivates one merchant. ```xml theme={null} ``` The table below covers the single attribute on `reactivateMerchant`. | Attribute | Required | Type | Description | | :- | :- | :- | :- | | `id` | Mandatory | String | Merchant ID of the deactivated record to reactivate. | ## Response file format After Fexco processes your Boarding File Upload XML file, a response file is placed in your Secure File Transfer Protocol (SFTP) folder. The response format and filename pattern are configured for your customer. Confirm the configured format, filename prefix, and output folder in your onboarding details. Available response writer formats include CSV and TXT, with versioned variants. For example, if your CSV configuration uses the request base name and a `.csv` extension, a request named `MBUACQ20260920.143000.XML` produces `MBUACQ20260920.143000.csv`. Your configured naming pattern may differ. ### CSV response file fields The table below describes one CSV response layout. Your configured format may use a different layout. | Column | Description | | :- | :- | | `Date` | Date and time Fexco processed the record. | | `Request ID` | Internal Fexco reference for the request. | | `Action` | Operation performed. One of: `CREATION`, `UPDATE`, `DEACTIVATE`. | | `Status Code` | HTTP-style result code. See [HTTP status codes](#http-status-codes). | | `Merchant Identifier` | The merchant `id` value from your XML file. | | `Merchant Originator` | The originator `tag` value from your XML file. | | `Warning List` | Any warnings generated. Each entry uses the format `#Code\|Title\|Message#`. | | `Error List` | Any errors generated. Each entry uses the format `#Code\|Title\|Message#`. | ### HTTP status codes The table below describes the three status codes that appear in the `Status Code` column. | Code | Meaning | Action required | | :- | :- | :- | | `200` | Operation accepted. May include warnings. | Review the `Warning List` column and correct optional data if needed. | | `400` | Operation rejected due to data errors. | Correct the errors in the `Error List` column and resubmit only the failed records. | | `500` | Internal server error. | Contact Fexco at [FMSservicedesk@fexco.com](mailto:FMSservicedesk@fexco.com). | ## Error codes Errors prevent the affected merchant operation from completing. Correct the identified data and resubmit only the failed records in a new Boarding File Upload file. Do not resubmit records that were processed successfully. ### File-level errors File-level errors cause the entire file to be rejected. No merchant records in the file are processed. The table below covers the three file-level error conditions. | Error | Cause | Corrective action | | :- | :- | :- | | File parsing error | File is not valid against the Boarding File Upload XSD schema. | Validate the file against the XSD before resubmitting. See [Validate an XML file before submission](https://docs.fexco.com/dcc/guides/merchant-boarding/validate-xml.md). | | Invalid XML content | XML syntax error, for example a bare `&` character in element content. | Fix the syntax error and use XML entity references for special characters. See [Special characters](#special-characters). | | Invalid distribution type | The `distributionType` value is not recognised. | Contact Fexco at [FMSservicedesk@fexco.com](mailto:FMSservicedesk@fexco.com). | ### Merchant record errors Merchant record errors affect only the individual record that caused them. The table below lists all merchant record error codes. | Code | Message | Applicable operations | Corrective action | | :- | :- | :- | :- | | 1 | Unknown file group | Create, Update | Verify that `fileGroupId` matches the value assigned by Fexco. | | 2 | Unknown base currency for file group | Create, Update | Verify that `baseCurrency` is valid for the specified `fileGroupId`. | | 3 | Unknown rate margin | Create, Update | Verify that `rateMarginGroupName` matches the value configured by Fexco. | | 4 | Merchant Originator Tag repeated | Create, Update | Each `tag` value must appear only once per operation. | | 5 | Merchant Originator Tag belongs to a different merchant | Create, Update | Verify that the `tag` value is correct for this merchant. | | 6 | Merchant already exists | Create | Use `updateMerchant` to modify an existing record. | | 7 | Unknown PSP code | Create | Verify that `pspCode` matches the value configured by Fexco. | | 8 | Merchant does not exist | Update | Verify that the merchant `id` is correct. | | 9 | Merchant is inactive | Update | Reactivate the merchant with `reactivateMerchant` before updating. | | 10 | Merchant originator does not exist | Delete | Verify the `tag` value in `deleteMerchantOriginator`. | | 11 | Merchant already deleted | Delete | Use `reactivateMerchant` if the merchant needs to be active again. | | 16 | Invalid rate margin and base currency combination | Create | Verify that `rateMarginGroupName` and `baseCurrency` are a valid combination for the originator `tag`. | | 17 | No merchant template found due to missing fields | Create, Update | Add the missing fields listed in the error message. | | 18 | No merchant template found | Create, Update | Verify that a template exists for the provided field values. | | 22 | Commission split cannot be updated | Update | Check that `acquirerPercent` does not exceed the existing acquirer-plus-merchant total. See [Update a commission split](#update-a-commission-split), and confirm configured allowed values with Fexco. | | 23 | Unknown acquirer | Create, Update, Delete | Verify the `id` attribute on the `acquirer` element. | ## Warning codes Warnings do not stop the merchant operation from completing. The merchant record is created or updated, but you should review the warning and correct optional data where possible. The table below lists all warning codes. | Code | Message | Applicable operations | Notes | | :- | :- | :- | :- | | 101 | Unknown account manager | Create | `accountManagerName` is optional. Omit the element if the name is unknown. | | 102 | Terminal already exists and is live | Create | Verify the terminal `id` value. | | 103 | Terminal already deleted | Update | Verify the terminal `id` in `deleteTerminal`. | | 104 | Terminal to delete does not exist | Update | Verify the terminal `id` in `deleteTerminal`. | | 105 | Merchant originator already deleted | Update | Verify the `tag` value in `deleteMerchantOriginator`. | | 106 | Merchant originator tag already exists for this merchant | Update | Verify the `tag` value in `addMerchantOriginator`. | | 107 | Unknown merchant group | Create | Confirm the `groupName` value with Fexco. | | 109 | Different rate margin submitted for existing originator | Create, Update | The submitted value is not applied. The existing `rateMarginGroupName` value is kept. | | 110 | Different base currency submitted for existing originator | Create, Update | The submitted value is not applied. The existing `baseCurrency` value is kept. | ## Special characters XML reserves certain characters for markup. If these characters appear in element content or attribute values, you must replace them with their XML entity references. Using a bare reserved character causes an Invalid XML content file-level error. The table below lists the five XML entity references you are most likely to need. | Character | XML entity reference | Example | | :- | :- | :- | | `&` | `&` | `Bath & Body Works` renders as Bath & Body Works. | | `"` | `"` | Used inside attribute values delimited by double quotes. | | `'` | `'` | `Victoria's Secret` renders as Victoria's Secret. | | `<` | `<` | Less-than sign in element content. | | `>` | `>` | Greater-than sign in element content. | ## Sample file The following sample shows a complete Boarding File Upload XML file. It includes two `createMerchant` operations and one `updateMerchant` operation. Cafe Berlin has one originator and one terminal. Harbour View Hotel has two originators and one terminal, and includes contact details. ```xml theme={null} Cafe Berlin
Friedrichstrasse 43 Berlin DE 10117
978 Standard Front desk Harbour View Hotel
1 Harbour Road Dublin IE D02 XY12
978 Standard 826 Standard Jane Smith jane.smith@harbourviewhotel.ie Reception Bar AB123456 ``` ## Next steps The following resources complement this reference. * [Board merchants via XML](https://docs.fexco.com/dcc/guides/merchant-boarding/board-xml.md): step-by-step instructions for building, validating, and submitting a Boarding File Upload XML file via SFTP. * [Validate an XML file before submission](https://docs.fexco.com/dcc/guides/merchant-boarding/validate-xml.md): how to validate your file against the Boarding File Upload XSD schema and resolve common schema errors before submission. * [Sample files](https://docs.fexco.com/dcc/developer-resources/sample-files.md): downloadable XML Boarding File Upload templates and example files you can use as a starting point. * [Field name mapping](https://docs.fexco.com/dcc/developer-resources/codes/field-mapping.md): reference for how XML Boarding File Upload fields map to their equivalents in the REST API, rate service, and transaction import files. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.