Accounts & Merchants

Lydian organizes your integration around two entities: an Account and the Merchants that operate under it. Understanding the relationship explains where configuration lives and how API calls are scoped to a specific merchant.

Account

An Account is the top-level entity. Account-level configuration holds the defaults every merchant under the account can inherit — such as asset and wallet catalogs, checkout branding, and network confirmation settings — plus the account's billing fee schedule. See the Accounts API.

Merchant

A Merchant operates under an account and is who a given payment is collected for. One merchant is created for the account by default, and an account can have multiple merchants. Merchants inherit the account defaults and can override specific settings through their inherit / canSet flags. See the Merchants API.

In short: an account provides the defaults and billing context; merchants are the entities that actually transact, each able to customize what the account allows.

Why merchant context matters

Many operations act on behalf of a specific merchant — creating a payment, issuing a refund, reading merchant configuration. Lydian therefore needs to know which merchant a request applies to. How that merchant is identified depends on the key you authenticate with:

  • API Key (ak_) — pass the merchant in the X-MID header (a merchant UUID or external merchant ID). See Authentication & Environments.
  • Publishable Key (pk_) — the merchant is encoded in the key itself. To target a sub-merchant, append :{EXTERNAL_MID} to the publishable key.

The externalMID is an external merchant identifier (for example from a partner platform or point-of-sale system) that can be used to reference a merchant instead of its Lydian UUID.

Sessions and transactions record the accountID, merchantID, and externalMID they belong to, so you can always trace a payment back to the account and merchant it was collected for.