Start with the commercial contract, not the new integration

A provider migration can be technically successful and still damage the customer experience. The new integration may create payment requests correctly, while an older unpaid request remains open, a delayed transfer reaches the previous provider, or support cannot tell which system owns the case. The challenge is not simply how to migrate to a new crypto payment provider. It is how to preserve every commercial promise while two providers temporarily describe different parts of reality.

The safest approach is a controlled transfer of payment ownership, not a dramatic switch. Existing requests need a defined home, new requests need deterministic routing, customer-facing instructions must remain stable, and finance must retain one coherent record. This guide treats migration as an operating change across product, engineering, finance, support and compliance. It also explains where parallel running helps, where it creates new cost, and when a business should delay the move rather than expose customers to an unfinished process.

The first migration document should describe what the business promises a customer between “pay” and “service delivered.” Code comes later. That promise includes the quoted amount, accepted asset and network, expiry, confirmation rule, treatment of smaller or larger transfers, refund policy, and the moment access or fulfilment may begin.

Provider terms such as created, detected, confirmed, completed and expired are not a universal language. Two providers can use the same word for different evidence. Copying labels from the old API into the new one therefore creates false equivalence. Define a small internal state model in business terms, then map each provider into it.

A useful model separates at least these decisions:

Internal decision Evidence needed Customer-facing consequence
Payment requested A valid request linked to the company’s commercial reference Show amount, asset, network and expiry
Transfer observed A transaction is visible but has not met the acceptance rule Keep fulfilment blocked; explain that verification is continuing
Payment accepted The company’s documented acceptance conditions are met Release the defined product, service or fulfilment action once
Exception review Amount, network, timing or reference differs from policy Route to a named owner; do not improvise in the customer chat
Closed unpaid The request expired without accepted payment Offer a fresh request rather than silently reusing old details
Refund approved Merchant policy and destination checks are complete Create a separately recorded outbound transfer

The internal reference matters more than either provider’s identifier. Create it before calling a provider and retain it across the full lifecycle. Store the provider name and provider reference as attributes, not as the primary identity of the sale. That choice allows finance and support to search by customer, account, invoice or purchase even after the old provider dashboard is no longer used daily.

For request-based B2B collection, the Cryptoway invoices page is a relevant planning reference. The merchant still owns its commercial terms, refund rules, tax treatment and customer relationship. A payment provider supplies evidence and processing capabilities; it does not decide what a paid purchase means inside the merchant’s product.

Migration principle: move provider-specific evidence behind an internal commercial record. If the provider identifier is the business record, the migration is already too tightly coupled.

Freeze the old system as it actually behaves

Teams often document the intended integration rather than the one running in production. Before building the replacement, capture the old system’s real behaviour from code, event logs, finance exports and support cases. The uncomfortable exceptions are more valuable than the happy path.

Build an inventory covering:

Do not assume an undocumented behaviour is harmless. A support agent may routinely reopen expired requests. Finance may depend on a custom export column. A SaaS product may grant access from a browser return because the authoritative event sometimes arrives later. These shortcuts become migration defects when the new provider behaves differently.

Create a “behaviour freeze” for the migration window. Product changes that alter price calculation, expiry policy, account entitlement or refund handling should usually wait unless they fix a blocker. Otherwise, the team cannot tell whether an incident came from the provider move or the simultaneous commercial change.

The inventory should also identify data that cannot be transferred. Cryptographic transaction history remains where it was recorded, and provider-side identifiers do not become native records in the replacement platform. Export what the contract and provider make available, retain it under the company’s record policy, and define how staff will retrieve older evidence. Do not describe a successful migration as “all data moved” if historical cases still require the old system.

Teams considering a deeper application connection can use the Cryptoway API overview as one input to their technical review. The decision between a hosted route and an application-level connection should be made against the business’s actual release logic; the guide to payment page or API choices gives additional context.

Engineering takeaway: the production baseline is a collection of behaviours, not a diagram. If an old exception cannot be explained, it cannot be migrated safely.

Run two providers without creating two sources of truth

