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.

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

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.

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.

id is the ID of the partner to update.

Edit partner request body

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.

Last updated