Portal do cliente

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.

Á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:

Caso de uso	Caminho recomendado
Cliente quer acessar cobrança por conta própria	Link público da organização
Seu app já sabe quem é o cliente logado	Criar uma `customer_portal.session` pela API
Suporte quer enviar um link pontual para um cliente	Criar uma `customer_portal.session` e enviar a `url`
Cliente precisa trocar cartão de uma assinatura específica	Session com flow `payment_method_update`
Cliente quer cancelar uma assinatura	Session com flow `subscription_cancel`
Cliente precisa corrigir dados de cobrança	Home do portal ou flow `customer_update`

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.

Link público da organização

Cada organização já tem uma página pública exclusiva:

https://billing.chargefy.io/portal/login/{public_token}

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.

A organização compartilha o link

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

O cliente informa o e-mail

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

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.

O cliente abre a sessão curta

O código do e-mail é de uso único e expira em 1 hora. Depois de aberto com sucesso, o navegador mantém uma sessão curta do portal por até 1 hora.

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.

curl -X POST "https://api.chargefy.io/v1/customer-portal-sessions" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": "cus_DVmiFAewgoVzTWGu",
    "locale": "pt-BR",
    "return_url": "https://app.example.com/account"
  }'

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. Ela contém um authorization_code de uso único, válido por 1 hora. Após o primeiro acesso, a hosted page usa uma sessão curta no navegador por até 1 hora. Veja o contrato completo em Customer Portal Sessions.

Como funciona

Etapa	Origem	Resultado
1	Seu app ou o link público	Abre o portal hospedado.
2	Portal hospedado	Consulta ou altera `customer`, métodos de pagamento, assinaturas e faturas.
3	Cada objeto alterado	Emite o webhook correspondente para o seu backend.

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.

Recurso	Como aparece no portal
`customer`	Dados cadastrais e dados de cobrança.
`payment_method`	Métodos de pagamento salvos e troca de cartão.
`subscription`	Plano ativo, próxima cobrança e ações permitidas.
`invoice`	Histórico de faturas quando disponível para a sessão.

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”.

Flow	Para que serve	Campos
`customer_update`	Abrir direto na edição dos dados do cliente.	Não exige opções extras.
`payment_method_update`	Abrir direto na troca de método de pagamento.	`subscription` é opcional.
`subscription_cancel`	Abrir direto no cancelamento de uma assinatura.	`subscription` é obrigatório.

Todos os flows podem receber after_completion para redirecionar o cliente depois da conclusão. No V1, o tipo suportado é redirect.

curl -X POST "https://api.chargefy.io/v1/customer-portal-sessions" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": "cus_DVmiFAewgoVzTWGu",
    "flow_data": {
      "after_completion": {
        "redirect": {
          "return_url": "https://app.example.com/account/subscription"
        },
        "type": "redirect"
      },
      "subscription_cancel": {
        "subscription": "sub_ai6C2jrVwuXADkpJ"
      },
      "type": "subscription_cancel"
    },
    "return_url": "https://app.example.com/account"
  }'

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

Item	Duração	Observação
Link público da organização	Permanente	Pode ser desligado no dashboard. Não autentica o cliente sozinho.
Código enviado por e-mail	1 hora	Uso único. Criado pelo login público ou por uma session.
Sessão no navegador	1 hora	Criada após o primeiro acesso bem-sucedido.

Se o cliente tentar usar um link expirado, crie uma nova customer_portal.session ou peça para ele solicitar outro acesso pelo link público da organização.

Marca

O portal usa a marca da organização, configurada em Configurações → Marca: logo principal, cores, fonte, tema, cantos 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 Configurar sua página de checkout. 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

Copie o link público em Configurações da organização → Portal do cliente.
Para links gerados pelo seu backend, use Criar customer portal session.
Para entender o objeto retornado, veja Objeto customer_portal.session.

Pagamentos online

Receber pagamentos

Clientes e faturamento

Assinaturas

Operação e pós-pagamento

Marketing e rastreamento

Portal do cliente

Quando usar

Dois caminhos de acesso

Link público da organização

Customer portal sessions

Como funciona

Flows

Segurança e expiração

Marca

Próximos passos

​Quando usar

​Dois caminhos de acesso

​Link público da organização

​Customer portal sessions

​Como funciona

​Flows

​Segurança e expiração

​Marca

​Próximos passos

Quando usar

Dois caminhos de acesso

Link público da organização

Customer portal sessions

Como funciona

Flows

Segurança e expiração

Marca

Próximos passos