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

{
  "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": null,
  "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=..."
}
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. 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 chaveHeader OrganizationEscopo
API key da organizaçãoproibidoCustomer da própria organização
API key de plataformaobrigatórioCustomer da organização conectada indicada

​
Attributes

​
customer
string
required
Customer que abrirá o portal.
​
flow_data
object
Fluxo inicial da hosted page. Quando omitido, o cliente abre a home do portal.
​
locale
string
Locale sugerido para a hosted page, por exemplo pt-BR.
​
metadata
object
Metadata da sessão. Padrão {}.
​
return_url
string
URL para onde o cliente pode voltar no seu app.
curl -X POST "https://api.chargefy.io/v1/customer-portal-sessions" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": "cus_123"
  }'

{
  "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": null,
  "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=..."
}

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

{
  "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": null,
  "metadata": {},
  "return_url": "https://example.com/account",
  "status": "created",
  "updated_at": null,
  "url": "https://billing.chargefy.io/portal/session/cps_123?authorization_code=..."
}

curl -X POST "https://api.chargefy.io/v1/customer-portal-sessions" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": "cus_123",
    "flow_data": {
      "payment_method_update": {
        "invoice": "inv_123"
      },
      "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

StatuscodeQuando ocorre
400invalid_requestcustomer, flow_data.type ou subscription obrigatório ausente
404resource_missingCustomer ou subscription não pertence ao escopo da API key
409resource_state_conflictSubscription em estado terminal

​
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: ela expira em 1 hora se ainda não tiver sido aberta. Após o primeiro acesso, a autorização do link é invalidada e a sessão hosted dura até 1 hora.