Skip to main content

STALLYONS TECHNOLOGIES

Innovating the future of digital with AI, design, and technology. From AI to Web — Stallyons transforms your ideas into digital reality. Building smarter digital experiences through AI, innovation, and technology. Innovating the future of digital with AI, design, and technology. From AI to Web — Stallyons transforms your ideas into digital reality. Building smarter digital experiences through AI, innovation, and technology.
EN
background

Blog

PayBridge: Bank Payment
API Integration

PayBridge: Bank Payment API Integration

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.

The Starting Point: Moving Money Cannot Be “Mostly Right”

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.

  • Replace manual payment work. Exporting files, uploading them to online banking, and checking results by hand is slow and easy to get wrong, so the connection to the bank had to be direct.
  • Leave fragile systems mostly alone. Older platforms were never built for bank-grade security or live status, and rewriting them heavily is risky, so the bank logic had to sit somewhere separate.
  • Never pay twice or lose a payment. A timeout can leave a system unsure whether a payment went through, and a naive retry can pay the same thing again.
  • Meet the bank’s security rules. Banks require strong authentication, certificates, and careful handling of credentials and personal data.
  • Prove every transaction is correct. The finance team needs evidence, through testing and reconciliation, that each payment matches the bank’s own record.

The Build: One Request In, Exactly One Payment Out

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:

  1. The client’s platform sends one request to PayBridge’s internal API with an idempotency key, when it needs to pay a supplier, refund a customer, or collect a payment.
  2. PayBridge validates the data, records the transaction as pending, and rejects any duplicate that carries a key it has already seen.
  3. It signs the request, authenticates with the bank, and submits it, which moves the transaction to submitted.
  4. Later status updates, from webhooks and polling, move the transaction to completed or failed.
  5. If the bank does not answer in time, PayBridge asks the bank for the status before trying again, so the same payment is never sent twice.
  6. Each night, the bank’s statement is matched line by line against the client’s ledger, and anything that does not match lands on an exceptions list for the finance team.

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.

Technical Architecture

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.

  • Internal API. A small REST interface that existing systems call to request a payment, carrying an idempotency key so duplicates can be rejected.
  • Bank connector. The one place that talks to the bank, authenticating with OAuth 2.0 and client certificates for bank-grade mutual trust.
  • Transaction state machine. Every payment moves through pending, submitted, completed, failed, and reversed, with no skipped steps, so its status is always known.
  • Status tracking. Bank webhooks are signature-checked before any status changes, with polling as a fallback when a callback does not arrive.
  • Reconciliation engine. A nightly job matches statement lines against the client’s ledger by reference, amount, and date, and surfaces anything unmatched the same day.
  • Security. Credentials and certificates live in a secrets vault, traffic is encrypted, sensitive fields are masked in logs, and every action is audited.

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.

Challenges Solved

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.

The Result

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.

Frequently Asked Questions

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.

Leave a Reply