A checklist before hiring a payment integration (Pix, credit card, bank slip)
What breaks in production when payment integration is treated as a one-week project: unverified webhooks, missing idempotency, and ignored reconciliation.
Integrating payments looks simple in the gateway docs: a POST, a response, a webhook. The complexity is not in the call that works. It is in the scenarios that break at 3 AM.
This is the list I check before putting any integration into production, after building payment systems that process Pix, credit cards, and bank slips for real businesses.
1. Webhook with HMAC, not a secret URL
A webhook without cryptographic verification accepts POSTs from any origin. If the payload arrives and the system processes it without validating the signature, an attacker can forge an approved payment notification.
The minimum is HMAC-SHA256: the gateway signs the payload with a secret key that only you and it know, and your endpoint validates the signature before processing. A secret URL is not security — it is obscurity that lasts until the first automated scan.
In the vehicle-data e-commerce I built, every payment notification went through HMAC validation before updating the order status. Without it, the system trusts whatever arrives — and trust is not a security mechanism.
2. Idempotency on the receiving end
The gateway may send the same webhook more than once. Network blip, timeout, retry. If your endpoint processes it twice, you deliver the product twice or charge twice.
The rule is simple: every notification carries a unique identifier (transaction ID or idempotency key). If the identifier has already been processed, the endpoint responds 200 and changes nothing. This protects against duplication without depending on the gateway being perfect.
3. Daily reconciliation
Webhooks are asynchronous. And asynchronous things fail. The webhook may not arrive. It may arrive late. The gateway may have been down at that exact moment.
Reconciliation is the daily routine that compares what the gateway says it received with what your system says it processed. Without it, you discover unaccounted payments when the customer complains — and a customer who complains about money disappears, they do not complain twice.
4. Sandbox is not production
The gateway sandbox has different latency, different timeout behavior, and often returns statuses that never happen in production (or vice versa). Testing only in sandbox is testing a different system.
What I do: certify in sandbox, but test failure scenarios in production with a minimum amount, during controlled hours, with active monitoring. If the gateway has a health check endpoint, I monitor it before and during.
5. LGPD and card data
You do not store card numbers. Period. If the gateway offers tokenization, you store the token, never the PAN. If the gateway does not offer tokenization, you switch gateways.
Payment data carries responsibility proportional to the damage. An email leak is serious. A card data leak is existential for a small business. The LGPD fine is proportional to revenue, but the reputational damage has no ceiling.
6. Who answers the phone at 3 AM
Payments do not have business hours. If Pix stops processing on Saturday at 10 PM, the loss accumulates until Monday morning — if anyone notices.
Before hiring the integration, define: who gets paged, through which channel, with which procedure. If the answer is "the developer who built it", that developer needs to be on call or the system needs controlled degradation (display a message, enqueue, notify the team the next morning).
Where it breaks
The most common mistake is treating payments as a feature, not as a critical service. A feature you test in sandbox, deploy, and forget. A critical service you monitor, reconcile, and have a contingency plan for. The difference in posture is the difference between a system that has been working for six months and one that broke on the first holiday.
If you are planning to integrate payments into your system, tell me about your context.