Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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

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

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

Last updated