Entity Management

The Entity Management API provides a unified interface for creating and managing the business objects that drive payments in Bead, including partners, merchants, locations, terminals, and related onboarding flows.

Partner → Merchant → Location → Terminal → Payment

It covers the full life cycle, from initial KYB onboarding through routine updates, so you can automate provisioning flows and build self-service dashboards.

Entity Management connects onboarding, provisioning, and ongoing administration across the Bead platform. Use it to move from initial merchant setup through operational management of merchants, locations, and terminals.

Why use Entity Management

Need: Onboard a new merchant

How the API helps: Submit KYB details, provide applicant and signerInfo details, and generate a hosted onboarding link that the merchant signer can complete securely.

Need: Track onboarding progress

How the API helps: Query onboarding status to see missing or invalid fields and determine when a merchant is ready for production.

Need: Manage locations

How the API helps: Create, rename, or deactivate merchant locations so your reporting and settlement views reflect the merchant’s structure.

Need: Manage terminals

How the API helps: Create, list, update, disable, or delete devices and set device-level webhooks that drive payment status events.

Available sections

Onboarding Submit KYB details for merchants and partners, provide required applicant and signer information, generate hosted onboarding links, and track status through approval.

Merchant Management Create, read, update, and deactivate merchants once onboarding is complete. Check merchant status before enabling production traffic.

Location Management Create and maintain merchant locations, including display names and address details used in receipts, reporting, and settlement.

Terminal Management Provision and manage terminals, including webhooks and configuration that control how payments are initiated and where events are delivered.

Navigation

Use the left navigation to move between sections:

• Onboarding

• Merchant Management

• Location Management

• Terminal Management

• Change Log

Getting started

1. Confirm the authentication method for the API flow you are using

   • Onboarding requests use an API key sent in the X-Api-Key header.

   • Other Entity Management endpoints may use the authentication model documented for that endpoint family.

   • See the Authentication page for current authentication guidance.

2. Create or retrieve the parent objects in order

   • Partner → Merchant → Location

3. Provision terminals under the correct location

   • Each terminal belongs to a location and merchant.

4. Use the terminalId when creating payments

   • Payments created through the Payments API reference the terminal and merchant defined here, then appear in Reporting and Settlement.