> ## 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.
# Configurar sua conta no Stripe
> Obtenha sua Secret API Key e configure os webhooks necessários no Stripe Dashboard antes de conectar ao Brain Studio.
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
Entre na conta Stripe do comerciante.
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**.
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.
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.
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**.
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**.
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.
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.
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](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
No **Stripe Dashboard**, localize a seção **Developers** (em algumas contas aparece na barra inferior).
Abra o **Workbench** pelo acesso que o Stripe oferece (por exemplo, o ícone de seta para cima na barra de desenvolvedores).
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).
### Escolher eventos e tipo de destino
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`
Se o Stripe perguntar a origem, escolha **Sua conta**.
Escolha **Webhook endpoint** (URL HTTPS), não outros conectores como EventBridge.
### URL do endpoint por ambiente
Copie a URL que corresponde ao modo ativo no Dashboard (barra ou indicador de **modo de teste** / **live**).
```text theme={null}
https://chat-payments.jelou.dev/link-webhook?provider=STRIPE
```
```text theme={null}
https://chat-payments.jelou.ai/link-webhook?provider=STRIPE
```
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.
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).
### Verificar o endpoint no Stripe
Antes de continuar, confirme no painel que o destino foi registrado corretamente:
Em **Stripe → Workbench → Webhooks**, o endpoint recém-criado deve aparecer com status **Ativo**.
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
Instale o Stripe no Marketplace e conecte sua conta usando sua Secret API Key.