A parallel run reduces cutover risk only when ownership is unambiguous. The dangerous design sends the same purchase to both providers, accepts whichever responds first, and asks finance to sort out the duplicates. A controlled design selects exactly one provider when a payment request is created and preserves that assignment until the request is closed.

Add a provider-routing record with the internal commercial reference, selected provider, selection reason, request time, expiry and migration cohort. Make the routing decision deterministic. Suitable cohort keys include account, region approved by the business, product line, sales channel or request creation date. Random traffic splitting may be useful for technical load testing, but it is difficult for support to explain and can give the same customer different instructions within one buying journey.

Existing unpaid requests should normally remain owned by the old provider until they are paid, expire or enter a documented exception path. Do not replace the destination details inside an already issued request. A customer may have copied the address, passed it to a colleague or scheduled the transfer. Changing the visible request does not recall the earlier instruction.

At the same time, the old event receiver must remain active for every open old-provider request. A delayed transfer can arrive after the company has stopped creating new requests there. Shutting down the receiver on cutover day turns a valid customer payment into a support incident.

Both provider adapters should feed the same internal processing path:

  1. verify that the incoming message is authentic under the relevant provider’s documented method;
  2. locate the internal reference and confirm that the provider matches its assigned owner;
  3. store the raw evidence under an appropriate access policy;
  4. map the provider event to the internal decision model;
  5. apply the commercial change once, using a durable event or transaction key;
  6. record the outcome and make it searchable by support and finance.

A browser redirect is not sufficient evidence for fulfilment. Customers can close the page, repeat the return, or reach it before stronger evidence is available. The browser should present progress and recovery options; the server-side record should control the commercial action.

Rollback also needs a precise meaning. It can stop routing new requests to the replacement provider. It cannot move an in-flight transfer back to the old provider or erase requests already shown to customers. A rollback plan must therefore keep both receivers, both support views and both finance evidence paths available until all affected requests reach a terminal decision.

Operating takeaway: dual running is safe when it creates two evidence sources behind one ledger of business decisions. It is unsafe when it creates two competing ledgers.

Move customers by payment journey, not by traffic percentage

Customers do not care which provider processed a transfer. They care whether the amount is clear, the network is correct, the page looks trustworthy, the product activates once, and support can answer without asking them to repeat the whole story. Migration cohorts should therefore follow complete payment journeys.

Start with internal accounts and staff-led test purchases, then move a bounded customer group whose commercial flow is well understood. Choose cases that exercise normal payment, delayed confirmation, expiry, a smaller amount, a larger amount, duplicate event delivery, refund review and a customer returning on another device. A pilot made only of perfect transfers proves little.

Keep customer communication proportionate. If the visible payment method, terms and required action do not change, a broad announcement may create unnecessary concern. If the asset list, network instructions, request domain, expiry rule or refund process changes, explain the change before the customer reaches the payment page. State what the customer must do; avoid vague claims about an “upgrade.”

Hypothetical microcase: a B2B SaaS product with 500 active accounts

Consider a hypothetical SaaS company with 500 active business accounts. Customers renew by following a fresh payment request rather than through a card-style automatic debit. The company moves new-account purchases first but leaves every already-issued renewal request with the old provider until expiry.

For the next renewal cycle, each reminder creates an internal renewal reference and selects one provider at creation. The accepted payment extends the stated service period once. A late transfer to an old request enters review rather than automatically extending access under the new cycle. Support sees the account, service period, expected amount, selected provider and latest decision in one timeline.

The key measure is not migration volume. It is whether renewal access changes correctly without support intervention, duplicate extension or unexplained suspension. The Cryptoway SaaS solution page and the article on crypto subscription payments are useful related resources when defining this journey.

Hypothetical microcase: an online store with 200 crypto purchases on a busy day

Now consider a hypothetical online store that may receive 200 crypto purchases on a busy day. It routes one low-risk product category to the replacement provider while the rest remain on the old route. Each purchase receives a provider assignment at creation, and warehouse release depends on the shared internal acceptance decision rather than a provider label.

