> For the complete documentation index, see [llms.txt](https://developers.bead.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.bead.xyz/entity-management/merchant-management/get-merchant.md).

# Get Merchant

Retrieves the complete profile of a single merchant, including company details, tender types, fee settings, and membership list.

#### Endpoint

```
GET /Merchants/{id}
```

#### Authentication

```
X-Api-Key: {adminApiKey}
```

#### Path parameters

| Name | Type   | Required | Description                               |
| ---- | ------ | -------- | ----------------------------------------- |
| `id` | string | Yes      | The `merchantId` assigned during boarding |

#### Request headers

| Header      | Value              |
| ----------- | ------------------ |
| `X-Api-Key` | `{adminApiKey}`    |
| `Accept`    | `application/json` |

#### Example request

```bash
curl -X GET "https://api.test.devs.beadpay.io/Merchants/{merchantId}" \
-H "X-Api-Key: {adminApiKey}"
```

#### Successful response

A `200` wraps the merchant record in two parts: `merchant` (core record) and `details` (extended KYB details, or `null` if not available). This is the same shape returned by [List Merchants](https://developers.bead.xyz/entity-management/merchant-management/list-merchants.md) at `data[].merchant` and `data[].details`.

The `merchant` object carries the core record:

```json
{
  "displayId": "M001667",
  "partnerId": "690e2895852fff2eff800c68",
  "companyName": "Acme Coffee Roasters",
  "description": "West-coast cafe chain",
  "taxNumberType": "ein",
  "isSettlementOnly": false,
  "isCommissionMerchant": false,
  "status": "active",
  "isSplitFundingEnabled": false,
  "feeInformation": {
    "achSettlementFixedFee": { "sellRate": 0.5, "isBilledByPartner": false },
    "settlementReturnFixedFee": { "sellRate": 25.0, "isBilledByPartner": false },
    "monthlyMaintenanceFee": null,
    "cryptoFees": [
      {
        "tenderType": "bitcoin",
        "transactionRate": { "sellRate": 3.5, "isBilledByPartner": false },
        "perItemFee": { "sellRate": 0.25, "isBilledByPartner": false }
      },
      {
        "tenderType": "usdcBase",
        "transactionRate": { "sellRate": 3.5, "isBilledByPartner": false },
        "perItemFee": { "sellRate": 0.25, "isBilledByPartner": false }
      }
    ],
    "digitalWalletsFees": [
      {
        "tenderType": "cashApp",
        "transactionRate": { "sellRate": 0.0, "isBilledByPartner": false },
        "perItemFee": { "sellRate": 0.0, "isBilledByPartner": false }
      }
    ]
  },
  "maxTransactionAmount": null,
  "memberships": [],
  "representsPartnerId": null,
  "isPinned": false,
  "receivableCurrencyIds": [1],
  "feeInfo": null,
  "settlementBeneficiary": { "type": "self", "partnerId": "690e2895852fff2eff800c68" },
  "tenderTypes": ["usdcBase", "usdcSolana", "bitcoin", "bitcoin_Lightning"],
  "id": "697109947a7f738950a8428d",
  "created": "2026-01-21T17:15:00Z",
  "updated": "2026-05-08T18:40:01.925Z"
}
```

The `details` object carries the extended KYB record: legal and DBA name, registration date, entity type, NAICS and MCC codes, seasonality, revenue and ticket-size figures, business website, email and phone, mailing address, proof-of-business type, main point of contact, and the merchant's banking details. Banking values are masked in the response.

`receivableCurrencyIds` contains integer IDs from the `/currencies` endpoint. `1` represents USD.

#### Key fields

| Field                               | Description                                                                                                                                                                                                                                                                                        |
| ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `merchant`                          | Core merchant record                                                                                                                                                                                                                                                                               |
| `details`                           | Extended KYB details, or `null` if not available                                                                                                                                                                                                                                                   |
| `tenderTypes`                       | Default rails every child location inherits unless overridden at the location or terminal                                                                                                                                                                                                          |
| `receivableCurrencyIds`             | Settlement currencies, matched against IDs from `/currencies`                                                                                                                                                                                                                                      |
| `feeInfo`                           | Nullable. Observed as `null` on merchants. It has the same `crypto` and `card` flat-rate shape used for partner creation and updates. Do not use it for per-asset crypto pricing.                                                                                                                  |
| `feeInformation.cryptoFees`         | Per-asset crypto fee breakdown. Each `tenderType` has its own `transactionRate` and `perItemFee`.                                                                                                                                                                                                  |
| `feeInformation.digitalWalletsFees` | Per-tender-type fees for wallet rails, or `null` when none are configured.                                                                                                                                                                                                                         |
| `status`                            | Boarding state: `unverified`, `active`, `locked`, `restricted`, `inactive`, `suspended`, `terminated`, or `closed`                                                                                                                                                                                 |
| `isSplitFundingEnabled`             | Whether the merchant is enrolled in the [Split Funding Program](https://developers.bead.xyz/split-funding.md). Returned on the flat `merchant` node, not inside `details`. Set it through [Update Merchant](https://developers.bead.xyz/entity-management/merchant-management/update-merchant.md). |
| `memberships`                       | Users and roles that manage this merchant in the dashboard                                                                                                                                                                                                                                         |

> **The old field name is not aliased.** `setRebateProgramEnabled` was renamed to `setSplitFundingEnabled`. A request that still sends `setRebateProgramEnabled` is dropped by the deserializer and returns a successful `200` with nothing enabled, so reading the merchant back and checking `isSplitFundingEnabled` is the only reliable confirmation that enrollment applied.

> **The banking details on this record are the merchant's account on file.** On the [Split Funding Program](https://developers.bead.xyz/split-funding.md) this is the only account the merchant portion can be settled to. It cannot be overridden on a payment.

#### feeInfo compared with feeInformation.cryptoFees

`feeInfo` and `feeInformation` are both live fields in the API, and `feeInfo` is not deprecated. In practice, `feeInfo` is returned as `null` on merchants. The same `feeInfo` shape is used as required input on partner creation and update, so it most likely reflects partner-level terms rather than something set per merchant. `feeInformation.cryptoFees` is the field that is populated on merchants and carries the actual per-`tenderType` breakdown, where each entry has its own `transactionRate` (percentage) and `perItemFee` (fixed). If you need to know what a merchant is charged for bitcoin versus USDC specifically, read `feeInformation.cryptoFees`.

#### Error responses

| Code  | Condition                                                    |
| ----- | ------------------------------------------------------------ |
| `401` | Missing or invalid API key                                   |
| `403` | Authenticated but not permitted to access this merchant      |
| `404` | Merchant `{id}` does not exist or is not visible to your key |

#### Best practices

* Cache the response for dashboard sessions. Merchant profiles rarely change during a user session.
* Use the `updated` timestamp to decide when to invalidate local copies.
* Check `status` before enabling production payment traffic. The merchant must be `active`.
* Respect `maxTransactionAmount` when building POS flows to prevent declines on oversize transactions.
* Read `feeInformation.cryptoFees` for the fee on a specific crypto asset. `feeInfo` is typically `null` on merchants.
* Check `isSplitFundingEnabled` on the `merchant` node before sending a split funding block on a payment. See [Split Funding Program](https://developers.bead.xyz/split-funding.md).

#### Related pages

* [Update Merchant](https://developers.bead.xyz/entity-management/merchant-management/update-merchant.md)
* [Split Funding Program](https://developers.bead.xyz/split-funding.md)
* [List Locations](https://developers.bead.xyz/entity-management/location-management/list-locations.md)
* [Create Location](https://developers.bead.xyz/entity-management/location-management/create-location.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://developers.bead.xyz/entity-management/merchant-management/get-merchant.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
