Tema
Extensão Stripe
Com a extensão Stripe conectada, o Columba cobra dentro da conversa: as automações e a sua equipe (pelo botão Cobrar do Chat) criam o link de pagamento (Pix, cartão ou boleto) ou a fatura com vencimento na sua conta Stripe, mandam o link pelo WhatsApp, conferem se foi pago e reagem sozinhas quando o pagamento entra, falha ou vence. A cobrança deixa de ser uma tarefa à parte e vira um passo do atendimento, junto com a IA, o funil, os tickets e o histórico do contato.
O dinheiro continua indo direto para a sua conta Stripe. O Columba só pede ao Stripe que crie e consulte as cobranças e recebe os avisos dele.
Para que serve
| Situação | Como a extensão resolve |
|---|---|
| Fechar a venda com o link na conversa | A IA qualifica o pedido, o fluxo cria a cobrança e manda o link de pagamento no WhatsApp na hora, sem o vendedor sair da conversa para gerar um link. |
| Cobrar o valor combinado, na hora | O atendente negociou o valor com o cliente: clica em Cobrar no cabeçalho da conversa, informa valor e descrição e o cliente recebe o link. O card da cobrança mostra quando foi pago. Veja Cobrar pela conversa. |
| Confirmação automática | Quando o pagamento é confirmado, o fluxo agradece o cliente, move o negócio para Ganho e etiqueta o contato. Ninguém precisa olhar o extrato. |
| Sinal de reserva com expiração | O link do sinal expira em, por exemplo, 2 horas. Pagou, a reserva é confirmada; expirou, a data é liberada e a equipe é avisada. |
| Mensalidade e inadimplência | Fatura vencida inicia um fluxo que lembra o cliente com a 2ª via e, se ele não pagar, transfere para o financeiro. |
| 2ª via sem humano | O cliente escreve "me manda o boleto" e o fluxo consulta as cobranças dele e responde com o link certo. |
| Cartão recusado na renovação | A renovação da assinatura falhou: o cliente recebe no WhatsApp o aviso com o link para pagar com outro cartão, antes de a assinatura cair. |
Antes de começar
- Plano do Columba: Profissional ou superior (veja Planos e limites).
- Conta Stripe ativa: para cobrar de verdade, a conta precisa estar ativada no Stripe (dados da empresa e conta bancária preenchidos). Para testar, o modo de teste basta e não exige ativação.
- Um usuário do Stripe que crie chaves: só usuários com a função Administrador ou Desenvolvedor no Stripe criam chaves de API.
- Métodos de pagamento ligados no Stripe:
- Cartão é liberado para todas as contas.
- Boleto é aberto a qualquer conta no Brasil: basta ligá-lo em Configurações › Pagamentos › Métodos de pagamento no Stripe.
- Pix, para empresas no Brasil, é liberado pelo Stripe por convite. Para pedir: no Dashboard do Stripe, abra Configurações › Pagamentos › Métodos de pagamento e procure o Pix. Se aparecer a opção de solicitar acesso, use-a; se não aparecer, peça a ativação do Pix ao suporte do Stripe (support.stripe.com). Quem decide a liberação é o Stripe, não o Columba. Enquanto isso, cartão e boleto funcionam normalmente.
O Columba mostra o que está ativo
Ao conectar, a página da extensão mostra quais métodos a sua conta tem ativos (cartão, Pix e boleto). Se o Pix não estiver ativo, aparece o aviso para pedir a ativação.
Criar a chave restrita no Stripe
O Columba se conecta com uma chave restrita: uma chave que só alcança o que a extensão precisa. Ela é criada em 1 minuto no Dashboard do Stripe.
- Entre no Dashboard do Stripe com um usuário Administrador ou Desenvolvedor.
- Escolha o modo: para testar, ligue o modo de teste (ou entre numa sandbox); para cobrar de verdade, deixe o modo de teste desligado. A chave vale só para o modo em que foi criada (veja Modo de teste e produção).
- Abra Developers › API keys (no Dashboard em português, Desenvolvedores › Chaves de API).
- Clique em Create restricted key (Criar chave restrita). O Stripe pergunta como a chave será usada: escolha Building your own integration (Criando a minha própria integração). Não escolha "Providing this key to another website": nesse caminho o Stripe monta as permissões sozinho para o site informado e elas não batem com as da tabela abaixo. Se já escolheu essa opção, marque Customize permissions for this key antes de continuar.
- Dê um nome que identifique o uso, por exemplo
Columba. - Ajuste as permissões exatamente como na tabela abaixo. Todo o resto fica em None (Nenhum).
- Clique em Create key e copie a chave inteira (
rk_live_…ourk_test_…). Copie assim que ela aparecer: no modo de produção, o Stripe pode não deixar revelá-la de novo.
| Recurso no Stripe | Permissão | Para que o Columba usa |
|---|---|---|
| Customers | Write | Localizar e criar o cliente do contato (Cliente no Stripe, Cobrança no Stripe e o botão Cobrar da conversa). |
| Payment Links | Write | Criar os links de pagamento (URL curta buy.stripe.com/…), desativar os vencidos e os cancelados pela conversa. |
| Checkout Sessions | Write | Conferir se um link foi pago e consultar as cobranças do cliente. |
| Invoices | Write | Criar, finalizar e enviar faturas; consultar as faturas do cliente; anular as faturas canceladas pela conversa. |
| Products | Read | Mostrar os seus produtos nos selects do editor. |
| Prices | Read | Mostrar os seus preços e cobrar por um preço do catálogo. |
| Subscriptions | Read | Consultar a assinatura do cliente e ler os eventos de assinatura. |
| Webhook Endpoints | Write | Criar, atualizar e remover o webhook Columba, que faz o gatilho Pagamento no Stripe funcionar. |
| Accounts (grupo Connect) | Read | Opcional: ler o nome, o país e a moeda da conta para mostrar na página da extensão. Sem ela a extensão funciona igual; a página mostra "Conta: faltando" e os dados da conta ficam em branco. |
Write inclui a leitura. No Dashboard em português, os nomes dos recursos e das permissões aparecem traduzidos; o recurso é o mesmo.
Esqueceu uma permissão? Não precisa criar outra chave: no Stripe, abra a chave restrita, edite as permissões e, no Columba, clique em Testar conexão.
Modo de teste e produção
| Chave | Modo | O que acontece |
|---|---|---|
rk_test_… | Teste | Nada é cobrado de verdade (cartão de teste, Pix e boleto simulados). A página da extensão mostra o selo Modo de teste e os nós gravam {{flow.stripe_livemode}} = false. |
rk_live_… | Produção | Cobranças reais. A página mostra o selo Produção e {{flow.stripe_livemode}} = true. |
Clientes, cobranças e eventos do modo de teste nunca se misturam com os de produção: cada chave conecta um modo da conta. Comece pelo modo de teste, valide os fluxos e, quando estiver pronto, desconecte e conecte de novo com a chave de produção.
Por que chave restrita (e não a chave secreta)
A chave secreta (sk_live_… / sk_test_…) faz tudo na sua conta Stripe: reembolsos, transferências, apagar clientes, mudar configurações. A chave restrita só faz o que está na tabela acima. Se um dia ela vazar, o estrago é limitado, e você pode revogá-la sem afetar os outros sistemas que usam o Stripe.
Se você colar a chave secreta, o Columba aceita, com um aviso fixo na página ("prefira uma chave restrita"). A extensão funciona igual, mas recomendamos trocar por uma chave restrita assim que possível. A chave publicável (pk_…) não serve e é recusada.
Conectar
- No Columba, abra Configuração › Extensões e clique no card Stripe.
- Cole a chave restrita no campo da chave e clique em Conectar.
- O Columba valida a chave no Stripe e mostra a conta conectada: nome, país, moeda, o selo Modo de teste ou Produção, os métodos de pagamento ativos e as permissões conferidas (ok ou faltando).
Se a chave for recusada, a tela diz o motivo. Os mais comuns: chave copiada pela metade, chave publicável (pk_) no lugar da restrita e chave revogada no Stripe.
O que acontece ao conectar
- A chave vai para um cofre de segredos e não é exibida de novo.
- O Columba confere, uma a uma, as permissões da chave, só com leituras: nada é criado na sua conta Stripe para testar. Se faltar uma permissão de escrita, você descobre na primeira execução do nó, que sai pela saída Erro com o motivo
permission_missing. - O Columba baixa o catálogo da sua conta: produtos e preços ativos na moeda da conta. É ele que aparece no select Preço do catálogo do nó Cobrança no Stripe.
- Um webhook chamado Columba é criado na sua conta Stripe (Developers › Webhooks; no Workbench do Stripe, aba Webhooks), assinando os eventos das notificações ligadas. É ele que faz o gatilho Pagamento no Stripe funcionar e que atualiza o card das cobranças feitas pela conversa. Não edite nem apague esse webhook por lá; ao desconectar, o Columba o remove.
- Os nós do grupo Stripe passam a aparecer na barra lateral do Flow Builder, e o grupo Gatilhos ganha Pagamento no Stripe.
- O botão Cobrar aparece no cabeçalho das conversas, para quem tem a permissão (veja Cobrar pela conversa), a ficha do contato ganha a seção Cobranças e os Relatórios ganham a aba Cobranças.
Se o catálogo ou o webhook falharem (por exemplo, sem a permissão Webhook Endpoints), a extensão fica conectada mesmo assim: os nós funcionam, só o gatilho não. O card mostra o que faltou, com um botão para tentar de novo.
Padrões das cobranças
No card Padrões das cobranças, você define o que o nó Cobrança no Stripe e o botão Cobrar da conversa usam quando o campo correspondente fica vazio:
| Configuração | Para que serve |
|---|---|
| Moeda | Moeda das cobranças por valor avulso. Padrão: a moeda da sua conta Stripe (normalmente real, BRL). Cobranças por preço do catálogo usam a moeda do preço. |
| Métodos de pagamento | Automático (padrão): o Stripe oferece na página de pagamento o que a sua conta tem ativo (Pix, cartão, boleto) e nunca falha por isso. Fixos: marque Pix, Cartão e/ou Boleto; se um método marcado não estiver ativo na conta, o nó sai pela saída Erro com o motivo payment_method_unavailable. |
| Expiração do link | Quanto tempo o link de pagamento fica válido: de 30 a 1440 minutos. Padrão: 1440 (24 horas). O código Pix da página acompanha essa expiração. |
| Vencimento da fatura | Dias até o vencimento das faturas criadas pelo nó. Padrão: 3 dias. |
| Nome do cliente criado | Como fica o nome dos clientes criados no Stripe pelos nós: Nome do contato ou Nome + 4 últimos dígitos do telefone ("Adriana 5451"), útil para diferenciar homônimos. |
| Texto após o pagamento | Mensagem mostrada ao cliente depois que ele paga (por exemplo, "Obrigado! Já avisamos a equipe pelo WhatsApp."). |
| Página após o pagamento | Para onde o Stripe leva o cliente depois de pagar pelo link (o Stripe exige uma página). Vazio = a página "Pagamento recebido" do Columba, que orienta a voltar ao WhatsApp. Pode ser uma página do seu site. |
O que for preenchido no nó (ou no modal do botão Cobrar) vale mais que o padrão. As alterações valem a partir da próxima execução dos fluxos e da próxima cobrança pela conversa.
Cobrar pela conversa
Além dos fluxos, a equipe cobra direto do Chat: o botão Cobrar, no cabeçalho da conversa (no celular, no menu ⋯), abre um modal com tipo (link de pagamento ou fatura com vencimento), valor, descrição, meios de pagamento, validade ou vencimento e a mensagem, com a prévia do que o cliente vai receber. Ao confirmar, o Columba:
- cria a cobrança na sua conta Stripe, com a mesma regra do nó Cobrança no Stripe;
- manda a mensagem com o link curto na conversa;
- deixa na linha do tempo um card de cobrança com a situação e as ações Copiar link, Reenviar, Cancelar e Atualizar.
Quando o cliente paga, o webhook Columba atualiza o card em tempo real (Aguardando → Pago em dd/mm), atualiza a seção Cobranças da ficha do contato e deixa uma nota interna "Pagamento confirmado" que só a equipe vê. Cancelar desativa o link (ou anula a fatura) no Stripe; cobrança já paga não se cancela por ali, e o reembolso continua sendo feito no painel do Stripe.
As cobranças feitas pelo botão também disparam o gatilho Pagamento no Stripe, como as dos nós, e entram na aba Cobranças dos Relatórios.
- Quem pode: só quem tem a permissão Chat › Cobrar pela conversa. Administrador, Gerente e Operador já têm; funções personalizadas precisam marcar. Veja Funções e permissões.
- Onde não aparece: sem a extensão conectada e em grupos de WhatsApp.
O passo a passo, os campos do modal e as variáveis da mensagem estão em Cobrar pela conversa.
Links curtos
Toda URL de pagamento que os fluxos mandam na conversa (link de pagamento, fatura e PDF) sai como um link curto com a marca do Columba: https://pay.columba.com.br/p/Ab3k9Qz (36 caracteres, contra mais de 400 do Checkout do Stripe). Ao abrir, o cliente é levado para a página do Stripe sem perceber a troca. O link curto respeita a validade da cobrança: vencido, mostra "Link expirado" em vez de abrir a página; um código inexistente mostra "Link inválido". O Columba conta quantas vezes cada link foi aberto. A URL original do Stripe continua disponível nos fluxos em {{flow.stripe_payment_url_long}}.
Notificações
No card Notificações, você escolhe quais avisos do Stripe a sua conta recebe. Cada grupo ligado vira um conjunto de eventos assinados no webhook Columba; mudar um grupo atualiza o webhook no Stripe na hora.
| Grupo | Eventos do Stripe | Quando acontece |
|---|---|---|
| Pagamento confirmado | checkout.session.completed (quando já pago), checkout.session.async_payment_succeeded, invoice.paid | O cliente pagou o link (cartão ou Pix na hora; boleto ou Pix compensados depois) ou a fatura. |
| Cobrança falhou ou expirou | checkout.session.async_payment_failed, checkout.session.expired, invoice.payment_failed | O pagamento assíncrono (boleto) não se confirmou, o link expirou sem pagamento ou a cobrança da fatura falhou, como o cartão recusado na renovação de uma assinatura. |
| Fatura venceu | invoice.overdue | A fatura passou do vencimento sem pagamento, conforme as configurações de cobrança da sua conta Stripe. |
| Renovação próxima | invoice.upcoming | Faltam alguns dias para uma assinatura renovar. A antecedência é configurada no próprio Stripe, nas configurações de assinaturas. |
| Assinatura mudou | customer.subscription.* (criada, atualizada, cancelada, pausada, retomada) | Qualquer mudança de estado de uma assinatura. |
| Reembolso ou disputa | charge.refunded, charge.dispute.created | Um pagamento foi reembolsado ou o cliente abriu uma contestação no cartão. |
Ao conectar, ficam ligados Pagamento confirmado, Cobrança falhou ou expirou e Fatura venceu.
Notificação não manda mensagem sozinha
Ligar um grupo só faz o evento chegar ao Columba. Quem decide o que fazer (mandar mensagem, mover o negócio, abrir chamado) é o fluxo com o gatilho Pagamento no Stripe. Grupo desligado = o gatilho nunca dispara para aqueles eventos.
No mesmo card:
- Número padrão do WhatsApp: por qual número a conversa nasce quando o gatilho do fluxo não escolhe um. Vazio = o primeiro número conectado.
- Criar contato desconhecido: quando o evento vem de um cliente do Stripe que ainda não é contato no Columba, cria o contato pelo telefone dele. Desligado, o evento só roda para contatos já cadastrados. O gatilho de cada fluxo pode mudar esse padrão.
Testar e atualizar o catálogo
- Testar conexão confere a chave, as permissões e o webhook agora e atualiza a situação da extensão. Se o webhook tiver sumido ou estiver desabilitado no Stripe, ele é recriado.
- Atualizar catálogo baixa de novo os produtos e preços ativos. Use depois de criar um produto ou um preço no Stripe, para ele aparecer no select do editor.
A página mostra também o webhook (endereço, situação no Stripe, eventos assinados e o último recebimento) e o uso (chamadas ao Stripe no mês).
Verificação diária
Independentemente dos botões, o Columba confere a conexão uma vez por dia: testa a chave e, se o Stripe tiver apagado ou desabilitado o webhook, cria outro. Se a chave passar a ser recusada (revogada ou expirada), a extensão fica Com erro e chega um aviso no sino.
Desconectar
Em Configuração › Extensões › Stripe, clique em Desconectar e confirme. O Columba remove o webhook Columba da sua conta Stripe, apaga a chave do cofre e limpa as configurações e o catálogo. Nada mais é apagado no Stripe: clientes, cobranças, faturas e pagamentos continuam lá.
Os fluxos que usam nós do Stripe continuam existindo, mas cada execução sai pela saída Erro desses nós até uma nova conexão, e o gatilho Pagamento no Stripe deixa de disparar. Os vínculos entre contatos do Columba e clientes do Stripe são mantidos e voltam a valer quando você reconectar a mesma conta.
Revogue a chave no Stripe
Desconectar apaga a chave no Columba, mas não a revoga no Stripe. Se não for mais usá-la, apague a chave restrita em Developers › API keys.
Segurança
- A chave nunca é exibida de novo, nem na tela nem em exportações de fluxo. Ela fica num cofre de segredos separado do banco de dados.
- Contas separadas: a sua assinatura do Columba é cobrada por outra conta Stripe, da AtivoCode. Nada da sua conta Stripe é usado para isso, e a extensão não consulta o seu saldo nem faz saques.
- Sem ações destrutivas nos fluxos: os nós criam e consultam cobranças. Reembolsar, cancelar assinatura e alterar preços não são feitos por automação.
- Pela conversa, só o que está em aberto: o botão Cobrar cria, reenvia e cancela cobranças em aberto (cancelar desativa o link ou anula a fatura). Cobrança paga não é cancelada pelo Columba: reembolso, só no painel do Stripe.
- Sem cobrança em dobro: toda criação leva uma chave de idempotência. Se o motor repetir um passo (uma falha de rede, por exemplo), o Stripe devolve a mesma cobrança em vez de criar outra. No botão Cobrar, cada confirmação é uma cobrança: se a tela repetir o mesmo envio (uma queda de conexão, por exemplo), o Stripe devolve a cobrança já criada.
- Eventos conferidos: cada aviso do Stripe chega assinado com um segredo exclusivo do seu webhook; aviso sem assinatura válida é recusado.
- Conectar, testar, alterar padrões e notificações e desconectar exige a permissão Configurações › Editar e fica registrado na auditoria da conta (ações
extension.*). - Cobrar pela conversa exige a permissão Chat › Cobrar pela conversa (além de enviar mensagens no Chat). Administrador, Gerente e Operador já têm; funções personalizadas nascem sem ela. Criar, reenviar e cancelar ficam na auditoria (
extension.stripe.charge.created,extension.stripe.charge.resenteextension.stripe.charge.canceled).
Limites e custos
- Taxas: as taxas de Pix, cartão e boleto são as do seu contrato com o Stripe e saem da sua conta Stripe. O Columba não cobra por chamada nem por cobrança criada.
- Valor mínimo: R$ 0,50 por cobrança (regra do Stripe). Valor abaixo disso faz o nó sair por Erro com
invalid_amount. - Expiração do link: de 30 minutos a 24 horas. Para uma cobrança com prazo maior, use a fatura com vencimento.
- Catálogo: até 200 produtos e 200 preços ativos aparecem no editor. Além disso, cobre por valor avulso.
- Cota de API: o Stripe limita requisições por segundo, bem acima do que um fluxo de atendimento consome. O card da extensão mostra as chamadas do mês.
Problemas comuns
| Sintoma | O que está acontecendo | O que fazer |
|---|---|---|
| A chave é recusada ao conectar | Chave copiada pela metade, chave publicável (pk_) ou chave revogada no Stripe | Copie a chave restrita de novo, inteira, em Developers › API keys. Se precisar, crie outra. |
A seção da conta mostra uma permissão faltando, ou os nós saem pela saída Erro com permission_missing em {{flow.stripe_error_code}} | A chave restrita não tem a permissão que aquele nó usa | No Stripe, edite a chave e ajuste a permissão conforme a tabela. Depois clique em Testar conexão. |
O Pix não aparece na página de pagamento, ou o nó sai por Erro com payment_method_unavailable | O Pix não está ativo na sua conta Stripe (no Brasil, é liberado por convite) | Peça a ativação ao Stripe (veja Antes de começar). Enquanto isso, deixe os métodos em Automático: o cliente vê cartão e boleto e o nó não falha. |
| O botão Cobrar não aparece na conversa | Falta a permissão Chat › Cobrar pela conversa, a extensão não está conectada ou a conversa é de um grupo de WhatsApp | Peça ao administrador para marcar a permissão na sua função, em Funções e permissões. Em grupos, o botão não existe. |
| Ao cobrar por fatura, aparece "Fatura exige o e-mail do cliente" | O Stripe só cria fatura com vencimento para cliente com e-mail | Informe o e-mail no campo E-mail do cliente do modal (ele fica salvo no contato) ou cobre por Link de pagamento, que não exige e-mail. |
| O cliente pagou e o card da conversa continua Aguardando | Boleto aguardando a compensação bancária, ou o aviso do Stripe não chegou (grupo Pagamento confirmado desligado em Notificações, webhook desabilitado) | Clique em Atualizar no card para conferir no Stripe na hora. Confira as Notificações e clique em Testar conexão. |
| O gatilho Pagamento no Stripe parou de disparar | O Stripe desabilita webhooks depois de muitas entregas falhas, ou o webhook Columba foi apagado | A verificação diária recria o webhook. Para não esperar, clique em Testar conexão. Confira também se o grupo do evento está ligado em Notificações e se o gatilho não está com Só cobranças criadas pelo Columba ligado para uma cobrança feita fora do Columba. |
| O fluxo repetiu um passo (falha de rede, reinício) e você quer saber se cobrou duas vezes | Toda retentativa do motor usa a mesma chave de idempotência | Não cobrou: o Stripe devolve a mesma cobrança. E, com Reaproveitar a aberta no nó, uma cobrança aberta igual para o mesmo contato é reaproveitada até numa execução nova. |
| Um evento de teste do Dashboard (Send test event) não iniciou o fluxo | O evento de teste não vem de uma cobrança do Columba nem de um cliente com telefone | Teste com cobranças criadas pelos próprios nós, com a chave rk_test_: pague com o cartão de teste 4242 4242 4242 4242 ou simule o Pix e o boleto de teste. |
| Os eventos de produção não chegam (ou só chegam os de teste) | A extensão está conectada com a chave do outro modo; cada chave recebe só os eventos do próprio modo | Confira o selo Modo de teste / Produção na página. Para trocar, desconecte e conecte com a chave do modo certo. |
| O evento chegou, mas o fluxo não rodou | O cliente do Stripe não tem telefone e não está vinculado a nenhum contato | O motivo fica no painel do gatilho ("último evento"). Cadastre o telefone do cliente no Stripe ou crie a cobrança pelo nó, que já grava o vínculo. |
Leia também
- Stripe nas automações: os nós e o gatilho, passo a passo, com exemplos de fluxo
- Cobrar pela conversa: o botão Cobrar do Chat, o card e o que acontece quando o cliente paga
- Relatórios — aba Cobranças: quanto foi cobrado, recebido e está em aberto
- Visão geral das Extensões
- Funil de vendas do Columba: para mover o negócio quando o pagamento entra