迁移 · Pix ↔ 稳定币
如何逐步迁移 On-ramp 或 Off-ramp API，保持应用运行
不要一次切换全部流程。 保留业务标识，在内部接口后适配新契约，验证测试环境及 webhook，开展小规模试点。首批交易对账完成前，保留原服务商作为回退选项。
Pix → USDT/USDCUSDT/USDC → PixPix 对外付款测试环境明确的回退方案
五步迁移方案
梳理产品正在使用的接口契约
列出创建、查询、webhook、重试、凭证、限额及对账。迁移实际使用的行为，不必照搬原服务商整份文档。
创建内部适配层
保留现有支付接口，并映射至 Lunium，避免在整个产品中散布服务商字段及状态名。
复现失败路径
在测试环境覆盖延迟、失败、过期、限额及相同标识重试。Cash-in 还须验证目录、限额、预览、模拟付款及 webhook；真实可付款二维码须使用生产密钥和受控试点。
开展受控试点
明确选择一部分新交易接入，记录各请求所用服务商，绝不能将同一付款发送至两条渠道。
逐步切换并保留回退
交易、webhook 及流水对账完成后再扩大范围。仅在无未完成订单或指向旧服务商的重试后，才停用旧渠道。
最小适配映射
interface SettlementProvider {
preview(input): Promise<Quote>
create(input, externalId): Promise<Order>
get(orderId): Promise<Order>
verifyWebhook(headers, rawBody): Event
}
// 在同一记录中保存 provider、externalId 与 orderId
// 随后才允许重试、轮询或经授权的通道变更
扩大试点的条件
接口契约
已映射状态及错误，不把“等待中”视为“失败”。
幂等性
相同内容重试返回原交易，冲突不会生成第二笔。
Webhook
已验证签名，处理程序兼容重复及乱序事件。
对账
每个内部订单只关联一个服务商及一笔交易。
何时不应将流量发送至 Lunium
无法自动判断时： 若目录、报价或配置不可用，保留订单并遵守 API 返回的处理建议，不要盲目路由。
避免重复： 只有在确认尚未创建交易，或完成对账并作出明确决定后，才可考虑切换渠道。
以证据为准： 使用
request_id、 external_id、webhook 及状态查询判断实际结果。介绍您的现有流程
技术评估围绕产品实际使用的接口，形成试点及回退方案。测试与生产密钥均有自助创建路径。