🤖 Explicar com IA

Construindo faturamento de assinatura recorrente com pagamentos 4Geeks¶

Visão geral¶

4Geeks Payments fornece ferramentas robustas para gerenciar pagamentos e assinaturas recorrentes, permitindo automatizar ciclos de faturamento, lidar com atualizações/downgrades e gerenciar o ciclo de vida completo da assinatura - tudo isso enquanto cuida da conformidade fiscal e da prevenção de fraudes como seu comerciante registrado.

Neste tutorial, você irá:

• Criar planos de assinatura
• Inscrever clientes em planos
• Lidar com upgrades, downgrades e cancelamentos
• Gerenciar o Portal de Autoatendimento do Cliente
• Lidar com pagamentos falhados e cobranças

Pré-requisitos¶

• Uma conta 4Geeks Payments ativada
• Chaves API (chave secreta)
• Compreensão básica dos modelos de negócios de assinatura

Etapa 1: Crie planos de assinatura¶

Via API¶

const axios = require('axios');

const response = await axios.post('https://api.4geeks.io/v1/plans', {
  name: 'Pro Plan',
  amount: 4900,           // $49.00 in cents
  currency: 'USD',
  interval: 'month',       // 'week', 'month', 'year'
  interval_count: 1,       // Every 1 month
  trial_period_days: 14,   // 14-day free trial
  metadata: {
    features: 'Unlimited projects, Priority support, API access',
    tier: 'pro'
  }
}, {
  headers: {
    'Authorization': `Bearer ${SECRET_KEY}`,
    'Content-Type': 'application/json'
  }
});

console.log('Plan created:', response.data);
// plan_xxxxxxxxxxxxx

Propriedades do plano¶

Etapa 2: inscrever um cliente¶

Crie o cliente primeiro¶

const customer = await axios.post('https://api.4geeks.io/v1/customers', {
  email: 'customer@example.com',
  name: 'Jane Smith',
  metadata: {
    company: 'Acme Corp',
    signup_source: 'website'
  }
}, {
  headers: { 'Authorization': `Bearer ${SECRET_KEY}` }
});

const customerId = customer.data.id; // cus_xxxxxxxxxxxxx

Criar assinatura¶

const subscription = await axios.post('https://api.4geeks.io/v1/subscriptions', {
  customer_id: customerId,
  plan_id: 'plan_xxxxxxxxxxxxx',
  payment_method_id: 'pm_xxxxxxxxxxxxx',  // From checkout form
  billing_cycle_anchor: 'now',             // or specific date
  metadata: {
    sales_rep: 'john@example.com'
  }
}, {
  headers: { 'Authorization': `Bearer ${SECRET_KEY}` }
});

console.log('Subscription created:', subscription.data);
// sub_xxxxxxxxxxxxx

Etapa 3: lidar com mudanças no plano¶

Atualizar uma assinatura¶

CODE_BLOCO_3

Downgrade de uma assinatura¶

const downgrade = await axios.post('https://api.4geeks.io/v1/subscriptions/sub_xxx/update', {
  plan_id: 'plan_basic_xxx',
  prorate: false,                   // Apply at next billing cycle
  billing_cycle_anchor: 'next_cycle'
}, {
  headers: { 'Authorization': `Bearer ${SECRET_KEY}` }
});

Cancelar uma assinatura¶

CODE_BLOCO_5

Reativar uma assinatura cancelada¶

const reactivate = await axios.post('https://api.4geeks.io/v1/subscriptions/sub_xxx/reactivate', {}, {
  headers: { 'Authorization': `Bearer ${SECRET_KEY}` }
});

Etapa 4: configurar o portal do cliente¶

O Portal de autoatendimento do cliente permite que os assinantes gerenciem suas próprias assinaturas.

Habilite o Portal¶

1. Vá para Pagamentos → Configurações → Portal do Cliente
2. Habilite o portal
3. Configure as ações permitidas:
4. Atualizar forma de pagamento
5. Ver histórico de faturamento
6. Plano de atualização/downgrade
7. Cancelar assinatura
8. Baixar faturas

Incorporar o Portal¶

<!-- Redirect to hosted portal -->
<a href="https://pay.4geeks.io/portal/{{ customer.portal_token }}">
  Manage Subscription
</a>

<!-- Or embed as iframe -->
<iframe 
  src="https://pay.4geeks.io/portal/{{ customer.portal_token }}"
  width="100%" 
  height="800"
  frameborder="0"
></iframe>

Gerar token do portal¶

const portal = await axios.post('https://api.4geeks.io/v1/customer-portal', {
  customer_id: customerId,
  return_url: 'https://yoursite.com/account/billing'
}, {
  headers: { 'Authorization': `Bearer ${SECRET_KEY}` }
});

console.log('Portal URL:', portal.data.url);

Etapa 5: Lidar com falhas de pagamento (cobrança)¶

Lógica de Nova Tentativa Automática¶

4Geeks Payments tenta automaticamente pagamentos com falha:

Eventos de webhook para pagamentos com falha¶

CODE_BLOCO_9

E-mails de cobrança personalizados¶

Configure e-mails de cobrança automatizados no console:

1. Vá para Pagamentos → Configurações → Cobrança
2. Personalize modelos de e-mail para:
3. Notificação de falha no pagamento
4. Notificação de nova tentativa
5. Aviso final antes do cancelamento
6. Notificação de cancelamento de assinatura
7. Defina o tempo para cada e-mail

Etapa 6: Monitore as métricas de assinatura¶

Principais métricas a serem rastreadas¶

Acesse relatórios¶

1. Vá para Pagamentos → Analytics → Assinaturas
2. Visualize painéis em tempo real para todas as métricas de assinatura
3. Exporte relatórios como CSV para análise posterior

Melhores práticas¶

Estratégia de preços¶

• Ofereça faturamento anual com desconto (por exemplo, 20% de desconto) para melhorar o fluxo de caixa
• Use períodos de teste para reduzir o atrito para novos clientes
• Implementar preços adquiridos para os primeiros usuários
• Considere modelos de preços baseados no uso ou em camadas

Reduzindo a rotatividade¶

• Envie relatórios de uso para mostrar o valor entregue
• Implementar campanhas de reconquista para assinantes cancelados
• Oferecer opção de pausa em vez de cancelamento
• Fornecer suporte proativo antes das datas de renovação

Conformidade¶

• Como Merchant of Record, a 4Geeks lida com a conformidade fiscal automaticamente
• A conformidade com PCI DSS está integrada: os dados do cartão nunca chegam aos seus servidores
• Conformidade com GDPR para clientes da UE
• Regulamentações de pagamento locais tratadas por jurisdição

O que vem a seguir?¶

• Saiba mais sobre 3D Secure para prevenção de fraudes
• Explore Check-out multimoedas

Precisa de ajuda?¶

• Documentação: docs.4geeks.io/en/payments
• Referência da API: docs.4geeks.io/en/api
• Suporte: disponível no painel do console

Ainda tem dúvidas? Pergunte na Discord or explore tutoriais