Criar uma sessão do portal do cliente

curl -X POST "https://api.chargefy.io/v1/customer-portal-sessions" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": "cus_64Aj89yABDYvyHHx"
  }'

{
  "id": "cps_PCaNjJY7XoXvtoVyJN4qhBoh",
  "object": "customer_portal.session",
  "configuration": null,
  "created_at": "2026-05-27T12:00:00Z",
  "customer": "cus_64Aj89yABDYvyHHx",
  "expires_at": "2026-05-27T13:00:00Z",
  "flow": null,
  "livemode": true,
  "locale": "pt-BR",
  "metadata": {},
  "return_url": "https://meusite.com/conta",
  "status": "created",
  "updated_at": null,
  "url": "https://billing.chargefy.io/portal/session/cps_PCaNjJY7XoXvtoVyJN4qhBoh?authorization_code=..."
}

Cria uma customer_portal.session e retorna uma url temporária. Redirecione o cliente para essa URL assim que ela for criada; a autorização embutida no link é de uso único e pode ser aberta pela primeira vez em até 1 hora (7 dias quando a sessão é criada pelo dashboard). Apenas customer é obrigatório. flow_data, locale, metadata e return_url são opcionais, e a validade do link é resolvida automaticamente pela Chargefy. Depois do primeiro acesso bem-sucedido, o authorization_code é consumido e a hosted page passa a usar uma sessão curta do navegador por até 1 hora. Depois desse período, crie uma nova customer_portal.session para gerar uma nova URL.

Autenticação

Header Authorization: Bearer {{API_KEY}}. Escopo necessário: write.

Tipo de chave	Header `Organization`	Escopo
API key da organização	proibido	Customer da própria organização
API key de plataforma	obrigatório	Customer da organização conectada à plataforma, indicada no header

Attributes

string

required

Customer que abrirá o portal.

object

Fluxo inicial da hosted page. Padrão: omitido — o cliente abre a home do portal (portal geral). Quando presente, flow_data.type é obrigatório.

Show Campos de flow_data

string

required

Fluxo que a hosted page abre. Obrigatório sempre que flow_data é enviado.

Valor	Descrição
`customer_update`	Cliente atualiza nome, email, telefone ou dados de cobrança.
`payment_method_update`	Cliente troca o cartão salvo.
`subscription_cancel`	Cliente agenda o cancelamento da assinatura no fim do período.

object

Ação após concluir o fluxo. Opcional; quando presente, after_completion.type deve ser "redirect" e after_completion.redirect.return_url é obrigatório (URL http(s)).

object

Opções para troca de cartão. subscription é opcional para atualizar o padrão da assinatura; invoice é opcional para atualizar o padrão de uma invoice open.

object

Opções para cancelamento. subscription é obrigatório quando type é subscription_cancel.

string

Locale sugerido para a hosted page, por exemplo pt-BR. Padrão: null.

object

Metadata da sessão. Padrão: {}.

string

URL http(s) para onde o cliente pode voltar no seu app. Padrão: null.

configuration ainda não é suportado: enviar esse campo retorna 400 com param: "configuration".

O que a Chargefy resolve sozinha

Validade do link — 1 hora quando a sessão é criada com API key; 7 dias quando é criada pelo dashboard, para compartilhar por email ou WhatsApp.
authorization_code — gerado automaticamente, de uso único e já embutido na url retornada.
Fluxo inicial — sem flow_data, o cliente abre a home do 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_64Aj89yABDYvyHHx"
  }'

{
  "id": "cps_PCaNjJY7XoXvtoVyJN4qhBoh",
  "object": "customer_portal.session",
  "configuration": null,
  "created_at": "2026-05-27T12:00:00Z",
  "customer": "cus_64Aj89yABDYvyHHx",
  "expires_at": "2026-05-27T13:00:00Z",
  "flow": null,
  "livemode": true,
  "locale": "pt-BR",
  "metadata": {},
  "return_url": "https://meusite.com/conta",
  "status": "created",
  "updated_at": null,
  "url": "https://billing.chargefy.io/portal/session/cps_PCaNjJY7XoXvtoVyJN4qhBoh?authorization_code=..."
}

