Pagamentos

Eventos de cobrança e o corpo de cada um.

Eventos de cobrança#

Evento	Disparado quando
`payment.created`	A cobrança é registrada.
`payment.pending`	A cobrança está aguardando o pagador.
`payment.processing`	O processador começou a analisar.
`payment.paid`	Pagamento confirmado. É o evento que libera o pedido.
`payment.failed`	A cobrança foi recusada.
`payment.expired`	O prazo terminou sem pagamento.
`payment.canceled`	Você cancelou a cobrança.
`payment.refunded`	O valor total foi devolvido.
`payment.partially_refunded`	Parte do valor foi devolvida.
`payment.chargeback`	O pagador contestou a compra.

Um evento decide o pedido

Libere produto ou serviço somente em payment.paid. Os demais eventos servem para atualizar a tela do cliente e o seu relatório.

payment.paid

{
  "event": "payment.paid",
  "sent_at": "2026-08-11T19:03:12Z",
  "data": {
    "id": "pay_3Kq8Zx91",
    "status": "paid",
    "method": "pix",
    "amount_centavos": 12990,
    "net_centavos": 12945,
    "platform_fee_centavos": 45,
    "installments": 1,
    "paid_at": "2026-08-11T19:03:11Z",
    "end_to_end_id": "E12345678202608111903...",
    "metadata": { "pedido": "8291" }
  }
}

Assinaturas recorrentes#

Evento	Disparado quando
`subscription.created`	Uma assinatura é criada.
`subscription.renewed`	Um ciclo é cobrado com sucesso.
`subscription.failed`	A cobrança do ciclo falhou.
`subscription.canceled`	A assinatura é cancelada.

Cadastro da conta#

Se você opera subcontas ou revende, também recebe merchant.pending, merchant.approved e merchant.rejected conforme a análise de cada conta avança.

tratamento idempotente

async function processar(evento) {
  if (evento.event !== "payment.paid") return;

  const pedido = await Pedido.porPagamento(evento.data.id);
  if (!pedido || pedido.status === "pago") return; // já tratado

  await pedido.marcarPago({
    liquido: evento.data.net_centavos,
    pagoEm: evento.data.paid_at,
  });
}