Skip to main content
The Boarding API lets you add merchants to the Fexco DCC system by sending JSON requests over HTTPS. You submit a batch of up to 1,000 merchants in a single request, then poll for results.
The API uses the term “location” in its request and response fields (for example, locationId and locations). In practice, a location is a merchant. This guide uses “merchant” throughout.

Before you start

You need the following before you can submit a boarding request:
  • An OAuth 2.0 access token (client credentials grant).
  • Your acquirer ID, a three-letter code provided by Fexco during onboarding.
  • A template ID for the merchant configuration, provided by Fexco during onboarding.
  • The Boarding API base URL for your environment.
For details on how templates control currencies, commission splits, and DCC/MCP activation, see How merchant boarding works.

Boarding workflow

The boarding workflow has three steps: submit a batch, poll for completion, and review the results.
1

Submit a boarding batch

Send a POST request to Create a batch of boarding requests with an array of merchant objects. Each merchant must include a locationId, name, merchant category code (mcc), and a cardAcceptors array with exactly one card acceptor. A card acceptor represents a merchant identity linked to a template and base currency, it carries the card acceptor ID (MID), template ID, and settlement currency that determine how DCC is configured for that merchant.In most cases, the locationId and cardAcceptorId are the same value. The examples on this page use matching values to reflect this.The following example boards a single merchant with one card acceptor.
The baseCurrency field uses an ISO 4217 numeric currency code instead of a three-letter code. For example, 978 is EUR and 840 is USD. See Currency codes for a reference.
The API returns 202 Accepted with a boardingId. Fexco validates and registers the merchants asynchronously, so the response returns immediately while boarding continues on the server. Save the boardingId to poll for results in the next step.
Each batch can contain up to 1,000 merchants. For larger boarding projects, split the data across multiple requests.
2

Poll the batch status

Send a GET request to Get boarding status to check whether processing is complete.
The status field indicates the batch state. Poll until the status is COMPLETED or FAILED.The following table shows the recommended polling pattern.
3

Review the batch summary

Once the batch status is COMPLETED (or FAILED), send a GET request to Get boarding summary status to see the results for each merchant.
If any merchants failed, the status field shows FAILED and the errors array contains the reason.
A merchant is successfully boarded when it shows "status": "COMPLETED" and "errors": [].You can filter the summary to show only merchants with a specific status by adding the severity query parameter. Valid values are COMPLETED, FAILED, PENDING, PROCESSING, COMPLETED_WITH_WARNINGS, and COMPLETED_WITH_ERRORS.
If any merchants failed, fix the data, and re-submit them in a new batch.

Optional fields

The Create a batch of boarding requests endpoint accepts optional fields that add detail to the merchant record, such as address, group name, contact information, and bank account details. These fields are not needed for boarding to succeed. For the full field reference, including types and validation rules, see the Boarding API reference.
The Boarding API does not support updating merchant details after boarding. To update a boarded merchant, contact your Fexco Key Account Manager (KAM) or use the XML Boarding File Upload method, which requires SFTP setup.

Next steps