Why open source payment orchestration for SaaS companies needs its own plan
A SaaS or marketplace team whose recurring charges depend on one processor has a single point of failure in its revenue. Self-hosted Hyperswitch can sit in front of several processors for routing, vaulting and retries, while a billing system such as *Kill Bill* owns subscription state, invoices and dunning schedules. The two systems should be planned together, because the payment layer and the billing layer each hold a piece of the customer's payment lifecycle.
SaaS payments differ from one-off checkout in three ways. Recurring and usage charges mean the platform initiates payments without a customer present, so stored credentials, network tokens and merchant-initiated transaction flags must be handled correctly for every processor in the route. Marketplaces add payouts to sellers, which means the team must decide whether funds flow through its own merchant account, what reconciliation looks like per seller, and which processor or payout provider owns each leg. Dunning is the other gap: failed renewals cause involuntary churn, and retry timing, decline-code handling and card updater behavior should be defined per processor, not assumed to match across providers. Confirm which of these your processors support before you design the retry rules.
The payment layer often holds more card data than the product team expects, because every stored card, retry queue and webhook payload can carry sensitive fields. The short answer for most SaaS teams is to use Hyperswitch for routing, vault and retries, Kill Bill for subscription state, and an external PCI vault so that your own environment stores tokens rather than primary account numbers. Under that design the scope question becomes concrete: which services touch raw card data, who holds the vault keys, and which processors and third-party providers are in the route. Ask your implementation partner to map those answers before any connector goes live.
Which rules shape a SaaS payment stack and what they mean for the build
This table maps the rules most likely to shape a SaaS or marketplace payment stack to what each one means for a self-hosted Hyperswitch build. Read each row for the requirement source, the build consequence and the questions to put to counsel, since applicability depends on your entity, customers and data flows.
| Requirement | What it means for the build | What to confirm with counsel |
|---|---|---|
| PCI DSS scope driven by card data handling | Where card data is stored and transmitted sets the cardholder data environment. Keeping raw card data in an external vault or a processor-hosted page usually shrinks scope, while an in-house vault brings the platform fully into assessment. See the PCI DSS scope and requirement 3 sibling topics. | Which vault model you run, who holds PCI DSS responsibility in writing, and whether your processors and vault provider are listed as third-party service providers in your assessment. |
| FTC Safeguards Rule (16 CFR 314.4) | Applies only if the company is a covered financial institution. If it is, the build needs encryption of customer information in transit over external networks and at rest, multi-factor authentication for anyone accessing information systems, documented change management, and logging of authorized user activity. | Whether your lending, payouts, wallet or embedded finance activities make you a covered financial institution under the FTC rule. |
| GDPR Article 28(3) processor terms for payer data | If you process payer personal data on behalf of merchants or customers, your contracts must limit processing to documented instructions, including for transfers, and require Article 32 security measures. Routing rules and vault access must follow those instructions. | Whether you act as controller or processor for each data flow, the content of your data processing agreements, and any transfers to processors outside the EEA. |
| SOC 2 Trust Services Criteria | Enterprise and marketplace buyers often ask for a SOC 2 report covering the security common criteria, and may add availability, processing integrity or confidentiality. The build needs evidence of access control, change management and monitoring across the orchestration, vault and key management components. SOC 2 is an examination by an independent CPA firm, and DeployOpen does not issue it. | Which Trust Services Criteria categories your customers require, whether they want a Type 1 or Type 2 report, and whether the report may be shared under its restricted-use terms. |
| EU Data Act switching rights | If the platform is a data processing service provider, customers must be able to switch to another provider or to on-premises infrastructure. The build should export tokens, routing configuration, transaction records and merchant settings in a usable form. From 12 January 2027, switching charges may not be imposed. | Whether your service qualifies as a data processing service under Regulation (EU) 2023/2854, and what export formats and notice periods your contracts commit to. |
Which open source platforms fit a SaaS payment stack and why
A SaaS payment stack usually pairs an orchestration layer with a billing engine and a vault decision. The cards below cover the components that connect them, the boundaries you must set between them, and the access and scope choices that follow.
Hyperswitch for multi-processor routing
Hyperswitch is an Apache-2.0 composable payments platform maintained by Juspay, with its latest release, v1.128.0, published on October 16, 2026. Its modules cover payment orchestration, routing, retries, vault tokenization, revenue recovery, reconciliation and cost observability, and it connects to more than 100 payment processors. For a SaaS company, the check is whether your current processors, payment methods and regional acquirers have connectors that you can test in your own environment before you move traffic.
Kill Bill for subscription and invoice state
Kill Bill is an Apache-2.0 subscription billing and payments platform, with killbill-0.24.22 published on September 29, 2026. It holds plans, subscriptions, usage, invoices and account balances, which makes it the system most likely to be the source of truth for what a customer owes. Confirm early whether your usage metering, proration and tax rules live inside Kill Bill or in a separate service, because that decision determines what the orchestration layer receives on each charge.
Setting the billing and orchestration boundary
Hyperswitch and a billing system connect through their APIs, but the integration only works if one system owns each decision. Typical questions are which system owns invoice status, which one sets retry timing for failed renewals, and which one runs dunning emails and customer notices. Illustratively, if both systems retry the same declined invoice, a customer can be charged twice or receive conflicting notices. Write this ownership map down before the first connector goes live.
Self-hosted vault or external PCI vault
Hyperswitch documents three vault models: a self-hosted native vault that makes you fully responsible for PCI DSS certification and data handling, self-hosted orchestration with an external PCI vault provider, and self-hosted orchestration with the SaaS Hyperswitch Vault. Each choice changes which systems enter your cardholder data environment. A SaaS company should compare the scope of each model with its assessor before selecting a vault, since the external option usually shrinks the systems that store card data while adding a third-party dependency.
Control Center access with OpenID Connect
The Hyperswitch Control Center supports single sign-on through OpenID Connect only, with SAML not supported. It has no just-in-time or SCIM provisioning, so users must be invited first, and roles are managed inside Hyperswitch rather than mapped from your identity provider. For a team that runs routing rules and refund actions, this means offboarding and role reviews must be done in two places. Confirm the access review process and who approves role changes before rollout.
Where the vault, billing and routing sit in a SaaS deployment
With the self-hosted, in-house PCI model, the company runs the Hyperswitch card vault (locker) itself, so card data is stored and encrypted inside its own environment. The Hyperswitch docs state that the merchant is fully responsible for PCI DSS certification and data handling. For a SaaS company, this places the vault, the encryption service for key management and the database holding tokens inside the PCI DSS scope it must assess every year.
- PCI scope effects: The vault cluster, its database, its key management path and every system that can reach them become part of the cardholder data environment and need segmentation and evidence.
- Cluster footprint: Helm charts on Kubernetes deploy the Router and Scheduler services, with PostgreSQL in a primary and replica setup and Redis for caching and the scheduler queue, alongside the vault service.
- Key management: Confirm how encryption keys are generated, stored, rotated and separated from the database, and whether a hardware security module is part of the design.
- Operational ownership: Patching, backups, restore tests and incident response for the vault sit with the company's own team.
- Control Center access: Single sign-on works only through OpenID Connect, with no SAML, JIT or SCIM provisioning, so users must be invited and roles are managed inside Hyperswitch.
Before committing, ask the platform team to map each vault component to the PCI DSS assessment and to name who holds the key custodian role.
In the self-hosted orchestration model with an external PCI vault provider, such as VGS or Tokenex, the card data is held by the external provider and Hyperswitch handles routing, tokens and workflows on the company's cluster. The Hyperswitch docs describe this as a way to keep orchestration in-house while outsourcing the vault. The PCI scope effect depends on how the integration is built, so the design must be checked against the provider's own attestation and the company's data flows.
- PCI scope effects: Scope usually shrinks because raw card numbers should not reach the company's Router, database or logs. Confirm this with the provider's documentation and a data flow review.
- Cluster footprint: The Kubernetes deployment still runs the Router, Scheduler, PostgreSQL primary and replica and Redis, which hold tokens, transaction metadata and retry state.
- Third-party management: The external vault becomes a third-party service provider in the route, so contracts, responsibility matrices and periodic reviews need an owner.
- Token portability: Ask how tokens and stored credentials can be exported or moved if the provider changes, since this affects switching costs and migration timelines.
- Control Center access: The same OpenID Connect-only limit applies, so the company must manage user invitations and Hyperswitch roles manually or through its own process.
Ask the partner to show the exact fields that leave the browser and where tokenization happens.
In the self-hosted orchestration model with the SaaS Hyperswitch Vault, the orchestration layer runs on the company's Kubernetes cluster while card storage is handled by the hosted Hyperswitch service. This reduces the vault the company must operate, but it introduces a dependency on a vendor-hosted service and on the terms that govern it. Scope and data location need to be confirmed against the current Hyperswitch documentation before a design is fixed.
- PCI scope effects: The company's cluster should not store card data, which generally narrows the cardholder data environment. The assessment must still cover how cards are captured, how tokens are passed and any hosted pages or SDKs used.
- Cluster footprint: Helm charts, PostgreSQL with a primary and replica, and Redis for caching and the scheduler queue remain on the company's infrastructure and still need backups, monitoring and access control.
- Vendor dependency: Review the service terms, data processing terms, hosting location and exit options, including how tokens are returned if the relationship ends.
- Fees and recurring costs: Confirm whether vault usage is priced per token or per transaction and how that scales with subscriber growth.
- Control Center access: Single sign-on remains limited to OpenID Connect, so role design and user lifecycle are still managed inside Hyperswitch.
Ask for written confirmation of where card data is stored and how a customer would move stored tokens out of the hosted vault.
How a SaaS team moves from one processor to orchestrated billing
This sequence moves a subscription or marketplace platform from a single processor integration to Hyperswitch-routed payments with Kill Bill handling recurring charges, while keeping cardholder data in a small, documented scope. Each phase closes with a named deliverable and an owner who signs it off before traffic moves.
Scope charge types and markets
The product, finance and payments leads inventory every charge type in use, including subscriptions, usage-based invoices, marketplace splits and refunds, plus the countries and currencies each one touches. The team lists which payment methods each market needs and which processor currently handles them. The output is a signed charge and market matrix, approved by the head of product and the finance controller, that defines what the orchestrated flow must cover before any connector is built. Confirm in writing whether any processor contract restricts routing or stored-card portability.
Deploy Hyperswitch in a staging cluster
The platform engineering team deploys Hyperswitch into a non-production Kubernetes cluster in the company's own cloud account, using the project's Helm charts and the self-hosting guide as the starting point. The deployment includes the Router and Scheduler services, PostgreSQL with replication, Redis, and the Control Center. Network policies, secrets handling and access to the cluster are set against the same standards as production. The output is a reproducible deployment definition in version control and a health report, signed off by the infrastructure lead and the security engineer who reviews the cluster boundary.
Configure primary and secondary processor connectors
The payments engineers configure a connector for the current primary processor and a second processor, then set the sandbox credentials, webhook endpoints and payment method mappings for each. They test authorization, capture, refund, void and webhook handling for each charge type defined in the scope matrix. Connector credentials are held in the platform's secret store and never in code or configuration files. The output is a connector test report showing pass or fail per charge type and per processor, signed off by the payments lead and the processor relationship owner.
Select vault model and plan token migration
The security and payments leads choose one of the vault models Hyperswitch documents: the native in-house vault, an external PCI vault provider, or the SaaS vault. The choice is made on the basis of who will carry PCI DSS responsibility for stored card data, and the team confirms that choice with its QSA or internal assessor before any data moves. The team then writes a token migration plan that covers how existing processor tokens are exported or re-tokenized, how mismatched or expired cards are handled, and how the migration is validated. The output is a signed vault decision record and a migration runbook approved by the CISO or security lead and the finance controller.
Integrate Kill Bill and design retry rules
The billing engineers connect Kill Bill to Hyperswitch so that recurring invoices create payment requests through the orchestrator, and webhook events from Hyperswitch update invoice and payment states in Kill Bill. In parallel, the team designs retry schedules and fallback routing: which decline codes trigger a retry, how long the retry window runs, and when a payment fails over to the secondary processor. Every rule is written as a versioned configuration and tested against sandbox declines. The output is an integration test suite and a signed retry and routing rule book, approved by the revenue operations lead and the billing owner.
Run shadow reconciliation
Before any customer traffic moves, the finance operations team runs the orchestrated flow in parallel with the existing processor path, compares authorization outcomes, captured amounts, refunds and settlement files, and records every mismatch by cause. The team checks that ledger entries from both paths reconcile to the bank statements and processor reports for the same period. Mismatches are classified as data, configuration or processor-side issues, and each class has an owner and a fix. The output is a reconciliation report with zero unexplained differences, signed off by the finance controller and the head of payments operations.
Execute staged traffic cutover
The platform team moves a small, defined share of traffic to the orchestrated path, starting with the charge types and markets that have the lowest risk in the matrix, and expands only after each stage passes its checks. Rollback steps are rehearsed before the first stage, and the on-call rota covers the cutover window. Authorization rates, decline reasons, latency and webhook delivery are compared against the baseline at each stage. The output is a stage log with a go or no-go decision per stage, approved by the engineering manager, the payments lead and the business owner of each affected product line.
Collect post-cutover evidence
After the final stage, the compliance and security teams gather the evidence that will support later assessments: the cluster configuration and change history, access reviews for Hyperswitch and Kill Bill, logging and monitoring records, the vault decision record, the PCI scope diagram with its segmentation boundary, connector and processor inventory, and the reconciliation reports. The team confirms with its auditors which evidence they expect for SOC 2 or PCI DSS purposes. The output is an evidence binder indexed to the controls it supports, reviewed by the compliance lead and filed with the CISO for the next scope confirmation. DeployOpen prepares this material, but the independent assessor decides what it proves.
How retries and revenue recovery change failed renewals
Failed renewals split into two groups that need different handling, and the first decision is how your team classifies each decline. Soft declines (such as insufficient funds or a temporary issuer or network problem) may succeed on a later attempt, so they justify a scheduled retry. Hard declines (such as a closed account, a card reported lost or stolen, or an invalid card) will keep failing, so retrying them mostly adds processor cost and issuer scrutiny. These customers need a card update, a new payment method or a direct request to the customer. In a self-hosted Hyperswitch deployment, confirm which decline codes each connector returns and how the platform maps them, because the mapping decides which path a failed renewal takes.
Hyperswitch handles retry and recovery logic through its Router and Scheduler services, backed by PostgreSQL and Redis. Confirm in the Hyperswitch revenue recovery and routing documentation which retry and recovery settings your version exposes, and whether they can be set per decline type, per connector or per merchant. Where they can, define separate rules for soft and hard declines, including attempt limits, timing and the fallback processor for each. If your billing system is Kill Bill, assign ownership of each retry to one component. Kill Bill's dunning and Hyperswitch's retries must not both reattempt the same invoice in the same window, or a customer may be charged twice or hit the issuer with duplicate attempts. Record which system owns each renewal and check that the decline event flows back to Kill Bill with the correct status.
Retry rules are business decisions, not defaults to accept from a platform. Finance, customer success and risk should agree on attempt counts, timing, the grace period before service suspension and when a customer is contacted. Test those rules in staging with a sample of real declined transactions from your past renewals, replayed against sandbox connectors, and check the outcomes against what your processor reports. Keep the sample and the results as change records, since they show how the rules were chosen. Before committing, confirm what your chosen Hyperswitch version supports, what your billing system supports and what your implementation partner will build and test, in writing and in the statement of work.
What SOC 2 and enterprise customers ask to see from the payment layer
This table maps the evidence a SOC 2 examiner or enterprise security reviewer usually asks for to the self-hosted payment components that produce it. Read each row as a question: what the auditor will test, which component holds the record, and what gap to close before the examination period starts. DeployOpen prepares the controls and evidence; independent auditors issue the SOC 2 report.
| Evidence area | What it shows | Where it lives in the self-hosted stack | What to confirm before the period starts |
|---|---|---|---|
| Logical access (CC6) | Who can reach the Control Center, vault and key services, and how access is granted and removed | Control Center user list, role assignments, SSO configuration, vault and encryption service access logs | Whether SSO uses OpenID Connect only, how invitations and role changes are approved, and how leavers are removed, since Hyperswitch Control Center has no JIT or SCIM provisioning |
| Change management (CC8) | Approval and testing of routing rule and connector changes before they reach production | Git history or ticketing records for configuration, deployment logs from Helm releases, sandbox test results | Whether routing changes follow the same approval path as code, and whether a rollback record exists for each change |
| Monitoring and logging (CC7) | Detection of anomalous payment activity and failed authentication attempts | Router and scheduler logs, observability output, alerts on connector errors and unusual refund or payout patterns | Log retention period, who reviews alerts, and whether logs are forwarded to a central store the vault team cannot edit |
| Availability (A1) for renewal runs | Recurring charges and dunning retries run on schedule, with capacity and failover evidence | Scheduler queue health, PostgreSQL replica status, Redis availability, failover test records | Restore test results, recovery targets agreed with the business, and proof that scheduled retries resume after an outage |
| Processing integrity (PI1) for charge accuracy | Amounts, currencies and statuses in the orchestrator match what each processor recorded | Reconciliation reports from the reconciliation module, exception queues, daily settlement files from each processor | How mismatches are assigned, aged and closed, and who signs off the reconciliation each period |
| Confidentiality and data handling (C1) | Customer and payment data are encrypted and key access is limited | Encryption service key management records, TLS configuration, vault encryption settings | Key rotation procedure, key custodian list, and where keys are generated and stored |
| PCI DSS scope documentation | Which systems store, process or transmit account data and how that boundary is kept small | Vault model chosen (in-house, external PCI vault or SaaS vault), network segmentation diagrams, list of connected processors and third-party providers | Annual scope confirmation with the QSA or internal assessor, and written responsibility split for each vault and processor |
| Type 1 versus Type 2 coverage | Type 1 describes controls as designed at a point in time; Type 2 tests operating effectiveness across a period | Control descriptions and evidence samples dated across the full observation window for Type 2 | Which report the customer asks for, and that the examination period, not DeployOpen, sets the report's coverage |
What SaaS teams ask before hiring an implementation partner
How much effort does a Hyperswitch and Kill Bill rollout take?
The effort depends mostly on scope, so no fixed figure applies to every SaaS company. The main drivers are the number of processor connectors and payment methods, the vault model you choose, and how deeply Kill Bill is wired into checkout, invoicing and entitlement logic. Hyperswitch connects to more than 100 processors according to its README, but each connector you need still has to be configured, tested and reconciled. Ask any partner to break the estimate into connectors, vault work, billing integration, reconciliation and operations, and to state which of those items are one-time and which recur.
Can our internal team run the platform after handover?
Yes, if the handover is planned for it, but the team needs ongoing Kubernetes, PostgreSQL, Redis and payments skills. Hyperswitch runs a Router and Scheduler backed by PostgreSQL with a master and replica setup and by Redis, so on-call engineers must understand both the application and its data tier. Ask the partner to deliver runbooks, dashboards, alert definitions, upgrade procedures and a named list of skills your staff need before go-live. Agree in the written scope whether training and shadowing are included, and how long the partner supports the system after cutover.
What does the work need from finance, product and security?
Finance owns processor contracts, settlement reports and reconciliation sign-off, so they must confirm which entity and merchant accounts each route uses. Product owns checkout flows, plan and price mappings in Kill Bill, retry and dunning rules, and the customer messages for failed payments. Security owns the vault decision, access control, key handling and evidence for your controls. Hyperswitch Control Center supports single sign-on through OpenID Connect only, not SAML, and does not offer JIT or SCIM provisioning, so security should review that gap early. Name one decision owner per function in the scope document.
How long do the phases take in practice?
Phase length depends on processor onboarding timelines, the number of markets and payment methods, and how many billing flows you migrate. Processor certification and sandbox approvals often run on the processors' schedules rather than the project's, so they tend to set the critical path. A reasonable first step is to ask for a phase plan with dependencies, including processor approvals, test windows and cutover criteria. Any timeline in a proposal should come from the written scope and be reviewed against those external dependencies rather than accepted as a fixed promise.
How does PCI scope change with the vault choice?
Scope changes most with the vault model, because that decides whether your systems store, process or only transmit card data. Hyperswitch documents three self-hosted models: the native Hyperswitch Vault with in-house PCI, self-hosted orchestration with an external PCI vault provider such as VGS or Tokenex, and self-hosted orchestration with the SaaS Hyperswitch Vault. In the in-house model, the Hyperswitch docs state the merchant is fully responsible for PCI DSS certification and data handling. An external vault generally keeps raw card data out of your environment, but you still need to confirm your own scope with a qualified assessor and document how the orchestration layer touches tokens.
What recurs after go-live?
Recurring work includes platform upgrades, monitoring and on-call, processor and connector changes, routing rule reviews, reconciliation checks, certificate and key rotation, and annual PCI scope confirmation. Hyperswitch publishes releases on GitHub, so upgrade testing should be a standing task, not an emergency. Processor API changes and new payment methods also require connector updates. Ask whether support is covered by a retainer, how upgrades are tested in a non-production environment, and who approves changes that affect live payments.
How is a fixed-scope engagement priced from a written scope?
DeployOpen does not publish a price list. Most engagements are fixed-scope, and the quote follows from a written scope that sets deliverables, timelines and responsibilities before work starts. Ask for the quote to separate one-time items such as design, connector setup, vault integration, billing integration, testing and handover from recurring items such as retainers for upgrades, monitoring and continuous testing. Also ask which costs sit outside the engagement, including processor fees, vault provider fees, cloud infrastructure, HSMs and your own PCI assessment.
What to ask a partner before a SaaS payment migration
Start with the state model, because most billing and payment errors in a SaaS migration come from two systems disagreeing about what a payment means. Ask the partner to show, in writing, how each Kill Bill subscription and invoice state maps to Hyperswitch payment states, including which system owns the transition for a failed renewal, a partial refund, a chargeback and a dunning retry. Ask who owns the mapping file or configuration, how it is versioned, and what happens to subscriptions that are mid-cycle when a mapping changes. Ask how marketplace payouts, if any, are handled: whether split or payout flows run through Hyperswitch or a separate payout provider, how seller balances are recorded, and which system reports the money owed to each seller. A partner who cannot explain these flows in plain terms has not yet designed them.
Next, ask how the card vault and key management are isolated and who controls each piece. The Hyperswitch card vault is a separate service, and self-hosted deployments can also use an external PCI vault provider. Ask which of the three documented vault models the partner recommends for your volume and risk, where encryption keys are generated and stored, who holds administrative access to the vault and the encryption service, and how that access is logged. Ask for the PCI DSS responsibility split in writing, stating which controls the partner operates, which your team operates, and which the processors and vault provider attest to. Also ask whether the Control Center single sign-on is OpenID Connect only, since SAML is not supported and roles are managed inside Hyperswitch, and how that affects your identity governance.
Then ask how routing and retry changes are tested before production, and how the partner has tested failover between two processors. Request the test plan: a staging environment with processor sandbox accounts, replayed traffic from the existing gateway, and explicit pass criteria for authorization rate, decline handling and duplicate charge prevention. Ask for evidence of an actual failover test between two connectors, including the trigger, the time to switch, and how in-flight payments and stored tokens behaved. Finally, ask how reconciliation works across billing, processors and the general ledger, how a payment that succeeds at the processor but fails in Kill Bill is detected, who receives the exception report, and how upgrades to Hyperswitch and Kill Bill are rolled out without payment downtime. Close by asking what the handover to your internal team includes: runbooks, on-call responsibilities, documented configuration, and training, all written into the fixed scope before work starts.
How DeployOpen scopes and supports SaaS payment orchestration
DeployOpen plans, implements, integrates, hardens, documents and supports self-hosted open-source platforms inside your own cloud accounts, data centers or air-gapped networks. For SaaS payment orchestration, that means a written scope covering Hyperswitch, the billing system, the vault boundary and the processor connections before any work starts.
How we scope
- Inventory the processors, payment methods and markets your subscription and marketplace flows need today.
- Define which billing, retry and revenue recovery rules move into the orchestration layer and which stay in the billing system.
- Agree in writing where card data enters, which external vault holds it and how PCI DSS responsibility is split.
How we build
- Deploy Hyperswitch on Kubernetes in your environment using the self-hosting documentation as the starting point.
- Configure processor connectors, routing and retry rules, then connect Kill Bill or your chosen billing system to them.
- Test routing changes, failed-payment retries and reconciliation in a non-production environment before any live traffic.
How we hand over
- Document the architecture, connector configuration, routing rules and the PCI scope boundary for your assessor and engineers.
- Provide runbooks for upgrades, key rotation, processor onboarding and incident response for payment flows.
- Walk your payments, finance and security teams through reconciliation outputs and the evidence each control produces.
How we support
- Ongoing support, upgrades and continuous testing are available as a retainer after handover.
- Confirm with us how security testing of checkout, APIs and the vault boundary is scheduled over time.
- Review processor and billing-system changes against the documented scope before they reach production.
