Partner Management

Use Partner Management APIs to create and update partner records. Partner records sit above merchants in the Bead entity model and are used to organize merchant ownership, reporting, permissions, and hierarchy.

Most integrations do not need to create partner hierarchy records directly. Use these APIs only when Bead has confirmed that your integration should manage partner records programmatically.

Where Partner Management fits

For most integrations, the entity model is:

Partner → Merchant → Location → Terminal → Payment

For advanced ISO, reseller, or boarding-platform configurations, the partner level may include an expanded hierarchy:

ISO → Agent → Corporate Entity → Master Merchant → Merchant

For ISO, Agent, Corporate Entity, and Master Merchant behavior, see Advanced Partner Hierarchy.

Find partner records

Use this endpoint to retrieve partner records with pagination and filters.

GET /Partners/all

Use this endpoint to retrieve a specific partner record.

GET /Partners/{id}

Use partner lookup before creating or updating records to confirm the correct parent partner ID and target hierarchy branch.

Add a partner

Use this endpoint to create a child partner under an existing parent partner.

POST /Partners/{parentId}/partners

parentId is the ID of the partner that should own the new partner record.

Automatic downstream creation

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

Partner type added	Records Bead automatically creates
iso	Agent, Corporate Entity, Master Merchant
agent	Corporate Entity, Master Merchant
corporateEntity	Master Merchant
masterMerchant	No additional partner hierarchy records are required

Create the highest-level partner record Bead instructed you to create, then use the created hierarchy to identify the downstream Master Merchant record.

Do not manually recreate the downstream hierarchy unless Bead has specifically instructed you to do so.

Add partner request body

{
  "partnerType": "iso",
  "name": "Acme Payments",
  "email": "[email protected]",
  "phoneNumber": "[phone]",
  "feeInfo": {
    "crypto": {
      "feeFactor": 0,
      "fixedFee": 0
    },
    "card": null
  },
  "tenderTypes": [
    "usdc",
    "btc"
  ],
  "maxTransactionAmount": 10000
}

In this example, adding Acme Payments as an ISO creates the required downstream Agent, Corporate Entity, and Master Merchant records automatically.

Add partner fields

Field	Required	Description
partnerType	Yes	Partner type to create. Supported advanced hierarchy values are iso, agent, corporateEntity, and masterMerchant.
name	Yes	Partner display name.
feeInfo	Yes	Partner fee configuration.
tenderTypes	Yes	Tender types enabled for the partner.
email	No	Partner contact email.
phoneNumber	No	Partner contact phone number.
maxTransactionAmount	No	Optional maximum transaction amount for this partner.

Add another Agent branch

If Bead has instructed you to create another Agent under an existing ISO, create the Agent as a child partner of the ISO.

{
  "partnerType": "agent",
  "name": "Acme Payments Agent Office 1",
  "email": "[email protected]",
  "phoneNumber": "[phone]",
  "feeInfo": {
    "crypto": {
      "feeFactor": 0,
      "fixedFee": 0
    },
    "card": null
  },
  "tenderTypes": [
    "usdc",
    "btc"
  ],
  "maxTransactionAmount": 10000
}

When the Agent is added, Bead automatically creates the Corporate Entity and Master Merchant records under that Agent branch.

Edit a partner

Use this endpoint to update an existing partner.

PUT /Partners/{id}

id is the ID of the partner to update.

Edit partner request body

{
  "name": "Acme Payments Agent Office 1",
  "email": "[email protected]",
  "phoneNumber": "[phone]",
  "feeInfo": {
    "crypto": {
      "feeFactor": 0,
      "fixedFee": 0
    },
    "card": null
  },
  "tenderTypes": [
    "usdc",
    "btc"
  ],
  "maxTransactionAmount": 10000
}

Edit partner fields

Field	Required	Description
name	Yes	Partner display name.
feeInfo	Yes	Partner fee configuration.
tenderTypes	Yes	Tender types enabled for the partner.
email	No	Partner contact email.
phoneNumber	No	Partner contact phone number.
maxTransactionAmount	No	Optional maximum transaction amount for this partner.

Notes

Partner creation and updates can affect downstream merchant ownership, reporting, permissions, tender availability, and which Master Merchant a merchant should be boarded under.

Before adding or editing partner records, confirm the intended parent partner ID and target hierarchy branch with Bead.

For advanced ISO, Agent, Corporate Entity, and Master Merchant behavior, see Advanced Partner Hierarchy.