Skip to main content

​
O que é o Módulo Payments?

O módulo Payments permite processar pagamentos no seu site usando o Stripe. Cada tenant tem a sua própria conta Stripe, com suporte a:
  • Checkout sessions — Páginas de pagamento alojadas no Stripe
  • Modo Test/Live — Teste com dados fictícios antes de ir para produção
  • Webhooks automáticos — O sistema configura os webhooks no Stripe automaticamente
  • Reembolsos — Totais ou parciais, diretamente do painel
  • Disputas — Gestão de chargebacks com alertas
  • Analytics integration — Compras são rastreadas como conversões automaticamente

​
Como funciona o Checkout

1

O developer adiciona o botão de checkout ao site

Usando o CheckoutButton do SDK ou a API diretamente, cria-se uma sessão de checkout.
2

O cliente é redirecionado para o Stripe

O Stripe aloja a página de pagamento. O cliente introduz os dados do cartão.
3

O Stripe notifica o FoxBase via webhook

O webhook é validado com a assinatura do Stripe e o pagamento é processado.
4

O painel mostra a transação

O pagamento aparece no dashboard com todos os detalhes, logs e opções de reembolso.

​
Painel de Administração

​
Configuração

Antes de aceitar pagamentos, configure as suas chaves Stripe:
  1. Aceda a Payments > Configuração
  2. Insira as chaves Test do Stripe (para testes)
  3. O sistema cria automaticamente os webhooks
  4. Quando estiver pronto, insira as chaves Live e mude o modo
Nunca partilhe as suas Secret Keys. O sistema encripta-as automaticamente com AES-256-GCM.

​
Dashboard

O tab Overview mostra:
MétricaDescrição
Revenue TotalSoma de todos os pagamentos bem-sucedidos
Taxa de SucessoPercentagem de pagamentos concluídos
Ticket MédioValor médio por pagamento
ReembolsosTotal reembolsado e taxa de reembolso
Inclui gráficos diários de revenue e contagem de transações.

​
Transações

Lista paginada com:
  • Filtro por status (Succeeded, Failed, Pending, Cancelled)
  • Pesquisa por email, descrição ou ID
  • Detalhe de cada transação com logs de debug
  • Ação de reembolso (total ou parcial)

​
Disputas

  • Lista de disputas ativas
  • Alertas urgentes para disputas que precisam de resposta
  • Deadline de evidência

​
Export CSV

Exporte todas as transações como CSV com colunas: ID, Data, Status, Valor, Moeda, Descrição, Email, Método de Pagamento, Impostos, Reembolsado, Razão de Falha, Modo.

​
SDK: Criar Checkout

​
Componente React

A forma mais simples de adicionar pagamentos ao seu site: 
import { CheckoutButton } from '@foxpixel/react/payments';

export function BuyButton() {
  return (
    <CheckoutButton
      amount={5000}           // em cêntimos (50.00 EUR)
      currency="EUR"
      description="Plano Premium"
      customerEmail="cliente@email.com"
      successUrl="/obrigado"
      cancelUrl="/cancelado"
      metadata={{
        orderId: '12345',
        plan: 'premium'
      }}
    >
      Comprar Agora
    </CheckoutButton>
  );
}
O componente:
  1. Chama a API de checkout
  2. Recebe a URL do Stripe
  3. Redireciona o cliente automaticamente
  4. Passa o visitorId do analytics para atribuição

​
Hook useCheckout

Para mais controlo: 
import { useCheckout } from '@foxpixel/react/payments';

export function CustomCheckout() {
  const { createCheckout, isLoading, error } = useCheckout();

  const handleBuy = async () => {
    const result = await createCheckout({
      amount: 5000,
      currency: 'EUR',
      description: 'Plano Premium',
      customerEmail: 'cliente@email.com',
      successUrl: window.location.origin + '/obrigado',
      cancelUrl: window.location.origin + '/cancelado',
      metadata: { orderId: '12345' }
    });

    // Redirecionar para o Stripe
    window.location.href = result.checkoutUrl;
  };

  return (
    <button onClick={handleBuy} disabled={isLoading}>
      {isLoading ? 'A processar...' : 'Comprar'}
    </button>
  );
}

​
Verificar estado do pagamento

Após o checkout, na página de sucesso: 
import { usePaymentStatus } from '@foxpixel/react/payments';

