Stripe

Uma configuração de Stripe precisa de duas coisas da sua conta Stripe: a secret key da API, que o broker usa para criar checkouts e clientes, e um webhook, pelo qual a Stripe avisa o broker de cada pagamento. Sem o webhook, nenhum pagamento é confirmado.

1. Secret key da API

1No Stripe, abra Developers → API keys. Use o modo de teste (Test mode) para uma configuração sandbox e o modo live para produção.
2Copie a Secret key: sk_test_… no teste, sk_live_… em produção. A Publishable key (pk_…) não é usada.
3Em Gateways → Adicionar gateway → Stripe, cole no campo Secret key da API e salve.

A secret key da API não tem relação com webhook: ela autentica as chamadas do broker à Stripe. O segredo do webhook (whsec_…) é outro, e vem no passo 3.

2. Webhook na Stripe

1Depois de salvar, a página do gateway ganha o bloco Webhook: copie a Webhook URL de lá. Ela leva o id desta configuração, então só existe depois de salvar.
2No Stripe, abra Developers → Webhooks → Add destination (ou Add endpoint) e escolha eventos da sua própria conta (Your account).
3Cole a Webhook URL como endpoint e marque os eventos abaixo. A versão da API pode ser qualquer uma: o broker lê os formatos antigo e novo.
4Testando local (localhost)? A Stripe só entrega em URLs públicas. Rode stripe listen --forward-to <Webhook URL> com o Stripe CLI e use o whsec_ que ele mostra no passo 3.

Eventos que você marca

Marque exatamente estes. Um evento a mais é ignorado; um a menos deixa pagamentos ou renovações sem confirmação.

Eventos

checkout.session.completed
checkout.session.async_payment_succeeded
checkout.session.async_payment_failed
checkout.session.expired
payment_intent.succeeded
charge.succeeded
charge.updated
charge.refunded
customer.subscription.created
customer.subscription.updated
customer.subscription.deleted
invoice.paid
invoice_payment.paid
payment_intent.payment_failed
charge.failed
charge.dispute.created
charge.dispute.updated
charge.dispute.closed

checkout.session.completedO cliente terminou o checkout: confirma o pagamento com cartão e ativa a subscription.

checkout.session.async_payment_succeededUm método que liquida depois (boleto, débito) foi pago.

checkout.session.async_payment_failedEsse pagamento posterior falhou.

checkout.session.expiredO checkout expirou sem pagamento.

payment_intent.succeededO pagamento foi capturado.

charge.succeededA cobrança foi aprovada.

charge.updatedA Stripe informou a transação de saldo depois: é daqui que sai a taxa.

charge.refundedA cobrança foi reembolsada.

customer.subscription.createdA subscription nasceu na Stripe.

customer.subscription.updatedStatus, período, cancelamento agendado ou past_due mudaram.

customer.subscription.deletedA subscription terminou.

invoice.paidUm ciclo da subscription foi pago: vira uma renovação no extrato.

invoice_payment.paidLiga o pagamento à fatura nas contas com a API 2025-03-31 ou mais nova.

payment_intent.payment_failedUma tentativa foi recusada (saldo, cartão vencido…): o motivo aparece na página de pagamento; o cliente ainda pode tentar outro cartão.

charge.failedA cobrança falhou: completa o motivo da recusa com o código do banco.

charge.dispute.createdO banco do cliente abriu um chargeback: o pagamento mostra a disputa e o app recebe session.disputed.

charge.dispute.updatedA disputa andou (provas enviadas, em análise): o status dela no pagamento acompanha.

charge.dispute.closedO banco decidiu a disputa, ganha ou perdida: o app recebe session.dispute_closed.

3. Webhook secret

1Ao criar o endpoint, a Stripe mostra um Signing secret (whsec_…). Clique em Reveal e copie.
2No broker, no bloco Webhook do gateway, cole em Webhook secret e clique em Salvar webhook.
3Com ele o broker confere a assinatura Stripe-Signature de cada evento; um evento com assinatura errada é recusado.

Qual segredo vai onde

sk_test_… / sk_live_…Secret key da API da Stripe. Vai no gateway, em Secret key da API.

whsec_…O Signing secret da Stripe. Vai no gateway, em Webhook secret.

pk_test_… / pk_live_…Publishable key da Stripe. Não é usada: o checkout é hospedado pela Stripe.

pwhsec_…O segredo que o broker usa para assinar os webhooks que ele envia ao seu app. Fica no seu app (PAY_WEBHOOK_SECRET), nunca no gateway.

4. Teste

1Com o gateway em Sandbox e as chaves de teste, use Teste de conexão → Rodar um pagamento sandbox na página do gateway: ele cria um pagamento real de teste e mostra os eventos que chegaram.
2Se o teste não passar de processing, o webhook não está chegando: confira a URL, os eventos e o webhook secret.
3Em Webhooks → Recebidos, cada evento da Stripe aparece com o resultado do processamento.

Próximos: Quick start · Apps e roteamento · Outbound events