The pilot includes one expired request, one payment below the requested amount and one customer who pays an earlier request after starting a new one. Staff verify that the warehouse does not release twice, that support can locate both attempts, and that finance can explain which transfer funded the sale. Only after these cases are handled cleanly does the store expand the cohort.

This example also exposes a limit: a category-based pilot is unsuitable if customers commonly combine items across categories and the platform cannot preserve one provider owner for the entire purchase. The Cryptoway e-commerce page provides additional product context for online merchants.

Product takeaway: a good cohort has one customer journey, one provider owner and one measurable business outcome. “Ten percent of traffic” says none of those things.

What migration teams notice too late

The obvious work is creating payment requests and receiving events. The expensive work appears around exceptions, access, evidence and people.

Historical evidence has an operating cost

Keeping the old account available may involve contract minimums, staff permissions, security reviews and data-retention work. Exporting records also consumes finance and engineering time. Include these costs in the migration budget rather than treating the old provider as free once new traffic stops.

Customer support needs one search surface

During parallel running, a transaction hash alone is a poor support key. Agents need customer email or account, internal reference, expected amount, asset, network, request expiry, assigned provider and current internal decision. They also need a clear escalation path for late, smaller, larger and wrong-network transfers. General service questions may be covered by the Cryptoway FAQ, but the merchant must write its own fulfilment, cancellation and exception policies.

Refunds do not migrate with the original payment

A refund is a new outbound action with its own approval, destination and network checks. The replacement provider may not have the original payment context, while the old account may have limited operational access after cutover. Decide which system executes refunds for old-provider payments, how finance links the two records, and how long that route remains available. The guide to crypto payment refund rules offers a useful starting point for customer wording.

Compliance review is not a one-time checkbox

Provider eligibility, merchant review requirements, supported jurisdictions, asset availability and transaction-monitoring practices can differ. Legal and compliance owners should review the intended entities, customer locations, products, transaction patterns and data handling before each cohort expands. The migration must not be positioned as a way to avoid restrictions or due diligence. Merchants remain responsible for their own laws, taxes, refund terms and customer obligations.

Staff may keep using the old route

A forgotten sales bookmark, support macro or recurring job can continue creating old-provider requests after cutover. Instrument request creation by source and alert on any old-route creation that is not explicitly permitted. Revoking access too early is also risky, because staff may still need historical evidence or refunds. Replace creation permissions separately from read and exception permissions.

Management takeaway: the migration budget should include the temporary cost of running two controlled operations. Cutting overlap too early often converts a visible contract cost into less visible support and finance work.

Exit on evidence: economics, limits and the final closure test

Provider charges are only one line in the migration decision. Compare the steady-state model and the transition model separately.

Steady-state operating cost = provider charges + network and conversion costs + treasury or withdrawal costs + engineering maintenance + finance review + support exceptions + refund handling + failed-payment impact.

Transition cost = implementation and testing + temporary provider overlap + historical export and retention + staff training + customer communication + extra exception handling + delayed releases or renewals caused by migration defects.

Use the company’s own observations: staff time per exception, share of requests needing manual review, renewal recovery, duplicate commercial actions prevented, time to answer a customer, and time to close finance records. Do not insert assumed savings to justify a decision already made. A cheaper quoted rate can be outweighed by manual work; a more expensive provider can still be unsuitable if it does not meet the company’s evidence, control or customer requirements.

The article on customer criteria for crypto payments can help define which users and journeys belong in the migration scope. It should not replace a provider-specific commercial, technical and compliance review.

A business should delay migration when any of these conditions applies:

Final closure should be a deliberate event, not the day new traffic reaches the replacement. Confirm that no old requests remain open, all late-payment windows have ended, refund and dispute obligations have an owner, historical evidence is retained under policy, old creation paths are disabled, and access is reduced to what continuing obligations require. Then compare the measured operating model with the migration hypothesis.

A migration has succeeded when customers can complete payment without learning the provider transition, staff can explain every exception from one commercial record, and finance can close the period without reconstructing events from two dashboards. Until those conditions hold, traffic may have moved, but the payment operation has not.