Validador de Chave Pública Stripe

Chaves Stripe: pk_, sk_, rk_ e a divisao live/test

A Stripe usa chaves de API com prefixo para tornar o proposito imediatamente reconhecivel em code review e busca em logs. Toda chave comeca com um indicador de papel de duas ou tres letras, seguido pelo slug de ambiente live ou test e um payload alfanumerico gerado pelo servico de aleatoriedade da Stripe. Os quatro prefixos com que voce lida no dia a dia:

• pk_live_ — publishable key, producao. Pode ser embutida em JavaScript de cliente, bundles mobile e paginas HTML.
• pk_test_ — publishable key, sandbox. Mesmas regras da live; cobrancas caem no ledger de teste.
• sk_live_ — secret key, producao. Acesso completo a conta. NUNCA pode sair do servidor.
• sk_test_ — secret key, sandbox. Mesmo risco da live em ambientes inferiores; trate com o mesmo cuidado.
• rk_live_ / rk_test_ — restricted key, com subconjunto de permissoes (ex: leitura em Charges, escrita em Invoices).
• whsec_ — segredo de assinatura de webhook, usado para verificar o payload via HMAC-SHA256.

A regex que esta ferramenta aplica e ^(pk|sk|rk)_(live|test)_[a-zA-Z0-9]{24,}$. A Stripe nao se compromete publicamente com tamanho fixo, e historicamente o payload cresceu de 24 para 99+ caracteres a medida que a entropia aumentou. O invariante relevante e o formato do prefixo, que o Stripe Radar e os SDKs internos usam para roteamento.

Cliente vs servidor: onde cada chave vai

A divisao e rigida. Publishable keys vao para Stripe.js, Elements e Checkout — codigo front-end que cria PaymentMethods, confirma PaymentIntents e renderiza formularios de cartao em iframes hospedados pela Stripe (assim os dados do cartao nunca tocam o seu servidor, satisfazendo o PCI DSS SAQ A). Secret keys ficam nos SDKs de backend (stripe-node, stripe-python, stripe-ruby, etc.) e sao usadas para criar Charges, emitir Refunds, consultar Customers e escrever endpoints de webhook.

// CLIENTE (navegador) - publishable key OK
const stripe = Stripe('pk_live_51ABC...');
const elements = stripe.elements();

// SERVIDOR (Node.js) - secret key somente
const Stripe = require('stripe');
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY); // sk_live_...
await stripe.paymentIntents.create({ amount: 5000, currency: 'brl' });

Vazar uma secret key e o erro mais danoso em uma integracao Stripe. Um bot da Stripe varre continuamente GitHub, npm, PyPI e Pastebin publicos atras de chaves vazadas; um hit revoga automaticamente e notifica o dono da conta. Ainda assim, a janela entre commit e rotacao basta para drenar saldos Connect ou emitir refunds.

Brasil: BRL, PIX, boleto e o lancamento full em 2024

A Stripe operou no Brasil por anos em modelo cross-border limitado, mas o lancamento full de 2024 trouxe entidade brasileira, adquirencia local em BRL e suporte direto aos tres metodos que o consumidor BR realmente usa:

• Cartao de credito: Visa, Mastercard, Elo, Hipercard, com parcelamento de ate 12x fixas.
• PIX: pagamento instantaneo, disponivel via Stripe desde 2021, com settlement em ate 30 segundos. A integracao usa payment_method_types: ['pix'] no PaymentIntent.
• Boleto bancario: o tradicional, em geral com vencimento de 2 dias.

O Stripe Connect, produto de marketplace, suporta vendedores brasileiros e e amplamente usado por SaaS que onboardam comerciantes BR. O 3D Secure 2 (3DS2) e obrigatorio em cross-border europeu sob PSD2; a Stripe trata a friccao automaticamente via Dynamic 3DS nos PaymentIntents. A tabela padrao Stripe Brasil fica em torno de 3,99% + R$ 0,39 em cartoes domesticos em 2024.

Webhooks, idempotencia, versionamento de API e cartoes de teste

Codigo Stripe robusto depende de quatro primitivas que nao sao chaves:

• Webhook signing secret (whsec_...): cada endpoint tem o seu, verificado por stripe.webhooks.constructEvent(payload, signature, secret). Nunca confie no body de eventos sem assinatura.
• Header Idempotency-Key: um UUID por requisicao logica, enviado em todo POST. A Stripe deduplica retries em 24 horas, evitando cobranca dupla em falha de rede.
• Versionamento de API: cada conta fica fixada em uma string de data (ex: 2024-04-10). Pin do SDK na mesma versao, e upgrade so com teste de migracao explicito.
• Cartoes de teste: 4242 4242 4242 4242 sempre aprova, 4000 0000 0000 0002 sempre nega, 4000 0000 0000 3220 aciona autenticacao 3DS. O baralho completo esta na referencia de testes da Stripe.

O rate limit da Stripe e de 100 leituras ou escritas por segundo em live, 25/seg em test, com burst permitido. Estourar retorna 429 Too Many Requests; os SDKs oficiais implementam backoff exponencial automaticamente. O Climate commitment da Stripe (1% da receita para remocao de carbono) e o produto Stripe Issuing (emissao programatica de cartoes virtuais e fisicos) completam o portfolio.

FAQ

Posso em algum momento enviar uma secret key para o navegador?

Nunca. Chaves sk_ dao acesso total a conta — podem reembolsar qualquer cobranca, transferir saldos e ler todo PII de clientes. Qualquer caminho de codigo que coloque uma secret key no front-end e um incidente critico.

A Stripe suporta mesmo PIX no Brasil?

Sim, desde 2021 em cross-border e desde o lancamento full de 2024 com settlement domestico em BRL. Habilite PIX como metodo no PaymentIntent e a Stripe renderiza o QR e o codigo copia-cola automaticamente.

Qual a diferenca entre chave live e chave test?

Apenas o slug de ambiente no prefixo. pk_test_ e sk_test_ caem no ledger de sandbox, nunca cobram um cartao real e nunca liquidam dinheiro real. Os dois ambientes compartilham o mesmo layout de painel.

Minha chave reprova na regex mas funciona em producao. Por que?

Ou o prefixo nao e padrao (ex: tokens legados tok_ nao sao chaves, sao card tokens) ou ha espacos contaminando o valor. Faca trim, confirme o prefixo e teste de novo. A Stripe nao emite chaves fora dos prefixos documentados.

Devo rotacionar chaves periodicamente?

Sim, especialmente apos toda mudanca de pessoas com acesso ao painel. A Stripe permite criar chaves novas e revogar antigas de forma independente; restricted keys (rk_) permitem escopo estreito por integracao.