Pular para o conteúdo principal
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:
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 válido até expires_at ou a conclusão da solicitação.
string
Identificador da sessão do portal. Usa o prefixo cps_*.
string
Sempre "customer_portal.session".
string
Data de criação em ISO 8601.
string
Customer que está autorizado a abrir o portal.
string
Vencimento fixo do link, contado desde a emissão. Abrir ou reabrir não altera esse valor; a duração do acesso no navegador é controlada separadamente.
object | null
Fluxo inicial da página hospedada. null abre a home do portal.
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.
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 uma autorização temporária e não deve ser salvo como link permanente.

Flows comuns

Como processar

  1. Crie a sessão no seu servidor com POST /v1/customer-portal-sessions.
  2. Redirecione o cliente para url imediatamente.
  3. 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

Sem flow_data, o link vale 1 hora e exige confirmação pelo e-mail cadastrado. Com flow_data, vale 30 dias e autoriza somente a solicitação indicada, até sua conclusão. As regras são iguais para painel e API. Abrir não altera a data de vencimento. O acesso do navegador encerra após 1 hora sem atividade, limitado pelo vencimento do link. Uma solicitação pendente pode ser reaberta enquanto seu link estiver válido; uma concluída mostra a confirmação e não permite novas alterações.

Eventos

Referências