Hyperswitch integrates INTO the Frappe payments abstraction, as ONE gateway: owner ruling 2026-08-16
Status: OWNER RULING. A decision record of a conversation, not new analysis. Ruled in the same conversation as the Frappe-over-Medusa ruling and inseparable from it, split into its own file for findability (someone arriving with a Hyperswitch question will not look under a Medusa filename), cross-linked in both directions.
Date: 2026-08-16. Measured against shc main @ db497738e.
No code changes.
1. The ruling
Section titled “1. The ruling”Hyperswitch integrates INTO the Frappe payments abstraction as ONE gateway.
| # | ruling |
|---|---|
| P1 | One gateway, not N. Hyperswitch enters the Frappe payments abstraction as a single gateway. We do not grow N per-processor integrations. |
| P2 | Into, not instead of. Hyperswitch does not replace Frappe. Frappe/ERPNext keeps invoice reconciliation, tax and the ledger. |
| P3 | Hyperswitch owns the rail: the connector fleet, and critically the tokenization/vault that keeps card data off our servers and us out of PCI scope. |
| P4 | The abstraction already exists. The work is adding a gateway to it, not building it; see §3, which is the measured half. |
2. The division of labour
Section titled “2. The division of labour”| concern | owner | why |
|---|---|---|
| Invoice, tax, receivables, the general ledger | Frappe / ERPNext | It is the book of record. This is the whole basis of the adjacent ruling. |
| Payment rail, PSP connector fleet, retries and routing | Hyperswitch | 300+ PSP integrations is the thing it is for: apps/standalone/hyperswitch/app.yaml:6. |
| Card data: tokenization / vault | Hyperswitch | ★ The load-bearing one. Cards never touch our servers, which is what keeps us out of PCI scope. |
P3 is the reason to do this at all. Connector breadth is convenience; PCI-scope avoidance is a compliance posture, and it is not obtainable by writing more integrations ourselves; writing them is the thing that drags card data into our scope. Any future proposal to “just integrate Stripe directly” is a proposal to re-enter PCI scope and must be argued on that ground.
3. The measured fact that sets the size of the work
Section titled “3. The measured fact that sets the size of the work”payments (the Frappe gateway abstraction) is ALREADY RUNNING on both
production benches on the bitspur estate. Measured 2026-08-04 and recorded
in-repo for an unrelated purpose (the bench apps-mode migration), which is
what makes it a fact rather than a recollection:
“MEASURED on the bitspur estate 2026-08-04, where the two restored production benches run this app:
ffxhas apps/ = builder erpnext frappe hrms india_compliance payments andbithas apps/ = builder erpnext frappe frappe_keycloak hrms payments scrum”apps/flagship/frappe/vars.yaml:10-13
So on both estates the abstraction is installed and live. The work is adding a gateway to an abstraction that exists, not building an abstraction. That is a materially smaller program than it is usually estimated to be, and misestimating it is how the “just integrate a processor directly” argument keeps getting oxygen.
Hyperswitch is also already packaged as an SHC app, with a socket ready to be consumed:
apps/standalone/hyperswitch/ app.yaml compose.yaml vars.yaml backup.yaml hyperswitch.socket.yaml # publishes hostname / port / adminApiKey hyperswitch.exporter.yaml postgres.plug.yaml files/ tests/The socket publishes hostname, port (8080) and adminApiKey
(apps/standalone/hyperswitch/hyperswitch.socket.yaml:22-26). What does not
exist yet is the consumer half on the Frappe side; there is no
hyperswitch.plug.yaml under apps/flagship/frappe/ today. That plug, plus
the Frappe Payment Gateway wiring behind it, is the owed work.
4. Owed work
Section titled “4. Owed work”- A
hyperswitch.plug.yamlon the Frappe app, consuming the existinghyperswitchsocket; the provider half already ships. - The gateway registration inside the Frappe
paymentsapp, so Hyperswitch appears as one selectable gateway rather than as a bypass of the abstraction. - Keep reconciliation on the ERPNext side (P2): capture and refund events land as ERPNext payment documents against the invoice. Nothing about the ledger moves to Hyperswitch.
- Record the PCI posture explicitly wherever the payment path is documented, so P3 is visible to whoever next proposes a direct processor integration.
None of this is scheduled by this ruling; the ruling fixes the shape, not the date.
5. What this ruling does not say
Section titled “5. What this ruling does not say”- It does not replace Frappe with Hyperswitch anywhere (P2).
- It does not authorise per-processor integrations behind or beside the abstraction (P1).
- It does not rule on the marketplace’s revenue-share or metering design,
which remains as ruled in
docs/proposals/2026-08-14-marketplace-architecture.md§4; that document already names Hyperswitch as “prob hyperswitch is the best route” behind a pluggable layer, and this ruling is that sentence settled. - It does not schedule the work in §4.
6. Verified vs unverified
Section titled “6. Verified vs unverified”Verified in-repo at db497738e: that the Frappe payments app is
installed on both bitspur-estate production benches, measured 2026-08-04
(apps/flagship/frappe/vars.yaml:10-13); that Hyperswitch is a packaged SHC
app with a socket publishing hostname/port/adminApiKey
(apps/standalone/hyperswitch/hyperswitch.socket.yaml:22-26,
apps/standalone/hyperswitch/app.yaml:1-16); that no Hyperswitch plug
exists on the Frappe app (ls apps/flagship/frappe/: imap, keycloakAdmin,
mysql, nextcloud, nextcloudPicker, oidc, smtp plugs only); that the
marketplace architecture already leaned this way
(docs/proposals/2026-08-14-marketplace-architecture.md §4).
unverified: do not assert these without a source: the “300+ PSP
integrations” figure, which is Hyperswitch’s own marketing copy as recorded in
apps/standalone/hyperswitch/app.yaml:6 and was not independently counted;
the precise PCI SAQ level our posture would qualify for (the ruling’s claim is
the direction (card data off our servers), not a certification tier); whether
the Frappe payments app’s Payment Gateway extension seam admits Hyperswitch
without a custom app, which is the first thing §4.2 must establish; the
Hyperswitch app’s license.id, which is literally unverified in
apps/standalone/hyperswitch/app.yaml:19.
7. See also
Section titled “7. See also”- Frappe is the platform; Medusa is not adopted as infrastructure: the ruling this one is inseparable from; DesiBox’s payments path (§4.3) depends on this file
- Marketplace architecture §4: the pluggable payment layer and the store’s money path
- The flagship bar is payment, not license family: unrelated sense of “payment”; noted here so the two are not confused