Stripe

Use a Stripe quando você precisar:

• Cobrar clientes fora do Brasil
• Trabalhar com múltiplas moedas no mesmo checkout
• Implementar splits via Stripe Connect com KYC delegado aos recebedores
• Processar cartões internacionais com taxas de conversão competitivas

A Stripe não oferece Pix nem boleto no Brasil. Para esses métodos use Pagar.me, Asaas, Mercado Pago ou PagSeguro.

Pré-requisitos da conta

• Cadastro em stripe.com e ativação por e-mail
• Para o ambiente de testes (sandbox): nenhuma documentação adicional. Você consegue processar cobranças de teste imediatamente.
• Para produção: dados bancários, CNPJ ou CPF e verificação de identidade (KYC). A Stripe valida documentos antes de liberar saques.

Onde obter a Secret Key

A Stripe oferece dois caminhos para chegar nas chaves. Use o que estiver disponível na sua conta.

Caminho rápido (contas novas)

Ao entrar no dashboard pela primeira vez em dashboard.stripe.com, a Stripe exibe um card Chaves de API na coluna direita com a Publishable Key e a Secret Key prontas para copiar. Esse atalho aparece enquanto a conta está no estágio inicial de configuração.

Repare em dois elementos:

• O banner no topo (Você está testando em uma área restrita...) confirma que as chaves exibidas são de teste. Toda chave gerada nesse modo começa com sk_test_ ou pk_test_.
• O botão Alternar para conta de produção no canto superior direito é como você muda para o modo live, onde as chaves passam a ter o prefixo sk_live_ e pk_live_. Só faça isso quando a verificação de identidade da Stripe estiver concluída.

Caminho canônico (sempre disponível)

Em contas com mais movimentação o card lateral pode não aparecer mais. O caminho oficial está em Developers → API keys:

1. Acesse o dashboard em dashboard.stripe.com.
2. Confira o modo atual pelo toggle no canto superior direito (Test mode ligado = chaves de teste).
3. Navegue até Developers → API keys no menu lateral. URL direta: dashboard.stripe.com/apikeys.
4. Clique em Reveal test key (ou Reveal live key em produção) e copie. A Stripe exibe a Secret key apenas uma vez por sessão — armazene em local seguro.

Campos esperados pela Toktus

Cadastrando

curl -X POST https://api.toktus.com/v1/credentials \
  -H "Authorization: Bearer tk_sua_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "gateway": "stripe",
    "credentials": {
      "secretKey": "sk_test_51Abc123XYZ...",
      "webhookSecret": "whsec_..."
    }
  }'

Particularidade crítica: tokenização de cartão

A Stripe não permite que a Toktus processe dados brutos de cartão. Esta é uma limitação imposta pelo modelo de compliance da Stripe e afeta diretamente como você integra a API.

Por que não funciona enviar número de cartão direto

Para reduzir o escopo de PCI DSS dos seus clientes, a Stripe restringe o processamento de PAN (número do cartão) e CVV ao próprio servidor deles. Provedores intermediários como a Toktus precisariam de certificação PCI DSS Level 1 (auditoria anual, scans trimestrais, segregação de rede) para receber esses dados, repassá-los e estar em conformidade.

A Toktus não opera nesse modelo. Em vez disso, todos os dados de cartão para cobranças com Stripe precisam ser tokenizados diretamente no navegador ou app do comprador, antes de chegarem ao seu backend ou à Toktus.

Na prática, isso significa que se você enviar creditCard.number, creditCard.cvv e creditCard.expMonth/expYear em uma cobrança com gateway: "stripe", a API retorna erro 422 e a cobrança não acontece.

O que enviar em vez disso

A Stripe oferece três identificadores que substituem os dados brutos:

A Toktus aceita os três no campo creditCard.paymentMethodId ou creditCard.token. A recomendação atual da Stripe (e da Toktus) é usar PaymentMethod ID, que tem suporte completo a 3D Secure, autenticação SCA na Europa e armazenamento off-session.

Fluxo completo de uma cobrança Stripe

1. Comprador preenche o cartão na sua página HTML/React/Vue/iOS/Android
2. Stripe.js (ou Stripe iOS/Android SDK) envia os dados direto para a Stripe
3. Stripe retorna um PaymentMethod ID (pm_xxx) para o navegador
4. Seu frontend envia esse pm_xxx para o seu backend
5. Seu backend chama a Toktus: POST /v1/charges com creditCard.paymentMethodId = pm_xxx
6. A Toktus repassa o pm_xxx para a Stripe junto da Secret Key cadastrada
7. A Stripe processa o pagamento e responde com aprovação/recusa
8. A Toktus normaliza a resposta e devolve para você

Em nenhum momento os dados brutos do cartão passam pelo seu servidor ou pela Toktus. É essa propriedade que reduz seu escopo PCI ao mínimo (SAQ A).

Exemplo de tokenização no frontend

