Pular para o conteúdo principal
O Portal do cliente é uma superfície hospedada da Chargefy onde o seu cliente final acessa dados de cobrança sem entrar no seu dashboard. Ele pode consultar informações de cobrança, atualizar dados cadastrais, gerenciar métodos de pagamento e executar ações permitidas em assinaturas. Use o portal quando você quer reduzir suporte operacional sem construir uma área financeira própria: segunda via de faturas, troca de cartão, atualização de dados de cobrança, cancelamento guiado ou acesso autenticado por e-mail.
Página de login do portal do cliente com sidebar de marca da organização e formulário de email

Página pública de login com a identidade visual da organização.

Área logada do portal do cliente mostrando métodos de pagamento, dados de cobrança e histórico de faturas

Área logada do portal com métodos de pagamento, informações de cobrança e histórico de faturas.

Quando usar

O portal resolve tarefas recorrentes de pós-venda e billing:
O portal não substitui webhooks nem a sua fonte interna de autorização. Ele é a experiência hospedada para o cliente executar ações; o seu backend continua acompanhando mudanças pelos objetos canônicos e pelos webhooks correspondentes.

Dois caminhos de acesso

Existem dois jeitos de abrir o portal. Eles atendem momentos diferentes do produto. Cada organização já tem uma página pública exclusiva:
Esse link é permanente, criado automaticamente e já vem ativo para cada organização, com endereços separados para produção e teste. Ele pode ser desativado e reativado nas configurações da organização, mantendo o mesmo endereço. Com um domínio próprio pronto e ativo, o link usa o seu endereço no lugar de billing.chargefy.io; o public_token é o mesmo. O link público não autentica o cliente sozinho. Ele só abre a tela de login. O cliente informa o e-mail cadastrado, recebe um link por e-mail e entra no portal. Desativar o link público impede novas solicitações de acesso por essa página; sessões individuais já emitidas e links gerados pelo dashboard ou pela API continuam funcionando.
1

A organização compartilha o link

O link já está disponível em Configurações → Assinaturas e faturamento → Portal do cliente. Copie o endereço e compartilhe com seus clientes.
2

O cliente informa o e-mail

A página pública usa a marca da organização e pede o e-mail do cliente.
3

A Chargefy envia um link de acesso

Se o e-mail existir para um customer ativo da organização, o cliente recebe um link com código de autorização.
4

O cliente abre a sessão curta

O link do e-mail expira 1 hora depois da emissão. Abrir não altera o prazo. O navegador encerra o acesso após 1 hora sem atividade, limitado pelo vencimento do link.
Use esse caminho quando o cliente precisa de um ponto de entrada simples e self-service, por exemplo um link em e-mails de cobrança, central de ajuda ou área “Financeiro” do seu produto.

Customer portal sessions

Uma customer_portal.session é uma URL temporária criada pelo seu backend para um customer específico. Ela é ideal quando o seu sistema já autenticou o usuário e sabe qual customer deve abrir o portal.
A resposta retorna uma url hospedada — no seu domínio próprio, quando ele está pronto e ativo. Redirecione o cliente para essa URL ou envie por e-mail quando fizer sentido. Sem flow_data, o link vale 1 hora e exige confirmação pelo e-mail cadastrado. Para uma solicitação específica, como troca de cartão, o link vale 30 dias, até a conclusão. Abrir não muda o prazo. Veja o contrato completo em Customer Portal Sessions.

Como funciona

O portal lê e altera recursos que já existem na API: customer, payment_method, subscription e invoice. Ele não cria um novo objeto de “conta do cliente” separado.

Flows

flow_data permite abrir a sessão direto em uma tarefa específica, em vez de mostrar a home do portal. Isso é útil para links contextuais: “trocar cartão”, “corrigir dados” ou “cancelar assinatura”. Todos os flows podem receber after_completion para redirecionar o cliente depois da conclusão. No V1, o tipo suportado é redirect.
Um flow define a tela inicial e as opções daquela sessão. Ele não muda a regra de negócio sozinho: a Chargefy valida se o customer, a assinatura e o modo (test/live) pertencem ao escopo da API key antes de criar a sessão.

Segurança e expiração

Por exemplo: Maria recebe um link para trocar o cartão na segunda-feira, confere a página e volta na terça-feira. Ela continua dentro dos 30 dias; a primeira visita não encurta esse prazo. Depois de salvar o cartão, o mesmo link mostra a confirmação da conclusão. Se o link expirou, crie outra customer_portal.session ou peça para o cliente solicitar outro acesso pelo link público da organização.

Marca

O portal usa a marca da organização, configurada em Configurações → Branding: logo principal, aparência (cores, estilo, fontes e tema) e marca do rodapé. A mesma marca veste o checkout e a fatura hospedada, e vale para a tela pública de login e para a área logada do portal. Com um domínio próprio pronto e ativo, o portal abre no seu endereço. Veja Marca e aparência. Isso permite que o cliente final reconheça a organização antes de interagir com dados sensíveis de cobrança.
Esta observação só se aplica a contas com o produto Chargefy for Platforms. Uma sessão do portal criada com a API key da plataforma para uma organização filha pode ser apresentada com a marca e o domínio da plataforma, conforme a escolha dela. Veja Marca e domínio próprio da plataforma.

Próximos passos