Skip to content

feat(gateway): multi-merchant support — sub-accounts under a single publishable key#49

Merged
aguilar1x merged 12 commits into
PACTO-LAT:mainfrom
fabicabvq06:feat/multi-merchant-subaccounts
Jul 19, 2026
Merged

feat(gateway): multi-merchant support — sub-accounts under a single publishable key#49
aguilar1x merged 12 commits into
PACTO-LAT:mainfrom
fabicabvq06:feat/multi-merchant-subaccounts

Conversation

@fabicabvq06

Copy link
Copy Markdown
Contributor

Summary

Adds multi-merchant support to the Connect Gateway: a single platform pk_/sk_ pair can host many isolated sub-merchants, each with isolated escrow settlement and webhook delivery, plus an admin listing of sub-merchants and their settled volume.

All new columns are nullable and all new tables additive, so existing single-merchant integrations are unchanged.

What's included

  • Data model — new Merchant (sub-account owned by a platform ApiKey) and MerchantSettlement (idempotent per-escrow ledger) models, plus a nullable merchantId on CheckoutSession, WebhookEndpoint, WebhookEvent, and Subscription, with a single additive migration.
  • SessionsPOST /v1/session accepts an optional merchantId, validated to be an active sub-merchant owned by the authenticated key (unknown/disabled/foreign → 400).
  • Escrow settlement — escrows inherit the session's merchantId; on release the amount/asset are recorded against that sub-merchant's settled volume (idempotent on escrowId, fire-once across both release paths).
  • Webhook isolation — dispatch is strictly scoped: an event with merchantId = M reaches only endpoints scoped to M; a platform event reaches only platform (null) endpoints. Endpoints can be registered with a merchantId; inbound webhooks and subscription events carry/inherit it.
  • Admin APIPOST/GET /admin/keys/:keyId/merchants (create / list with per-asset settled volume) and POST /admin/merchants/:id/disable.
  • Docs — new MULTI_MERCHANT.md and merchantId additions to WEBHOOKS.md.

Acceptance criteria

  • ✅ Creating a session with a merchantId routes settlement to that sub-merchant only.
  • ✅ Webhooks for one sub-merchant's escrow never reach another sub-merchant's endpoint (nor a platform endpoint, and vice-versa).
  • ✅ A platform can list its sub-merchants and per-sub-merchant volume via the gateway API.

Testing

  • Gateway test suite: 178/178 passing (TDD per change).
  • tsc --noEmit clean, Biome clean.

Closes #44

@aguilar1x aguilar1x left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

lgtm!

@aguilar1x
aguilar1x merged commit ec698e9 into PACTO-LAT:main Jul 19, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

feat(gateway): multi-merchant support — sub-accounts under a single publishable key

2 participants