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
id
string
Yes
The merchantId assigned during boarding
Request headers
X-Api-Key
{adminApiKey}
Accept
application/json
Example request
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 at data[].merchant and data[].details.
The merchant object carries the core record:
{
"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
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. Returned on the flat merchant node, not inside details. Set it through Update Merchant.
memberships
Users and roles that manage this merchant in the dashboard
The old field name is not aliased.
setRebateProgramEnabledwas renamed tosetSplitFundingEnabled. A request that still sendssetRebateProgramEnabledis dropped by the deserializer and returns a successful200with nothing enabled, so reading the merchant back and checkingisSplitFundingEnabledis 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 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
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
updatedtimestamp to decide when to invalidate local copies.Check
statusbefore enabling production payment traffic. The merchant must beactive.Respect
maxTransactionAmountwhen building POS flows to prevent declines on oversize transactions.Read
feeInformation.cryptoFeesfor the fee on a specific crypto asset.feeInfois typicallynullon merchants.Check
isSplitFundingEnabledon themerchantnode before sending a split funding block on a payment. See Split Funding Program.
Related pages
Last updated