export function SuccessPage() {
  const paymentId = new URLSearchParams(window.location.search).get('paymentId');

  const { data, isLoading } = usePaymentStatus({
    paymentId,
    pollInterval: 2000,     // Verifica a cada 2 segundos
    stopOnTerminal: true     // Para quando o estado é final
  });

  if (isLoading) return <p>A verificar pagamento...</p>;

  if (data?.status === 'SUCCEEDED') {
    return <p>Pagamento confirmado! Obrigado.</p>;
  }

  return <p>Estado: {data?.status}</p>;
}

​
API Pública

Autenticação via API Key (Authorization: Bearer sk_live_xxxxx).

​
Criar checkout session

POST /api/v1/payments/checkout/create
Authorization: Bearer sk_live_xxxxx
Content-Type: application/json

{
  "amount": 5000,
  "currency": "EUR",
  "description": "Plano Premium",
  "receiptEmail": "cliente@email.com",
  "successUrl": "https://meusite.com/obrigado?paymentId={PAYMENT_ID}",
  "cancelUrl": "https://meusite.com/cancelado",
  "metadata": {
    "orderId": "12345",
    "plan": "premium"
  }
}
Resposta: 
{
  "paymentId": "uuid-do-pagamento",
  "checkoutUrl": "https://checkout.stripe.com/c/pay/cs_xxx",
  "sessionId": "cs_xxx",
  "expiresAt": "2026-02-10T20:00:00Z"
}

​
Verificar estado

GET /api/v1/payments/{paymentId}/status
Authorization: Bearer sk_live_xxxxx
Resposta: 
{
  "paymentId": "uuid-do-pagamento",
  "status": "SUCCEEDED",
  "amount": 5000,
  "currency": "EUR",
  "description": "Plano Premium",
  "succeededAt": "2026-02-10T18:30:00Z"
}

​
Webhooks

O sistema configura automaticamente os webhooks no Stripe quando guarda a configuração. Os eventos processados são:
Evento StripeAção
checkout.session.completedPagamento marcado como PROCESSING
payment_intent.succeededPagamento marcado como SUCCEEDED
payment_intent.payment_failedPagamento marcado como FAILED
payment_intent.canceledPagamento marcado como CANCELLED
charge.refundedValor reembolsado atualizado
charge.dispute.createdDisputa criada com alerta
charge.dispute.closedDisputa marcada como WON/LOST
Os webhooks são idempotentes — processar o mesmo evento duas vezes não causa problemas.

​
Eventos de Domínio

Outros módulos podem reagir a eventos de pagamento:
EventoQuando acontece
PAYMENT_CREATEDCheckout session criada
PAYMENT_SUCCEEDEDPagamento confirmado
PAYMENT_FAILEDPagamento falhou
PAYMENT_CANCELLEDPagamento cancelado
PAYMENT_REFUNDEDReembolso processado
DISPUTE_NEEDS_RESPONSEDisputa precisa de resposta
DISPUTE_WONDisputa ganha
DISPUTE_LOSTDisputa perdida

​
Integração com Analytics

Quando ambos os módulos estão ativos:
  • Compras são automaticamente rastreadas como conversões “purchase”
  • Reembolsos são enviados como eventos “refund” para as plataformas de anúncios
  • A atribuição liga a compra aos touchpoints de marketing do visitante
  • Os dados aparecem no tab Revenue do Analytics
Para que a atribuição funcione corretamente, use o CheckoutButton do SDK — ele passa automaticamente o visitorId para o Stripe.

​
Permissões

PermissãoDescrição
payments:config:readVer configuração Stripe
payments:config:writeEditar configuração
payments:config:deleteRemover configuração
payments:transactions:readVer transações
payments:transactions:createCriar pagamentos
payments:refunds:readVer reembolsos
payments:refunds:createCriar reembolsos
payments:disputes:readVer disputas
payments:disputes:writeGerir disputas
payments:stats:readVer estatísticas
payments:logs:readVer logs de debug
payments:checkout:createCriar checkout (SDK)
payments:checkout:readVer estado do checkout (SDK)

​
Modos Test e Live

Modo TestModo Live
Chavespk_test_xxx / sk_test_xxxpk_live_xxx / sk_live_xxx
Dinheiro realNãoSim
Cartões de teste4242 4242 4242 4242Cartões reais
WebhooksEndpoint separadoEndpoint separado
Pode alternar entre modos a qualquer momento sem perder configuração.