Blog
A finance team exports a file of payments, logs into online banking, uploads it, and then checks each result by hand. It holds up until a payment times out and no one is sure whether it went through, or until the file has to be built twice in one afternoon. For a business moving real money through its bank every day, “mostly right” is not good enough.
PayBridge is our blueprint for replacing that routine with a direct connection to the bank’s transaction API. It was scoped for a company in South Africa that wanted its existing platform to pay suppliers, refund customers, and collect payments straight through a major local bank, with strong security and proof that every transaction is correct. This is a solution blueprint based on requirements we have scoped, not the results of one delivered project, so what follows describes how we design the integration and why.
Put simply, a business’s existing systems make one plain call to ask for a payment, and PayBridge handles the rest: it validates and signs the request, sends it to the bank exactly once, tracks it until the bank confirms, and reconciles every transaction against the bank’s own records each night.
Paying through a bank’s API is not like calling a normal web service, because a mistake moves real money and has to answer to auditors. The design has to hold up against the ways payment integrations usually go wrong, so the requirements start from those failure modes.
The design puts a dedicated .NET service between the client’s systems and the bank, so the business gets a dedicated API integration to call instead of wiring bank logic into old code. A payment moves through it in a clear sequence:
Everything is built and proven in the bank’s sandbox before go-live. Because the bank connection lives in its own service, the rest of the client’s platform changes very little, which is what makes this a piece of custom software a client can trust around real money rather than a risky rewrite of systems that already work.
PayBridge is designed as an ASP.NET Core service with its own database. It exposes a small internal REST API to the client’s systems and a connector that talks to the bank using OAuth tokens and client certificates. Background workers handle status checks, retries, and nightly reconciliation. Each part is built around one idea: be correct even when the network is not.
The hard part is not calling the bank. It is guaranteeing correctness when networks fail, and then proving it. A timeout that leaves a payment in an unknown state is the dangerous case, so PayBridge resolves it with a status query rather than a blind resend, and the daily reconciliation turns that promise into evidence the finance team can hand to an auditor.
The challenge that decides whether a bank integration can be trusted is the timeout. When the bank does not reply, the payment may or may not have gone through, and guessing is how a business pays twice. PayBridge never guesses. It queries the bank’s status first and only resends when the bank confirms nothing was received, and the strict state machine plus idempotency keys mean a crash or a retry cannot duplicate a payment that already exists.
The rest comes down to working safely around systems that already run and meeting the bank’s rules. A small internal API lets the existing platform request payments with minimal change, so none of the risky rewriting is needed, while all the bank logic stays in one tested service. Certificates and credentials are vaulted and rotated rather than left in code, personal data is masked in logs, and because bank sandboxes rarely behave exactly like production, every failure case is proven in the sandbox before going live with small, monitored volumes.
As a blueprint, PayBridge is built to reach one outcome: every transaction processed exactly once, always matching the bank’s record, with any exception visible the same day. The business gets direct bank payments in place of manual files, one internal API to call instead of bank logic scattered through old code, and a full request-and-response log that satisfies both auditors and the bank. New payment types, or even a second bank, plug into the same service rather than starting again.
If you are planning a bank or payment integration like this, you can hire back-end developers who design for timeouts, idempotency, and reconciliation from the start, or tell us which bank API you need to reach and we will scope the integration service, the state machine, and the testing plan. The approach is built for fintech and financial platforms that move money and have to prove every cent of it.
What is PayBridge?
It is our solution blueprint for a dedicated bank integration service. Built on ASP.NET Core, it sits between a business’s existing systems and its bank, so those systems make one plain API call and PayBridge validates, signs, submits, tracks, and reconciles each payment. It is a design we have scoped for clients, not the results of a single delivered project.
How does it make sure a payment is never sent twice?
Every request carries an idempotency key, so a duplicate is rejected before anything is sent. Payments move through a strict state machine, and if the bank does not answer in time, PayBridge queries the bank for the status before trying again, rather than resending blindly.
What happens if the bank does not respond?
The payment is held in a known pending state and PayBridge asks the bank what happened. It only resends when the bank confirms nothing was received. An unknown outcome is never treated as a failure or a success until the bank’s status says which it is.
How does reconciliation work?
Each night, the bank’s statement is matched line by line against the client’s own ledger by reference, amount, and date. Anything that does not match appears on an exceptions list the same day, so the finance team can act on it before it becomes a bigger problem.
How is it kept secure?
Credentials and certificates live in a secrets vault and are rotated rather than kept in code, all traffic is encrypted, sensitive fields such as account numbers are masked in logs, and every action is audited. Authentication with the bank uses OAuth 2.0 and client certificates.