Back to the blog

Payment architecture: why a charge isn't an HTTP call

Experience in banking and fintech leaves an operational rule: creating a link does not complete a charge. A provider responds asynchronously, retries notifications and may deliver partial information. In MiCuota, that reality translated into a state model, idempotency controls and an auditable ledger.

A charge is an asynchronous process

For someone collecting a fee, the flow looks linear: share a link, the person pays and the money shows up. On the system side, though, the provider may notify a few seconds later, notify again if it didn't get a response, or send a notification with less data than you expected. It's a well-known reality in payments, but it becomes very concrete when the business depends on knowing for sure who paid and who didn't.

In MiCuota I decided to treat every charge as a state machine. The operation is created, sent, receives updates and changes state with a source and a date. The provider takes part in that story, but doesn't write all of it. The application needs its own reliable version of the facts.

Idempotency as a business control

The problem with a repeated webhook isn't elegant or academic. It can be a duplicate subscription, a person charged twice or a seller who loses trust in the tool. That's why processing a notification twice must produce exactly the same result as processing it once.

That requires identifying the notification, validating whether the transition makes sense and querying the provider again when the notice arrives incomplete. The external reference plays a humble but crucial role: it lets you go from a partial signal back to the exact operation that produced it.

An event ledger for support and reconciliation

Logs are indispensable for understanding what a service did. But when someone asks why a payment didn't go through, they need a business answer, not an excursion through five observability dashboards. That's why I stored the charge creation, the link being sent, every webhook and every transition in a ledger.

You feel the difference at the first incident. Instead of reconstructing a probable version of what happened, you can read the timeline of the operation. And that same history, which serves support today, enables reconciliation, recovery and delinquency reports tomorrow.

Reference architectureProcessing a charge operation

The provider starts a charge in MiCuota. The platform records the operation and delegates execution to a payment provider. Webhooks update the ledger through validated, idempotent transitions.

Operational principle: a reliable payment requires valid transitions, idempotent processing and traceability that lets you explain every state without depending on scattered logs.

Keep reading

More in Fintech and payments Reading path: Platform engineering and architecture