What the Hyperswitch reconciliation module matches and when finance needs it
The Hyperswitch reconciliation module matches records across order management, PSP and bank systems, and it posts those matches to an accounting-grade ledger that uses double-entry bookkeeping. For a finance team running a self-hosted Hyperswitch stack, this is the layer that lets the books close from the three sources of truth together, rather than from order exports, processor reports and bank statements that never agree on timing, fees or amounts. Without it, the team reconciles by hand in spreadsheets, and the gap between what the orchestration layer routed and what the bank settled stays open until someone finds it.
The need usually becomes urgent at month-end close. When payments are captured on one day, settled by a processor on another and paid out by the bank after that, the close depends on matching those events to the same order and the same entry. Teams that route volume across several processors hit the same problem sooner, because each processor reports in its own format, with its own fee lines and settlement cycle. Split payments add a further layer, since one order can produce several captures, refunds and partial settlements that must roll up to a single balance.
The module is built around a file upload pipeline, transformed entries and an exception queue. Finance and payments owners should decide early which feeds will be loaded, how often, and who approves a manual adjustment. They also need to map merchants and profiles correctly, because a mismatch in that mapping produces exceptions that look like processor errors but are configuration problems. The Hyperswitch reconciliation documentation covers amount mismatches, split payments and bulk void as exception types, so a close checklist should name an owner for each one before the first live run.
DeployOpen implements and operates the reconciliation module inside your own infrastructure, in your cloud accounts, data centers or air-gapped network, alongside the rest of your Hyperswitch deployment. The work covers feed design, ledger and account mapping, exception workflows, access control for finance users and the operating runbook for each close. Before scoping, confirm which order management, PSP and bank formats you need to load, which processors are in the first wave, and whether your auditors expect a specific evidence trail. DeployOpen prepares the system and its evidence, while independent auditors give any assurance opinion.
How Hyperswitch reconciliation builds matches across three record sources
The order management side is the record of what the merchant intended to charge, refund or pay out. In Hyperswitch, the payment records held by the core app are the starting point for the comparison, and the reconciliation module checks what processors and banks later report against them.
The points to confirm for this side are:
- Payment-level and attempt-level records: confirm which Hyperswitch objects the module reads and how a retried payment is represented.
- Refunds and voids: these appear as separate movements that must be linked back to the original payment.
- Amount and currency fields: amount mismatches are a named exception category, so confirm which amount field and precision the module compares.
- Merchant references: confirm whether your order management IDs are stored in Hyperswitch metadata or must be linked through a mapping.
- Split payments: these create one order with several movements, and the docs treat them as an exception type to plan for.
Check with the Hyperswitch version you run which order-side objects are in scope and how your order IDs reach the module.
The processor side is what each payment processor reports about the transactions it authorized, captured, refunded or voided. Processor records reach the module as files or data that your team supplies, and the path depends on the processor and the deployed version, so confirm it for each connector you run.
The points to confirm for this side are:
- Report formats: each processor has its own layout, and the module needs a defined way to read it.
- Processor reference IDs: these are usually the strongest link to Hyperswitch records, so confirm which field carries them in each report.
- Status values: processor statuses such as pending, settled or reversed must map to the statuses the module uses.
- Reporting dates: processors may report by authorization date, capture date or settlement date, which affects which period a record falls into.
- Bulk void activity: bulk voids are an exception type in the docs and can create many processor-side movements at once.
Before go-live, obtain a sample report from each processor and test it against the module in a non-production environment.
The bank side is the cash the merchant actually receives or sends, as shown in bank statements. It is the last source in the chain, and it often differs from processor reports because of settlement timing, netting and fees. Bank records enter the module through the same type of file upload pipeline used for other sources.
The points to confirm for this side are:
- Statement file format and cadence: confirm which statement types your bank provides and how often they arrive.
- Value dates and posting dates: these can differ from the processor settlement date, so decide which date the module uses for matching.
- Netted payouts: one bank credit may cover many processor settlements, which requires a grouping step before matching.
- Fees and adjustments: processor and bank fees need their own ledger treatment so that the totals reconcile.
- Narrative fields: confirm which bank fields carry the processor or batch reference.
Request a sample statement and a sample processor payout that cover a netted settlement, then trace both through the module before you rely on the matching output.
The ledger is where the reconciliation result is recorded. Hyperswitch reconciliation is built on an accounting-grade ledger that uses double-entry bookkeeping, so every matched or exception event is posted as balanced debits and credits rather than as a simple status flag.
The points to confirm for this part of the design are:
- Account structure: decide which ledger accounts represent receivables, processor clearing, bank cash and fees, and confirm how the module maps to them.
- Balanced postings: confirm how each match and exception produces entries and how the totals are checked.
- Audit trail: every entry should be traceable to the source records that created it, which auditors and finance teams will request.
- Corrections: confirm how a wrong match is reversed and whether the reversal is itself posted to the ledger.
- Period close: confirm how entries that span a month end are assigned to a period.
Ask the Hyperswitch maintainers or your implementation partner to show the entries produced for one payment, one refund and one netted payout before you finalize the chart of accounts.
Matching only works if each record is attached to the right merchant and profile. The docs describe merchant and profile mapping as a configuration step, and they describe file upload pipelines that convert incoming files into entries the module can compare. The processed entries are what the matching logic works on, not the raw files.
The points to confirm for this part of the setup are:
- Merchant and profile mapping: each processor account, bank account and file source must point to the correct Hyperswitch merchant and profile.
- Upload pipeline steps: confirm the file types accepted, the validation applied, and what happens to a rejected file.
- Processed entries: confirm the exact fields the pipeline creates and which of them feed the matching keys.
- Matching keys and rule behavior: the exact keys and the order in which rules are applied must be confirmed against the current documentation and the version you deploy, because they can change between releases.
- Test cases: prepare files that cover single payments, refunds, split payments and mismatched amounts.
Before production use, run a full cycle with your own files and record which keys produced each match, so the behavior is confirmed for your deployment rather than assumed.
Hyperswitch reconciliation module options and when each fits
This table compares the main reconciliation configuration choices in Hyperswitch: how records enter, how entries are transformed, how merchant and profile mappings are structured, and how exceptions are assigned. Read each row for the fit with a single-entity merchant and with a group of several profiles, then check the finance decisions before configuring. The main takeaway is that mapping and exception ownership are finance policy decisions, so settle them before the build starts.
| Configuration choice | Option | When it fits | What finance must decide |
|---|---|---|---|
| Record intake | File upload pipeline | Single entity with one processor and bank file per cycle. Groups need one feed per entity or profile. | File cadence, file owner, cut-off times and which feed belongs to which entity |
| Record intake | Other supported inputs (to be confirmed with Hyperswitch) | Only after confirming the input types the module accepts for your processors and bank feeds | Whether a non-file feed is acceptable for audit evidence and who maintains it |
| Entry transformation | Transformed entries mapped to ledger accounts | Single entity using one processor format. Groups with several processors need a mapping per source format. | How fees, refunds, chargebacks and settlements map to ledger accounts |
| Merchant and profile mapping | One merchant with one profile | Single entity with one brand, one currency set and one bank account | Whether any ledger view is needed beyond the single entity |
| Merchant and profile mapping | One merchant with a profile per brand or entity | Group with several brands, legal entities or regions that need separate ledgers and reports | Which legal entity owns each profile and how intercompany movements are recorded |
| Exception assignment | Central finance queue | Single entity or small team where one group reviews every exception | Who reviews amount mismatches, split payments and standard exceptions, and the response time expected |
| Exception assignment | Owners by entity or brand | Group where each profile has its own finance or operations team and its own bank relationships | Ownership per profile, escalation paths between entities and reviewer sign-off rules |
| Bulk void handling | Restricted approval for bulk void actions | Any merchant that allows bulk void, with stricter controls for groups that share one dashboard | Who may approve a bulk void, required evidence and whether approval thresholds apply |
Hyperswitch reconciliation module setup from file upload to first run
This sequence takes a self-hosted Hyperswitch reconciliation module from a confirmed deployment to a first run that matches uploaded processor and bank files against the ledger. Each step names who does the work and the check that shows it is done. Exact screens and field names depend on the Hyperswitch version in use, so confirm them against that version's documentation before work starts.
Confirm the deployment and Hyperswitch version
The platform lead records the Hyperswitch version, the Control Center version and the PostgreSQL and Redis services in use, then checks them against the compatibility matrix published with that release. If the deployment is at v1.124.0 or later, confirm that a Superposition service is running, because the release notes make it a required dependency. The step is done when the version record and compatibility check are filed with the project and the reconciliation module is confirmed available in a non-production environment.
Define merchant and profile mapping
The finance lead and the Hyperswitch administrator list each legal entity, merchant account and business profile, and the processor settlement accounts and bank accounts that fund each one. Shared accounts are documented with the entity that owns the cash. The check is that every settlement and bank account maps to exactly one merchant and profile, and the signed mapping table becomes the reference used in every later step.
Agree file formats and cadence with each source
The reconciliation lead collects sample files from each processor and bank, then confirms the format, delimiter, encoding, column meanings, delivery method and delivery schedule with each provider. Field definitions come from the provider's own documentation and sample files, not from assumptions carried over from another source. The check is that each source has a sample file, a documented schema, a delivery schedule and a named contact for failed or late deliveries.
Configure the upload pipeline
The platform engineer and Hyperswitch administrator configure the upload pipeline for each source, mapping file columns to Hyperswitch fields and linking each source to the merchant and profile mapping from the earlier step. Upload permissions are limited to named users. The check is a validation run that accepts a clean sample file and rejects a file with a missing required column, with the rejection recorded for the operator to see.
Run a test file through to transformed entries
The reconciliation lead uploads one sample file per source to the non-production environment and follows each file through processing into transformed entries. Each entry should reference the correct merchant and profile from the mapping table. The check is that rows in equal entries or recorded exceptions out, with no row lost between the file and the output. A mismatch in row counts is resolved before the next step begins.
Review exception handling and statuses
The finance operations lead reviews the exceptions produced by the test run, including amount mismatches, split payments and bulk voids, and confirms the status each one received. The team agrees who clears each exception type and how it escalates. The check is that every exception type seen in the test has a named owner and a documented resolution step, and that deliberately created test cases for each type produce the expected status.
Verify ledger balances against source files
The finance lead compares the balances in the double-entry ledger with the totals in each processor and bank source file for the test period, and explains every difference. Fees, refunds and disputes are included in the comparison where the source file reports them. The check is that posted entries tie to each file total, or each remaining difference has a recorded exception with an owner. The first run is complete when balances tie and the evidence, including row counts and balance reports, is archived.
What finance teams must supply before reconciliation can match anything
The quality of what finance and operations supply will decide how well the Hyperswitch reconciliation module matches records, and how many exceptions your team works each close. Platform configuration matters, but a well-configured module fed with inconsistent files will still produce unmatched items. Start collecting these inputs at the beginning of the engagement, not during the first test run.
Ledger and accounting structure. The reconciliation module is built on a double-entry ledger, so it needs your chart of accounts, the ledger structure that sits beneath it, and the account each payment type, settlement and fee should post to. Ask finance to confirm which accounts hold clearing balances for processor settlements, which hold payouts in transit, and which record fees and chargebacks. Also confirm how merchant and profile mapping should reflect your legal entities, since that mapping determines which records land in which books.
Processor, bank and order management files. Collect real sample files from every processor connected to Hyperswitch, plus payout files, bank statement formats and the order management export your team uses. Request at least one sample for each file type and each currency, including files that contain refunds, disputes, split payments and reversals. Ask for the file layout documentation as well, because column meanings and date formats often differ from what the sample suggests. Confirm with each processor and bank how and when files are delivered, and whether they are full or incremental.
Currency, fee and cutoff rules. Document how each currency converts to the reporting currency, which exchange rate source and timing finance uses, how each processor's fees and interchange appear in settlement files, and which fees are netted before payout. Add the cutoff times for processor settlement, bank value dating and your own order and close calendar, including weekend and holiday handling. Mismatched cutoffs are a common source of timing exceptions that look like missing money. Ask finance to confirm these rules in writing and to flag any that changed during the last year.
Close calendar and exception ownership. Share the month-end and daily close calendar, the reporting deadlines the reconciliation output feeds, and the named owner for each exception category, such as amount mismatches, split payments and bulk voids. Decide early who approves manual matches and who may bulk-void items, since those decisions shape how exceptions are handled once the module is live. Plan a review of the sample files with finance before build starts, so that gaps are found while changes are still inexpensive.
How exceptions get worked: amount mismatches, split payments and bulk voids
An amount mismatch appears when the value on a processor or bank record does not equal the value recorded for the matching order or payment. Reconciliation matches records across order management, processor and bank systems, so a mismatch is what remains when two records agree on identifiers but disagree on money. This is usually the exception that carries the most direct financial exposure, so it is often the first queue finance teams review.
- What triggers it: Differences between the amount captured in the order system and the amount the processor reports as settled. Illustrative causes include partial captures, currency conversion, or fees netted from a payout.
- Who reviews it: Finance operations or accounts receivable staff. Platform or integration owners join when the cause is a field mapping or file format problem.
- What finance decides: Whether the difference is an expected fee or rounding item, an adjustment that should be posted, or an error to raise with the processor or the owner of the order system.
- What the platform records: The exception and its current state, with transformed entries linked back to the source records. Confirm which ledger entries are created, which stay pending, and whether any adjusting entry is posted automatically.
Before go-live, confirm the tolerance rules, the status names and the handling rules in the version you deploy.
A split payment exception occurs when one order or payment settles as several processor or bank records, or when one bank or processor record covers several orders. Matching has to link one side to many on the other, so a simple one-to-one match will not close these items. The exception stays open until every part is accounted for or deliberately left as an open balance.
- What triggers it: A single customer payment divided across several captures or refunds, multi-party settlements where one payout covers several sellers, or batch payouts that cover many orders at once.
- Who reviews it: The finance team, usually with the operations or marketplace team that knows the commercial split between parties.
- What finance decides: Whether all child records belong to the right parent, whether the grouping is correct, and whether any remaining part is a real open item or an expected timing difference.
- What the platform records: A link between the related records and the state of each part, with the exception open until the group resolves. Confirm how grouping is represented, whether partial matches post entries, and how merchant and profile mapping assigns each part to the correct entity.
Before go-live, confirm the grouping keys in your file formats and how the platform handles a split that never fully closes.
A bulk void cancels or reverses many authorizations or transactions in one action. Teams usually run one after a batch error, a duplicated file upload, a faulty export or a processor-side cancellation affecting a window of transactions. Because one action can change many records at once, bulk voids need the tightest review in the module.
- What triggers it: A batch file loaded twice, a bad export, a processor cancellation covering a window of authorizations, or cleanup of stale authorizations.
- Who reviews it: A finance controller or designated approver who did not run the upload, with the platform owner confirming the scope of the action.
- What finance decides: Whether the selected set is correct, whether each item should be voided, reversed or re-matched, and whether reversing ledger entries is appropriate for the open period.
- What the platform records: The exception and reversing activity for each affected item. Confirm whether one bulk action creates one record per item, which user identity is logged, and what audit fields are kept.
- Access control: Restrict who can run bulk actions, and confirm whether the version in use supports an approval step before execution.
Before go-live, confirm role permissions, the approval steps and the audit trail retained for each voided record.
Security and operational controls for reconciliation data
Settlement files, bank data and ledger entries are the inputs Hyperswitch reconciliation uses to match order, processor and bank records. Access, separation of duties, retention, audit trails and backups depend on one another, so set them together before finance teams start uploading files.
Settlement, bank and ledger data
Settlement files, bank statements and ledger entries show who paid whom, how much, and through which processor. Classify them as sensitive financial data so they inherit the access, retention and backup rules in this section. Confirm with your finance and security teams which fields are personal data, such as payer names or account references, because those fields bring data protection obligations into the reconciliation scope.
Role-based access to reconciliation views
Uploads, exception queues and ledger views should each map to a defined role, granted to the smallest group that needs it. Hyperswitch manages roles itself, and Control Center single sign-on supports OpenID Connect only, with no JIT or SCIM provisioning. Each reviewer must be invited in Hyperswitch before signing in, so plan onboarding and offboarding steps for every reviewer and check the role set against your Hyperswitch version.
Separation of duties for adjustments
The person who uploads a settlement or bank file should not also approve the adjustments that file produces. Map upload, exception review and adjustment approval to distinct roles, then test that the Hyperswitch role configuration blocks one user from holding both. If team size makes full separation difficult, document the compensating review and the person who signs it off.
Retention of source files
Keep original settlement and bank files as received, since transformed entries are only as reliable as their source. Set retention periods with your finance, legal and data protection owners, and confirm where uploaded files are stored and who can delete them. Check whether any storage lifecycle rule could remove a file that a closed reconciliation period still needs.
Audit trails for matches and adjustments
Reviewers and auditors need to see who uploaded a file, who changed a match, who approved an adjustment, and when. Confirm which events Hyperswitch records for uploads, exception handling and adjustments, and whether they can be exported to your log platform. Test the trail by tracing one adjustment from the original exception to its approved ledger entry.
PostgreSQL backups for ledger data
The ledger is stored in the PostgreSQL database that Hyperswitch uses, so backup scope belongs to finance controls as well as infrastructure. Plan point-in-time recovery, test restores in a separate environment, and agree a recovery point that finance accepts. Confirm with your database team how backups cover the master and replica setup in the architecture docs, and who holds approval to run a restore.
Hyperswitch reconciliation module cost and effort questions
What drives the cost of a Hyperswitch reconciliation implementation?
The scope of data sources and the condition of the sample files drive most of the cost. Each payment processor, bank account and file format needs its own ingestion path and mapping, so adding one multiplies the design and test work. Multiple legal entities and currencies add mapping of merchant and profile records, plus rules for conversion and settlement timing. Clean, complete sample files from each source shorten discovery and testing, while sparse or inconsistent files add investigation before any build starts. Ask any provider to price these items separately so you can see which decision moves the quote.
How long does it take to set up Hyperswitch reconciliation?
The duration follows from the same drivers as cost, so ask for milestones tied to them rather than a single date. A written plan should show when sample files are received and validated, when transformed entries and exception rules are agreed, when the environment is built, and when testing against real closing cycles is complete. Your own finance calendar sets the earliest practical cutover, because a reconciliation cannot be proven until it has run through a full close. Request the schedule, the dependencies on your team, and the point at which the scope is considered complete.
What costs are one-time and what costs recur after go-live?
Setup work is one-time, while close support, new data sources and platform upgrades recur. One-time work includes discovery, file parsers, ledger and profile mapping, exception policy, environment build and acceptance testing. Recurring work includes monitoring the reconciliation during close, adding a processor or bank account, and applying Hyperswitch releases, which ship roughly monthly with compatibility matrices for the Control Center and web client. Support can be contracted as a retainer. In a quote, ask which items are fixed, which are time-and-materials, and what a change request costs.
What does a reconciliation project need from finance and engineering?
Finance supplies the rules and the sample data, and engineering supplies the platform and access. Finance should provide sample files from every processor and bank, the chart of accounts, the treatment for fees, refunds, chargebacks and split payments, the tolerance for amount mismatches, and named owners for the exception queue. Engineering should provide a Kubernetes environment for the Helm-based deployment, PostgreSQL and Redis, secret storage, a controlled drop location for files, network access to each file source, and an identity decision for the Control Center. Hyperswitch Control Center single sign-on uses OpenID Connect only, and users must be invited first.
Can our team configure Hyperswitch reconciliation without outside help?
A capable internal team can do it, but the hardest parts are decisions that finance has to own. Engineers with Kubernetes and PostgreSQL experience can deploy the stack by following the self-hosting documentation. The slower work is mapping each source file to transformed entries, deciding how each exception type should be classified and resolved, and proving the output matches the books across a full close. Estimate your team's capacity honestly, including the time needed for upgrades. An outside partner can help with scope, build and testing, while your team keeps ownership of the rules.
How do file uploads and exceptions move through the reconciliation pipeline?
Files enter through an upload pipeline, become transformed entries, and are matched against order management, processor and bank records before any exception is raised. Matched records clear automatically, while unmatched items receive a status and appear in the exception queue. The documented exception types include amount mismatches, split payments and bulk void, so each needs a defined rule for when it clears, escalates or requires a journal entry. Engineers should confirm how merchant and profile mapping is applied to each source, which status values are used, and how exports reach the general ledger of record in your environment.
What should a written scope for reconciliation include?
A written scope should name every data source, entity and currency, plus the acceptance test that proves the reconciliation works. Include the processors, bank accounts and file formats in scope, the legal entities and profiles to be mapped, the exception types handled and their resolution rules, the ledger accounts receiving entries, and the environments to be built. Add the testing approach, the close cycles used for acceptance, the handover materials, and what is excluded. Also request the support terms, the change control process, and the dependencies on your team. DeployOpen agrees most engagements as fixed scope in writing before work starts, and a quote follows from that document.
Limits to confirm for reconciliation in your environment
The Hyperswitch reconciliation docs describe the module's pipelines, entries and exception handling, but they do not settle every limit your finance and operations teams will depend on. Treat the items below as confirmations to request from Juspay, the Hyperswitch docs or a test environment before you commit to a build. Each one should be closed with evidence from your own sample files and volumes.
Supported processors and file formats
Ask which processor settlement reports and bank statement formats the file upload pipeline parses natively, and which need a custom transformation step. Confirm the exact file types, encodings, delimiters and header layouts for each processor you use. Request a parse test with a real sample file from each source, including one with partial refunds and one with chargebacks, so you know what fails before go-live.
Fee and currency handling in transformed entries
Confirm how transformed entries represent processor fees, interchange, scheme fees and FX conversion, and whether these become separate ledger lines or are netted into the settlement amount. Ask how the module records the rate used, the source of that rate and the currency of each leg. Check the output against a reconciled sample so your accounting team can trace every cent to a source record.
Tested file sizes and volumes
Ask Juspay or your test environment for the largest file size, row count and daily transaction volume the upload pipeline has been tested against, and under what hardware and database configuration. Request run times for your own peak settlement file. Use these results to size the PostgreSQL and worker capacity in your infrastructure, since the module's throughput depends on your deployment as much as on the code.
Reversals and late settlements in the ledger
Confirm how the double-entry ledger posts refunds, voids, chargebacks and reversals that arrive in a later settlement file than the original payment. Ask whether a late record reopens a closed period, creates an exception or adjusts the existing entry. Test a scenario where a refund settles two business days after the sale and verify that balances and open items match your finance policy.
Version behavior against the documentation
Confirm that the release you plan to run matches the reconciliation behavior described in the docs for that version, since the module changes with the monthly minor releases. Check the GitHub releases notes and compatibility matrix for any reconciliation change, and read the upgrade notes for required dependencies. Repeat your test cases after each upgrade in a staging environment before applying it to production.
Merchant and profile mapping rules
Confirm how the module maps records from each processor account, merchant and profile to the correct ledger entity, and what happens to a record that matches none of them. Ask how multi-entity structures, such as several legal entities sharing one processor, are represented. Test with records from every account you will reconcile to confirm that no transaction lands in an unmapped bucket.
How DeployOpen works on this
DeployOpen plans, builds and runs Hyperswitch reconciliation inside infrastructure you control, so matching across order management, processor and bank records stays in your environment. Engagements are fixed-scope, with scope, deliverables and timelines agreed in writing before work starts. Ongoing support, upgrades and testing are available as retainers.
How we scope
- The written scope lists the processor, bank and order management sources to reconcile, with file formats agreed for each.
- Finance supplies the ledger chart of accounts, merchant and profile mapping, and sample settlement files before design starts.
- The scope lists exception types, such as amount mismatches, split payments and bulk voids, and who resolves each.
How we build
- Ingestion pipelines load processor and bank files, then produce transformed entries that map to double-entry ledger postings.
- Matching rules are tested against sample files that include mismatches, split payments and voids before go-live.
- Deployment targets your own Kubernetes cluster and PostgreSQL, using the Helm charts Hyperswitch documents, with configuration kept under version control.
How we hand over
- Handover covers the reconciliation runbook, exception queue procedures, and mapping tables for merchant and profile records.
- Training for finance and operations staff on record statuses and exception handling can be included in the written scope.
- Each deliverable, including configuration, test evidence and architecture notes, is documented and transferred to your team.
How we support
- Upgrades are planned around Hyperswitch releases and their compatibility matrices for Control Center and web client versions.
- Ongoing support, upgrades and continuous testing are available as a retainer after handover, agreed in writing.
- Changes to matching rules or file formats go through the same scope and test steps before they reach production.
