Stripe do zero: conta, chave restrita só de leitura e vendas nas Finanças

Para que serve no AFK

Venda entra sozinha nas Finanças. Cada cobrança paga (assinatura ou venda avulsa) vira receita. A taxa do Stripe entra como despesa da categoria taxa.
Estorno e contestação descontam sozinhos. O que você devolve, ou perde em contestação, até 180 dias depois da venda, entra como despesa da categoria estorno. A tarifa da contestação não entra: lance à parte. Contestação aberta aparece no resumo do dia com o prazo de resposta.
Assinantes no CRM. Quem pagou vira cliente no CRM, com o plano. Assinatura cancelada, pagamento que não passou e plano que vence em até 7 dias aparecem em Quem chamar hoje, com a mensagem pronta. Nada é enviado sozinho.
Resumo do mês com assinantes ativos e receita recorrente por mês (MRR).
Quando ele lê: a rotina da manhã traz os últimos 7 dias e atualiza os assinantes. Em Finanças → Vendas automáticas, o botão Importar vendas agora traz os últimos 30 dias na hora.

Só entra venda em real. Cobrança em outra moeda fica de fora, e o AFK avisa.

Antes: quanto custa e o Pix

A API do Stripe é grátis. O AFK só lê. Você paga ao Stripe a tarifa de cada venda, como já paga hoje.

Tarifas do Stripe no Brasil, na página oficial, conferidas em 30/10/2026:

O quê	Tarifa
Cartão nacional	3,99% + R$ 0,39 por cobrança
Cartão internacional	mais 2%
Boleto pago	R$ 3,45
Pix pago	1,19%, só por convite
Billing (assinaturas)	0,7% do volume cobrado pelo Billing
Contestação recebida	R$ 55,00

As tarifas mudam: confira em stripe.com/br/pricing.

Pix no Stripe: não conte com ele. A página de preços diz que o Pix é "disponível somente por convite". A documentação diz que contas no Brasil podem aceitar Pix avulso, e o Pix Automático (recorrente) não existe para empresa com sede no Brasil. Na prática, o Pix pode não aparecer para a sua conta. Veja em dashboard.stripe.com/settings/payment_methods se ele está liberado. Se o Pix é importante para o seu negócio, use o Mercado Pago: veja Mercado Pago do zero: aplicação, Access Token e vendas nas Finanças.

Parte 1: criar a conta e ativar o modo de produção

Crie a conta em dashboard.stripe.com/register.
Verifique a empresa em dashboard.stripe.com/account/onboarding. O Stripe pede os dados da empresa, do produto e a sua relação com a empresa. Escolha Brasil com cuidado: depois de ativar, o país não muda.
Até a verificação sair, a conta fica na área restrita (o modo de teste). Lá nada é cobrado de verdade.

Parte 2: ligar a verificação em duas etapas (2FA)

O Stripe pede a verificação em duas etapas para criar a chave. Faça antes.

Abra dashboard.stripe.com/settings/user.
Ligue a autenticação de dois fatores. O Stripe aceita chave de acesso (passkey), chave de segurança, app autenticador e SMS. Prefira chave de acesso ou app autenticador. O SMS é o último recurso.
Use uma senha só do Stripe, que você não usa em outro site.

Parte 3: criar a chave restrita só de leitura

Por que a restrita. A chave secreta (sk_) faz tudo na conta: cobra, estorna e transfere. A chave restrita (rk_) só faz o que você liberar. O AFK só lê, então a restrita com Leitura basta. Se ela vazar, quem pegar só consegue ler.

Teste ou produção. O Stripe tem duas chaves para cada coisa. A da área restrita começa com rk_test_ e só vê dados de teste. A de produção começa com rk_live_ e vê as vendas de verdade. Para o AFK, use a de produção.

Abra dashboard.stripe.com/apikeys (no menu, Desenvolvedores → Chaves de API). Confira que está no modo de produção, e não na área restrita.
Clique em Criar chave restrita.
Se o Stripe oferecer um conjunto pronto de permissões, comece sem nenhuma permissão.
Em Nome de chave, escreva afk.
Na lista de recursos, marque Leitura nestes seis. Deixe todo o resto em Nenhuma.
- Charges (Cobranças): as vendas. Sem ela, o Testar falha.
- Customers (Clientes): quem paga, para o CRM.
- Subscriptions (Assinaturas): planos, cancelamentos e vencimentos.
- Refunds (Reembolsos): os estornos.
- Disputes (Contestações): as contestações e o prazo.
- Balance (Saldo): a taxa de cada venda. Sem ela, a venda entra sem a taxa, e o AFK avisa.
  Nunca marque Gravação. O AFK não precisa.
Clique em Criar chave e conclua a verificação de dois fatores.
Clique na chave para copiar. Ela aparece uma vez só e começa com rk_live_.
No campo Adicionar uma nota, escreva onde ela está guardada (por exemplo, "AFK, no computador do escritório") e clique em Concluído.

Parte 4: colar no AFK

No painel do AFK, abra Conexões, clique no cartão Stripe — vendas e assinantes, cole em Chave restrita (só leitura), clique em Salvar conexão e depois em Testar.
Abra Finanças → Vendas automáticas e clique em Importar vendas agora. As cobranças dos últimos 30 dias entram como receita.

Onde a chave fica. Só no arquivo .env da pasta do AFK, no seu computador. Ela não vai para a nuvem do AFK, não sobe para o GitHub e não aparece na conversa. O Stripe nunca pede a sua chave. Ninguém do AFK pede também.

