Advanced Partner Hierarchy

Most integrations do not need to manage the full partner hierarchy directly. Use this reference when Bead instructs you to create or manage ISO, Agent, Corporate Entity, or Master Merchant partner records.

For most partners, the common operating model is:

Partner → Merchant → Location → Terminal → Payment

Some larger ISO, super-ISO, reseller, or boarding-platform programs require additional partner records before merchants are created. In those cases, merchants ultimately roll up under a Master Merchant partner record.

Key rule

Every partner hierarchy branch must resolve to a Master Merchant record.

When a partner is created at the ISO, Agent, or Corporate Entity level, Bead automatically creates the downstream sub-partner records required to reach a Master Merchant.

Partner record created	Downstream records automatically created by Bead
ISO	Agent, Corporate Entity, Master Merchant
Agent	Corporate Entity, Master Merchant
Corporate Entity	Master Merchant
Master Merchant	No additional partner hierarchy records are required

For example, when an ISO partner is added, Bead creates the ISO and automatically creates an Agent, Corporate Entity, and Master Merchant under it. You do not need to separately add each downstream level.

Partner hierarchy

ISO
 └─ Agent
    └─ Corporate Entity
       └─ Master Merchant
          └─ Merchant
             └─ Location
                └─ Terminal
                   └─ Payment

Partner types

Partner type	API value	Typical use
ISO	iso	Top-level ISO or super-ISO organization.
Agent	agent	Regional office, sales group, or sub-organization under an ISO.
Corporate Entity / Corp	corporateEntity	Business or legal entity layer under an Agent.
Master Merchant / Master	masterMerchant	Required partner-level record that merchants are created under.

Multiple Agents under an ISO

Large ISO or super-ISO relationships may have multiple Agent records under the same ISO. Agent records often represent regional offices, business units, or similar operational groupings.

Example:

ISO: Acme Payments
 ├─ Agent: Acme Payments
 ├─ Agent: Acme Payments Agent Office 1
 └─ Agent: Acme Payments Agent Office 2

Each Agent branch resolves to its own Corporate Entity and Master Merchant structure so merchants can be boarded under the appropriate Master Merchant.

Merchant ownership

Merchants are created under the Master Merchant record.

The Master Merchant is the partner record that owns the merchant portfolio for that hierarchy branch. Even when the visible commercial relationship starts at the ISO, Agent, or Corporate Entity level, the hierarchy must resolve to a Master Merchant before merchants can be boarded underneath it.

When to use this model

Use the advanced partner hierarchy only when Bead has confirmed that the partner relationship requires one or more of the following:

Scenario	Example
Super-ISO or ISO structure	A top-level ISO manages multiple offices or sub-organizations.
Regional Agent organization	Each Agent represents a regional office or sales group.
Boarding platform on behalf of another partner	A software provider boards merchants for a super-ISO or reseller.
Separate merchant portfolios	Merchants need to roll up under different Agent or Master Merchant branches.

When not to use this model

Do not use the advanced hierarchy for standard merchant onboarding unless Bead has instructed you to do so.

Most partners should continue using the standard merchant onboarding and entity management flow. Adding ISO, Agent, Corporate Entity, or Master Merchant records when they are not needed can make reporting, permissions, and merchant ownership harder to manage.

Best practice

Create the highest-level partner record Bead has instructed you to create, then use the automatically created downstream records.

Do not manually recreate the downstream hierarchy unless Bead has specifically instructed you to do so. Before adding new partner branches, confirm the intended parent partner ID and target hierarchy with Bead.