Sessões do portal do cliente

Uma customer_portal.session é uma autorização temporária para um customer abrir o portal hospedado da Chargefy. Ela não cria uma conta de login no seu produto e não substitui os objetos canônicos customer, subscription, invoice e payment_method. O portal é só a experiência hospedada onde o cliente final executa uma ação segura. O termo session significa que a Chargefy criou uma página hospedada com autorização embutida, escopo definido e expiração curta. Depois de criar a sessão no seu servidor, redirecione o cliente para a url, por exemplo:

https://billing.chargefy.io/portal/session/cps_h8x3WR14QtEcMxkrtfnMcW6e?authorization_code=...

Use esse objeto quando você quer permitir autoatendimento sem construir telas sensíveis no seu app: atualizar dados cadastrais, trocar cartão, abrir uma área de cobrança ou iniciar um fluxo de cancelamento de assinatura. As alterações feitas no portal atualizam os objetos reais e emitem os webhooks desses objetos.

Objeto customer_portal.session

Este é o formato completo retornado em create. A url inicial contém um authorization_code de uso único.

{
  "id": "cps_h8x3WR14QtEcMxkrtfnMcW6e",
  "object": "customer_portal.session",
  "configuration": null,
  "created_at": "2026-05-27T12:00:00Z",
  "customer": "cus_t9B7RSLrEUMQXsaV",
  "expires_at": "2026-05-27T13:00:00Z",
  "flow": {
    "after_completion": {
      "redirect": {
        "return_url": "https://meusite.com/account/subscription-canceled"
      },
      "type": "redirect"
    },
    "subscription_cancel": {
      "subscription": "sub_NyyDbxZv5oYXG5Gf"
    },
    "type": "subscription_cancel"
  },
  "livemode": true,
  "locale": "pt-BR",
  "metadata": {},
  "return_url": "https://meusite.com/account",
  "status": "created",
  "updated_at": "2026-05-27T12:05:00Z",
  "url": "https://billing.chargefy.io/portal/session/cps_h8x3WR14QtEcMxkrtfnMcW6e?authorization_code=..."
}

string

Identificador da sessão do portal. Usa o prefixo cps_*.

string

Sempre "customer_portal.session".

string | null

Reservado para configurações de portal futuras. No V1 retorna null.

string

Data de criação em ISO 8601.

string

Customer que está autorizado a abrir o portal.

string

Expiração da autorização. Antes do primeiro acesso, é o limite para abrir a URL inicial. Depois do primeiro acesso, passa a representar a expiração da sessão curta no navegador.

object | null

Fluxo inicial da página hospedada. null abre a home do portal.

Show Campos de flow

string

Fluxo inicial: customer_update, payment_method_update ou subscription_cancel.

object | null

Ação após concluir o fluxo. Hoje suporta redirect para uma URL do seu app.

object | null

Opções para troca de cartão. Pode apontar para uma subscription ou invoice específica.

object | null

Dados do fluxo de cancelamento. Inclui a subscription que será cancelada no fim do período.

boolean

true em produção; false em ambiente de teste.

string | null

Locale sugerido para a página hospedada, como pt-BR. null usa o padrão da experiência.

object

Objeto livre para correlacionar a sessão com o seu sistema. Quando vazio, retorna {}.

string | null

URL de volta para o seu app. Aparece na experiência hospedada quando aplicável.

string

Estado da sessão.

Valor	Descrição
`created`	Sessão criada; o link ainda não foi aberto.
`opened`	O cliente abriu o portal hospedado.
`completed`	O fluxo da sessão foi concluído.
`expired`	A sessão expirou.

string | null

Data da última atualização em ISO 8601.

string

URL hospedada da Chargefy. Redirecione o cliente para essa URL logo após criar a sessão. O link contém autorização de uso único e não deve ser salvo como link permanente.

Flows comuns

Flow	Quando usar	Resultado esperado
`customer_update`	Cliente precisa corrigir nome, email, telefone ou dados de cobrança.	O objeto `customer` é atualizado.
`payment_method_update`	Cliente quer trocar o cartão salvo ou atualizar o cartão de uma invoice aberta.	Um novo `payment_method` pode ser criado/anexado e vinculado ao customer, invoice ou subscription.
`subscription_cancel`	Cliente quer cancelar a assinatura no fim do período atual.	A `subscription` é atualizada com cancelamento agendado.

Como processar

Crie a sessão no seu servidor com POST /v1/customer-portal-sessions.
Redirecione o cliente para url imediatamente.
Depois da conclusão, use webhooks dos objetos alterados para atualizar seu sistema. O portal não emite um evento próprio no V1.

Expiração

O link inicial contém um authorization_code de uso único. Ele pode ser aberto pela primeira vez em até 1 hora quando criado via API, ou em até 7 dias quando criado pelo dashboard. Depois do primeiro acesso, o código é consumido e a página hospedada usa uma sessão curta no navegador por até 1 hora. Se o cliente precisar acessar novamente depois da expiração, crie uma nova customer_portal.session.

Eventos

Ação no portal	Webhook esperado
Atualizar dados do cliente	`customer.updated`
Atualizar cartão	`payment.method.created`, `payment.method.attached`
Vincular cartão a assinatura	`subscription.updated`
Cancelar assinatura no fim do período	`subscription.updated`

Referências

Criar customer portal session

Fundamentos da API

Objetos de sistema

Webhooks e eventos

SDKs

MCP

Sessões do portal do cliente

Objeto customer_portal.session

Flows comuns

Como processar

Expiração

Eventos

Referências

​Objeto customer_portal.session

​Flows comuns

​Como processar

​Expiração

​Eventos

​Referências

Objeto customer_portal.session

Flows comuns

Como processar

Expiração

Eventos

Referências