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 — 200

The response 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 / data[].details.

{
  "merchant": {
    "displayId": "M001667",
    "partnerExternalId": null,
    "partnerId": "690e2895852fff2eff800c68",
    "companyName": "Acme Coffee Roasters",
    "description": "West-coast café chain",
    "taxNumberType": "ein",
    "taxNumber": "99-9999999",
    "companyLogoPath": null,
    "isSettlementOnly": false,
    "isCommissionMerchant": false,
    "commissionMerchantId": null,
    "status": "active",
    "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": "bitcoin_Lightning",
          "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 }
        },
        {
          "tenderType": "usdcSolana",
          "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 },
          "refundFee": { "sellRate": 0.0, "isBilledByPartner": false },
          "chargebackFee": { "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"
  },
  "details": {
    "legalName": "Acme Coffee Roasters, Inc.",
    "dbaName": "Acme Coffee Roasters",
    "registrationDate": "2025-12-04",
    "legalEntityType": "corporationSType",
    "naicsCode": "541511",
    "merchantCategoryCode": "5734",
    "isSeasonal": false,
    "grossAnnualRevenue": 100000.0,
    "highestMonthlyVolume": 12000.0,
    "averageTicketSize": 200.0,
    "maxTicketSize": 10000.0,
    "businessWebsite": "https://acmecoffee.example.com/",
    "businessEmail": "[e-mail]",
    "businessPhone": "[phone]",
    "mailingAddress": {
      "address1": "1800 City Farm Dr",
      "address2": "Bldg 1B",
      "city": "Baton Rouge",
      "region": "LA",
      "country": "US",
      "postalCode": "70806"
    },
    "proofOfBusinessType": "articlesOfIncorporation",
    "proofOfAddressType": null,
    "mainPointOfContact": {
      "lastName": "Roaster",
      "firstName": "Ada",
      "email": "[e-mail]",
      "phoneNumber": "[phone]"
    },
    "bankInfo": {
      "bankName": "Example Bank",
      "accountNumber": "****1234",
      "accountType": "checking",
      "routingNumber": "****5678",
      "depositMethod": "ach"
    },
    "id": "697109947a7f738950a8428d",
    "created": "2026-01-21T17:15:00Z",
    "updated": "2026-05-08T18:40:02.237Z"
  }
}

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

This is a live example (redacted). feeInfo came back null here — see the callout below for what that means.

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; carries the same crypto/card flat-rate shape used when creating or updating a partner. Not the field to read for per-asset crypto pricing
feeInformation.cryptoFees	Per-asset crypto fee breakdown — one entry per tenderType (e.g. bitcoin, bitcoin_Lightning, usdcBase, usdcSolana). This is the field to read for the rate on a specific crypto asset
feeInformation.digitalWalletsFees	Per-tender-type fees for wallet rails (Cash App, PayPal, Venmo, etc.), same shape as cryptoFees, or null if none configured
status	Boarding state: unverified, active, locked, restricted, inactive, suspended, terminated, closed
memberships	Users and roles that manage this merchant in the dashboard

<details> <summary>feeInfo vs. feeInformation.cryptoFees</summary>

feeInfo and feeInformation are both live fields in the API — feeInfo is not deprecated. In practice, feeInfo is returned as null on merchants; the same feeInfo shape (crypto/card, each with a single feeFactor/fixedFee) 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's populated on merchants and carries the actual per-tenderType breakdown — 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.

</details>

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

Related pages

• Merchant Management

• List Locations

• Create Location