> 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](/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", "isRebateProgramEnabled": 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` | | `isRebateProgramEnabled` | Whether the merchant is enrolled in the [Split Funding Program](/split-funding.md). Set it through [Update Merchant](/entity-management/merchant-management/update-merchant.md). | | `memberships` | Users and roles that manage this merchant in the dashboard | > **The banking details on this record are the merchant's account on file.** On the [Split Funding Program](/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 the enrollment flag before sending a split funding block on a payment. See [Split Funding Program](/split-funding.md). #### Related pages * [Update Merchant](/entity-management/merchant-management/update-merchant.md) * [Split Funding Program](/split-funding.md) * [List Locations](/entity-management/location-management/list-locations.md) * [Create Location](/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 dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://developers.bead.xyz/entity-management/merchant-management/get-merchant.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.