Integração Stripe

O MIDDAG Account integra-se ao Stripe para processamento de pagamentos, gerenciamento de assinaturas e manipulação de faturas. A integração opera em modo de conta dupla para suportar duas entidades jurídicas faturando em moedas diferentes.

Arquitetura de conta dupla

A MIDDAG opera duas contas Stripe:

Conta	Entidade jurídica	Moeda	Utilizada para
Stripe BR	MIDDAG Tecnologia LTDA	BRL	Todos os produtos brasileiros
Stripe US/LLC	MIDDAG, LLC	USD	Plugins e serviços internacionais

Cada conta possui suas próprias chaves de API, endpoint de webhook e segredo de assinatura. O plugin roteia as transações para a conta correta automaticamente.

Configuração

Chaves de API

Configure as seguintes variáveis de ambiente no seu wp-config.php ou ambiente:

Variável	Descrição
STRIPE_BR_SECRET_KEY	Chave secreta do Stripe BR
STRIPE_BR_PUBLISHABLE_KEY	Chave pública do Stripe BR
STRIPE_BR_WEBHOOK_SECRET	Segredo de assinatura de webhook do BR
STRIPE_LLC_SECRET_KEY	Chave secreta do Stripe US
STRIPE_LLC_PUBLISHABLE_KEY	Chave pública do Stripe US
STRIPE_LLC_WEBHOOK_SECRET	Segredo de assinatura de webhook do US

Você pode encontrar esses valores no Stripe Dashboard em Developers > API keys e Webhooks.

Endpoints de webhook

Registre estas URLs no dashboard de cada conta Stripe:

Conta Stripe	URL do Webhook
Stripe BR	https://seusite.com/wp-json/middag-account/v1/webhooks/stripe/br
Stripe US/LLC	https://seusite.com/wp-json/middag-account/v1/webhooks/stripe/llc

Resolução de conta

Quando um evento de pagamento ou assinatura ocorre, o plugin determina qual conta Stripe utilizar através de uma resolução em cascata:

1. Override explícito -- Um admin ou o header X-Middag-Company da API especifica a conta diretamente.
2. Channels do produto -- O YAML do produto define com quais contas Stripe ele sincroniza.
3. Entidade da organização -- O ID de cliente Stripe existente da organização determina a conta.
4. Auto-detecção -- Recorre ao formato do ID fiscal (CNPJ = Brasil) ou moeda preferida.

Gerenciamento de clientes

Cada organização armazena IDs de cliente Stripe separados:

Campo	Conta
stripe_customer_id_br	Stripe BR
stripe_customer_id_global	Stripe US

Os clientes são criados sob demanda -- apenas quando a primeira transação é roteada para aquela conta. Uma organização pode ter registros de cliente em ambas as contas (raro, mas suportado).

Dados sincronizados

Pagamentos e faturas

O WooCommerce é a fonte da verdade para o estado de faturamento. O Stripe alimenta o WooCommerce por meio de webhooks, e o plugin lê do WooCommerce. O plugin nunca lê o estado de faturamento diretamente do Stripe.

Assinaturas

Alterações de assinatura no Stripe (upgrades, downgrades, cancelamentos) são refletidas nos registros de entitlement do plugin. Nível, período e status são atualizados quando o Stripe envia eventos de assinatura.

Eventos de webhook

Eventos principais

Evento Stripe	Ação do plugin
invoice.paid	Fatura sincronizada. Status da cotação vinculada definido como paid.
invoice.payment_failed	Política de recuperação de pagamento consultada. Entitlement pode ser suspenso.
subscription.updated	Entitlement atualizado (nível, período).
subscription.deleted	Entitlement definido como cancelled.
charge.refunded	Fatura marcada como reembolsada. Admin notificado.

Eventos adicionais

Evento Stripe	Ação do plugin
checkout.session.completed	Pedido criado a partir da sessão Stripe Checkout.
payment_intent.succeeded	Pedido marcado como pago.
payment_intent.payment_failed	Falha de pagamento registrada.
customer.subscription.created	Registro local de assinatura criado ou atualizado.
charge.dispute.created	Admin notificado, disputa registrada.

Válidação de assinatura

Cada webhook de entrada é validado usando HMAC-SHA256 com o header Stripe-Signature. A janela de tolerância é de 300 segundos (5 minutos). Webhooks que falham na válidação de assinatura são rejeitados com HTTP 401 e registrados como erros.

Cada conta Stripe utiliza seu próprio segredo de assinatura de webhook. Nunca compartilhe segredos entre contas.

Comportamento de rateio

Nível do produto	Comportamento de rateio	Observações
Plugins	create_prorations	Rateio padrão do Stripe em alterações
Suporte	none	Cobranças únicas, rateio não necessário
Plataforma	create_prorations	Add-ons rateados no meio do ciclo
Serviços	always_invoice	Alterações geram uma fatura imediata

Marcação de transações

Cada registro financeiro (pedido, fatura, licença, contrato) carrega uma tag billing_entity (middag_br ou middag_global). A REST API suporta filtro por entidade: ?billing_entity=middag_br.

Adicionando uma nova entidade

A arquitetura de conta dupla é projetada para escalar. Para adicionar uma terceira entidade (por exemplo, middag_eu):

1. Adicione variáveis de ambiente para a nova conta Stripe.
2. Registre a conta no container de DI.
3. Adicione a entidade à whitelist do resolvedor de contas.
4. Registre um novo endpoint de webhook (/webhooks/stripe/eu).
5. Adicione um campo stripe_customer_id_eu às organizações.
6. Configure o webhook no Stripe Dashboard.

Nenhuma alteração nos handlers centrais de webhook ou filtros da API é necessária.

Solução de problemas

Sintoma	Causa provável	Correção
Webhooks retornando 401	Segredo de assinatura de webhook incorreto	Verifique se o segredo corresponde ao Stripe Dashboard
Pagamentos não sincronizando	URL do webhook não registrada no Stripe	Adicione a URL do endpoint em Stripe > Webhooks
Conta errada usada no pagamento	Bloco channels do produto ausente	Verifique se o YAML do produto possui os channels do Stripe
Registros duplicados de fatura	Verificação de idempotência falhando	Verifique o rastreamento de stripe_event_id no banco de dados
Entitlement não atualizando	Evento de assinatura fora da lista tratada	Verifique se o tipo de evento está habilitado no Stripe