Transações

Uma transaction é um lançamento no extrato da sua organização: quanto dinheiro entrou (ou saiu), quando liquida e o que foi descontado no caminho. Cada parcela de uma venda é um lançamento próprio e um estorno é um lançamento negativo — o extrato reflete o dinheiro se movendo, não a venda como um todo. A venda como experiência — parcelamento escolhido, juros, desconto — vive no payment intent. A transaction é a contabilidade: net_amount = amount - fee_amount, sempre, e fee_amount é a soma dos itens de fee_details.

Sinal dos valores

Entradas são positivas e saídas são negativas. A regra existe para que somar não tenha caso especial: somar net_amount de qualquer conjunto de movimentos dá o efeito líquido no seu saldo — sem inverter sinal por tipo, sem excluir estorno.

Campo	Pode ser negativo?
`amount`	Sim. Negativo quando o movimento tira dinheiro da conta (`type: "refund"`).
`net_amount`	Sim, pelo mesmo motivo — acompanha o sinal de `amount`.
`fee_amount`	Não. É sempre `0` ou positivo: representa quanto foi descontado, não a direção do movimento.
`fee_details[].amount`	Não. Sempre positivo.

Um estorno de R$ 50,00 aparece como amount: -5000, fee_amount: 0 e net_amount: -5000 — a taxa da venda original não é devolvida, então não há o que deduzir do movimento de saída.

Objeto transaction

Este é o formato completo retornado em get, itens de list e em data.object dos webhooks transaction.*.

{
  "id": "txn_9fK2mQ4xW7pLnR8s",
  "object": "transaction",
  "amount": 11000,
  "available_at": "2026-09-19T00:00:00Z",
  "created_at": "2026-07-20T14:32:11Z",
  "currency": "brl",
  "description": "Installment 2/10",
  "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,
  "livemode": true,
  "metadata": {},
  "net_amount": 9601,
  "payment_intent": "pi_M2nQ7xW4pL9kR3sT",
  "settled_at": null,
  "source": "ch_Q7xW4pL9kR3sTM2n",
  "status": "pending",
  "type": "charge",
  "updated_at": null
}

string

Identificador único do movimento. Usa o prefixo txn_*.

string

Sempre "transaction".

integer

O bruto do movimento em centavos: todo o dinheiro que entrou (ou saiu) antes dos componentes de fee. É de onde fee_amount é descontado para chegar em net_amount.O que ele representa muda com o tipo do movimento:

Parcela de venda (charge): a fatia daquela parcela no total pago pelo comprador — incluindo juros de parcelamento, quando houver. Numa venda de R$ 1.100,00 em 10x, cada movimento tem amount: 11000.
Fee (platform_fee, chargefy_fee): o valor bruto da fee daquela parcela, antes do custo de quem a recebe.
Estorno (refund): valor negativo — é dinheiro saindo da conta. Um estorno de R$ 50,00 tem amount: -5000.

Nunca é 0: movimento sem dinheiro não vira lançamento.

string | null

Previsão de liquidação (ISO 8601). null enquanto a data depende da conciliação. Quando o movimento liquida, settled_at traz a data efetiva — compare os dois para medir atraso.

string

Data de criação em formato ISO 8601.

string

Moeda em minúsculas. Hoje sempre brl.

string | null

Rótulo derivado do movimento, quando aplicável (ex.: Installment 2/10, Refund).

integer

Total descontado do bruto, em centavos. 0 quando não há desconto. Nunca é negativo — é a soma exata dos itens de fee_details.

array

Decomposição tipada do fee_amount. Vazio quando não há desconto. Cada item diz por que aquele valor saiu do bruto.

`type`	O que é	Quando aparece
`chargefy_fee`	A taxa de processamento cobrada pela Chargefy.	Em venda direta, no movimento do lojista. Em venda por plataforma, no movimento de fee da plataforma — é o custo dela.
`platform_fee`	A taxa cobrada pela plataforma ao lojista conectado.	No movimento do lojista, quando a venda acontece por uma plataforma. Substitui `chargefy_fee` ali: o lojista paga uma taxa só, a da plataforma.
`installment_interest`	Os juros de parcelamento pagos pelo comprador.	Em parcelamento com juros. É dinheiro que entra no bruto da parcela mas não pertence ao lojista, por isso aparece como componente de fee.
`provider_fee`	O custo de processamento retido na liquidação.	No movimento de fee da Chargefy, que é quem absorve esse custo. Aparece também no movimento do lojista em vendas antigas, quando o custo era retido direto do recebível dele.

