> For the complete documentation index, see [llms.txt](https://docs.hyperswitch.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hyperswitch.io/integration-guide/account-management/multiple-accounts-and-profiles/hyperswitch-account-structure.md). # Organization, Merchant Account, and Business Profile Understand the Organization, Merchant Account, and Business Profile hierarchy. Hyperswitch separates organization ownership, merchant authentication, and payment configuration. * An **Organization** owns merchant accounts and can be standard or platform type. * A **Merchant Account** belongs to an organization and is the scope for merchant API keys. * A **Business Profile** belongs to a merchant account and stores payment configuration, including return URL, webhook details, routing-related settings, and profile-level feature settings. * A **merchant\_connector\_account** belongs to a profile. Its connector account details are where processor credentials are stored. Do not put processor credentials on the organization or merchant account. ### Identifiers Every object in the hierarchy has an identifier, and the naming convention changed between API versions. This is worth understanding before you read an API response, because v1-era examples and v2 responses describe the same objects with different field names. The rule is short: on v1, an object's identifier is named after the object; on v2, an object's own identifier is always `id`. | Object | v1 | v2 | | ----------------- | ----------------------- | ---- | | Organization | `organization_id` | `id` | | Merchant Account | `merchant_id` | `id` | | Business Profile | `profile_id` | `id` | | Connector account | `merchant_connector_id` | `id` | The rename applies only to an object's *own* identifier. When one object points at another, that reference keeps its descriptive name on both versions. A connector account is the clearest example: on v2 its response carries `id` for itself and `profile_id` for the profile it belongs to, side by side. Seeing `profile_id` in a v2 payload does not mean you are looking at a profile. It means you are looking at something that belongs to one. These shapes come from `OrganizationResponse`, `MerchantAccountResponse`, `ProfileResponse`, and `MerchantConnectorResponse`. When you create a connector account, the processor credentials go in `connector_account_details` on `MerchantConnectorCreate`. ### Choosing the level Merchant accounts and profiles solve different problems, and the question that separates them is whether the units need their own credentials or only their own configuration. Add **merchant accounts** when each unit needs its own API keys, because API keys are issued at the merchant-account scope. Separate legal entities, separate billing relationships, or any case where one unit's credentials must not work for another all point here. A retailer whose Shoes, Clothing and Bags brands each integrate separately, or a marketplace whose sub-merchants embed their own keys, both land on this shape.

One Organization with multiple Merchant Accounts, each having its own Profile and Connectors

Add **profiles** when one business needs several payment setups but can share a single set of API keys. A profile owns its connectors, routing rules, webhook endpoint and return URL, so profiles are how you separate a web storefront from a mobile app, or one region from another, without multiplying credentials. The same retailer wanting one key across all three brands, but different routing rules for each, belongs here instead.

One Organization with one Merchant Account (Merchant A) and multiple Profiles (Clothing, Shoes, Bags), each with its own Connectors — One Merchant Account with multiple Profiles, each having its own set of Connectors

Because payments, connectors and webhooks are all configured at the profile level anyway, reach for a second merchant account only when the API-key boundary is the actual requirement. #### Selecting a profile for a payment Each payment runs against exactly one profile. How that profile is chosen differs by version, and the v1 behavior deserves attention because the field is optional without always being safe to omit. **On v1**, `PaymentsRequest` carries an optional `profile_id`. The handler, `get_profile_id_from_business_details`, tries three sources in order: 1. the `profile_id` on the request, if you sent one; 2. the merchant account's `default_profile`; 3. the legacy `business_country` and `business_label` pair, resolved together. If none of the three produces a profile, the request fails with a missing-field error. The practical consequence is in step 2. An account with a single profile that is also its `default_profile` will accept payments that omit `profile_id`, which makes the field look unnecessary. Add a second profile and nothing breaks. The payment simply keeps going to the default profile, which may not be the one you intended. That silent outcome is the reason to send `profile_id` explicitly once an account has more than one profile. The field being optional describes the request schema; it does not tell you whether omitting it is safe for your account. **On v2**, `PaymentsRequest` has no `profile_id` field at all. The profile comes from the `X-Profile-Id` request header, which `V2ApiKeyAuth` reads and requires while authenticating the call. Every v2 payment therefore names its profile explicitly, and there is no default-profile fallback to depend on. ### Create merchant accounts and profiles Sign-up creates one merchant account with one profile. You add more from the switchers in the dashboard, not from the settings pages. Creating either one is restricted by role. Adding a merchant account needs Organization Admin; adding a profile needs Merchant Admin or above. Without the role, the option is visible but disabled. **To add a merchant account:** 1. Open the **Merchant Account** switcher at the top of the left sidebar. 2. Select **+ Create new**. 3. In **Add a new merchant**, enter the merchant name. Some deployments also ask for a merchant type. 4. Select **Add Merchant**.

Sidebar dropdown with the Create new merchant option highlighted — Sidebar merchant dropdown with the "+ Create new" option to add a new merchant

**To add a profile:** 1. Open the **Profile** switcher at the top of the main content area. 2. Select **+ Create new**. 3. In **Add a new profile**, enter the **Profile Name**. 4. Select **Add Profile**.

Profile dropdown with the "+ Create new" option to add a new profile

Both switchers list everything you already have, so they double as the way to move between merchant accounts and profiles. ### Edit a Business Profile You can update a profile with the API or from the dashboard. #### API For v1, send `POST /account/{account_id}/business_profile/{profile_id}`. For v2, send `PUT /v2/profiles/{profile_id}`. The route registrations bind these methods to `profile_update`. The request can update the profile name, return URL, webhook details, authentication connector details, shipping-detail collection settings, retry and routing settings, metadata, and other fields defined by the versioned `ProfileUpdate` struct. To update the profile webhook URL, include the `webhook_details` object with its `webhook_url` member. The v1 and v2 request names differ for some shipping fields, so copy the fields from the API version you are calling. Example v1 shape: ```json { "webhook_details": { "webhook_url": "https://example.com/hyperswitch-webhooks" } } ``` The profile update handler validates `webhook_details` before calling the update operation. The endpoint is not the merchant-account update endpoint. #### Dashboard Open the active profile's settings and edit the available profile configuration. The control center fetches a profile with the business-profile endpoint and sends the edited profile through the version-specific update method. Its request model includes `profile_name`, `return_url`, `webhook_details`, authentication connector details, shipping collection options, retry settings, metadata, and version-specific feature flags. The profile page displays the `Profile ID` beside `Profile Name` and `Merchant ID`. Profile IDs are also available in the dashboard's developer payment settings view. Look for the `Profile ID` field and use its copy control. ### Route out * KV mode and Redis retention, plus the drainer configuration, are self-hosting concerns. See [Operations](/integration-guide/control-center/operations.md) and the self-hosting operations documentation. * For the complete field list for `POST /payments`, use the [Payments Create API reference](https://api-reference.hyperswitch.io/v1/payments/payments--create). The list is generated from the `PaymentsRequest` schema and must be kept with the API reference rather than duplicated here. If you need programmatic merchant onboarding, continue to [Platform Organization](/integration-guide/account-management/multiple-accounts-and-profiles/platform-organization-concepts.md). --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.hyperswitch.io/integration-guide/account-management/multiple-accounts-and-profiles/hyperswitch-account-structure.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.