Skip to content
Henrique Vieira
All projects

Multi-tenant billing API for Multicaixa payment references

AutoPropina

An API that lets schools and clinics bill through Multicaixa payment references without each one integrating the payment gateway.

Role
Sole author: architecture, backend, console, site and operations
Period
Sep 2026 - present
Status
In pilot
Technologies
TypeScriptNestJSPrismaPostgreSQLRedisBullMQNext.jsPlaywrightDocker

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

  1. 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.

  2. 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.

  3. 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.

  4. 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.

  5. 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.

The results

69 ms
p95 for charge creation, at about 170 charges/s per instance
605 s -> 119 s
to confirm 3,000 concurrent payments, after parallelising the worker
0
charges lost or duplicated, with every notification delivered twice
100%
of the findings from an offensive security review fixed, each with a regression test
83
operations in the OpenAPI contract, checked on every change

What I learned

The biggest gain came from a place only the tests showed: the webhook worker. I now measure before optimising, and keep the machine and the load next to every number.

Next case

Electronic invoicing

Software for Angola's tax authority (AGT), multi-tenant

Read the case