Teams & Multi-Tenancy

PayHero is multi-tenant by design. A single organization can be split into many Teams — each an isolated Account with its own wallet, payment channels, KYC and members. This lets one integrator run money movement for many independent sub-entities from a single set of API credentials.

The model

Organization                      ← your top-level entity (owns the API key)
├── Account (Team)  "Vendor A"     ← scoped wallet · payment channels · KYC · members
├── Account (Team)  "Vendor B"
└── Account (Team)  "Vendor C"

Concept	What it is
Organization	Your enterprise. Owns the API key and all Teams beneath it.
Account (Team)	An isolated sub-entity. Gets its own service wallet (created automatically), its own payment channels, its own KYC, and its own members.
Member	A user invited into a Team, with a role that scopes what they can do.
Wallet	Every Team is provisioned a dedicated wallet on creation — balances never mix between Teams.

Isolation is the point

Each Team’s wallet balance, transactions, payment channels and KYC are fully isolated. Collecting into Vendor A’s wallet never touches Vendor B. This is what makes PayHero safe to build a multi-vendor product on.

Who this is for

Multi-vendor platforms (SaaS)

You run a platform and your customers are themselves businesses that move money.

Example — a WiFi / ISP SaaS. You sell software to WiFi vendors. For each vendor that joins, you create a Team (Account) for them. That Team gets its own scoped wallet (their captive-portal payments land there), its own payment channels (their Till/Paybill), and its own KYC. You manage all of them through your one organization’s API key — but each vendor’s money stays ringfenced to their Team.

Enterprises with departments

You are one large business and want to organize money movement by department or business unit.

Example — a company with divisions. Create a Team for Customer Support, another for the Tech Team, another for Marketing. Each has its own wallet and reporting, its own channels, and its own members — while rolling up under the same organization.

What you can do over the API

The multi-tenancy endpoints are API-key authenticated (HTTP Basic — see Authentication). Your API key identifies the organization and the acting user, so most ownership fields are inferred from the key rather than passed in the body.

Capability	Endpoint
Discover your Teams & profile	GET /api/v2/user_profile/{user_id}
Create a Team	POST /api/v2/accounts
Fetch a Team	GET /api/v2/account/{account_id}
Update a Team	PUT /api/v2/accounts
Remove a Team	DELETE /api/v2/accounts/{account_id}
Invite a user to a Team	POST /api/v2/account_invites
Remove a user from a Team	DELETE /api/v2/account_invites
Submit KYC for a Team	POST /api/v2/account_kycs
Update a Team’s KYC	PUT /api/v2/account_kycs/{id}

Continue to:

• Managing Teams — create, read, update and delete Accounts, and discover the ones you own.
• Team members — invite and remove users.
• Team KYC — submit and update KYC so a Team can transact. See also KYC tiers & limits.