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

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.

O cliente informa o e-mail

A página pública usa o branding 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. 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.

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

Ative 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

Integrações avançadas

Payment Intents e cobranças

Formas de pagamento

Customers

Faturas

Assinaturas

Operação financeira

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

Branding

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

​Branding

​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

Branding

Próximos passos