Merchant API

A Merchant is a sub-merchant you onboard for acquiring under your platform. This page documents the object field by field, the tri-state capability model your product should gate on, and the four endpoints — create, list, retrieve, update. How verification itself works is on Onboarding & KYB.

The Merchant object

GET /v1/merchants/mch_7Rq3wN8dK2Vs

{
  "id": "mch_7Rq3wN8dK2Vs",
  "object": "merchant",
  "legal_name": "Aurora Retail B.V.",
  "trading_name": "Aurora",
  "country": "NL",
  "mcc": "5734",
  "mid": "845512000318",
  "kyb_status": "active",
  "capabilities": {
    "card_payments": "active",
    "local_methods": "active",
    "payouts": "active"
  },
  "livemode": false,
  "created_at": "2026-07-16T08:02:19Z"
}

Field	Type	Description
id	string	Unique identifier, always prefixed `mch_`.
legal_name	string	Registered legal name of the entity. Fixed after creation.
trading_name	string · nullable	Customer-facing name (doing-business-as). Appears on card statements where the scheme allows.
country	string	Two-letter ISO 3166-1 country code of incorporation. Fixed after creation.
mcc	string	Four-digit ISO 18245 merchant category code. Validated — and corrected if wrong — during review.
mid	string · nullable	Merchant id at the acquiring level, assigned once the merchant becomes `active`. This is what appears in scheme clearing records and settlement reports. `null` until then.
kyb_status	enum	`created` · `kyb_pending` · `under_review` · `active` · `restricted` · `suspended` — the KYB lifecycle.
capabilities	object	Per-capability activation state — see below.
livemode	boolean	`true` for objects created with a live-mode key, `false` in test mode.
created_at	timestamp	Creation time, ISO 8601 UTC.

Capabilities

Capabilities answer the only question your product actually asks: can this merchant do X right now? Each one moves independently through three states:

Capability	Governs
`card_payments`	Accepting card payments — the card-family methods (`card`, `apple_pay`, `google_pay`). See Cards & 3DS.
`local_methods`	Accepting local payment methods — bank redirects, real-time rails, wallets, vouchers. See the method catalog.
`payouts`	Receiving payouts to the merchant's settlement bank account.

Gate on capabilities, not on kyb_status kyb_status: active tells you verification passed; it doesn't tell you which features work. Capabilities can stagger during activation (card_payments active while payouts is still pending) and pause individually while a merchant is restricted. Check capabilities.card_payments === "active" before offering card acceptance — nothing else.

Endpoints

Four endpoints, standard conventions: Bearer auth, Idempotency-Key on POSTs, cursor pagination on lists. There is no delete — merchants carry regulatory history and are deactivated, never erased.

POST /v1/merchants

curl https://api.finscale.dev/v1/merchants \
  -H "Authorization: Bearer sk_test_51FinscaleDemo…" \
  -H "Idempotency-Key: idem_mch_aurora_01" \
  -H "Content-Type: application/json" \
  -d '{
    "legal_name": "Aurora Retail B.V.",
    "trading_name": "Aurora",
    "country": "NL",
    "mcc": "5734"
  }'

Returns 201 with the merchant in kyb_status: kyb_pending — see the onboarding walkthrough for the full response and what happens next. legal_name, trading_name, and mcc are required-or-optional exactly as shown: only trading_name may be omitted.

POST /v1/merchants/mch_7Rq3wN8dK2Vs

curl https://api.finscale.dev/v1/merchants/mch_7Rq3wN8dK2Vs \
  -H "Authorization: Bearer sk_test_51FinscaleDemo…" \
  -H "Content-Type: application/json" \
  -d '{
    "trading_name": "Aurora Home",
    "mcc": "5732"
  }'

Only trading_name and mcc are updatable — legal_name and country are fixed at creation; a different legal entity is a new merchant. Pass "trading_name": null to clear it. Changing mcc can send kyb_status back to under_review while the new line of business is validated.

GET /v1/merchants?kyb_status=active

curl "https://api.finscale.dev/v1/merchants?kyb_status=active&limit=20" \
  -H "Authorization: Bearer sk_test_51FinscaleDemo…"

# 200 OK
{
  "object": "list",
  "data": [
    {
      "id": "mch_7Rq3wN8dK2Vs",
      "object": "merchant",
      "legal_name": "Aurora Retail B.V.",
      "kyb_status": "active",
      "mid": "845512000318"
    }
  ],
  "has_more": false,
  "url": "/v1/merchants"
}

Most recently created first. Filter by kyb_status — ?kyb_status=restricted is the working list for your operations team. Page with limit, starting_after, ending_before like every other list endpoint.

Webhook events

One event type covers the object: merchant.updated, fired on every kyb_status or capability change, carrying the full Merchant as data.object. There is no merchant.created — creation is your own API call, so you already know. Payload example on the onboarding page; delivery mechanics in Webhooks.

Error scenarios

Scenario	Response
Missing `legal_name`, malformed `mcc` or `country`	`400` — `invalid_request_error`
Attempting to update `legal_name` or `country`	`400` — `invalid_request_error`; fixed after creation
Unknown merchant id	`404` — `invalid_request_error`
Same `Idempotency-Key`, different payload	`409` — `idempotency_error`
Too many requests	`429` — `rate_limit_error`; see Rate limits

All error responses use the standard error envelope. Full request/response schemas are in the API reference.