Portal do Cliente

Ofereça um portal self-service para seus clientes gerenciarem assinaturas, pagamentos e vendas.

​

Visão Geral

O Portal do Cliente é uma interface self-service que permite aos seus clientes gerenciar suas assinaturas, métodos de pagamento, histórico de vendas e downloads de benefícios — sem precisar entrar em contato com o suporte.

O portal pode ser acessado de duas formas:

• Portal hospedado pela Chargefy — URL pronta para uso, sem necessidade de implementação
• Portal embarcado — componentes React para integrar diretamente na sua aplicação

​

Funcionalidades Disponíveis

​

Visualizar Assinaturas

O cliente pode ver todas as suas assinaturas ativas, suspensas e canceladas, incluindo:

• Status atual da assinatura
• Próxima data de cobrança e valor
• Histórico de cobranças anteriores
• Opção de cancelar ou pausar a assinatura

​

Gerenciar Métodos de Pagamento

O cliente pode adicionar, remover e atualizar seus métodos de pagamento:

• Cartão de Crédito — adicionar novo cartão, definir cartão padrão, remover cartões
• PIX — gerar QR Code para pagamentos avulsos
• Boleto — visualizar boletos pendentes e segunda via

A atualização de cartão em assinaturas ativas é refletida automaticamente nas próximas cobranças.

​

Download de Benefícios

Para produtos digitais, o cliente pode acessar e baixar seus benefícios:

• Arquivos para download (PDFs, e-books, etc.)
• Chaves de licença
• Links de acesso a conteúdo exclusivo

​

Configuração e Customização

​

Ativar o Portal

No dashboard da Chargefy, acesse Configurações > Portal do Cliente para ativar e configurar o portal.

Configuração	Descrição
URL do portal	Domínio customizado ou subdomínio Chargefy
Logo	Logo da sua marca exibido no portal
Cores	Cores primária e secundária do tema
Funcionalidades	Habilitar/desabilitar seções do portal
Política de cancelamento	Permitir cancelamento imediato ou apenas no final do período

import { Chargefy } from "@chargefy/sdk";

const chargefy = new Chargefy({
  accessToken: process.env.CHARGEFY_ACCESS_TOKEN,
});

// Configurar o portal do cliente
await chargefy.customerPortal.updateSettings({
  organization_id: "org_xxx",
  enabled: true,
  allow_cancellation: true,
  cancel_at_period_end: true,
  allow_payment_method_update: true,
  show_sale_history: true,
  branding: {
    logo_url: "https://suaempresa.com.br/logo.png",
    primary_color: "#6366f1",
    secondary_color: "#818cf8",
  },
});

​

Customer Session Token

Para que um cliente acesse o portal, ele precisa de um Customer Session Token (chargefy_cst_xxx). O token pode ser obtido de duas formas:

​

Magic Link (OTP)

O cliente informa seu email e recebe um código de 6 dígitos por email:

1. Solicitar código OTP

   O cliente informa o email cadastrado. A Chargefy envia um código OTP de 6 dígitos.

2. Validar código

   O cliente informa o código recebido e a Chargefy retorna um customer_session_token.

3. Acessar o portal

   Com o token, o cliente pode acessar todas as funcionalidades do portal.

// 1. Solicitar código OTP
await chargefy.customerSessions.requestOTP({
  email: "[e-mail]",
  organization_id: "org_xxx",
});

// 2. Validar código e obter token
const session = await chargefy.customerSessions.authenticate({
  email: "[e-mail]",
  otp_code: "847293",
  organization_id: "org_xxx",
});

console.log(session.token); // "chargefy_cst_xxx"
// Token válido por 15 dias

​

Via API (Server-side)

Para integrar o portal diretamente na sua aplicação, você pode criar uma sessão no backend sem exigir OTP do cliente:

// No seu servidor — gera um token para o cliente autenticado
const session = await chargefy.customerSessions.create({
  customer_id: "cust_xxx",
});

console.log(session.token); // "chargefy_cst_xxx"
console.log(session.expires_at); // "2026-03-27T00:00:00Z"

Sessões criadas via API server-side são ideais quando o cliente já está autenticado no seu sistema. Nunca exponha seu CHARGEFY_ACCESS_TOKEN no frontend.

​

API do Portal do Cliente

​

Listar assinaturas do cliente

cURL

curl -X GET "https://api.chargefy.io/api/v1/customer-portal/subscriptions" \
  -H "Authorization: Bearer chargefy_cst_xxx"

