Pagamentos vs. transações

O pagamento é a venda como o comprador viveu: um valor, um parcelamento escolhido, um desfecho. A transação é a contabilidade: cada linha de dinheiro entrando ou saindo da sua conta, com a taxa descontada e a data em que liquida. Uma venda de R$ 1.100,00 em 10x é um pagamento e dez lançamentos no extrato. Confundir os dois é o motivo mais comum de um relatório de faturamento não bater com o extrato.

	Pagamento (`payment_intent`)	Transação (`transaction`)
Responde	”Essa venda foi paga?"	"Quanto entra na minha conta e quando?”
Unidade	A venda inteira	Cada movimento de dinheiro
Quantidade	Um por venda	Um por parcela, por taxa e por estorno
Valor negativo?	Nunca	Sim: saída de dinheiro tem sinal negativo
Prefixo do ID	`pi_`	`txn_`
Escrita pela API	Criar, confirmar, capturar, cancelar	Nenhuma — é somente leitura

O exemplo que explica a diferença

Uma venda de **R

1.100,00 em 10x com juros pagos pelo comprador**, aprovada no cartão: o produto custa R

1.000,00 e os juros do parcelamento são R$ 100,00. O pagamento registra a venda como ela foi vendida:

{
  "id": "pi_M2nQ7xW4pL9kR3sT",
  "object": "payment_intent",
  "amount": 110000,
  "installment_interest_amount": 10000,
  "installments": 10,
  "payment_method_options": {
    "credit_card": {
      "installments": {
        "amount": 110000,
        "count": 10,
        "installment_interest_amount": 10000,
        "interest_payer": "buyer",
        "principal_amount": 100000,
        "surcharge_amount": 0
      }
    }
  },
  "principal_amount": 100000,
  "status": "succeeded",
  "...": "demais campos do pagamento"
}

O extrato registra os dez movimentos que ela produz. Cada parcela é um lançamento próprio, com a sua fatia dos juros e da taxa:

{
  "id": "txn_9fK2mQ4xW7pLnR8s",
  "object": "transaction",
  "amount": 11000,
  "available_at": "2026-09-19T00:00:00Z",
  "description": "Installment 2/10",
  "expected_payout_at": null,
  "fee_amount": 1399,
  "fee_details": [
    {
      "amount": 1000,
      "description": "Installment interest",
      "type": "installment_interest"
    },
    {
      "amount": 399,
      "description": "Chargefy processing fee",
      "type": "chargefy_fee"
    }
  ],
  "installment": 2,
  "installment_count": 10,
  "net_amount": 9601,
  "payment_intent": "pi_M2nQ7xW4pL9kR3sT",
  "source": "ch_Q7xW4pL9kR3sTM2n",
  "status": "pending",
  "type": "charge",
  "...": "demais campos da transação"
}

Se a organização pagasse os juros (interest_payer: "organization"), o comprador teria pago R

1.000,00 em 10x e o pagamento traria `amount: 100000` com o mesmo `installment_interest_amount: 10000`. No extrato, cada parcela entraria com `amount: 10000`, o componente `installment_interest` de R

10,00 continuaria em fee_details — agora como dedução real do seu líquido — e o net_amount seria R$ 86,01. Repare no que muda de um objeto para o outro:

Pergunta	Onde está a resposta
Quanto o comprador pagou?	`payment_intent.amount` — R$ 1.100,00, uma vez só
Em quantas vezes?	`payment_intent.installments` — 10
Quem pagou os juros?	`payment_method_options.credit_card.installments.interest_payer` — `buyer`
Quanto entra na conta a cada mês?	`transaction.net_amount` — R$ 96,01 por parcela
Quanto foi de taxa?	`transaction.fee_amount` e a quebra em `fee_details`
Quando o dinheiro cai?	`transaction.available_at`, e `settled_at` quando liquidar

A conta sempre fechanet_amount = amount - fee_amount, e fee_amount é exatamente a soma dos itens de fee_details. Somar net_amount de qualquer conjunto de movimentos dá o efeito líquido no seu saldo — sem inverter sinal por tipo, sem excluir estorno.

Entradas e saídas

Entradas são positivas, saídas são negativas. Um estorno de R$ 50,00 não altera a venda original: ele entra como um lançamento próprio, negativo, valendo o líquido que a venda tinha creditado.

{
  "id": "txn_9fK2mQ4xW7pLnR8s",
  "object": "transaction",
  "amount": -4851,
  "expected_payout_at": null,
  "fee_amount": 0,
  "net_amount": -4851,
  "source": "re_8sT4nK2wQ7xLpR9m",
  "type": "refund",
  "...": "demais campos da transação"
}

A taxa da Chargefy volta junto com o estorno, então o movimento de saída é o líquido que tinha entrado (R

50,00 menos R

1,49 de taxa, nesse exemplo) — por isso fee_amount é 0 e não há nada a deduzir dele.

O que cada tipo de movimento significa

`type`	O que é
`charge`	Uma parcela de venda entrando na conta.
`refund`	Um estorno saindo da conta. Valor negativo.
`chargefy_fee`	A remuneração da Chargefy naquela parcela.
`platform_fee`	A remuneração da plataforma, quando a venda acontece por uma plataforma.
`adjustment`	Um acerto pontual lançado no extrato.