No dia a dia

Você quer	Como
Trazer as vendas agora	Finanças → Vendas automáticas → Importar vendas agora. Ou diga ao AFK "lança o que entrou no Stripe".
Ver as vendas por canal	Finanças → Vendas por canal: vendido, devolvido, taxas e líquido do Stripe.
Ver quem chamar	Quem chamar hoje: cancelou, pagamento recusado ou plano vencendo, com a mensagem pronta. Você decide se envia.
Responder uma contestação	Abra a contestação no painel do Stripe e responda antes do prazo que o AFK mostrou. O AFK não responde por você.
Lançar a tarifa de uma contestação	Lance à mão como despesa. O AFK não lança essa tarifa.
Ver o que a chave fez	Em Chaves de API, no menu ⋯ da chave → Ver logs de solicitações.
Trocar a chave	Crie outra (Parte 3), cole por cima no cartão, clique em Salvar conexão e Testar. Depois expire a antiga.
Desligar a conexão	No cartão, clique em Desconectar e confirme. No Stripe, expire a chave: menu ⋯ → Expirar chave.

Se a chave vazar (print, mensagem, arquivo enviado): gire na hora, mesmo sem certeza de que alguém viu. Em dashboard.stripe.com/apikeys, no menu ⋯ da chave, clique em Girar chave, escolha Agora em Expiração e clique em Girar chave de API. A antiga para de funcionar e aparece uma nova com as mesmas permissões. Copie e cole no AFK. Com chave restrita só de leitura, quem pegou a antiga não conseguia cobrar nem estornar, mas conseguia ler os seus clientes.

Erros e soluções

O que aparece	O que fazer
`O serviço recusou a chave (inválida, revogada ou sem permissão).` no Testar	A chave foi expirada, girada, copiada pela metade ou está sem Leitura em Charges. Crie outra (Parte 3) e cole por cima.
`Invalid API Key provided`	A chave está errada ou incompleta. Copie de novo. A chave restrita não dá para ver de novo no modo de produção: se perdeu, crie outra.
`api_key_expired`	A chave foi expirada ou girada. Cole a nova.
`secret_key_required`	Você colou a chave publicável (`pk_`). Use a restrita (`rk_live_`).
`Chave restrita (só leitura): o formato não parece o esperado.`	Faltou um pedaço ou é outro tipo de chave. A certa começa com `rk_live_`.
Erro `403` com `does not have the required permissions`	Falta Leitura em algum recurso. No menu ⋯ da chave → Editar chave, marque o que falta.
`Stripe: a chave não lê as taxas`	Falta Leitura em Balance (Saldo). As vendas entraram sem a taxa. Edite a chave.
`Stripe: a chave não lê estornos` ou `não lê contestações`	Falta Leitura em Refunds ou Disputes. Edite a chave.
Testar passa, mas nenhuma venda entra	A chave é da área restrita (`rk_test_`). Crie a de produção (`rk_live_`).
`Ficaram de fora: 1 moeda USD`	Cobrança em outra moeda. O AFK só lança venda em real. Lance à mão, convertida.
O Pix não aparece no checkout do Stripe	O Pix no Stripe Brasil depende de liberação da conta. Veja Antes e use o Mercado Pago para Pix.

Se nada funcionar

Veja Travou ou quero sugerir uma melhoria: o que mandar. Mande o texto do erro. Nunca mande a chave.

Fontes oficiais (conferido em 30/10/2026): docs.stripe.com/keys/restricted-api-keys (chave restrita rk_live_/rk_test_; Leitura, Gravação ou Nenhuma; Criar chave restrita, verificação de dois fatores, a chave não pode ser recuperada depois; recomendada para agentes de IA) · docs.stripe.com/keys (área restrita e modo de produção; prefixos; Girar chave com Expiração e período de até 7 dias; Expirar chave; logs de solicitações; chave marcada como agente) · docs.stripe.com/keys-best-practices (chave exposta: girar na hora; o Stripe nunca pede a chave) · docs.stripe.com/api/errors (401 sem chave válida; 403 chave sem permissão) · docs.stripe.com/error-codes (api_key_expired, secret_key_required) · docs.stripe.com/get-started/account/activate (verificar a empresa; país não muda depois de ativar; 2FA com passkey, chave de segurança, app ou SMS) · docs.stripe.com/payments/pix (contas no Brasil aceitam Pix avulso; Pix Automático indisponível para empresa no Brasil; elegibilidade nas configurações de formas de pagamento) · stripe.com/br/pricing (cartão nacional 3,99% + R$ 0,39; internacional +2%; boleto R$ 3,45; Pix 1,19% só por convite; Billing 0,7%; contestação R$ 55,00).

trilha Receber e controlar as vendas · passo 2 de 5

próximoNuvemshop: importar os pedidos da sua loja

ainda não tem o AFK?

Com o Stripe ligado, cada cobrança paga entra sozinha nas Finanças do AFK, e quem cancelou a assinatura aparece em Quem chamar hoje com a mensagem pronta.

O AFK deixa o Claude que você assina configurado e atualizado no seu computador: painel do negócio, conteúdo, documentos, travas e antivírus prontos. Você fala, o sistema opera. 7 dias de garantia.

Conhecer o AFK

Chaves e conexões

Não resolveu?

Escreva para contato@afk.ia.br com o passo em que você estava, o que apareceu na tela e um print. A lista do que mandar está em travou ou quer sugerir algo.