A checklist before hiring a payment integration
What can fail when payments are treated as a one-week project.
A gateway's documentation can make payment integration look simple. A POST request from your system is one step. Then come a response and a webhook (an automatic notice from the service).
The request that works is rarely the problem. The risk is in failures that can show up at 3 AM.
This is the list I check before putting an integration into production (real use). It comes from payment systems I built for real businesses, with Pix, credit cards, and bank slips.
1. Verify the webhook with HMAC, not a secret URL
A webhook without cryptographic verification accepts POST requests from any source. If the system receives the message without checking its signature, someone can fake an approved payment notice.
The minimum is HMAC-SHA256 (a digital signature made from the data and a secret key). Only you and the gateway know that key. Your system checks that signature before processing the message. A secret URL does not protect the system. It only hides the address until the first automated scan.
In the vehicle-data e-commerce I built, every payment notice went through HMAC verification before changing the order status. Without it, the system trusts any message it receives. Trust is not protection.
2. Do not process the same notice twice
The gateway may send the same webhook more than once. The network fails, the wait times out, or the service tries again. If your system processes the message twice, it may deliver the product or charge twice.
Each notice needs a unique identifier, such as the transaction ID. An idempotency key also works. It marks the action so it cannot be repeated. If the identifier was already processed, the system responds 200 and does nothing. This prevents duplicates without depending on a perfect gateway.
3. Compare the records every day
A webhook is a notice that arrives after a payment, and this kind of message can fail. It may not arrive, may arrive late, or the gateway may go down at that exact moment.
Reconciliation is the daily comparison between payments the gateway says it received and payments your system says it processed. Without this comparison, you discover a missing payment only when the customer complains. Customers who complain about money tend to leave instead of complaining again.
4. The test environment is not the real one
The gateway sandbox (its test environment) may respond at a different speed and behave differently when there is a delay. It may also show situations that never happen in production, or the reverse. Testing only in the sandbox means testing a different system.
I test in the sandbox. Then I check failure cases in production with a minimum amount, R$ 0.01 or the equivalent. I do this at a controlled time and watch the system. If the gateway has an address that reports whether it is working, I check it before and during the test.
5. Protect card data
You do not store the card number. Period. Tokenization replaces the card number with a code. If the gateway offers it, keep that code. Never keep the PAN (the full card number). If the gateway does not offer tokenization, switch gateways.
Payment data brings responsibility proportional to the harm. A leaked email is serious. Leaked card data can end a small company. The LGPD (Brazil's General Data Protection Law) sets fines in proportion to revenue. Reputational damage has no ceiling.
6. Who answers at 3 AM?
Payments do not keep business hours. If Pix stops processing at 10 PM on Saturday, losses can grow until Monday morning, if anyone notices at all.
Before hiring the integration, decide who gets notified, through which channel, and what that person should do. If the answer is "the developer who built it," that developer needs to be available. Another option is to reduce service in a controlled way. The system can show a message, save the request for later, and notify the team the next morning.
Where it fails
The most common mistake is treating payments as a system feature instead of a critical service. You test a feature in the sandbox, put it live, and forget it. A critical service needs monitoring, daily comparisons, and a plan for failures.
That difference separates a system that has worked for six months from one that breaks on the first holiday.
If you are planning to add payments to your system, tell me about your context.