Quais desses você recebe depende do papel da sua organização: quem vende vê as vendas e os estornos; uma plataforma vê também os movimentos de fee das organizações conectadas.

Para que serve cada um

Use o pagamento para

Tudo que é venda: liberar pedido, mostrar o valor cobrado, explicar o parcelamento ao cliente, decidir se houve ou não pagamento.

Use a transação para

Tudo que é dinheiro: fechar caixa, conferir taxas, projetar recebíveis, conciliar com o extrato bancário, apurar o líquido de um período.

Um teste rápido para saber qual usar: se a pergunta tem data de liquidação ou taxa na resposta, é transação. Se tem cliente, produto ou desfecho da venda, é pagamento.

Não some payment_intent.amount para descobrir quanto entrou na conta. Esse campo é o que o comprador pagou: quando ele paga os juros do parcelamento (interest_payer: "buyer"), eles estão ali e não são seus; quando a organização paga (interest_payer: "organization"), eles não estão ali, mas saem do seu líquido. Em nenhum dos casos o amount desconta a taxa. Para saldo, some net_amount das transações.

Como os dois se ligam

Toda transação de venda aponta para dois objetos:

Campo	Aponta para	Serve para
`payment_intent`	O pagamento (`pi_*`)	Chegar na venda: cliente, parcelas, produto
`source`	A cobrança (`ch_`) ou o reembolso (`re_`) que causou o movimento	Agrupar: todos os movimentos com o mesmo `ch_*` são a mesma cobrança

Para ver as dez parcelas de uma venda parcelada, liste as transações e agrupe pelo source. Para ir da linha do extrato até o cliente, siga o payment_intent.

Quando o dinheiro liquida

Campo	O que é
`available_at`	A previsão de liquidação. Pode ser `null` enquanto depende de conciliação.
`settled_at`	A data em que o dinheiro efetivamente entrou. `null` enquanto pendente.
`status`	`pending` (não liquidou), `paid` (liquidou), `canceled` (não vai liquidar) ou `refunded` (a venda foi estornada).

Compare available_at com settled_at para medir atraso de liquidação. Movimentos canceled não entram em soma de saldo: a cobrança de origem não se concretizou.

Perguntas frequentes

Um pagamento aprovado sempre gera transação?

Sim, quando ele efetivamente move dinheiro. Um pagamento cancelado antes de qualquer tentativa não produz lançamento nenhum.

Por que a soma das parcelas é maior que o valor do produto?

Porque o comprador pagou os juros do parcelamento (interest_payer: "buyer") e eles entram no bruto de cada parcela. São dinheiro que passa pela sua conta mas não é seu — por isso aparecem em fee_details como installment_interest e saem do net_amount. Quando a organização paga o juro (interest_payer: "organization"), a soma das parcelas é igual ao valor do produto, e o mesmo componente installment_interest aparece em fee_details como uma dedução real do seu líquido. Nos dois casos o juro vai para quem o detém.

Um estorno zera a transação original?

Não. A transação da venda continua no extrato como aconteceu, com status refunded, e o estorno entra como um lançamento negativo separado. O extrato reflete o dinheiro se movendo, não a venda como um todo.

Onde vejo quanto a Chargefy cobrou nessa venda?

Em fee_details, dentro do movimento da parcela. Numa venda por plataforma, o lojista vê apenas a taxa da plataforma (platform_fee): como essa taxa se divide entre a plataforma e a Chargefy pertence ao movimento da plataforma, não ao dele.

Próximos passos

Objeto transaction

Contrato completo: campos, tipos, sinais, fee_details e liquidação.

Conciliar pagamentos

Como fechar o extrato com o que foi vendido.

Pagamentos vs. cobranças

O processo da venda e cada tentativa dentro dele.

Repassar a taxa ao comprador

O que muda no valor cobrado e no que você recebe.

Pagamentos online

Receber pagamentos

Clientes e faturamento

Assinaturas

Operação e pós-pagamento

Marketing e rastreamento

Pagamentos vs. transações

O exemplo que explica a diferença

Entradas e saídas

O que cada tipo de movimento significa

Para que serve cada um

Use o pagamento para

Use a transação para

Como os dois se ligam

Quando o dinheiro liquida

Perguntas frequentes

Próximos passos

Objeto transaction

Conciliar pagamentos

Pagamentos vs. cobranças

Repassar a taxa ao comprador

​O exemplo que explica a diferença

​Entradas e saídas

​O que cada tipo de movimento significa

​Para que serve cada um

Use o pagamento para

Use a transação para

​Como os dois se ligam

​Quando o dinheiro liquida

​Perguntas frequentes

​Próximos passos

Objeto transaction

Conciliar pagamentos

Pagamentos vs. cobranças

Repassar a taxa ao comprador

O exemplo que explica a diferença

Entradas e saídas

O que cada tipo de movimento significa

Para que serve cada um

Como os dois se ligam

Quando o dinheiro liquida

Perguntas frequentes

Próximos passos