MIGRAÇÃO · PIX ↔ STABLECOIN

Como migrar de uma API de on-ramp ou off-ramp sem parar o aplicativo

Não troque tudo de uma vez. Preserve os identificadores do seu negócio, adapte o novo contrato atrás de uma interface interna, valide sandbox e webhook, rode um piloto pequeno e mantenha o provedor anterior como rollback até reconciliar as primeiras operações.
PIX → USDT/USDCUSDT/USDC → PIXPayout PIXSandboxRollback explícito
Receber mapa de migraçãoComparar OpenAPI

Plano de migração em cinco etapas

Mapeie o contrato que seu produto usa

Liste criação, consulta, webhook, retry, comprovante, limites e reconciliação. Migre o comportamento utilizado, não toda a documentação do provedor anterior.

Crie um adaptador interno

Mantenha sua interface de pagamentos e traduza para a Lunium. Isso evita espalhar nomes de estado e campos do provedor por todo o produto.

Reproduza os caminhos ruins

No cash-out sandbox, exercite demora, falha, expiração, limite e repetição do mesmo identificador. Para cash-in, valide catálogo, limites, prévia e webhook; QR pagável exige chave de produção e piloto real controlado.

Rode um piloto controlado

Ative uma parcela explícita das novas operações. Registre qual provedor recebeu cada pedido; nunca envie o mesmo pagamento para dois trilhos.

Faça o corte e preserve o rollback

Amplie após reconciliar operação, webhook e extrato. Desative o provedor antigo somente quando não houver ordens pendentes ou retries apontando para ele.

Mapa mínimo do adaptador

interface SettlementProvider {
  preview(input): Promise<Quote>
  create(input, externalId): Promise<Order>
  get(orderId): Promise<Order>
  verifyWebhook(headers, rawBody): Event
}

// grave provider + externalId + orderId na mesma linha
// antes de liberar retries, polling ou troca de rota

Critérios para avançar o piloto

Contrato

Estados e erros estão mapeados sem transformar “aguardando” em “falha”.

Idempotência

Retry idêntico retorna a mesma operação e conflito não cria uma segunda.

Webhook

Assinatura é validada e o consumo tolera repetição e fora de ordem.

Reconciliação

Cada pedido interno aponta para um único provedor e uma única operação.

Quando a Lunium não deve receber o tráfego

Sem diagnóstico automático: se catálogo, cotação ou configuração estiver indisponível, preserve a ordem e siga a ação devolvida pela API; não rote cegamente.
Sem duplicidade: failover só pode acontecer antes da criação confirmada ou depois de uma decisão de reconciliação.
Com prova: use request_id, external_id, webhook e consulta de status para saber o que realmente ocorreu.

Traga o seu fluxo atual

A revisão técnica compara apenas os endpoints que seu produto usa e devolve um plano de piloto e rollback. Sandbox e chave de produção são self-service.

Pedir revisão técnicaAbrir sandbox