Skip to main content
Uma customer_portal.session é uma autorização temporária para um customer abrir o portal hospedado. Ela não cria login de cliente e não substitui os objetos canônicos customer, subscription e payment_method; ações feitas no portal atualizam esses recursos e emitem os webhooks correspondentes.

​
Objeto

CampoTipoObservação
idstringID da sessão (cps_*)
objectstringSempre "customer_portal.session"
configurationstring | nullReservado para configurações de portal futuras. No V1 retorna null.
created_atstringISO 8601
customerstringCustomer que abrirá o portal
expires_atstringISO 8601. Antes do primeiro acesso, a URL deve ser aberta antes desse horário. Depois do primeiro acesso, passa a refletir a expiração da sessão hosted curta.
flowobject | nullFluxo inicial da hosted page. null abre a home do portal.
livemodebooleantrue em produção; false em ambiente de teste
localestring | nullLocale sugerido para a hosted page
metadataobjectMetadata da sessão
return_urlstring | nullURL de volta para seu app
statusstringcreated, opened, completed ou expired
updated_atstring | nullISO 8601
urlstringURL hospedada que você redireciona o cliente para abrir
{
  "id": "cps_123",
  "object": "customer_portal.session",
  "configuration": null,
  "created_at": "2026-05-27T12:00:00Z",
  "customer": "cus_123",
  "expires_at": "2026-05-27T13:00:00Z",
  "flow": {
    "after_completion": {
      "redirect": {
        "return_url": "https://example.com/account/subscription-canceled"
      },
      "type": "redirect"
    },
    "subscription_cancel": {
      "subscription": "sub_123"
    },
    "type": "subscription_cancel"
  },
  "livemode": true,
  "locale": "pt-BR",
  "metadata": {},
  "return_url": "https://example.com/account",
  "status": "created",
  "updated_at": null,
  "url": "https://billing.chargefy.io/portal/session/cps_123?authorization_code=..."
}

​
Flows

flow é opcional. Quando enviado, a hosted page abre direto no fluxo indicado.
TipoUso
customer_updateCliente atualiza nome, email, telefone ou dados de cobrança.
payment_method_updateCliente troca o cartão salvo. Opcionalmente recebe subscription e/ou invoice para atualizar o padrão desses objetos.
subscription_cancelCliente agenda cancelamento no fim do período. Exige uma subscription.

​
Expiração

O link inicial contém um authorization_code de uso único. Esse link pode ser aberto pela primeira vez em até 1 hora depois da criação da sessão. Quando o cliente abre o link com sucesso, o código é consumido e não pode ser reutilizado. Depois disso, a hosted page usa uma sessão curta no navegador por até 1 hora. Se o cliente precisar acessar o portal depois da expiração, crie uma nova customer_portal.session.

​
Webhooks

O portal não emite evento próprio no V1. Acompanhe os objetos alterados:
Ação no portalWebhook
Atualizar dados do clientecustomer.updated
Atualizar cartãopayment.method.created, payment.method.attached, subscription.updated quando vinculado a uma assinatura
Cancelar assinatura no fim do períodosubscription.updated

​
Referências