# Phase 14.2 — Merchant Accounts

| Field | Value |
| --- | --- |
| Identifier | `payment-14.2` |
| Implementation Priority | **HIGH** |
| Status | Complete |
| Service | `payment` |
| Depends On | `payment-14.1` |

> Full specification: [payment-roadmap.md](../../payment-roadmap.md#phase-14-2--merchant-accounts)

## Purpose

Introduce Torbat Pay Merchant (facilitator) sub-merchant account shells for tenants who accept payments through platform facilitator mode.

## Business Scope

Sub-merchant onboarding lifecycle; KYC/KYB document refs (File Storage); link merchant to workspace and optional branch refs.

## Technical Scope

Aggregates: MerchantAccount, MerchantAccountProfile, MerchantSettlementProfile, MerchantComplianceRef, MerchantAccountStatusHistory. Facilitator platform settings.

## Dependencies

`payment-14.1`

## Out of Scope

Live KYC vendor, bank payouts (14.7/14.9), payment capture (14.3).

## Capabilities

`payment.merchant_accounts`, `payment.facilitator_mode`

## Permissions

`payment.merchant_accounts.view|create|update|submit|activate|suspend|close|manage`

## Events

`payment.merchant_account.created|submitted|activated|suspended|closed`

## API Contracts

`/api/v1/merchant-accounts`, `/api/v1/merchant-settlement-profiles`, lifecycle POST actions

## Data Ownership

Payment owns merchant domain; Identity users; Storage for compliance blobs (refs).

## Provider Ownership

Platform facilitator PSP credentials in Payment platform settings.

## Integration Rules

Required when workspace `default_payment_mode=torbat_pay_merchant`. BYO mode skips merchant for routing.

## Quality Gates

Lifecycle transitions, PII redaction, tenant isolation.

## Definition of Done

Merchant CRUD + lifecycle; facilitator flag on workspace; no payment requests.

## Future Compatibility

Multi-currency settlement profiles; international merchant descriptors.