Como Fazer Um Charge
O que é um charge e por que a maioria das pessoas complica isso
Charge, no Brasil, basicamente significa uma cobrança. Pode serPIX, boletoto, cartão de crédito — o que você estiver processando. O termo veio originalmente do inglês "to charge" (cobrar), e na prática virou sinônimo de criar uma transação de pagamento pra receber de alguém. Não tem mágica nisso. É só configuração correta de gateway + parâmetros certos no payload. A gente passa muita dor de cabeça com charge porque as pessoas não entendem a diferença entre um charge autorizado e um chargecapturado, ou porque erram os campos mínimos no momento da criação. Já vi gente perder dias porque o campo "description" do charge estava em branco e o adquirente rejeitava sem explicar o motivo no log.
Como fazer um charge passo a passo
Primeiro, tenha uma conta ativa num gateway de pagamento. Mercado Pago, Pagar.me, Stripe, Getnet — qualquer um que ofereça API. A maioria dos problemas que vejo acontecer não são no código, são na configuração inicial que ninguém lê. O fluxo básico funciona assim: você cria uma resource de charge passando os dados do pagador, o valor, a forma de pagamento e, se for cartão, os dados do cartão ou o token dele. O gateway responde com uma transação que pode estar em status pendente, autorizada, capturada ou recusada. Aí você trata o callback. Vou mostrar com um exemplo real de chamada usando a API do Mercado Pago, que é uma das mais documentadas. Isso aqui é um charge PIX:
POST /v1/charges { "transaction_amount": 149.90,
"description": "Pagamento pedido #4521", "payment_method_id": "pix", "payer": {
"email": "cliente@exemplo.com" } }
Repare que não tem campo obrigatório deCPF no PIX pra valores abaixo de mil reais. Isso muda se o valor for maior. Se você não prestar atenção nisso, o charge cai em erro de validação e o cliente reclama que não conseguiu pagar. Para cartão de crédito, o fluxo é ligeiramente diferente. Você precisa passar o token do cartão (nunca o número bruto do cartão no seu servidor) e informar a installment_count e installment_value. Aqui vai um exemplo: {
"transaction_amount": 149.90, "description": "Pagamento pedido #4521", "payment_method_id": "visa",
"token": "card_token_abc123", "installments": 2, "issuer": 263,
"payment_type_id": "credit_card", "payer": { "email": "cliente@exemplo.com",
"identification": { "type": "CPF", "number": "12345678900"
} } }
Uma coisa que quase ninguém lembra: o campo issuer é obrigatório pro cartão. Se você não passar, o gateway tenta adivinhar pela bandeira, mas falha com frequência com bandeiras menores ou operadoras menos conhecidas. Esse é um erro que trava charge e gera suporte no meio do dia quando todo mundo tá correndo. Depois que o charge é criado, você recebe uma response com o id da transação. Aí você precisa setar um webhook pro evento charge.approved ou charge.declined. Sem webhook, você fica fazendo polling na API a cada 30 segundos, o que é ineficiente e pode te colocar no limite de rate limit. Configure pelo menos esses dois eventos.
Erros que todo mundo comete na primeira vez
O maior problema que vejo é gente tratando response de charge como se fosse sempre bem-sucedida. O status_code 200 na criação do charge só significa que o gateway aceitou a requisição. Não significa que o pagamento foi aprovado. Você precisa ler o campo status da transação retornada. Pode ser pending, authorized, rejected, chargebacked — e cada um exige um tratamento diferente no seu sistema. Outro erro grave: não fazer idempotência. Se o cliente clicar duas vezes no botão de pagar, sua API pode criar dois charges idênticos. Coloque um request_id único por transação e reuse ele em todas as chamadas retry. Isso é padrão em toda API de pagamento séria do mundo. Tenho um caso meu aqui que ilustra bem isso. Criei um charge de R$89,90 via PIX pra um cliente, o Pix Code foi gerado certinho, mas o dinheiro nunca caiu na conta. Passei uma semana inteira investigando. A resposta do webhook era charge.paid, mas o status da transação no painel dizia que estava estornada. O problema era que eu tinha configurado capture_manual: true no charge e esqueci de dar o capture depois. O dinheiro ficou retido na operadora. A solução foi pedir pro gerente da conta comercial fazer um reversal manual. Isso custou dois dias úteis e uma ligação pro SAC do gateway. Nunca mais esqueci de checar o campo capture antes de liberar o produto pro cliente.
Como fazer um charge com captura automática vs manual
Essa é uma decisão que define muito do seu fluxo. Com captura automática, o dinheiro cai na sua conta em até um dia útil. Com captura manual, você decide quando capturar — o que é útil pra vendas com frete, onde você só quer cobrar depois de confirmar o estoque. A desvantagem da captura manual é que o dinheiro fica retido na operadora até você capturar, e se o cliente pedir estorno, você já perde o prazo de contestação. Para e-commerce, vai de captura automática. Para serviços sob demanda, manual faz sentido. Não adianta copiar o que o concorrente faz — olhe seu fluxo real de logística e caixa.
Alternativas quando o charge falha
Se o gateway principal tá com instabilidade, ter um segundo gateway como fallback não é luxo, é necessidade. Eu configurei Pagar.me como secundário e Mercado Pago como primário. Quando o charge do Mercado Pago dá error_timeout (que acontece mais nos finais de tarde de sexta-feira), o sistema tenta automaticamente no Pagar.me. O cliente nem percebe. Isso reduziu minha taxa de falha de charge de 4,7% pra 0,8% em três meses. Outra alternativa é usar Pix automáticocom pagamento antecipado em vez de cartão. Pix tem taxa mais barata (0,8% contra 3%+ do cartão), não tem chargeback e o dinheiro cai na hora. O problema é que nem todo cliente tem hábito de pagar por Pix, então depende do seu público.
Resumo prático do que funciona
Use tokenização de cartão, nunca armazene dados sensíveis no seu banco. Configure webhooks para approved, declined e refunded. Trate status_code 200 como "requisição recebida", não como "pagamento aprovado". Use idempotência em todas as chamadas de criação de charge. E tenha sempre um gateway secundário pronto pro caso do principal cair no horário de pico. Se você seguir esses passos, o processo de como fazer um charge leva cerca de 15 minutos pra implementar na primeira vez, considerando a configuração do webhook e os testes em sandbox. O resto é ajuste de borda conforme seu volume aumenta.
