%201.svg)
How to Design a Multi-Tenant Chargeback Architecture for Payment Platforms
Chargebacks?
Dat is niet langer jouw probleem.
Haal 4x meer chargebacks terug en voorkom tot 90% van de inkomende betalingen, dankzij AI en een wereldwijd netwerk van 20.000 handelaren.
Meer dan 600 beoordelingen
TL;DR:
- A multi-tenant chargeback architecture should bind every dispute, evidence object and action to an immutable platform tenant and merchant account. Authorization must be enforced server-side on every object, with separate platform and merchant roles, auditable service access and no reliance on client-side filtering.
- Bind every dispute, evidence file, job and export to an authorized tenant and merchant.
A multi-tenant chargeback architecture should bind every dispute, evidence object and action to an immutable platform tenant and merchant account. Authorization must be enforced server-side on every object, with separate platform and merchant roles, auditable service access and no reliance on client-side filtering.
Chargeback systems hold transaction details, customer communications, delivery records, policies and financial outcomes. In a platform product, that information belongs to different merchants that share the same infrastructure. A routing error is therefore both an operational defect and a data-isolation incident.
The safest design makes tenant context part of the data model and authorization decision from the start. It cannot be added reliably as a filter after the product is built. Start with the canonical dispute model across processors so source identifiers remain attached to merchant ownership.
At a glance
The contracting platform or partner boundary.
The sub-merchant or seller whose transactions and disputes are managed.
A credentialed source associated with one or more permitted merchant accounts.
A case bound to tenant, merchant, processor account and original transaction.
Versioned artifacts and generated packages with the same ownership chain.
Platform admin, merchant user, service identity or provider operator with scoped permissions.
An immutable record of access, changes, generation, approval and submission.
Enforce tenant and merchant authorization at every boundary, including workers, files, exports and support tools.
Put tenant identity in every authorization path
A request should resolve tenant and merchant context from authenticated claims and server-side mappings. The service should then query or mutate objects only within that scope. Passing a merchant ID in a URL is not authorization; the system must confirm that the caller is entitled to that merchant.
OWASP identifies broken object-level authorization as a leading API risk. Chargeback objects are especially sensitive because identifiers can expose the existence of transactions and disputes even when the payload is hidden.
Model the hierarchy explicitly
A simple one-tenant-to-one-merchant model rarely survives. Platforms may have legal entities, brands, locations, connected accounts and seller groups. Define which entity owns the transaction, which entity can see aggregate reporting and which entity can approve evidence.
Use stable internal IDs and mapping tables. Do not use email domains, business names or processor display names as tenant keys. Those attributes can change and are not unique.
Separate human roles from service identities
Platform administrators may need portfolio visibility, merchant users should see only their own cases and background services need narrow API access. Each actor type requires a separate permission model, credential lifecycle and audit trail.
PCI DSS scope can include services that affect payment-account security without storing full card data. Assess the actual service, access paths and responsibility boundary, then document the applicable controls with the compliance team or assessor.
Design async work with tenant context attached
Evidence generation, webhook processing and submission happen asynchronously. Queue messages and jobs must carry immutable tenant, merchant and dispute identifiers. Workers should re-authorize the relationship before accessing data rather than trusting a user-supplied job payload.
Logs and traces should include tenant-safe correlation IDs but avoid unnecessary personal or payment data. Operational teams need to diagnose a job without gaining broad access to merchant records.
Test isolation as a product requirement
Create automated tests in which a valid user from tenant A requests, lists, updates and exports objects from tenant B. Repeat them across direct object access, search, batch endpoints, webhooks and reports. Successful isolation requires empty or denied results without disclosing whether the object exists.
Also test support tooling and administrator impersonation. Privileged workflows should require explicit authorization, be time-bound where possible and create a clear audit event.
Implementation sequence
Map platform, legal entity, merchant, location, processor account and user relationships.
Separate platform users, merchant users, services and provider operations.
Require tenant and merchant ownership on disputes, evidence, documents and jobs.
Check ownership and permission on every read, write and export.
Attach signed or server-generated tenant context to queues and webhook jobs.
Capture access, changes, approvals, submissions and privileged support activity.
Test direct objects, lists, reports, exports and background workflows.
Failure modes and controls
| Failure mode | Business consequence | Control |
|---|---|---|
| Client-side merchant filtering | A caller can request another merchant's object directly. | Enforce authorization in every backend object lookup. |
| Shared platform API key for all services | Compromise grants portfolio-wide access. | Issue scoped credentials and separate environments. |
| Tenant context dropped in queues | Background workers process data under the wrong account. | Use immutable context and revalidate ownership before access. |
| Support access without audit | Privileged activity cannot be explained. | Log reason, actor, scope, time and object for every privileged action. |
| Search index missing tenant filters | Results leak metadata across merchants. | Make tenant a mandatory partition and query condition. |
Cross-tenant acceptance tests for dispute operations
A row-level tenant key is only the start. Test the complete chargeback API path, then repeat the same boundary checks through webhook workers, search, files and support tools. Pair each test with a result that can fail a release, rather than treating “has tenant_id” as a pass.
Recommended test fixtures for the platform’s own implementation, not vendor API response guarantees.
| Test fixture | Expected behavior | Evidence to retain |
|---|---|---|
| A merchant A user requests merchant B’s dispute or evidence ID | Deny access without disclosing foreign case content or existence. | Actor, requested object, resolved scope and denial result. |
| Two processor accounts reuse the same source case reference | Keep two cases under distinct tenant, merchant and processor-account mappings. | Composite mapping keys and the original source payloads. |
| An export requester loses access while the job is queued | Reauthorize before producing or releasing the export; deny a new download request from the revoked actor. | Requesting actor, policy decision time and cancellation or denial event. |
| A worker cannot retrieve merchant A’s processor credential | Fail within A’s scope and escalate; never use another merchant’s fallback credential. | Job scope, credential reference and exception owner. |
| A search or cache lookup repeats under a different merchant | Return only the new caller’s authorized results, including counts and snippets. | Tenant-bound cache key or query scope and result audit. |
| A batch contains authorized and foreign-merchant IDs | Do not read or mutate unauthorized objects; document whether permitted items proceed or the whole batch fails. | Per-item authorization decisions and the chosen atomicity rule. |
| Merchant A creates a large evidence-generation backlog | Measure merchant B’s queue age against its internal submission cutoff; verify the chosen quotas and worker isolation. | Per-tenant queue age, available capacity and deadline alerts. |
Scroll horizontally when all columns do not fit.
Treat document links as a separate access path. Amazon S3 describes presigned URLs as bearer tokens: possession can grant access until the URL or underlying credentials expire or access is otherwise denied. Revoking a user in the platform does not, by itself, revoke a previously issued storage URL. Choose a bounded lifetime and, where immediate revocation is required, an authorized download path that enforces current policy. Test both a newly requested link and a link issued before revocation.
Chargeflow’s EaaS quickstart currently documents a seven-day evidence download link and obtaining a fresh link by reading the evidence record. That documented lifetime is not a platform user-session policy. Store the account and evidence relationship, protect the link, and apply your own access decision before distributing it. The evidence-generation guide covers the artifact handoff.
Evidence base: PayPal embedded RBAC guidance; Adyen user roles documentation.
How Chargeflow Connect fits
Chargeflow Connect: The merchant onboarding guide requires a Chargeflow account for each merchant. Map its returned account ID to the platform’s immutable merchant ID; the account anchors that merchant’s disputes, evidence and integrations.
Connect documents team permissions and platform APIs. Enforce authorization in the platform’s own services, especially where dispute data joins internal orders, users or financial records.
Confirm the delivery model and entitlement with your account team. The platform documentation marks White-Label as beta and Alerts-as-a-Service as Soon; Evidence-as-a-Service is not positioned for merchants of record.
Build a secure multi-merchant chargeback product on Chargeflow Connect.
Frequently asked questions
Is a merchant ID in the API request enough for tenant isolation?
No. The backend must verify that the authenticated actor is allowed to access that merchant before using the ID.
Should each merchant have a separate database?
Not necessarily. Logical isolation can work when ownership fields, authorization, storage controls and testing enforce separation consistently.
Can platform administrators see every merchant?
They can when their role requires portfolio oversight, but access should be explicit, logged and limited to necessary functions.
What should an audit log contain?
It should contain actor, tenant, merchant, object, action, timestamp, result and a reason for privileged support access.
How does PCI DSS relate to an embedded chargeback product?
Scope depends on the data and services involved, but service providers that can affect payment-account security should assess applicable controls and document the responsibility boundary.
Bronnen
The original PCI DSS v4.0 assessment reference below is retained as a historical source. Use the current PCI SSC Document Library and the service-provider scope FAQ when assessing applicable requirements.
- PCI DSS v4.0 service-provider assessment guidance
- PCI SSC service-provider scope FAQ
- OWASP API Security Top 10
- Chargeflow for Platforms overview
- Chargeflow merchant onboarding API guide
Related platform guides
Add Chargeback Management to Your Platform
Use a platform-first integration to offer chargeback automation across your merchant base.
Chargebacks?
Dat is niet langer jouw probleem.
Haal 4x meer chargebacks terug en voorkom tot 90% van de inkomende betalingen, dankzij AI en een wereldwijd netwerk van 20.000 handelaren.
.png)
