Skip to content
SHC Docs

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.


Hyperswitch integrates INTO the Frappe payments abstraction as ONE gateway.

#ruling
P1One gateway, not N. Hyperswitch enters the Frappe payments abstraction as a single gateway. We do not grow N per-processor integrations.
P2Into, not instead of. Hyperswitch does not replace Frappe. Frappe/ERPNext keeps invoice reconciliation, tax and the ledger.
P3Hyperswitch owns the rail: the connector fleet, and critically the tokenization/vault that keeps card data off our servers and us out of PCI scope.
P4The abstraction already exists. The work is adding a gateway to it, not building it; see §3, which is the measured half.

concernownerwhy
Invoice, tax, receivables, the general ledgerFrappe / ERPNextIt is the book of record. This is the whole basis of the adjacent ruling.
Payment rail, PSP connector fleet, retries and routingHyperswitch300+ PSP integrations is the thing it is for: apps/standalone/hyperswitch/app.yaml:6.
Card data: tokenization / vaultHyperswitch★ 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: ffx has apps/ = builder erpnext frappe hrms india_compliance payments and bit has 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.


  1. A hyperswitch.plug.yaml on the Frappe app, consuming the existing hyperswitch socket; the provider half already ships.
  2. The gateway registration inside the Frappe payments app, so Hyperswitch appears as one selectable gateway rather than as a bypass of the abstraction.
  3. 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.
  4. 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.


  • 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.

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.