Platform Organizations are a new account model in Hyperswitch for businesses that operate payments across many merchants namely vertical SaaS platforms, marketplaces, multi-brand retail groups, franchise operators. The shape is simple: a privileged Platform Merchant sits at the top, holding a single Platform API Key. Beneath it, any number of child merchants each classified at creation as either Connected (sharing customers and saved cards with the rest of the platform) or Standard (fully isolated). The Platform API Key handles management and on-behalf operations across the org; per-merchant keys handle everything else.

Below: how the model is wired, the configurations that map to common enterprise shapes, and what to watch out for.

The architecture in one frame

A Platform Organization contains exactly one Platform Merchant the control plane and any number of child merchants beneath it. The Platform Merchant doesn't process its own payments. Its job is to own the shared resource scope and to manage the rest of the org.

Every child merchant is classified at creation:

• Connected merchants participate in the platform's shared scope. Their Customers and Payment Methods are visible to the Platform Merchant and to other Connected merchants in the same org. They can run payments using their own API key, or the platform can run payments on their behalf using the Platform API Key.
• Standard merchants stay isolated. Their Customers and Payment Methods don't cross any boundary, even within the same Platform Org. The Platform API Key can create a Standard merchant and generate its keys, but it cannot run payments or configure connectors on its behalf that boundary is enforced at request authentication, not by application code.

Underneath each merchant, the existing Profiles model still handles business units, regions, and connector groupings. Profiles haven't changed.

What gets shared, what stays isolated

For Connected merchants, sharing happens at the orchestration layer. The same customer_id resolves to the same Customer entity at any Connected merchant in the org. A card saved at Connected Merchant A including its tokenization state with the underlying connector is available for charging at Connected Merchant B, subject to consent recorded at save time.

Standard merchants keep their own namespaces. There's no cross-merchant lookup path for Standard customer or payment-method records.

One thing worth being explicit about: this sharing is an orchestration-layer concept. The actual card data still lives wherever the relevant connector puts it the PSP's vault, an external vault, or Hyperswitch's vault if the merchant is using Hyperswitch's tokenization. What changes between Connected and Standard isn't where the bytes live. It's whether two merchants see the same logical Customer record.

Direct vs on-behalf

For Connected merchants, the platform can run payments two ways:

• Direct. The Connected merchant uses its own API key. Identical in shape to a non-platform Hyperswitch payment.
• On-behalf. The Platform API Key runs the call, with the target Connected merchant indicated per request. The orchestration layer resolves merchant context, applies that merchant's connector configuration, and attributes the resulting transaction to the Connected merchant.

The choice is per-call, not per-merchant. The same Connected merchant can be operated either way.

Standard merchants run direct only. The on-behalf path is closed at the auth layer.

The current Platform-Connected setup supports the full Payments lifecycle end-to-end, including 3DS, on both initiation modes for Connected merchants. Refunds and disputes are now fully supported on-behalf as well. Standard merchants have feature parity with non-platform Standard merchants for refunds, disputes, and everything else.

Configuration shapes for real enterprises

The same model fits the topologies below. The integration doesn't change between them only the configuration does.

"Run our payments end-to-end." A retail brand wants the platform to handle all payment operations without involving their engineering team. Connected merchant, on-behalf initiation, connector configured by the platform via the Platform API Key.

"We have our own acquirers." An enterprise has an existing Adyen or Cybersource relationship and wants the orchestration layer without touching their acquiring stack. Connected (if they want shared scope) or Standard (if they want isolation), direct initiation, connector configured by the merchant. Credentials are scoped to that merchant's record and never exposed to the platform.

A regulated brand inside a larger group. A retail group has fifteen brands. Thirteen want a unified saved-card experience. Two are regulated (pharmacy, financial services) and have contractual obligations preventing co-mingling of cardholder or customer data. → Thirteen brands as Connected, two as Standard, all in the same Platform Org. The Platform API Key is barred from running payments or configuring connectors for the two Standard brands.

