Core ConceptsADR Library

ADR-002: Hybrid Merchant-of-Record posture

Status

Accepted (2026-05-28)

Context

Two MoR models are viable:

  • Per-tenant: each MVS customer signs their own BAA + AOC with each connector.
  • Platform Organization: MVS is MoR; one BAA + AOC per connector covers all customers; Hyperswitch’s Platform Organization API onboards customers as sub-merchants.

Decision

Hybrid: per-tenant default, opt-in Platform Organization tier. Phase 1 ships the opt-in toggle (MerchantExtension.isPlatformOrgMember); the full Platform Organization KYC API integration is deferred until upstream surfaces it stably and product confirms the tier is shipping.

Consequences

  • Schema includes the toggle from Phase 1 onwards.
  • Two compliance trees: per-tenant tier requires customer-side BAA tracking; Platform Org tier requires MVS to maintain BAA per connector.
  • Two onboarding flows: simple connector creation (per-tenant) vs sub-merchant KYC (Platform Org, deferred).

Alternatives considered

  • Per-tenant only: simplest; locks out Platform Org as a future product.
  • Platform Org only: assumes MVS wants the higher compliance burden + customer relationship; rejected as too aggressive without product validation.