Skip to main content
Este guia cobre o fluxo completo de pagamento com cartão de crédito na Chargefy: desde a criação da sessão de checkout até o tratamento de respostas, incluindo parcelamento, pré-autorização e boas práticas de segurança.

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

Configure a variável de ambiente:
.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.
A resposta inclui o 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.
Conformidade PCI-DSS: Nunca armazene, registre em logs ou trafegue dados completos de cartao pelo seu servidor em texto plano. A tokenizacao da Chargefy garante que os dados sensiveis sao processados em ambiente seguro e certificado PCI-DSS Level 1.
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

As regras de parcelamento (quantidade maxima de parcelas, juros por faixa) sao configuradas por produto no dashboard da Chargefy. A API retorna as opcoes disponiveis automaticamente.

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)

A pre-autorizacao expira em 7 dias. Se nao for capturada ou cancelada nesse prazo, o valor e liberado automaticamente para o titular do cartao.

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.
PCI-DSS: Se voce processa, armazena ou transmite dados de cartao pelo seu servidor, sua aplicacao precisa estar em conformidade com o padrao PCI-DSS. A maneira mais simples de evitar esse requisito e usar o Checkout Embed da Chargefy ou a tokenizacao client-side via Chargefy.js, onde os dados sensiveis nunca passam pela sua infraestrutura.

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.