A marketplace. Thousands of sellers, programmatic onboarding, buyers expecting saved cards to follow them across sellers. → All sellers Connected, payments typically on-behalf, new sellers created by calling Merchant Account Create and API Key Create from the marketplace's backend at signup, both authenticated with the Platform API Key.

A holding company with deep BU structure. Multiple subsidiaries, each with divisions, settlements, and reporting. → Each subsidiary is its own merchant (Connected or Standard depending on data-sharing rules). Profiles model the divisions inside. The Platform Organization sits over everything as the management plane.

The pattern: most of the enterprise asks that used to mean build-time decisions now collapse into onboarding-time configuration. A platform with thirty enterprise tenants runs one integration with thirty configurations.

Where responsibilities split

Two boundaries worth being explicit about, because most misconfigurations come from getting them wrong.

Platform Merchant vs child merchants. The Platform Merchant is a control-plane entity. It owns the shared Customer and Payment Method scope, holds the Platform API Key, and manages child merchants. It doesn't process its own payments and has no merchant connector account of its own. Child merchants own everything transactional their connector credentials, their payments, their refunds, their disputes, their Profiles.

Platform Organization vs PSP. The Platform Organization is an orchestration topology, not a regulatory one. KYC, acquirer onboarding, PCI scope, and chargeback liability live with the underlying PSP each merchant connects to (Adyen, Stripe, Worldpay, Cybersource, Authorize.Net, and so on) under that PSP's onboarding model. Hyperswitch is the orchestration plane on top. A merchant moving between Platform Organizations doesn't re-onboard with its PSP.

What can go wrong

A few things to watch for:

Misclassification at creation. Classification is set at Merchant Account Create time and can only be changed via an admin path. Onboarding a regulated brand as Connected and discovering later that its Customer records are co-mingled in the Connected pool isn't a configuration tweak it requires admin intervention and possibly customer-data segregation work to undo. Default to Standard, upgrade to Connected only after explicit confirmation of data-sharing terms with the merchant.

Customer-ID collisions in shared scope. The same customer_id resolves to the same Customer entity across all Connected merchants in the org. Code that assumes per-merchant customer namespacing say, an upstream system generating IDs that happen to collide across two Connected tenants will see merged records, not separate ones. Generate customer_id values that are globally unique within the Connected scope, or let Hyperswitch auto-generate them.

Mixing credentials by classification. Code that uses the Platform API Key uniformly across all child merchants without branching on classification will fail closed against Standard merchants with a 4xx auth response. The pattern that works: Platform API Key for management operations universally; Platform API Key for on-behalf payment operations on Connected only; merchant API keys for everything on Standard.

Programmatic onboarding without an explicit classification decision. If your signup flow calls Merchant Account Create without setting classification, every newly onboarded merchant inherits whatever default the Platform Organization has. Make it an explicit field in the onboarding form or contract metadata.

Choosing Connected or Standard

The classification you pass to Merchant Account Create is the one decision in this model that's expensive to reverse. Worth getting right at onboarding.

Choose Connected when the merchant operates within a portfolio where saved-card portability across sibling merchants is a product requirement (marketplaces, multi-brand retail, franchises); when customer-data sharing is contractually permitted under the merchant's terms with its end-customers; or when the platform expects to run on-behalf payment operations.

Choose Standard when the merchant's contract or regulatory regime requires named-tenant data isolation (pharmacy, healthcare, financial services, gambling in some jurisdictions); when the merchant explicitly requires that no other tenant's operations can touch its records; or when the platform doesn't need to run on-behalf payment operations for this merchant.

Two mutual exclusions worth remembering: a merchant requiring on-behalf payment operations cannot be Standard — the auth layer will block it. A merchant requiring full data isolation cannot be Connected — shared scope is part of the Connected definition.

For the API call shape and field-by-field reference, see the Platform Org and Merchant Setup documentation and the Merchant Account Create API reference.