Building a Multi-Tenant Payment Platform with Defensible Data Isolation

Define the boundary around a payment obligation#

A payment platform must keep one tenant’s recipients, balances, approval rules, provider credentials and exports inaccessible to another tenant. A tenant ID column organizes records; it does not authorize the user, constrain a privileged worker or prove that a callback belongs to the selected tenant.

Document a tenant-scoped chain from authenticated request to invoice, payment instruction, external account, callback, journal and report. The design below is a proposed implementation and verification plan for a platform using shared PostgreSQL tables. Adapt it to your provider and runtime rather than treating it as a statement about Gruv’s deployed architecture.

Choose placement from requirements you can operate#

Microsoft’s multitenant storage guidance treats isolation as a requirements decision, including customer keys, geography, restore policies and shared-resource contention. Choose stronger placement when those requirements demand it. There is no universal tenant count at which shared tables become unsafe, and a separate database still needs correct routing and authorization.

Bind tenant identity before data access#

Authenticate the principal, resolve its current tenant membership, and authorize the requested action on the specific tenant. If a URL or header selects a tenant, treat it as a requested scope and verify membership. Do not let the client replace the authenticated scope with a different tenant ID in the body.

Load the target recipient, invoice or payout under that verified scope. Validate that linked resources belong to the same tenant before making changes. For example, an invoice in tenant A must not reference a destination in tenant B even if the caller knows its globally unique ID. Use tenant-aware relationship constraints where practical, in addition to application checks.

Represent intentionally global operations separately. A service that aggregates platform metrics should have an explicit authorized scope and a limited output contract; it should not invent a default tenant or use an ordinary tenant endpoint with authorization disabled.

Make the deployed database role part of the policy#

PostgreSQL’s RLS documentation states that superusers and BYPASSRLS roles bypass row security. Owners normally bypass it too; FORCE ROW LEVEL SECURITY subjects owners to policies but does not constrain those first two categories. Serve tenant requests through a least-privileged non-owner role with neither bypass attribute, and inspect deployed role membership.

Enable RLS on tenant tables. Use USING to constrain existing rows and WITH CHECK to constrain inserted or changed rows. Review applicable policies together: permissive policies combine with OR. Whole-table operations such as TRUNCATE are outside RLS, so do not grant them to the request role.

For this design, each policy compares the row’s non-null tenant_id with the verified transaction tenant. Missing or invalid context must deny access or raise an error; it must never run an unscoped fallback. Protect every related tenant table, not only the payout table. Use composite tenant/resource references where required so a valid child identifier cannot link across tenants.

Keep schema ownership and migrations on a separate privileged path. Audit security-definer functions, views and administrative tooling for their effective privileges. A payment worker using an owner connection can defeat a policy that worked correctly in an API test.

Contain tenant context on pooled connections#

Begin a transaction, establish its authorized tenant, run all dependent queries on that same connection, then commit or roll back. PostgreSQL SET documentation defines SET LOCAL as lasting only through the current transaction; session settings can persist after commit. Use transaction-local context and re-establish it for every transaction.

Do not set the tenant on one pooled connection and query through another. Prohibit session-level tenant settings on the ordinary runtime path and configure checkout/reset behavior so an older session value cannot become a fallback. Roll back failed transactions before returning connections to the pool, including on cancellation. If context establishment fails, perform no tenant query.

A custom setting is an enforcement input, not authenticated identity. The trusted service must authorize its value. A role allowed to run arbitrary SQL may be able to change that setting, so RLS based on it does not protect against an attacker with unrestricted use of the same database identity. Constrain SQL entrypoints and credentials, and choose a stronger boundary when that threat is in scope.

Carry the boundary through asynchronous money movement#

The OWASP multitenant guidance includes transaction context and tenant-aware asynchronous work. A shared queue is not an authorization boundary. For the payment design here, create a job only after authorizing its producer, and bind the tenant, payout ID and destination version in a trusted message.

At consumption, authenticate the broker or producer path, resolve tenant scope and reauthorize the operation if permissions may have changed. Reload the payment instruction under that scope instead of trusting a message’s amount or wallet address. Missing scope, a foreign recipient or a revoked destination moves the job to a restricted exception queue before provider submission.

For a callback, verify the provider signature using the appropriate endpoint or account configuration. Resolve the external provider account and reference through a server-maintained mapping to the tenant and payout. An arbitrary tenant field in a signed payload is not sufficient: the signature proves the provider sent the payload, while the mapping establishes which account and obligation it represents.

Deduplicate events with the provider account and event identity included where those values are account-scoped. Apply monotonic, documented state transitions so replaying an old pending event cannot undo a final status. Commit the journal effect once, under a unique business-event constraint, and acknowledge the event only after durable processing or durable queuing.

A payout submission timeout is a money-outcome question as well as a job retry question. Preserve the original request identity and investigate the provider before sending a replacement. Tenant-scoped idempotency prevents one class of duplicate, but does not make an unknown transfer safe to resend through another provider.

Protect caches, exports and keys with the same scope#

• Key tenant-specific caches by tenant and resource, and authorize before returning cached results. A cache hit must not skip membership checks.
• Authorize the exact export and storage object before generating a signed download URL. Constrain the object and expiry; a tenant-named path alone is not access control.
• Select payout credentials and limits from the verified tenant’s configuration. Reject a provider-account mapping that belongs to a different tenant.
• Authorize decryption for the tenant and record the key version. Tenant-specific keys reduce exposure only when the decrypting identity is also constrained.
• Apply per-tenant concurrency and queue limits alongside global limits. Correct row isolation does not prevent one tenant exhausting shared workers.

Verify negative cases with payment-specific evidence#

Run these checks using the actual runtime role and pool mode in a non-production environment. Capture request identity, resolved tenant, provider-call count and resulting journal rows. Testing only returned HTTP status misses a background worker that still moved money. Keep test fixtures synthetic and avoid real transfers.

Migrate with an explicit tenant cutover#

If a tenant needs dedicated placement, copy its records with scoped counts and monetary totals, verify credential and provider-account mappings, and pause that tenant’s writers and queued work during the cutover. Establish one authoritative destination for new writes, then drain or rebind jobs so old and new stores cannot submit the same payout.

Compare open obligations, journals, external references and export access after migration. Retain a rollback plan that addresses any payments submitted after cutover; restoring a database snapshot does not reverse those external transfers. Review the same boundary evidence after a new worker, reporting tool or administrative feature is added.