Pular para o conteúdo principal

Documentation Index

Fetch the complete documentation index at: https://docs.jelou.ai/llms.txt

Use this file to discover all available pages before exploring further.

Este guia cobre as duas tarefas que você deve completar no Stripe Dashboard antes de conectar ao Brain Studio:
  1. Obter sua Secret API Key (Teste ou Produção) para instalar o Stripe no Marketplace.
  2. Configurar webhooks para que a Jelou receba eventos de pagamento e seu fluxo funcione corretamente.
Ao final deste guia você terá credenciais e webhooks prontos para conectar o Stripe no Brain Studio.

​
Antes de começar

Você precisa de uma conta Stripe ativa, acesso ao painel do Stripe e permissões para visualizar/criar API Keys e Webhooks. Não é necessário conhecimento técnico avançado.

​
Ambientes no Stripe (Teste vs Produção)

O Stripe separa os ambientes por tipo de chave:
  • Teste (sk_test_...): para testes sem transações reais.
  • Produção (sk_live_...): para cobranças reais em produção.
O Brain Studio se conecta ao Stripe usando a chave que você inserir. Se você instalar com uma chave de Teste, sua integração permanece em modo de teste. Se você instalar com uma chave de Produção, ela está pronta para produção.

​
Parte 1 — Obter sua Secret API Key

1

Faça login no painel do Stripe

Entre na conta Stripe do comerciante.
Painel principal do Stripe
2

Vá para Developers → API Keys

Existem duas formas de acessar API Keys:
  • Via configurações (ícone no canto superior direito → Developers → Manage API keys)
  • No menu lateral esquerdo, encontre a seção Developers e clique em API Keys.
Menu lateral com acesso direto a Developers e API Keys
3

Escolha o ambiente (Teste ou Produção)

O Stripe pode exibir o modo de teste de duas formas (dependendo da sua conta):
  • Uma opção como “Test mode” / “Switch to a test environment” no seletor de conta.
  • Uma barra superior indicando que você está usando dados de teste.
Seletor de conta com opção de alternar para ambiente de teste
Se sua conta estiver em modo de Produção, é normal ver chaves com live na seção de API Keys. Para obter chaves de Teste, você deve entrar no modo de teste e retornar a esta mesma tela.
Opção de sair do modo de teste no Stripe
4

Criar (ou copiar) sua Secret API Key

Em API Keys, você verá dois tipos de chaves:
  • Publishable key (pk_...) → NÃO é usada para instalar o Stripe no Brain Studio
  • Secret key (sk_...) → SIM, esta é a que você precisa
No Brain Studio você deve sempre usar uma Secret API Key (sk_test_... ou sk_live_...). Não use a Publishable Key (pk_...).
Se você já tem uma Secret key pronta para uso, pode copiá-la. Se precisar criar uma nova, clique em Create secret key.
Seção de chaves padrão e botão para criar secret key
5

Escolha o tipo de chave (recomendado: Standard)

Ao criar uma chave, o Stripe geralmente exibe opções como:
  • How I’m building my integration (chave padrão / acesso total)
  • I’m providing this key to another website (o Stripe sugere uma chave restrita)
Para o Marketplace (BYOK) e para evitar atrito, recomendamos usar uma chave padrão.
Modal do Stripe para criar uma secret key com opções
O Stripe pode recomendar chaves restritas para compartilhamento com terceiros. Na Jelou, a chave é armazenada de forma segura no nível da plataforma (não fica exposta ao usuário final). Se você precisar de controle adicional, revise a seção Chaves restritas (opcional) ao final deste guia.
Se a chave copiada começa com sk_test_ ou sk_live_, você tem tudo o que precisa para instalar o Stripe.
Confirmação de secret key criada no Stripe
6

Use a Secret API Key no Brain Studio

Durante a instalação pelo Marketplace, o Brain Studio solicitará uma única credencial: API Key.Cole sua Secret API Key (sk_test_... ou sk_live_...) e confirme.
Modal do Brain Studio solicitando API Key para instalar o Stripe
Após configurado:
  • As cobranças são processadas diretamente na conta Stripe do comerciante.
  • A Jelou não retém fundos.
  • O resultado do pagamento retorna ao fluxo para continuar com base no status real.

​
Teste vs Produção no Brain Studio

  • Se você instalar com sk_test_..., opera em modo de teste.
  • Se você instalar com sk_live_..., opera em produção.
Para mudar de Teste → Produção (ou vice-versa), atualmente você precisa: desinstalar o Stripe no Marketplace e reinstalar com a nova chave.

​
Chaves restritas (opcional)

O Stripe permite criar Chaves Restritas (geralmente vistas como rk_...) com permissões específicas. Você pode usar uma chave restrita se sua organização exigir maior controle, mas deve garantir que as permissões necessárias estejam habilitadas para que o Stripe funcione corretamente no Brain Studio.
Se quiser saber mais, consulte a documentação oficial do Stripe sobre API keys: https://docs.stripe.com/keys