Você precisa publicar a sua Publishable Key (pk_test_... ou pk_live_...) no frontend. Diferente da Secret, a Publishable foi feita para isso e não permite cobrar — só tokenizar.

Stripe Elements (recomendado)

<script src="https://js.stripe.com/v3/"></script>
<form id="payment-form">
  <div id="card-element"></div>
  <button type="submit">Pagar</button>
</form>

<script>
  const stripe = Stripe("pk_test_sua_publishable_key");
  const elements = stripe.elements();
  const card = elements.create("card");
  card.mount("#card-element");

  document.getElementById("payment-form").addEventListener("submit", async (e) => {
    e.preventDefault();

    const { paymentMethod, error } = await stripe.createPaymentMethod({
      type: "card",
      card,
    });

    if (error) {
      console.error(error.message);
      return;
    }

    // Envia o paymentMethod.id para seu backend
    const res = await fetch("/api/cobrar", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ paymentMethodId: paymentMethod.id }),
    });
  });
</script>

Token simples (uso único)

const { token, error } = await stripe.createToken(cardElement);
// envia token.id para o backend

Exemplo de cobrança no backend (chamando a Toktus)

curl -X POST https://api.toktus.com/v1/charges \
  -H "Authorization: Bearer tk_sua_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "gateway": "stripe",
    "paymentMethod": "credit_card",
    "amount": 10000,
    "currency": "brl",
    "customerId": "cus_abc123",
    "creditCard": {
      "paymentMethodId": "pm_1Abc2Def3Ghi"
    }
  }'

O que isso significa para integradores server-only

Se você está construindo um sistema que não tem frontend próprio — por exemplo, um backend que processa pagamentos disparados por outro serviço — você ainda precisa tokenizar via Stripe antes de chamar a Toktus. As alternativas, em ordem de menor esforço:

• Toktus Checkout (recomendado): use a página de pagamento pronta da própria Toktus. Ela já carrega o Stripe.js, coleta o cartão no navegador do comprador, faz a tokenização e dispara a cobrança via Toktus automaticamente. Você configura o produto no painel ou via API e compartilha o link — zero código no frontend, zero PCI a se preocupar. É a forma mais simples de aceitar Stripe sem manter integração JavaScript própria.
• Stripe Checkout: hospedar a coleta de cartão na própria Stripe, redirecionar o comprador e capturar o PaymentMethod via webhook. Mais limitado em customização visual que o Toktus Checkout.
• Stripe Payment Links: gerar um link de pagamento pronto no painel da Stripe e enviar ao comprador. Útil para cobranças avulsas, sem necessidade de integração.
• Outros gateways: se o requisito é processamento puramente server-to-server com dados raw de cartão, use Pagar.me, Asaas ou PagSeguro, que oferecem essa modalidade.

A Toktus não consegue contornar a limitação de PCI imposta pela Stripe na chamada server-to-server da Secret Key. Mas, ao usar o Toktus Checkout, você nunca precisa lidar com tokenização diretamente — nós fazemos isso por você.

Métodos de pagamento suportados

Webhooks

A Stripe envia notificações HTTP POST assinadas. Configure o endpoint apontando para a Toktus:

1. Acesse Developers → Webhooks em dashboard.stripe.com/webhooks.
2. Clique em Add endpoint.
3. URL: https://api.toktus.com/webhooks/stripe/<seu-webhook-token> (o webhook-token está disponível em GET /v1/account).
4. Selecione os eventos que a Toktus normaliza:
   • payment_intent.succeeded
   • payment_intent.payment_failed
   • charge.refunded
   • customer.subscription.created
   • customer.subscription.updated
   • customer.subscription.deleted
   • invoice.payment_succeeded
   • invoice.payment_failed
5. Copie o Signing secret (whsec_...) que aparece após criar o endpoint e atualize sua credencial via POST /v1/credentials enviando o campo webhookSecret.

Sem o webhookSecret, a Toktus aceita os eventos mas não valida a assinatura. Em produção, configure sempre.

Cartões de teste

Use estes cartões no modo de área restrita (test mode). Qualquer CVV de 3 dígitos e qualquer data futura funcionam.

Lista completa de cenários: stripe.com/docs/testing.

Armadilhas comuns

Não confunda Publishable Key com Secret Key. A Publishable (pk_test_...) só funciona no frontend para tokenizar. Enviá-la no campo secretKey da Toktus resulta em erro 401 da Stripe.

Modo de teste vs produção é determinado pela chave. Se você cadastrou a credencial de teste mas espera processar cobranças reais, a Stripe rejeita. Atualize a credencial enviando a sk_live_....

Stripe Connect é split com destinatário único. Para dividir entre múltiplos recebedores em uma única transação, considere usar Pagar.me. Veja Coprodutores e splits.

Documentação oficial

• Quickstart Stripe Elements
• PaymentMethod API
• Webhooks
• Stripe Connect