The day a payment provider renames a field, you find out how many files know that field name.
Most integrations start honestly. You get a provider SDK, the response comes back already parsed, and copying it into your own structure feels like wasted work. So the provider's shape leaks: into your ORM columns, into your serializers, into the frontend, into analytics. Six months later that vocabulary is your product's vocabulary.
Then the business wants a second provider in a new market, or the first one deprecates an endpoint, and the estimate comes back as a rewrite.
What we do instead is boring and cheap at the start: one translation layer per provider, and its only job is to turn their response into our own type, and their failures into our own errors. Business code never sees a provider status string. It sees our states.
Two details make it actually work.
We keep the raw response stored next to the translated record. When the provider disputes something, the argument ends with data, not with logs.
And we map error taxonomies deliberately (retryable, declined, needs-manual-review), because every provider names those differently, and the retry logic is the part that costs real money when it's wrong.
We've built payment services, KYC integrations, and multi-carrier delivery on top of this. The layer never looked impressive in code review. It's probably what made adding the next provider a week instead of a quarter.
When you added a second provider, something leaked further into your codebase than you expected.