Get Merchant

Overview

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

Endpoint

GET /Merchants/{id}

Path parameters

Name	Type	Required	Description
id	string	✔︎	The merchantId assigned during boarding

Request headers

Header	Value
Authorization	Bearer <access-token>
Accept	application/json

Example request

curl -X GET "https://api.test.devs.beadpay.io/Merchants/123123" \
     -H "Authorization: Bearer $TOKEN"

Successful response — 200

{
  "id": "mer_123123",
  "created": "2025-06-04T18:41:14.402Z",
  "updated": "2025-06-04T18:41:14.402Z",
  "tenderTypes": ["ethereum"],
  "companyName": "Acme Coffee Roasters",
  "description": "West-coast café chain",
  "companyLogoPath": "https://cdn.bead.xyz/logos/acme.svg",
  "taxNumber": "99-9999999",
  "receivableCurrencyIds": [1],               // USD
  "partnerId": "part_e9ab6c82b6d74a4f9c33",
  "maxTransactionAmount": 2500000,
  "externalProps": [
    {
      "system": "cybrid",
      "id": "abca1b69977e69ee0a0725b837ba9d0b",
      "additionalData": {
        "accounts": [
          { "id": "acct_fiat_usd", "accountType": "fiat", "name": "USD settlement", "currencyId": 1 }
        ]
      }
    }
  ],
  "status": "unverified",
  "feeInfo": {
    "crypto": { "feeFactor": 0.015, "fixedFee": 0 },
    "card":   { "feeFactor": 0.029, "fixedFee": 30 }
  },
  "settlementBeneficiary": { "type": "self", "partnerId": "part_e9ab6c82b6d74a4f9c33" },
  "memberships": [
    { "userIssuerId": "user_ab12", "role": "admin" },
    { "userIssuerId": "user_cd34", "role": "viewer" }
  ]
}

Key fields

Field	Description
tenderTypes	Default rails every child location inherits (override at location/terminal if needed)
receivableCurrencyIds	Settlement currencies (match IDs from /currencies)
feeInfo.crypto / feeInfo.card	Factor = percentage (0.015 → 1.5 %), fixedFee in minor units
status	Boarding state: unverified, pending, active, etc.
memberships[]	Users and roles that manage this merchant in the dashboard

Error responses

Code	Condition
404	Merchant {id} does not exist or is not visible to your token

Best practices

✔︎ Action	Why
Cache response for dashboard sessions	Merchant profile rarely changes during a user session
Use updated timestamp to invalidate caches	Quick check for profile edits
Display status prominently	Guides ops teams through KYC / activation workflow
Respect maxTransactionAmount when building POS flows	Prevents declines on oversize transactions

Related endpoints

• List Merchants – GET /Partners/{id}/merchants (coming soon)

• List Locations – GET /Merchants/{id}/locations

• Create Location – POST /Merchants/{id}/locations