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.

Authentication

All Partner Management endpoints use API key authentication.

Header	Value
X-Api-Key	{adminApiKey}
Accept	application/json

For write operations, also include:

Header	Value
Content-Type	application/json

List partners

Returns a paginated list of partner records. Use this endpoint to browse the partner hierarchy or locate a specific partner before creating or updating records.

GET /Partners/all

Query parameters

Parameter	Type	Required	Description
PartnerIds	array	No	Filter by specific partner IDs
IsEnabled	boolean	No	Filter by enabled status
Type	string	No	Filter by partner type: iso, agent, corporateEntity, masterMerchant
Search	string	No	Search by name, email, or phone number
SortBy	string	No	One of: Created, Updated, IsEnabled, PartnerType, Name
SortDirection	string	No	asc or desc
Page	integer	No	Page number, zero-indexed
PageSize	integer	No	Results per page, max 100

Example request

curl -X GET "https://api.test.devs.beadpay.io/Partners/all?Page=0&PageSize=50" \
     -H "X-Api-Key: {adminApiKey}"

Response codes

Code	Condition
200	Partners returned successfully
401	Missing or invalid API key
403	Not permitted to list partners

Get a partner

Retrieves a specific partner record.

GET /Partners/{id}

id is the ID of the partner to retrieve.

Example request

curl -X GET "https://api.test.devs.beadpay.io/Partners/{partnerId}" \
     -H "X-Api-Key: {adminApiKey}"

Response codes

Code	Condition
200	Partner returned successfully
401	Missing or invalid API key
403	Not permitted to access this partner
404	Partner not found

Add a partner

Creates 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 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	None

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.

Request body

{
  "partnerType": "iso",
  "name": "Acme Payments",
  "email": "[e-mail]",
  "phoneNumber": "[phone]",
  "feeInfo": {
    "crypto": {
      "feeFactor": 0,
      "fixedFee": 0
    },
    "card": null
  },
  "tenderTypes": ["usdcBase", "bitcoin"],
  "maxTransactionAmount": 10000
}

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

Request fields

Field	Type	Required	Description
partnerType	string	Yes	Type to create: iso, agent, corporateEntity, or masterMerchant
name	string	Yes	Partner display name. Max 256 characters
feeInfo	object	Yes	Partner fee configuration
tenderTypes	array	Yes	Tender types enabled for the partner
email	string	No	Partner contact email
phoneNumber	string	No	Partner contact phone number
maxTransactionAmount	number	No	Maximum transaction amount for this partner

Note: root may appear as a partnerType value in read responses. It cannot be used when creating a partner.

Example request

curl -X POST "https://api.test.devs.beadpay.io/Partners/{parentId}/partners" \
     -H "X-Api-Key: {adminApiKey}" \
     -H "Content-Type: application/json" \
     -d '{
       "partnerType": "iso",
       "name": "Acme Payments",
       "email": "[e-mail]",
       "phoneNumber": "[phone]",
       "feeInfo": {
         "crypto": { "feeFactor": 0, "fixedFee": 0 },
         "card": null
       },
       "tenderTypes": ["usdcBase", "bitcoin"],
       "maxTransactionAmount": 10000
     }'

Response codes

Code	Condition
200	Partner created successfully
201	Partner created successfully
202	Creation accepted for processing
400	Invalid fields or validation error
401	Missing or invalid API key
403	Not permitted to create a partner under this parent
409	Conflict — duplicate or constraint violation

Add another Agent branch

If Bead has instructed you to create an additional Agent under an existing ISO, create the Agent as a child partner of the ISO. Bead automatically creates the Corporate Entity and Master Merchant records under that Agent branch.

{
  "partnerType": "agent",
  "name": "Acme Payments Agent Office 1",
  "email": "[e-mail]",
  "phoneNumber": "[phone]",
  "feeInfo": {
    "crypto": {
      "feeFactor": 0,
      "fixedFee": 0
    },
    "card": null
  },
  "tenderTypes": ["usdcBase", "bitcoin"],
  "maxTransactionAmount": 10000
}

Edit a partner

Updates an existing partner record.

PUT /Partners/{id}

id is the ID of the partner to update.

Request body

{
  "name": "Acme Payments Agent Office 1",
  "email": "[e-mail]",
  "phoneNumber": "[phone]",
  "feeInfo": {
    "crypto": {
      "feeFactor": 0,
      "fixedFee": 0
    },
    "card": null
  },
  "tenderTypes": ["usdcBase", "bitcoin"],
  "maxTransactionAmount": 10000
}

Request fields

Field	Type	Required	Description
name	string	Yes	Partner display name. Max 256 characters
feeInfo	object	Yes	Partner fee configuration
tenderTypes	array	Yes	Tender types enabled for the partner
email	string	No	Partner contact email
phoneNumber	string	No	Partner contact phone number
maxTransactionAmount	number	No	Maximum transaction amount for this partner

Example request

curl -X PUT "https://api.test.devs.beadpay.io/Partners/{partnerId}" \
     -H "X-Api-Key: {adminApiKey}" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "Acme Payments Agent Office 1",
       "email": "[e-mail]",
       "phoneNumber": "[phone]",
       "feeInfo": {
         "crypto": { "feeFactor": 0, "fixedFee": 0 },
         "card": null
       },
       "tenderTypes": ["usdcBase", "bitcoin"],
       "maxTransactionAmount": 10000
     }'

Response codes

Code	Condition
200	Partner updated successfully
202	Update accepted for processing
204	Update completed, no response body
400	Invalid fields or validation error
401	Missing or invalid API key
403	Not permitted to update this partner
404	Partner not found
409	Conflict — duplicate or constraint violation

Delete a partner

Removes a partner record.

DELETE /Partners/{id}

id is the ID of the partner to delete.

Example request

curl -X DELETE "https://api.test.devs.beadpay.io/Partners/{partnerId}" \
     -H "X-Api-Key: {adminApiKey}"

Response codes

Code	Condition
204	Partner deleted successfully
400	Invalid request or business rule violation
401	Missing or invalid API key
403	Not permitted to delete this partner
404	Partner not found

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.

Related pages

• Advanced Partner Hierarchy

• Merchant Management

• List Merchants