Skip to main content

​
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çãoDescrição
URL do portalDomínio customizado ou subdomínio Chargefy
LogoLogo da sua marca exibido no portal
CoresCores primária e secundária do tema
FuncionalidadesHabilitar/desabilitar seções do portal
Política de cancelamentoPermitir 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: 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: "[email protected]",
  organization_id: "org_xxx",
});

// 2. Validar código e obter token
const session = await chargefy.customerSessions.authenticate({
  email: "[email protected]",
  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 -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

EscopoPermissão
customer_portal:readVisualizar dados do portal (assinaturas, vendas, benefícios)
customer_portal:writeGerenciar assinaturas e métodos de pagamento
customer_sessions:writeCriar sessões de cliente (server-side)

​
Webhooks

Eventos disparados por ações no portal do cliente:
EventoDescrição
customer_portal.session_createdNova sessão de portal criada
customer_portal.subscription_canceledCliente cancelou uma assinatura pelo portal
customer_portal.payment_method_addedCliente adicionou novo método de pagamento
customer_portal.payment_method_removedCliente 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