Visão geral do fluxo
O pagamento com cartão de crédito na Chargefy segue este fluxo:1
Criar sessão de checkout
Seu backend cria uma sessão via API com o produto e valor.
2
Coletar dados do cartão
O frontend coleta os dados do cartão de forma segura (tokenização client-side).
3
Confirmar pagamento
Envie os dados tokenizados junto com o número de parcelas para confirmar o pagamento.
4
Tratar resposta
Verifique se o pagamento foi aprovado, recusado ou se houve erro, e aja de acordo.
Pré-requisitos
- Uma conta Chargefy com Supabase JWT
- Pelo menos um produto criado no dashboard
- Node.js 18+ e o SDK
@chargefy/sdkinstalado - Familiaridade com o ambiente sandbox
.env
Passo 1: Criar sessão de checkout
Crie uma sessão de checkout no seu backend informando o produto e opções de pagamento.client_secret, que sera usado para confirmar o pagamento no frontend.
Passo 2: Coletar dados do cartão com segurança
Os dados do cartão devem ser coletados diretamente no frontend e enviados para confirmacao. A Chargefy realiza a tokenizacao dos dados sensiveis de forma segura. Os campos necessarios para o cartao sao:Passo 3: Confirmar pagamento com dados do cartao
Com a sessao criada e os dados do cartao coletados, confirme o pagamento:Os dados do cartao sao tokenizados automaticamente durante a confirmacao. A Chargefy nunca armazena os dados sensiveis do cartao — apenas o token gerado e utilizado para processar a transacao.
Passo 4: Parcelamento (1-12x)
A Chargefy suporta parcelamento de 1 a 12 vezes no cartao de credito. O comportamento varia conforme a configuracao do produto:Exemplo: Calcular parcelas para exibicao
Passo 5: Tratar a resposta
Apos confirmar o pagamento, verifique o status da resposta para tomar a acao adequada:Codigos de recusa comuns
Pre-autorizacao e captura
Para cenarios onde voce precisa reservar o valor no cartao e capturar depois (ex: marketplaces, entregas, reservas), use o fluxo de pre-autorizacao:1. Criar checkout com pre-autorizacao
2. Confirmar pagamento (reserva o valor)
3. Capturar o valor (quando pronto para cobrar)
4. Cancelar pre-autorizacao (liberar o valor)
Componente React para formulario de cartao
Exemplo de componente React para coletar dados do cartao com validacao:components/CardForm.tsx
Exemplo completo: Express + React
Backend (Express)
src/routes/card-checkout.ts
Frontend (React)
pages/Checkout.tsx
Testes no sandbox
Use o ambiente sandbox para testar pagamentos sem cobrar de verdade. Utilize os cartoes de teste abaixo:Cartoes de teste
Para cartoes de teste, use qualquer data de validade futura (ex:
12/2028) e qualquer CVV de 3 digitos (ex: 123). O nome do titular pode ser qualquer valor.Testar via cURL
Boas praticas de seguranca
1
Nunca registre dados de cartao em logs
Nunca use
console.log(), logger.info() ou qualquer mecanismo de log para registrar numero do cartao, CVV ou data de validade. Registre apenas os 4 ultimos digitos para referencia.2
Use HTTPS em producao
Todo trafego contendo dados de pagamento deve ocorrer exclusivamente sobre HTTPS/TLS. Nunca transmita dados de cartao em conexoes nao criptografadas.
3
Prefira tokenizacao client-side
Sempre que possivel, use o Checkout Embed ou a tokenizacao Chargefy.js no frontend para que os dados do cartao nunca passem pelo seu servidor.
4
Valide no servidor
Mesmo com validacoes no frontend, sempre valide os dados novamente no backend antes de enviar para a API da Chargefy.
5
Implemente idempotencia
Use chaves de idempotencia para evitar cobranças duplicadas em caso de retry ou timeout de rede.
6
Monitore transacoes
Configure webhooks para receber notificacoes em tempo real sobre aprovacoes, recusas e estornos.
Proximos passos
Checkout PIX
Integre pagamentos via PIX com QR Code.
Webhooks
Receba notificacoes de pagamento em tempo real.
Checkout Embed
Incorpore o checkout diretamente no seu site.
Reembolsos
Processe estornos totais e parciais.

