---
title: "Board a merchant onto an acquirer (synchronous)"
method: POST
path: "/merchants/{username}/acquirers"
tags: ["Acquirer connections"]
---

# Board a merchant onto an acquirer (synchronous)

`POST /merchants/{username}/acquirers`

## Request

- Base URL: `https://gateway.pmnts.io/v2/partners`
- URL: `https://gateway.pmnts.io/v2/partners/merchants/{username}/acquirers`
- Auth: HTTP basic

Boards the merchant onto an acquirer synchronously and returns the
resulting connection with `201`. There is no pending state.

You name an `acquirer` (your bank relationship) and the
acquirer-assigned `merchant_id` (MID), plus the
`terminal_id` (TID) when the acquirer needs one. Fat Zebra validates the MID/TID and `currencies`
against its config and boards the merchant onto every processor behind
that acquirer that can carry a requested currency — you never name a
processor. Omit `currencies` to board everything the acquirer supports.

Boarding is idempotent: re-posting the same acquirer returns the
existing connection rather than creating a duplicate.

Failures are reported inline:

* `422 validation_error` — an unsupported currency, a missing
  `merchant_id`, or no
  processor supports the acquirer for the requested currencies. The
  offending fields are listed under `error.fields`.
* `422 processor_error` — an underlying processor board was rejected or
  errored upstream.
* `404 not_found` — the acquirer is unknown or not available to this
  partner.

## Request body

- AcquirerConnectionCreateRequest: Board onto an acquirer. Name the `acquirer` and send the acquirer-assigned `merchant_id` (MID); `terminal_id` (TID) is optional. Fat Zebra validates the MID/TID and `currencies` against its config and boards the merchant onto every supporting processor behind the acquirer — you never name a processor.
  - `acquirer` string, required: Required. Acquirer code (e.g. `nab`).
  - `merchant_id` string, required: The acquirer-assigned MID. Required.
  - `terminal_id` string: The acquirer-assigned TID. Optional. If omitted, Fat Zebra generates a deterministic 8-character placeholder from the merchant's trading name (e.g. `ACMEC001`) and uses it across every processor behind this acquirer. The generated value is returned on subsequent reads, and once set — supplied or generated — it is immutable.
  - `currencies` string[]: Optional. Defaults to every currency the acquirer supports.

## Response `201`

The boarded connection.

- AcquirerConnection: The combined state across every acquirer link provisioned for one acquirer. Boarding is synchronous, so a connection that exists is always boarded.
  - `acquirer_name` string, nullable, required: The acquirer's display name (e.g. `NAB`).
  - `merchant_id` string, nullable: The acquirer-assigned MID (e.g. `ent_a1b2c3d4`).
  - `terminal_id` string, nullable: The acquirer-assigned TID (e.g. `T0001`), or a Fat Zebra-generated 8-character placeholder (e.g. `ACMEC001`) if none was supplied at board time. Immutable once set.
  - `currencies` string[]: Currencies the connection can transact.
  - `schemes` string[]: Networks the merchant can transact for this acquirer.
  - `modes` string[]: Transaction modes the connection supports.
  - `wallets` string[]: Wallets the connection accepts.
  - `three_ds_enabled` boolean: Whether a boarded processor for this acquirer supports 3DS.
  - `status` 'enabled' | 'disabled', required: Routing toggle across the underlying links — disable to turn the connection off without deleting it.

## Other responses

- `401`: Missing or invalid HTTP Basic credentials.
- `404`: Resource not found.
- `422`: The request couldn't be completed. A `validation_error` is something the caller can fix — a bad payload, a merchant that failed validation, or a processor rejecting a field (e.g. the MID); the reason is in `fields`, keyed by a processor-agnostic field name. A `processor_error` is an unactionable upstream failure (a processor was unreachable, busy, or errored); `fields` is empty and the caller should retry or escalate. Raw upstream detail is never surfaced here — only a parsed, processor-neutral reason.

---

[API](https://skmtc.dev/fatzebra/apis/fat-zebra-partner-api.md) - [All operations](https://skmtc.dev/fatzebra/apis/fat-zebra-partner-api/llms.txt) - [OpenAPI document](https://skmtc.dev/fatzebra/apis/fat-zebra-partner-api/revisions/10f1181ea916?raw)