The email nobody read in time
Three months ago your partner bank sent a developer notice. A field in the payment status response was being renamed, an older endpoint version would be retired, and a new status value was being added for payments held for review. It went to a shared engineering inbox during a busy sprint.
On the switch-over date, outbound payments still went out, but your app stopped updating them from pending to sent. The new status value fell through to a default branch in the code, so a handful of payments showed as failed when they had not. Support noticed first, because customers noticed first. An engineer spent the evening reading logs and the next morning writing a patch, and ops spent two days checking which payments had been shown the wrong status.
Why each change turns into a fire
Partner APIs change for ordinary reasons: new features, security updates, version retirements. The pain comes from how the integration grew.
- Calls to the provider are made from many places in the codebase, so a change has to be found in all of them.
- Provider responses are passed straight into your own data model, so a renamed field breaks things far from the integration.
- Unknown status values are not handled explicitly, so they fall into whatever the default is.
- The provider's sandbox is only used during the first build, not on an ongoing basis.
- Change notices arrive by email or on a developer portal page nobody watches.
Startups often sit on two or three partners at once, perhaps a banking partner, a card issuer processor and an open banking provider, each with its own change cadence.
What the breakages really cost
Each incident pulls engineers off planned work, often at short notice. Ops has to find the affected customers and payments by hand. Support answers worried customers without full information. And each one gives your partner a reason to ask harder questions about your operational controls.
The costs are uneven: most changes are harmless, but you cannot tell which ones are not without reading every notice and testing every flow.
An integration layer with its own early warning
What we build is a thin, well-tested layer for each partner, plus the monitoring that tells you when that partner has changed something.
- One adapter per provider. Every call to that provider goes through it, and it translates the provider's shapes into your own internal model.
- An explicit mapping of every provider status to your internal statuses. An unknown value is never silently defaulted; it is held and raised as an alert.
- Contract tests that call the provider's sandbox on a schedule and compare responses with what the adapter expects, so a change shows up in the sandbox before it reaches production.
- Schema checks on live webhook payloads that flag new or missing fields without blocking processing.
- A change log page listing each provider, the API version you use, the retirement dates you know about and who owns the upgrade.
- Alerts to the channel your engineers already watch, such as Slack or Microsoft Teams.
| Kind of change | How it shows up | What happens |
|---|---|---|
| Field renamed or removed | Contract test fails against sandbox | Engineer alerted before the production date |
| New status value | Adapter sees an unmapped value | Payment held, alert raised, no default guess |
| Endpoint version retired | Version tracked on the change log | Upgrade ticket raised well ahead |
| New optional field | Webhook schema check notes it | Logged for review, processing continues |
| Slower responses or errors | Latency and error-rate monitor | Alert with the provider and endpoint named |
We can build the layer in your stack, whether that is Node, Python, Go or something else, and hand it to your engineers with tests and documentation, or look after it with you.
What the next change notice looks like
The notice still arrives. Someone adds the retirement date to the change log and the upgrade becomes a normal ticket. When the provider switches the sandbox over, a contract test goes red in the morning run, and the engineer who owns that adapter changes one mapping in one place.
If something slips through, the unmapped status is caught by the adapter rather than shown to a customer as a failure, and ops get a list of exactly which payments are held.
Does this match your integration?
- Provider SDK or HTTP calls appear in many services or files.
- The last provider change was found by customers or support.
- Nobody tests against the provider's sandbox after launch.
- Unknown statuses fall through to a default in the code.
- Retirement dates live in someone's inbox.