O lojista nunca vê como a taxa que ele paga se divide entre a plataforma e a Chargefy — essa decomposição pertence ao movimento da plataforma, não ao dele.

Show atributos

integer

Valor do item, em centavos. Sempre positivo.

string | null

Rótulo legível do item.

string

Natureza do componente de fee, conforme a tabela acima.

integer | null

Número da parcela (1-based). null em movimentos não parcelados.

integer | null

Total de parcelas da venda. null em movimentos não parcelados.

boolean

false em modo de teste.

object

Sempre {} — metadados vivem no payment intent.

integer

Líquido do movimento, em centavos, com sinal: amount - fee_amount. É o que impacta o extrato — some este campo para fechar caixa.

string | null

Pagamento que originou o movimento, quando houver. É por onde se chega na venda como experiência: parcelas escolhidas, juros e desconto.

string | null

Quando o movimento liquidou de fato. null enquanto pendente.

string | null

O objeto que causou o movimento. É a ponte entre o extrato e o evento de negócio que o originou.

Prefixo	Objeto	Aparece em
`ch_`	Charge — a cobrança aprovada	Movimentos de venda (`charge`) e de fee (`platform_fee`, `chargefy_fee`)
`re_`	Refund — o reembolso	Movimentos de estorno (`refund`)

Use para agrupar: todos os movimentos com o mesmo ch_ pertencem à mesma cobrança — em venda parcelada, são as N parcelas.

string

Situação do movimento.

Valor	Significado
`pending`	Ainda não liquidou. A previsão está em `available_at`.
`paid`	Liquidado. `settled_at` traz a data efetiva.
`canceled`	Não vai liquidar — a cobrança de origem não se concretizou. Não entra em soma de saldo.
`refunded`	A venda foi estornada. O débito correspondente é um movimento próprio, de `type: "refund"`.

string

A natureza do movimento — “que dinheiro é esse”. Quais você recebe depende do papel da sua organização: um lojista vê as vendas e os estornos dele; uma plataforma vê, além dos próprios, a platform_fee que cobra das organizações conectadas.

Valor	O que é	Sinal	Quem recebe
`charge`	Uma parcela de uma venda aprovada. Venda à vista gera um; venda em 10x gera dez.	Positivo	O lojista que vendeu
`refund`	O débito de um estorno. Não é parcelado: o estorno sai de uma vez.	Negativo	O lojista que estornou
`platform_fee`	A taxa que a plataforma cobrou naquela parcela.	Positivo	A plataforma
`chargefy_fee`	A taxa de processamento da Chargefy naquela parcela.	Positivo	A Chargefy — nunca aparece para você

Um mesmo pagamento gera movimentos diferentes para cada parte, e cada uma só enxerga os seus. Numa venda por plataforma, o lojista recebe o charge com a taxa que ele pagou; a plataforma recebe o platform_fee com a fee dela. Nenhum dos dois vê o movimento do outro.

string | null

Última atualização em formato ISO 8601.

Operações

O extrato é somente leitura: os movimentos nascem do processamento de pagamentos, nunca de uma chamada do parceiro.

Eventos

Mudanças nesse objeto disparam os seguintes eventos:

O payload carrega o objeto transaction completo em data.object.

Como se relaciona

transaction é o recurso público do extrato financeiro. Use payment_intent para decidir o estado do pagamento e charge para investigar a tentativa concreta. Use Transaction para explicar bruto, taxas, líquido, parcelas, previsão e liquidação.

Lifecycle financeiro

Relação entre Payment Intent, Charge e Transaction.

Conciliar pagamentos

Como ligar pedidos, movimentos, taxas e liquidação.

Fundamentos da API

Objetos de sistema

Webhooks e eventos

SDKs

MCP

Sinal dos valores

Objeto transaction

Operações

Eventos

Como se relaciona

Lifecycle financeiro

Conciliar pagamentos

​Sinal dos valores

​Objeto transaction

​Operações

​Eventos

​Como se relaciona

Lifecycle financeiro

Conciliar pagamentos

Sinal dos valores

Objeto transaction

Operações

Eventos

Como se relaciona