How to migrate a stablecoin payout integration to a new provider

Migrating a stablecoin payout integration to a new provider is a re-onboarding project with a code change attached, not a code change with some paperwork attached. The API surface, the part that what a stablecoin API is describes, will differ in ways an engineer can absorb in a sprint. What takes the time is that every customer of yours has to be verified again by the new counterparty, every payout destination has to be registered again, and every balance has to be moved by an entity that is legally allowed to move it.

This guide is the plan for that project, written for the operations lead who owns it rather than the engineer who executes the code. The original integration is covered in how to integrate a stablecoin API, and the choice of the new provider in the guide to choosing one; here we assume the choice is made and the question is how to get from one to the other without a customer noticing.

Why you are migrating decides how you migrate

The reason for the move sets the pace, so write it down before the plan.

A migration for cost or coverage is a project with a deadline you choose. You can run the two providers in parallel for as long as the numbers justify, move customers in cohorts, and cut over corridor by corridor. A migration because the current provider is exiting a market, losing a licence or a banking partner, or has told you it will not renew, is a project with a deadline you do not choose, and the parallel phase shrinks to whatever the notice period allows. A migration because of an incident, a frozen balance or a failed audit, is an evacuation, and the sequence below runs in the same order but with the balance movement first.

In every case, the first document to produce is the list of what the current provider holds on your behalf: customer records and their verification status, registered destinations, stablecoin balances by customer and by network, local-currency balances in named accounts, pending payouts, and any open collections. That list is the scope of the migration.

What moves, what has to be rebuilt, and what cannot move at all

The stablecoin balances move. They are assets on a blockchain, and a transfer from a wallet at the old provider to a wallet at the new one is a transaction like any other. What decides whether it is simple is who holds the keys. With a custodial provider, the transfer is a payout instruction the provider executes for you, per customer, once the receiving wallet exists; the sequence is set out in what a custodial wallet is. The receiving wallet, at the new provider, exists only once the customer is approved there, which is why verification comes before balances in the timeline.

The customer records have to be rebuilt. Verification is not portable between providers in the general case, because each provider is the regulated party for its own onboarding and has to satisfy its own obligations. Some providers can accept a verification performed by a shared vendor through a token-sharing arrangement, which shortens the process to a re-check rather than a full re-submission, and it is worth asking for. Either way, plan for every customer to go through onboarding at the new provider, with the documents that a KYB (know your business, the verification of a company and its owners) review needs, and plan for some fraction of them to hit an RFI (request for information, a compliance hold that asks for a document before a transaction clears).

The named accounts cannot move. A local account in a customer's name is issued by the old provider's banking partner, and it stays there. The new provider issues a new account, with a new number, and every counterparty that pays into the old one has to be told the new details. For a customer collecting from a handful of business payers that is an email; for a customer whose account number sits on hundreds of invoices it is a campaign, and the old account has to stay open long enough for the stragglers to arrive.

The verification wave, and how to size it

Onboarding every customer at the new provider is the critical path, so it gets the first weeks and the most attention.

Sequence customers by what they hold and how active they are. A customer with a balance and daily payouts is migrated early, because each day at the old provider costs and because they will test the new integration hardest. A customer with no balance and no activity in months may not be migrated at all: it is cheaper to re-onboard them if they ever come back than to chase documents from a dormant account. The middle cohort, active but small, goes in batches sized to what the new provider's compliance queue can absorb in a week; ask them for that number rather than guessing it.

The documents to collect are the same ones the original onboarding needed, and the mistake to avoid is asking for them one at a time. Send each customer the complete list for their structure on day one, with an explanation that the change of provider is why, and a date by which their payouts will run on the new rails. A customer who first hears about the migration from a verification email will assume something is wrong.

Limits reset. The new provider applies its own per-transaction, daily and monthly caps from its own verification level, and a customer who had raised limits at the old provider starts at standard limits at the new one until enhanced verification is done there. For a customer whose normal payout exceeds a standard limit, the enhanced review has to be part of the migration, with its supporting documents, before their first payout on the new provider is attempted.

Destinations, purpose codes and the data you should not carry over blindly

Every bank account a customer pays out to has to be registered again at the new provider, with the holder's details and the relationship between the customer and the holder, because the new provider screens payouts on that relationship. It is tempting to export the destination table and import it. Do not do that without a review.

The export from the old provider carries every destination ever created, including ones that failed, ones for counterparties the customer no longer pays, and ones registered with a relationship that was chosen because it sat at the top of a list. The migration is the one moment when cleaning that table costs nothing extra: register only the destinations with a payout in the last few months, confirm the relationship with the customer where it looks wrong, and let the rest expire with the old provider. A payout to a supplier registered as an employee is a compliance question waiting to happen, and it is easier to fix before the first payout than after a hold.

The same applies to the purpose category each payout carries. Providers use overlapping but not identical lists, and a mapping from the old list to the new one has to be written, reviewed by whoever owns compliance on your side, and tested on the flows with the most volume before cutover. A mismatch between the purpose and what the documents show is the most common cause of a hold at any provider, and a migration that mechanically maps every payout to the closest-sounding category will produce holds in the first week that look like a problem with the new provider and are in fact a problem with the mapping.

Running both providers in parallel without double-paying anyone

