XML Boarding File Upload

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. Sample XML files are available on the Sample files 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 version="1.0" encoding="UTF-8"?>

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.

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.

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	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.
`contact`	Optional	Element	Added in v26.1	Contact details for the merchant. See Contact elements.
`bankAccount`	Optional	Element	Added in v26.1	Bank account details for settlement. See Bank account elements.
`terminal`	Optional	Element	0 or more	Point of sale (POS) or Automated Teller Machine (ATM) terminal. See 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 numeric currency code. For example, `978` for EUR and `826` for GBP. See Currency codes.
`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	Merchant-specific commission split.

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 alpha-2 country code. See Country codes.
`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.
`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.
`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 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:

<updateMerchant id="10000001">
  <newAddress>
    <line1>15 Example Street</line1>
    <countryCode>IE</countryCode>
    <postalCode>D02 XY12</postalCode>
  </newAddress>
</updateMerchant>

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.

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.

<reactivateMerchant id="10000001"/>

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

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.
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.
Invalid distribution type	The `distributionType` value is not recognised.	Contact Fexco at 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, 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 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://mercury.fexcodcc.com/dais/schema/VanillaMBU_V26.1.xsd">

  <acquirer id="128">

    <!-- Create merchant 1: Cafe Berlin -->
    <createMerchant id="10000001" mcc="7314" distributionType="Terminal">
      <name>Cafe Berlin</name>
      <address>
        <line1>Friedrichstrasse 43</line1>
        <line2>Berlin</line2>
        <countryCode>DE</countryCode>
        <postalCode>10117</postalCode>
      </address>
      <originator
        tag="012345678"
        fileGroupId="10154"
        fmsProduct="DCC">
        <baseCurrency>978</baseCurrency>
        <rateMarginGroupName>Standard</rateMarginGroupName>
      </originator>
      <terminal id="AB123456">
        <location>Front desk</location>
      </terminal>
    </createMerchant>

    <!-- Create merchant 2: Harbour View Hotel -->
    <createMerchant id="10000002" mcc="5812" distributionType="Terminal">
      <name>Harbour View Hotel</name>
      <address>
        <line1>1 Harbour Road</line1>
        <line2>Dublin</line2>
        <countryCode>IE</countryCode>
        <postalCode>D02 XY12</postalCode>
      </address>
      <originator
        tag="1ACDF45678"
        fileGroupId="10154"
        description="MasterCard"
        fmsProduct="DCC">
        <baseCurrency>978</baseCurrency>
        <rateMarginGroupName>Standard</rateMarginGroupName>
      </originator>
      <originator
        tag="212345678"
        fileGroupId="10155"
        description="VISA"
        fmsProduct="DCC">
        <baseCurrency>826</baseCurrency>
        <rateMarginGroupName>Standard</rateMarginGroupName>
      </originator>
      <contact>
        <name>Jane Smith</name>
        <email>jane.smith@harbourviewhotel.ie</email>
      </contact>
      <terminal id="CD123456">
        <location>Reception</location>
      </terminal>
    </createMerchant>

    <!-- Update merchant 1: add a new terminal and remove the original -->
    <updateMerchant id="10000001">
      <addTerminal id="AC123456">
        <location>Bar</location>
      </addTerminal>
      <deleteTerminal>AB123456</deleteTerminal>
    </updateMerchant>

  </acquirer>

</merchantBulkUpload>

Next steps

The following resources complement this reference.

Board merchants via XML: step-by-step instructions for building, validating, and submitting a Boarding File Upload XML file via SFTP.
Validate an XML file before submission: how to validate your file against the Boarding File Upload XSD schema and resolve common schema errors before submission.
Sample files: downloadable XML Boarding File Upload templates and example files you can use as a starting point.
Field name mapping: reference for how XML Boarding File Upload fields map to their equivalents in the REST API, rate service, and transaction import files.

File formats

Android app

Codes and standards

File naming

Character encoding

File structure

`createMerchant` fields

Merchant attributes

Merchant elements

Merchant originator fields

Merchant originator attributes

Merchant originator elements

Commission split fields

Terminal fields

Address elements

Contact elements

Bank account elements

`updateMerchant` fields

Update attributes

Update elements

Update a commission split

`deleteMerchant` fields

`reactivateMerchant` fields

Response file format

CSV response file fields

HTTP status codes

Error codes

File-level errors

Merchant record errors

Warning codes

Special characters

Sample file

Next steps

File naming

Character encoding

File structure

createMerchant fields

Merchant attributes

Merchant elements

Merchant originator fields

Merchant originator attributes

Merchant originator elements

Commission split fields

Terminal fields

Address elements

Contact elements

Bank account elements

updateMerchant fields

Update attributes

Update elements

Update a commission split

deleteMerchant fields

reactivateMerchant fields

Response file format

CSV response file fields

HTTP status codes

Error codes

File-level errors

Merchant record errors

Warning codes

Special characters

Sample file

Next steps

`createMerchant` fields

`updateMerchant` fields

`deleteMerchant` fields

`reactivateMerchant` fields