The problem
Every institution that wants to bill through Multicaixa references has to integrate, maintain and reconcile a payment gateway on its own. It is repeated work, and mistakes cost money: a duplicated charge or an unconfirmed payment is a real problem for a family and for a school.
The goal was to centralise that integration in one API serving many institutions at once, with the guarantee that one institution's data never mixes with another's.
The approach
- 01
Tenant isolation in the data layer
The per-institution filter is applied underneath the business code, at database access. If the tenant context is missing, the query fails instead of returning everyone's data. No route depends on someone remembering to write the filter.
- 02
End-to-end idempotency
Every write request carries an idempotency key, stored with a hash of the body. On the settlement side, a unique constraint in the database prevents crediting the same payment twice, even if the notification arrives repeated or concurrently.
- 03
Re-read the payment at the gateway before crediting
A webhook can be forged, repeated or never arrive. When one comes in, the API re-reads the charge status directly from the gateway and only then credits it. A periodic reconciliation job catches the payments whose notification was lost.
- 04
Contract generated from code
The OpenAPI document and the error catalogue are generated from the code, and continuous integration fails if the published contract drifts from what the API does.
- 05
Load tests
I wrote load tests for charge creation, inbound webhooks, the billing schedule and message delivery. They showed that the webhook worker was processing one notification at a time.