​

Listar métodos de pagamento

const paymentMethods = await chargefy.customerPortal.listPaymentMethods();

paymentMethods.items.forEach((pm) => {
  console.log(pm.type);       // "credit_card"
  console.log(pm.brand);      // "visa"
  console.log(pm.last4);      // "4242"
  console.log(pm.exp_month);  // 12
  console.log(pm.exp_year);   // 2028
  console.log(pm.is_default); // true
});

​

Cancelar assinatura

await chargefy.customerPortal.cancelSubscription("sub_xxx", {
  cancel_at_period_end: true,
});
// O cliente mantém acesso até o final do período pago

​

Embarcando o Portal na Sua Aplicação

​

Instalação

npm install @chargefy/sdk

​

Componente React

Use o componente CustomerPortal para embarcar o portal completo na sua aplicação React:

import { CustomerPortal } from "@chargefy/sdk/react";

function PortalPage() {
  // Token obtido do seu backend
  const customerSessionToken = "chargefy_cst_xxx";

  return (
    <CustomerPortal
      token={customerSessionToken}
      theme={{
        primaryColor: "#6366f1",
        borderRadius: "8px",
      }}
      onSubscriptionCancel={(subscriptionId) => {
        console.log("Assinatura cancelada:", subscriptionId);
      }}
      onError={(error) => {
        console.error("Erro no portal:", error);
      }}
    />
  );
}

​

Componentes Individuais

Se você precisa de mais controle, utilize os componentes individuais:

import {
  CustomerSubscriptions,
  CustomerPaymentMethods,
} from "@chargefy/sdk/react";

function CustomPortal({ token }: { token: string }) {
  return (
    <div className="space-y-8">
      <section>
        <h2>Minhas Assinaturas</h2>
        <CustomerSubscriptions token={token} />
      </section>

      <section>
        <h2>Métodos de Pagamento</h2>
        <CustomerPaymentMethods
          token={token}
          allowAdd={true}
          allowRemove={true}
        />
      </section>
    </div>
  );
}

​

Exemplo Completo com Next.js

Exemplo de integração do portal em uma aplicação Next.js com autenticação:

// app/portal/page.tsx
"use client";

import { useEffect, useState } from "react";
import { CustomerPortal } from "@chargefy/sdk/react";

export default function PortalPage() {
  const [token, setToken] = useState<string | null>(null);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    async function createSession() {
      // Seu backend cria a sessão do cliente
      const response = await fetch("/api/customer-session", {
        method: "POST",
      });
      const data = await response.json();
      setToken(data.token);
      setLoading(false);
    }
    createSession();
  }, []);

  if (loading) return <div>Carregando...</div>;
  if (!token) return <div>Erro ao criar sessão</div>;

  return (
    <div className="max-w-4xl mx-auto py-8">
      <h1 className="text-2xl font-bold mb-6">Minha Conta</h1>
      <CustomerPortal token={token} />
    </div>
  );
}

// app/api/customer-session/route.ts
import { Chargefy } from "@chargefy/sdk";
import { NextResponse } from "next/server";

const chargefy = new Chargefy({
  accessToken: process.env.CHARGEFY_ACCESS_TOKEN!,
});

export async function POST(request: Request) {
  // Obtenha o customer_id do usuário autenticado no seu sistema
  const customerId = await getAuthenticatedCustomerId(request);

  const session = await chargefy.customerSessions.create({
    customer_id: customerId,
  });

  return NextResponse.json({
    token: session.token,
    expires_at: session.expires_at,
  });
}

​

Escopos de API

Escopo	Permissão
customer_portal:read	Visualizar dados do portal (assinaturas, vendas, benefícios)
customer_portal:write	Gerenciar assinaturas e métodos de pagamento
customer_sessions:write	Criar sessões de cliente (server-side)

​

Webhooks

Eventos disparados por ações no portal do cliente:

Evento	Descrição
customer_portal.session_created	Nova sessão de portal criada
customer_portal.subscription_canceled	Cliente cancelou uma assinatura pelo portal
customer_portal.payment_method_added	Cliente adicionou novo método de pagamento
customer_portal.payment_method_removed	Cliente removeu um método de pagamento

---

Gestão de Clientes

Crie e gerencie clientes via API

Assinaturas

Configure assinaturas recorrentes

Métodos de Pagamento

PIX, Cartão e Boleto

Autenticação

Configure tokens e escopos de acesso