Deep link para cancelamento

curl -X POST "https://api.chargefy.io/v1/customer-portal-sessions" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": "cus_64Aj89yABDYvyHHx",
    "flow_data": {
      "subscription_cancel": {
        "subscription": "sub_z8fednkL8y7nk7zu"
      },
      "type": "subscription_cancel"
    }
  }'

{
  "id": "cps_PCaNjJY7XoXvtoVyJN4qhBoh",
  "object": "customer_portal.session",
  "configuration": null,
  "created_at": "2026-05-27T12:00:00Z",
  "customer": "cus_64Aj89yABDYvyHHx",
  "expires_at": "2026-05-27T13:00:00Z",
  "flow": {
    "after_completion": {
      "redirect": {
        "return_url": "https://meusite.com/conta/assinatura-cancelada"
      },
      "type": "redirect"
    },
    "subscription_cancel": {
      "subscription": "sub_z8fednkL8y7nk7zu"
    },
    "type": "subscription_cancel"
  },
  "livemode": true,
  "locale": null,
  "metadata": {},
  "return_url": "https://meusite.com/conta",
  "status": "created",
  "updated_at": null,
  "url": "https://billing.chargefy.io/portal/session/cps_PCaNjJY7XoXvtoVyJN4qhBoh?authorization_code=..."
}

Deep link para atualizar cartão de uma invoice

curl -X POST "https://api.chargefy.io/v1/customer-portal-sessions" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": "cus_64Aj89yABDYvyHHx",
    "flow_data": {
      "payment_method_update": {
        "invoice": "inv_9aQauDS1jKeg22Hx"
      },
      "type": "payment_method_update"
    }
  }'

Quando o cliente conclui o formulário hospedado, o cartão salvo passa a ser o default_payment_method do customer e da invoice informada. Se a sessão também enviar subscription, o mesmo cartão passa a ser o padrão da assinatura.

Erros comuns

Status	`code`	Quando ocorre
`400`	`invalid_request`	`customer`, `flow_data.type` ou `subscription` obrigatório ausente; `configuration` enviado (não suportado)
`404`	`resource_missing`	Customer, subscription ou invoice não pertence ao escopo da API key
`409`	`resource_state_conflict`	Subscription em estado terminal ou invoice que não está `open`

Próximos passos

Depois de criar a sessão, redirecione o cliente para url. A URL não deve ser armazenada como link permanente, mas pode ser enviada por email: se ainda não tiver sido aberta, ela expira em 1 hora quando criada com API key (7 dias quando criada pelo dashboard). Após o primeiro acesso, a autorização do link é invalidada e a sessão hosted dura até 1 hora.

curl -X POST "https://api.chargefy.io/v1/customer-portal-sessions" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": "cus_64Aj89yABDYvyHHx"
  }'

{
  "id": "cps_PCaNjJY7XoXvtoVyJN4qhBoh",
  "object": "customer_portal.session",
  "configuration": null,
  "created_at": "2026-05-27T12:00:00Z",
  "customer": "cus_64Aj89yABDYvyHHx",
  "expires_at": "2026-05-27T13:00:00Z",
  "flow": null,
  "livemode": true,
  "locale": "pt-BR",
  "metadata": {},
  "return_url": "https://meusite.com/conta",
  "status": "created",
  "updated_at": null,
  "url": "https://billing.chargefy.io/portal/session/cps_PCaNjJY7XoXvtoVyJN4qhBoh?authorization_code=..."
}

Fundamentos da API

Objetos de sistema

Webhooks e eventos

SDKs

MCP

Criar uma sessão do portal do cliente

Autenticação

Attributes

O que a Chargefy resolve sozinha

Deep link para cancelamento

Deep link para atualizar cartão de uma invoice

Erros comuns

Próximos passos

​Autenticação

​Attributes

​O que a Chargefy resolve sozinha

​Deep link para cancelamento

​Deep link para atualizar cartão de uma invoice

​Erros comuns

​Próximos passos

Autenticação

Attributes

O que a Chargefy resolve sozinha

Deep link para cancelamento

Deep link para atualizar cartão de uma invoice

Erros comuns

Próximos passos