The parallel phase is where the migration is safest and where the most expensive mistake can happen: a payout executed twice, once by each provider, because a retry went to the wrong one.

Idempotency is the control. Every payout instruction carries a key that identifies the operation, and the provider refuses to execute the same key twice. During the parallel phase the key has to identify the operation across both providers, which means your system, not either provider, owns it and records which provider a given key was sent to. A retry after a timeout then goes to the same provider with the same key and is answered from its cache rather than executed again. How the mechanism works at Lumx, including that both successful and failed responses are cached for the key's lifetime, is on the idempotency page of the docs, and the equivalent at the old provider should be read the same way before the first parallel day.

Routing is the second control. A customer is on one provider or the other for payouts at any moment, never both, and the switch is a flag in your system that changes once, when the balance has landed and the first test payout has succeeded. Migrating by customer rather than by percentage of traffic makes every payout attributable to one provider and makes the reconciliation for the parallel period readable.

Events are the third. Both providers will send status updates for the flows they execute, and the receiving endpoint on your side has to know which provider a given event came from and which internal record it belongs to. Merging the two streams into one handler without a source field produces a payout with two conflicting statuses.

The cutover, and what to leave running at the old provider

Cutover is per customer, and the checklist is short: customer approved at the new provider, accounts active where they are needed, destinations registered and approved, balance landed, one small test payout completed end to end with its events received and reconciled. Then the routing flag changes and the customer's payouts run on the new provider from the next instruction.

What stays at the old provider is decided by what is still in flight. Pending payouts complete where they were started; recalling them to re-issue elsewhere adds a failure mode for no benefit. Open collections into a named account stay open until their window expires or the deposit lands, and the account itself stays open for a period after the last collection, because a payer who was told the new details will still, some fraction of the time, pay the old ones. A late deposit into an account that has been closed is refunded to the sender and becomes a support conversation; a late deposit into an account that is still open is money.

Turn the old integration off in stages: new customers first, then new collections, then payouts as each customer cuts over, then, weeks later, the accounts and the contract. Negotiate read access to the old provider's records for a full accounting period after the last transaction, because the first month-end close will need both sides.

When migrating is the wrong move

A migration is expensive in customer attention, the currency that matters most to a payments business. Three situations argue for not doing it, or not yet.

If the problem is one corridor, the answer may be a second provider for that corridor rather than a migration of everything. Running two providers permanently has a cost in reconciliation and in routing logic, and it is smaller than the cost of re-onboarding a customer base to fix one currency. The coverage page is the corridor-by-corridor view of one provider, and reading two of them side by side is the comparison that decides between adding and replacing.

If the current provider's issue is price, the number to compare is the total cost over the migration period, including the parallel phase and the customer attention, against the saving over the horizon you can actually forecast. A saving of a few basis points on a volume that might change next year rarely covers a re-onboarding of every customer this year.

And if the reason is an incident at the current provider that is being handled, moving in the middle of it adds your own incident to theirs. The exception is a frozen or disputed balance, where the first action is to get the assets out and the migration is what you do afterwards.

What the receiving side of a migration looks like on Lumx

Lumx is stablecoin payments infrastructure for businesses that move money between Latin America and the rest of the world: one API to collect, hold, convert, and pay out in BRL, MXN, COP, USD, EUR, and GBP or in USDC and USDT, over local rails such as PIX, SPEI, PSE, ACH, FEDWIRE, SEPA, and Faster Payments, with SWIFT and on-behalf-of payments and collections (POBO and COBO) in USD, EUR, and GBP, plus named virtual accounts, custodial wallets, and KYB/KYC built in.

A migration into Lumx follows the sequence above with a few specifics. A customer is created with the currencies it needs listed at creation, so the named accounts are requested at the same time as verification rather than afterwards, and the accounts for BRL and MXN activate as soon as the customer is approved. Where an individual customer was verified by Sumsub at the previous provider, the verification can be reused through a share token, which turns the wave into a re-check rather than a full re-submission; business customers go through KYB again. Wallets are created only for approved customers, so the receiving address for the balance transfer exists exactly when the customer can legally hold it there, and it is issued per network, which is the detail that prevents a balance on Tron from being sent to an address on Ethereum during the move.

Destinations are registered per customer with the holder relationship from a fixed list, and payouts carry a purpose from a fixed list, so the mapping from the old provider's categories is written against something concrete and tested in the sandbox before cutover. Every mutation accepts an idempotency key that is cached for twenty-four hours, with a conflict returned if the same key arrives with a different body, which is what makes the parallel phase safe against double execution. Limits are readable per customer with used and remaining amounts, so a migrated customer whose payouts exceed standard limits is visible before their first payout fails rather than after. What the payout itself looks like once the customer is across is described in global payments, and the cost structure they land on is in how stablecoin payout pricing works.

My position on migrations, formed from being on the receiving end of them, is that the ones that go badly are never the ones with the hardest code. They are the ones where the customer list was exported from the old provider and imported into the new one without anyone reading it, so the first week is spent discovering dormant accounts, mislabelled destinations and customers who did not know they were moving. I would rather a prospect spend two weeks cleaning that list before we see it than two weeks after, and I say so on the first call, even though it delays the start.

Verified on September 25, 2026. Operational context, not legal, tax, or investment advice.

Cover photo: Ries Bosch on Unsplash.