> ## 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 the Boarding API

> Submit, track, and verify merchant boarding batches using the Boarding API.

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.

> [!NOTE]
>
> 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](https://docs.fexco.com/dcc/api-reference/authentication/oauth.md) (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](https://docs.fexco.com/dcc/api-reference/environments.md) for your environment.

> [!NOTE]
>
> For details on how templates control currencies, commission splits,
> and DCC/MCP activation, see
> [How merchant boarding works](https://docs.fexco.com/dcc/guides/merchant-boarding/how-it-works.md#templates).

## Boarding workflow

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

**Step 1**

### Submit a boarding batch

Send a `POST` request to [Create a batch of boarding requests](https://docs.fexco.com/dcc/api-reference/boarding-rest/create-boarding-batch.md) 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.

> [!NOTE]
>
> The `baseCurrency` field 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
> `840` is USD. See [Currency codes](https://docs.fexco.com/dcc/developer-resources/codes/currency.md) for a reference.

> [tab] Request
>
> ```bash theme={null}
> curl -X POST https://BOARDING_API_BASE_URL/v1/boarding \
>   -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
>   -H "x-acquirer-id: YOUR_ACQUIRER_ID" \
>   -H "Content-Type: application/json" \
>   -d '[
>     {
>       "operation": "CREATE",
>       "location": {
>         "locationId": "MID12345678",
>         "name": "Cafe Berlin",
>         "mcc": 5814,
>         "cardAcceptors": [
>           {
>             "cardAcceptorId": "MID12345678",
>             "templateId": 1,
>             "baseCurrency": 978
>           }
>         ],
>         "address": {
>           "lineOne": "12 Friedrichstrasse",
>           "city": "Berlin",
>           "country": "DE"
>         }
>       }
>     }
>   ]'
> ```

> [tab] Response
>
> ```json theme={null}
> {
>   "boardingId": "26aad567-edee-4a74-97ba-1bd8232fbf15",
>   "status": "ACCEPTED",
>   "submittedAt": "2026-09-20T15:15:42.193Z"
> }
> ```

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.

> [!NOTE]
>
> Each batch can contain up to 1,000 merchants. For larger
> boarding projects, split the data across multiple requests.

**Step 2**

### Poll the batch status

Send a `GET` request to [Get boarding status](https://docs.fexco.com/dcc/api-reference/boarding-rest/get-boarding-status.md) to check
whether processing is complete.

> [tab] Request
>
> ```bash theme={null}
> curl -X GET https://BOARDING_API_BASE_URL/v1/boarding/{BOARDING_ID} \
>   -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
>   -H "x-acquirer-id: YOUR_ACQUIRER_ID"
> ```

> [tab] Response
>
> ```json theme={null}
> {
>   "boardingId": "26aad567-edee-4a74-97ba-1bd8232fbf15",
>   "status": "COMPLETED",
>   "submittedAt": "2026-09-20T15:15:42.193Z",
>   "completedAt": "2026-09-20T15:16:12.481Z",
>   "batchSummary": {
>     "total": 1,
>     "completed": 1,
>     "errors": 0,
>     "warnings": 0
>   }
> }
> ```

The `status` field indicates the batch state. Poll until the
status is `COMPLETED` or `FAILED`.

The following table shows the recommended polling pattern.

| Poll attempt | Wait before next poll |
| :- | :- |
| First check | 30 seconds after submission. |
| Subsequent checks | Increase wait by 50% each time (30s, 45s, 67s, 100s, 150s, 225s, 300s). |
| Maximum interval | 5 minutes between polls. |
| Timeout | Stop after 1 hour total. |

**Step 3**

### Review the batch summary

Once the batch status is `COMPLETED` (or `FAILED`), send a `GET`
request to [Get boarding summary status](https://docs.fexco.com/dcc/api-reference/boarding-rest/get-boarding-summary.md) to see the
results for each merchant.

> [tab] Request
>
> ```bash theme={null}
> curl -X GET "https://BOARDING_API_BASE_URL/v1/boarding/{BOARDING_ID}/summary?page=1&pageSize=50" \
>   -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
>   -H "x-acquirer-id: YOUR_ACQUIRER_ID"
> ```

> [tab] Response
>
> ```json theme={null}
> {
>   "boardingId": "26aad567-edee-4a74-97ba-1bd8232fbf15",
>   "locations": [
>     {
>       "locationId": "MID12345678",
>       "status": "COMPLETED",
>       "errors": [],
>       "warnings": []
>     }
>   ],
>   "pagination": {
>     "page": 1,
>     "size": 50,
>     "totalElements": 1
>   }
> }
> ```

If any merchants failed, the `status` field shows `FAILED` and
the `errors` array contains the reason.

```json theme={null}
{
  "locationId": "LOC002",
  "status": "FAILED",
  "errors": [
    {
      "code": "100",
      "title": "Validation Error",
      "message": "MCC is required"
    }
  ]
}
```

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

```bash theme={null}
curl -X GET "https://BOARDING_API_BASE_URL/v1/boarding/{BOARDING_ID}/summary?severity=FAILED&page=1&pageSize=50" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-acquirer-id: YOUR_ACQUIRER_ID"
```

If any merchants failed, fix the data, and re-submit them in a new batch.

## Optional fields

The [Create a batch of boarding requests](https://docs.fexco.com/dcc/api-reference/boarding-rest/create-boarding-batch.md) 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](https://docs.fexco.com/dcc/api-reference/endpoints/merchant-boarding).

> [!NOTE]
>
> 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](https://docs.fexco.com/dcc/guides/merchant-boarding/update-merchant.md),
> which requires
> [SFTP setup](https://docs.fexco.com/dcc/guides/getting-started/security-setup.md).

## Next steps

* [Deactivate a merchant](https://docs.fexco.com/dcc/guides/merchant-boarding/deactivate-merchant.md):
  remove a merchant from active DCC participation.
* [How merchant boarding works](https://docs.fexco.com/dcc/guides/merchant-boarding/how-it-works.md):
  review how templates, identifiers, and the boarding lifecycle fit
  together.
* [Troubleshoot merchant boarding](https://docs.fexco.com/dcc/guides/merchant-boarding/troubleshoot.md):
  resolve common boarding errors and warnings.


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