A provider retires an API. Your payouts keep moving.

At a glance

Use caseThis page describes how Flominzo handles this situation. It is not a report of a specific customer’s results.

Typical team

Payout platforms, remittance companies, PSPs

Flominzo product

Flominzo Payouts

Deadline set by

Your payment provider

Stays with you

Provider contract, cutover window, production approval

The situation

A payment provider announces that the endpoints behind quotes, payouts, status lookups, refunds, or webhooks will stop working on a date it chooses. Missing that date does not slow payments down. It stops them.

The engineering is rarely the hard part. What makes these migrations slip is finding every path that depends on the old contract, including retries and callback handlers, and keeping evidence that each path still behaves correctly after the change.

Why it goes wrong

• A migration tested on the success path alone fails later, on a timeout or a refund nobody re-ran.
• A changed status code is mapped to the wrong outcome, so an unknown result is treated as a failure and paid again.
• Provider-specific fields have leaked into many places, so the change spreads across products instead of staying in one place.

What you send us

• The deprecation notice and the endpoints it names.
• Sandbox credentials for the new contract.
• Your definition of a correctly migrated path, which becomes the acceptance standard.

How the change runs

Every provider sits behind the same Rail Adapter Contract, so a retired API is an adapter change, not a search through every product.

1. Map: list every capability call the adapter makes to the retiring endpoints: quotes, payouts, status lookups, cancellations, refunds, and webhook parsing.
2. Translate: implement the new contract inside the adapter and its Rail Profile. The payment core keeps consuming the same canonical results.
3. Classify outcomes: map every new status code to SUCCESS, RETRYABLE, NON_RETRYABLE, or UNKNOWN_OUTCOME, so an ambiguous answer is looked up, never re-sent.
4. Prove each case: run the provider sandbox for success, rejection, timeout, duplicate callback, refund, and reversal on every path, and keep the evidence with the change.
5. Run in parallel: send limited traffic through the new version while reconciliation runs at full strength.
6. Cut over: switch in the window you choose, with the previous profile version kept until you approve its removal.

A payment provider API migration checklist

Whether or not Flominzo carries out the change, these are the checks that keep a provider migration from turning into duplicate payouts or a lost day of reconciliation.

1. Inventory: list every call to the retiring endpoints, including retries, scheduled jobs, refunds and admin tools, not just the main payout path.
2. Webhooks: check new event names, payload shapes, signature schemes and delivery guarantees, and whether old and new events can arrive for the same payment during cutover.
3. Status mapping: map every new status and error code to a success, a retryable failure, a final failure, or an unknown outcome. Unknown must mean “look it up”, never “send again”.
4. Idempotency: confirm how the new contract treats a repeated request with the same key, and with the same key but a different body.
5. References: check that your reference is still echoed back, in which field, and whether its length or character set changed.
6. Settlement files: ask whether reports, settlement files or their identifiers change with the API, and when.
7. Timeouts and limits: note new rate limits, timeouts and maintenance windows.
8. Sandbox cases: prove success, rejection, timeout, duplicate callback, late callback, refund and reversal on every path, and keep the evidence.
9. Parallel run: send limited traffic through the new contract first, with reconciliation watching both old and new paths.
10. In-flight payments: decide how payments started on the old contract finish, and how their status is looked up after cutover.
11. Rollback: keep the previous version ready until the new one has been proven in production, and know who can switch back.
12. Deadline: track the provider’s sunset date, and plan to finish well before it.

What you receive

• A versioned adapter and Rail Profile change, reviewed separately from everything else.
• Sandbox evidence for every response case, kept as one record.
• A list of any calls deliberately left on the old contract, with the reason for each.

Decisions that stay with you

• The commercial relationship and contract terms with the provider.
• The cutover window your customers will see.
• Approval to deploy to production.

Where this lives in Flominzo