Guias

Guia de Migração

8 min de leitura

Migrando de uma integração direta com Stripe, MercadoPago ou PayPal para o Orquestraio. A mudança é cirúrgica — na maioria dos casos, é um único endpoint diferente.

Tempo estimado: 1–2 horas para a migração técnica. Sem downtime necessário — o Orquestraio aceita as mesmas credenciais dos gateways que você já usa.

O que muda e o que fica igual

Conceito	Status	Detalhe
Credenciais dos gateways	✓ IGUAL	Suas chaves do Stripe/MercadoPago/PayPal vão para variáveis de ambiente no Orquestraio. Você não precisa gerar novas.
Lógica de negócio	✓ IGUAL	Sua aplicação continua chamando um único endpoint POST para criar pagamentos.
Idempotência	✓ MELHOR	Se você já usava `Idempotency-Key` no Stripe, a lógica é a mesma — agora via campo `idempotencyKey` no body, com cache Redis de 24h.
Endpoint de pagamento	↳ MUDA	Em vez de chamar `api.stripe.com` ou `api.mercadopago.com` diretamente, você chama `/v1/payments` do Orquestraio.
Formato do request body	↳ MUDA	Schema unificado do Orquestraio — não o schema proprietário de cada gateway.
Formato da resposta	↳ MUDA	Resposta normalizada com `status: APPROVED \| DECLINED \| PENDING` independente do gateway.
SDKs dos gateways (stripe-node, etc.)	↳ REMOVE	Você pode remover as dependências dos SDKs individuais. O Orquestraio faz a chamada ao gateway internamente.
Webhooks	↳ MUDA	Configure os webhooks dos gateways para apontar para o Orquestraio, que normaliza e re-entrega para o seu endpoint.

Migrando do Stripe

Comparação direta: criação de um PaymentIntent no Stripe vs. o mesmo pagamento via Orquestraio.

— ANTES (Stripe direto · Node.js)

import Stripe from 'stripe'; const stripe = new Stripe(process.env.STRIPE_SECRET_KEY); const intent = await stripe.paymentIntents.create({ amount: 5000, // centavos currency: 'brl', payment_method: 'pm_card_visa', confirm: true, idempotencyKey: 'order-abc-001', }); if (intent.status === 'succeeded') { // aprovado }

+ DEPOIS (Orquestraio · Node.js)

// Sem import de SDK const res = await fetch( 'https://api.orquestraio.com/v1/payments', { method: 'POST', headers: { 'x-api-key': process.env.OZ_API_KEY, 'Content-Type': 'application/json', }, body: JSON.stringify({ idempotencyKey: 'order-abc-001', amount: 50.00, // reais currency: 'BRL', paymentMethodRequest: { type: 'card_token', token: 'pm_card_visa', }, customer: { id: 'u1', email: '[email protected]' }, }), } ); const data = await res.json(); if (data.status === 'APPROVED') { // aprovado }

Atenção ao amount: O Stripe usa centavos (inteiro). O Orquestraio usa o valor em reais com decimais (50.00, não 5000). Não esqueça de converter.

Mapeamento de status (Stripe → Orquestraio)

Stripe status	Orquestraio status
`succeeded`	`APPROVED`
`requires_payment_method`	`DECLINED`
`processing`	`PENDING`
`requires_action`	`PENDING`
`canceled`	`DECLINED`

Migrando do MercadoPago

A SDK do MercadoPago tem um schema bem diferente. O Orquestraio normaliza tudo isso para você.

— ANTES (MercadoPago direto · Python)

import mercadopago sdk = mercadopago.SDK(os.environ["MP_ACCESS_TOKEN"]) payment_data = { "transaction_amount": 50.00, "payment_method_id": "pix", "payer": { "email": "[email protected]", "identification": { "type": "CPF", "number": "12345678901" } } } result = sdk.payment().create(payment_data) if result["status"] == 201: qr = result["response"]["point_of_interaction"] \ ["transaction_data"]["qr_code"]

+ DEPOIS (Orquestraio · Python)

import requests, uuid res = requests.post( "https://api.orquestraio.com/v1/payments", headers={"x-api-key": os.environ["OZ_API_KEY"]}, json={ "idempotencyKey": str(uuid.uuid4()), "amount": 50.00, "currency": "BRL", "paymentMethodRequest": { "type": "pix" }, "customer": { "email": "[email protected]", "document": "123.456.789-01" } } ) data = res.json() if data["status"] == "APPROVED": qr = data["details"]["pixCode"] # mesmo campo, nome normalizado

Não force o gateway: Na migração, você pode omitir metadata.gateway e deixar o SmartRouter escolher o MercadoPago automaticamente — ele respeita as regras de roteamento que você configurar.

Migrando os Webhooks

Em vez de receber webhooks direto do Stripe ou MercadoPago, você configura o Orquestraio como intermediário. Ele valida a assinatura do gateway, normaliza o evento e re-entrega para o seu endpoint com um formato único.

Como configurar

No dashboard do Stripe: configure o endpoint de webhook para https://api.orquestraio.com/webhooks/stripe
No MercadoPago: aponte para https://api.orquestraio.com/webhooks/mercadopago
No Orquestraio: configure o seu endpoint em metadata.webhookUrl ou via painel
O Orquestraio entrega eventos com assinatura HMAC — veja Webhooks

Mapeamento de eventos

Stripe event	MercadoPago action	Orquestraio event
`payment_intent.succeeded`	`payment.updated (approved)`	`payment.approved`
`payment_intent.payment_failed`	`payment.updated (rejected)`	`payment.declined`
`payment_intent.processing`	`payment.created`	`payment.pending`
`charge.refunded`	`payment.updated (refunded)`	`payment.refunded`

Checklist de Migração

Credenciais configuradas — Adicione STRIPE_API_KEY, MP_ACCESS_TOKEN etc. como variáveis de ambiente no servidor do Orquestraio
API Key do Orquestraio gerada — Crie sua Oz_live_... no painel. Em dev, use orquestraio-livre-123
Endpoint atualizado — Substitua chamadas diretas ao gateway por POST /v1/payments
amount convertido — Se usava centavos (Stripe), converta para reais (5000 → 50.00)
status normalizado — Substitua verificações de succeeded / approved por APPROVED
Webhooks redirecionados — Aponte os webhooks dos gateways para o Orquestraio e atualize seu endpoint receptor
Testado no Sandbox — Use gateway: "MOCK" para simular APPROVED, DECLINED e PENDING antes de ir a produção. Ver Sandbox & MOCK
SDKs antigos removidos — Remova stripe, mercadopago etc. das dependências do projeto

Dúvidas na migração? Abra uma issue no GitHub com o label migration-help. Respondemos em até 24h.