Skip to main content
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
Área logada do portal do cliente mostrando métodos de pagamento, dados de cobrança e histórico de faturas

​
Quando usar

O portal resolve tarefas recorrentes de pós-venda e billing:
Caso de usoCaminho recomendado
Cliente quer acessar cobrança por conta própriaLink público da organização
Seu app já sabe quem é o cliente logadoCriar uma customer_portal.session pela API
Suporte quer enviar um link pontual para um clienteCriar uma customer_portal.session e enviar a url
Cliente precisa trocar cartão de uma assinatura específicaSession com flow payment_method_update
Cliente quer cancelar uma assinaturaSession com flow subscription_cancel
Cliente precisa corrigir dados de cobrançaHome 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. Cada organização pode ter uma página pública exclusiva: 
https://billing.chargefy.io/portal/login/{public_token}
Esse link é permanente e pertence à organização. Ele é criado quando o portal é ativado pela primeira vez no dashboard e pode ser ligado ou desligado nas configurações da organização. 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.
1

A organização ativa o portal

A Chargefy gera uma URL pública única para aquela organização. O mesmo link continua sendo usado enquanto o portal estiver ativo.
2

O cliente informa o e-mail

A página pública usa o branding 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 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_123",
    "locale": "pt-BR",
    "return_url": "https://app.example.com/account"
  }'
A resposta retorna uma url hospedada. 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

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.
RecursoComo aparece no portal
customerDados cadastrais e dados de cobrança.
payment_methodMétodos de pagamento salvos e troca de cartão.
subscriptionPlano ativo, próxima cobrança e ações permitidas.
invoiceHistó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”.
FlowPara que serveCampos
customer_updateAbrir direto na edição dos dados do cliente.Não exige opções extras.
payment_method_updateAbrir direto na troca de método de pagamento.subscription é opcional.
subscription_cancelAbrir 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_123",
    "flow_data": {
      "after_completion": {
        "redirect": {
          "return_url": "https://app.example.com/account/subscription"
        },
        "type": "redirect"
      },
      "subscription_cancel": {
        "subscription": "sub_123"
      },
      "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

ItemDuraçãoObservação
Link público da organizaçãoPermanentePode ser desligado no dashboard. Não autentica o cliente sozinho.
Código enviado por e-mail1 horaUso único. Criado pelo login público ou por uma session.
Sessão no navegador1 horaCriada 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.

​
Branding

O portal usa a identidade visual da organização: logo, nome, cor de marca, cor de destaque, tema e formato de borda. A mesma configuração visual vale para a tela pública de login e para a área logada do portal. Isso permite que o cliente final reconheça a organização antes de interagir com dados sensíveis de cobrança.

​
Próximos passos