Validador de Chave Pública Stripe

Chaves Stripe: pk_, sk_, rk_ e a divisão live/test

A Stripe usa chaves de API com prefixo para tornar o propósito imediatamente reconhecivel em code review e busca em logs. Toda chave começa com um indicador de papel de duas ou três letras, seguido pelo slug de ambiente live ou test e um payload alfanumérico gerado pelo serviço de aleatoriedade da Stripe. Os quatro prefixos com que você lida no dia a dia:

• pk_live_ — publishable key, produção. Pode ser embutida em JavaScript de cliente, bundles mobile e páginas HTML.
• pk_test_ — publishable key, sandbox. Mesmas regras da live; cobrancas caem no ledger de teste.
• sk_live_ — secret key, produção. 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 permissões (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 não 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 divisão e rigida. Publishable keys vão para Stripe.js, Elements e Checkout — código front-end que cria PaymentMethods, confirma PaymentIntents e renderiza formulários de cartão em iframes hospedados pela Stripe (assim os dados do cartão 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 são 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 públicos atrás 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 lançamento full em 2024

A Stripe operou no Brasil por anos em modelo cross-border limitado, mas o lançamento full de 2024 trouxe entidade brasileira, adquirencia local em BRL e suporte direto aos três métodos que o consumidor BR realmente usa:

• Cartão de crédito: Visa, Mastercard, Elo, Hipercard, com parcelamento de até 12x fixas.
• PIX: pagamento instantaneo, disponível via Stripe desde 2021, com settlement em até 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 obrigatório em cross-border europeu sob PSD2; a Stripe trata a friccao automaticamente via Dynamic 3DS nos PaymentIntents. A tabela padrão Stripe Brasil fica em torno de 3,99% + R$ 0,39 em cartões domésticos em 2024.

Webhooks, idempotencia, versionamento de API e cartões de teste

Código Stripe robusto depende de quatro primitivas que não são 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 requisição lógica, 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 versão, e upgrade so com teste de migração explícito.
• Cartões de teste: 4242 4242 4242 4242 sempre aprova, 4000 0000 0000 0002 sempre nega, 4000 0000 0000 3220 aciona autenticação 3DS. O baralho completo esta na referência 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 (emissão programatica de cartões virtuais e fisicos) completam o portfólio.

FAQ

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

Nunca. Chaves sk_ dão acesso total a conta — podem reembolsar qualquer cobranca, transferir saldos e ler todo PII de clientes. Qualquer caminho de código que coloque uma secret key no front-end e um incidente crítico.

A Stripe suporta mesmo PIX no Brasil?

Sim, desde 2021 em cross-border e desde o lançamento full de 2024 com settlement doméstico em BRL. Habilite PIX como método no PaymentIntent e a Stripe renderiza o QR e o código copia-cola automaticamente.

Qual a diferença 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 cartão real e nunca liquidam dinheiro real. Os dois ambientes compartilham o mesmo layout de painel.

Minha chave reprova na regex mas funciona em produção. Por que?

Ou o prefixo não e padrão (ex: tokens legados tok_ não são chaves, são card tokens) ou ha espaços contaminando o valor. Faca trim, confirme o prefixo e teste de novo. A Stripe não emite chaves fora dos prefixos documentados.

Devo rotacionar chaves periodicamente?

Sim, especialmente após toda mudança 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.