O módulo commerce do Hedhog integra com Stripe e Mercado Pago para cobranças únicas e assinaturas recorrentes. As credenciais ficam em um Perfil de Integração (tipo payment), e uma única configuração escolhe qual está ativo.

1. Crie um Perfil de Integração do tipo Payment, provedor stripe ou mercado_pago, com as chaves do gateway na sua config
2. Aponte commerce-default-payment-profile-id para esse perfil — seja definindo-o diretamente, ou (recomendado) usando a ação Auto-configure webhook descrita abaixo, que o define para você
3. CommerceCheckoutService.processCheckout() carrega esse perfil e chama o gateway diretamente: Mercado Pago via POST https://api.mercadopago.com/v1/payments (ou /preapproval para planos recorrentes), Stripe via a Charges API legada POST https://api.stripe.com/v1/charges
4. O resultado é registrado em commerce_payment/commerce_order, e entitlements ou assinaturas são criados em caso de sucesso

Apenas um perfil de pagamento fica ativo por vez — commerce-default-payment-profile-id é uma configuração única, não por produto ou por moeda.

Status: ⚠️ Funciona de ponta a ponta, mas apenas se conectado através da URL de webhook correta — veja "A URL de Webhook Não É a Que Você Esperaria" abaixo, o erro de configuração mais comum de todos.

1. Crie um Perfil de Integração (tipo Payment, Stripe ou Mercado Pago) com suas chaves em Settings → Integration Profiles
2. Vá em Commerce → Webhooks → Webhook Settings, selecione o perfil e clique em Generate Webhook
3. Copie a URL {API_URL}/webhook/{public_uuid} gerada para o dashboard do gateway — não /commerce/webhooks/...
4. Faça uma cobrança de teste e confirme que o pedido muda de pending para paid sozinho

Nota sobre o Stripe: a integração atual do Hedhog com o Stripe usa a clássica Charges API com um token source de cartão, não PaymentIntents/Elements. Seu frontend de checkout precisa tokenizar o cartão em um source/token compatível com essa API antes de chamar o endpoint de checkout do Hedhog.

Esta é a parte que mais provavelmente vai enganar um novo desenvolvedor: o Hedhog não usa um path de webhook fixo e previsível como /api/payment/stripe/webhook. Há dois endpoints diferentes, e apenas um deles realmente atualiza o status de pagamento/pedido/assinatura:

Para obter a URL de webhook real e funcional:

1. No admin, vá em Commerce → Webhooks, abra Webhook Settings e selecione seu Perfil de Integração de pagamento — isso o salva imediatamente como commerce-default-payment-profile-id
2. Clique em Generate Webhook (chama POST {API_URL}/commerce/webhooks/auto-configure com { "integrationProfileId": <id> })
3. O Hedhog cria (ou reutiliza) uma Webhook Integration genérica em Settings → Integrations and Webhooks, e o painel mostra uma URL pública de ingestão no formato {API_URL}/webhook/{public_uuid} com um botão de copiar para a área de transferência
4. Registre essa URL {API_URL}/webhook/{public_uuid} no dashboard do Stripe ou do Mercado Pago — não o path /commerce/webhooks/...

Se os pagamentos têm sucesso mas os pedidos nunca mudam para "paid" e as assinaturas nunca ativam, verifique isto primeiro — quase sempre significa que o gateway está apontado para o endpoint de log de auditoria em vez do auto-configurado.

---

Console: dashboard.stripe.com

1. Ative sua conta para o modo live quando estiver pronto (o modo test funciona imediatamente, sem ativação)
2. Vá em Developers → API keys e copie a Publishable key e a Secret key para o Perfil de Integração
3. Execute a etapa Generate Webhook acima, depois vá em Developers → Webhooks → Add endpoint no dashboard do Stripe e cole a URL {API_URL}/webhook/{public_uuid} gerada
4. Selecione pelo menos charge.succeeded, charge.failed e quaisquer eventos relacionados a assinaturas que seus planos usem

Cartão de teste: 4242 4242 4242 4242, qualquer validade futura, qualquer CVC.

---

Console: developers.mercadopago.com

1. Em Your integrations → Create application, vá em Credentials e copie o Access token e a Public key (use a aba Test credentials enquanto desenvolve)
2. Execute a etapa Generate Webhook acima, depois registre a URL {API_URL}/webhook/{public_uuid} resultante como a URL de notificação de webhook/IPN da aplicação no dashboard do Mercado Pago
3. Para planos recorrentes, o Mercado Pago usa objetos de preapproval (assinatura) em vez de cobranças repetidas — o Hedhog os cria automaticamente para preços marcados como billing_type: recurring

O Mercado Pago suporta vários métodos de pagamento através do mesmo access_token automaticamente: cartões de crédito/débito, Pix (Brasil, transferência instantânea) e métodos específicos por região, dependendo do país do pagador. Teste com os números de cartão de teste deles.

---

• Faça uma cobrança de teste (4242 4242 4242 4242 para Stripe, os cartões de teste do Mercado Pago para MP) e confirme que o pedido passa de pending para paid sozinho — se ele não mudar em alguns segundos, a URL de webhook está quase certamente errada, não a cobrança em si
• Verifique o log da Webhook Integration (Settings → Integrations and Webhooks) para confirmar que o evento realmente chegou

---