Third-Party Integrations Are Where Projects Go to Die
Payments, e-signatures, banking cores. The integration is always estimated as "a few days" and always takes longer. What I learned building them, and how to build them so they do not break at 2am.
Over the years I have built integrations with payment providers like Stripe and Monri, e-signature platforms like DocuSign, and a handful of banking core systems on large US lending projects. Very different APIs, very similar lessons.
The integration itself is rarely the hard part. The hard part is everything the documentation does not tell you.
The sandbox is not production
Every provider has a sandbox, and every sandbox lies a little. Responses are faster, data is cleaner, edge cases never happen, and some features simply behave differently. It is common for an integration to pass every test and then fail on the first real customer, because production returned something the sandbox never sent.
Plan for a period of careful, monitored real traffic before you call an integration done. The first week in production is part of the build, not after it.
Assume every call can fail, and every call can happen twice
Networks drop. Providers time out. Your own server restarts halfway through a request. If your integration only works when everything succeeds exactly once, it does not work.
- Make operations idempotent. Charging a card or creating a document twice should be impossible, even if your code retries.
- Use the idempotency keys most good APIs offer. They exist because everyone gets this wrong once.
- Retry with backoff, and know which errors are worth retrying. A declined card is not a network glitch.
Webhooks are not optional, and not reliable either
For anything asynchronous, a payment settling, a document being signed, a loan status changing, the provider tells you through webhooks. Treat them carefully:
- Verify signatures, so nobody can fake an event.
- Expect duplicates and events arriving out of order.
- Store the raw event before processing it, so you can replay it when your processing has a bug.
- Have a reconciliation job that asks the provider for the truth periodically, because some webhooks will never arrive.
Log like you will need to prove what happened
When a client says "the customer was charged but the order shows unpaid", you need to answer in minutes, not days. That means logging every request and response with a correlation id, in a way you can search, with sensitive data masked. In finance-related integrations this is also usually a compliance requirement, not just good practice.
Keep the provider at arm's length
Do not let a provider's data model leak into the rest of your system. Wrap it in your own small interface: ChargeCustomer, RequestSignature, GetLoanStatus. The rest of the code talks to that, and only one place knows about the provider.
It feels like extra work on day one. It pays off the day you need to switch providers, add a second one for another country, or mock it in tests.
Estimate the unknowns, not the endpoints
The reason integrations are always late is that they are estimated by counting endpoints. The real time goes into access and credentials, unclear documentation, support tickets with the provider, certification steps, and the edge cases nobody listed. When I estimate an integration now, the API calls are the smallest line.
What is the worst integration you have ever had to build?
More writing
What a Website in 2026 Should Look Like?
Most business websites are still built like brochures from 2015. A website in 2026 should answer, convert and actually do part of the work for you.
Why I Build the Website Before Anyone Pays for It
Pitching a website with words almost never works. Showing a finished one does. Here is how I build small business sites fast, and why the work comes before the invoice.