​
Solução de problemas

Em algumas contas Stripe, o acesso ao Teste aparece no seletor de conta (canto superior esquerdo) como:
  • Switch to a test environment
  • Test mode
  • Manage test environments
Se você já está no modo de teste, geralmente aparece uma barra superior indicando que você está usando dados de teste.
Você está usando uma Publishable key (pk_...).Volte para Developers → API Keys e copie uma Secret key (sk_...).
O Stripe exibe a chave completa apenas uma vez no momento da criação.Se você não a salvou:
  • crie uma nova chave
  • salve-a em um local seguro (gerenciador de senhas / cofre de segredos)
Este é o comportamento normal do Stripe para proteger as chaves secretas.

​
Boas práticas

  • Não compartilhe sua sk_... por chat ou e-mail.
  • Armazene-a em um gerenciador de senhas ou cofre de segredos.
  • Se suspeitar de exposição, faça a rotação pelo painel do Stripe e reinstale o Stripe no Brain Studio com a nova chave.
  • Use sk_test_... para testes internos e QA.
  • Antes de entrar em produção, instale com sk_live_... e valide um pagamento real de ponta a ponta.

​
Parte 2 — Configurar webhooks no Stripe (obrigatório)

A Jelou precisa que o Stripe envie eventos de pagamento à plataforma para alinhar o resultado da cobrança com seu fluxo no Brain Studio. Isso é configurado no Stripe Dashboard: você cria um endpoint de webhook e seleciona os eventos indicados abaixo.
Sem webhooks corretos, um pagamento pode ser concluído no Stripe e, ainda assim, o fluxo no Brain Studio pode ficar inconsistente (por exemplo, pendente ou sem avançar para a saída esperada do nó).
O Stripe distingue modo de teste (Test) e modo de produção (Live). Configure um webhook por modo se for usar os dois. A Secret API Key que você instalará no Marketplace (sk_test_... ou sk_live_...) deve corresponder ao mesmo modo que o webhook que você está configurando no painel.

​
Abrir Developers, Workbench e Webhooks

1

Abrir Developers

No Stripe Dashboard, localize a seção Developers (em algumas contas aparece na barra inferior).
2

Abrir Workbench

Abra o Workbench pelo acesso que o Stripe oferece (por exemplo, o ícone de seta para cima na barra de desenvolvedores).
3

Ir para a aba Webhooks

Dentro do Workbench, selecione a aba Webhooks e crie um novo destino ou novo endpoint (o nome exato pode variar dependendo da versão do painel).
Stripe Dashboard: Workbench com a aba Webhooks visível

​
Escolher eventos e tipo de destino

1

Selecionar eventos

Quando o assistente perguntar quais eventos notificar, busque payment_intent e marque apenas estes três:
  • payment_intent.succeeded
  • payment_intent.requires_action
  • payment_intent.payment_failed
2

Origem dos eventos

Se o Stripe perguntar a origem, escolha Sua conta.
3

Tipo de destino

Escolha Webhook endpoint (URL HTTPS), não outros conectores como EventBridge.
Lista de eventos do Stripe com payment_intent.succeeded, requires_action e payment_failed marcados

​
URL do endpoint por ambiente

Copie a URL que corresponde ao modo ativo no Dashboard (barra ou indicador de modo de teste / live). 
https://chat-payments.jelou.dev/link-webhook?provider=STRIPE
1

Colar a URL e salvar

No campo de URL do endpoint, cole o endereço da aba acima de acordo com o modo em que você está trabalhando. Revise o resumo: devem constar os três eventos e o tipo webhook. Crie ou salve o destino.
2

Repetir no outro modo (se aplicável)

Se você usar Teste e Produção, volte e crie o endpoint no outro modo do Dashboard com a outra URL (jelou.dev para Teste, jelou.ai para Produção).
Formulário do Stripe para criar destino de webhook com a URL da Jelou e nome do destino

​
Verificar o endpoint no Stripe

Antes de continuar, confirme no painel que o destino foi registrado corretamente:
1

Revisar a lista de destinos

Em Stripe → Workbench → Webhooks, o endpoint recém-criado deve aparecer com status Ativo.
2

Confirmar eventos e URL

Abra o detalhe do destino e verifique que:
  • Ele escuta exatamente os três eventos (payment_intent.succeeded, payment_intent.requires_action, payment_intent.payment_failed)
  • A URL aponta para o endereço correto da Jelou para seu ambiente (jelou.dev para Teste, jelou.ai para Produção)
Se o destino aparecer como Ativo com os três eventos e a URL da Jelou, a configuração no Stripe está completa.
Se algo não bater, verifique nesta ordem: que o modo do Dashboard (Teste vs Produção) corresponde à URL, que os três eventos estão selecionados e que a URL não tem espaços ou caracteres extras.

​
Próximo passo

Conectar no Brain Studio

Instale o Stripe no Marketplace e conecte sua conta usando sua Secret API Key.