Pular para o conteúdo principal
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 dos movimentos de uma mesma moeda dá o efeito líquido nesse saldo — sem inverter sinal por tipo, sem excluir estorno. Um estorno de R$ 50,00 numa venda com R$ 1,49 de taxa aparece como amount: -4851, fee_amount: 0 e net_amount: -4851 — a taxa da Chargefy é devolvida junto com o estorno, então sai só o líquido que tinha entrado e não há o que deduzir do movimento de saída.

Incentivo de cartão

Quando a condição comercial inclui incentivo de cartão, a organização recebe um desconto na taxa de cada venda no crédito. O valor efetivamente aplicado aparece em fee_details com type: "card_incentive" e sinal negativo. O total fee_amount já inclui esse desconto. Em um exemplo de venda de R$ 1.000,00, a taxa de R$ 39,90 e o incentivo de R$ 5,00 resultam em taxas de R$ 34,90 e líquido de R$ 965,10. O incentivo aplicado pode ser menor que o combinado. Consulte o valor de cada venda no extrato. Em vendas parceladas, ele é distribuído entre os lançamentos das parcelas. O estorno devolve proporcionalmente o que cada parte recebeu, considerando o incentivo aplicado na venda. O lançamento de estorno tem sua própria quantia negativa.

Objeto transaction

Este é o formato completo retornado em get, itens de list e em data.object dos webhooks transaction.*.
string
Identificador único do movimento. Usa o prefixo txn_*.
string
Sempre "transaction".
integer | null
Percentual da comissão de afiliado em pontos-base. Presente nos lançamentos da afiliada, inclusive nas devoluções; null nas demais linhas.
string | null
Vínculo da comissão de afiliado, quando o lançamento pertence à afiliada.
string | null
Organização que originou o movimento. Receber uma comissão de afiliado não concede acesso aos pagamentos ou compradores dessa organização.
string | null
Vínculo que recebeu esta comissão de afiliado; null nos outros descontos.
integer
O bruto do movimento na menor unidade da moeda: 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 os juros de parcelamento quando o comprador os paga (interest_payer: "buyer" no payment intent). Numa venda de R$ 1.000,00 em 10x com R$ 100,00 de juros pagos pelo comprador, cada movimento tem amount: 11000; se a organização pagasse o juro, o comprador pagaria R$ 1.000,00 e cada movimento teria amount: 10000.
  • 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 na liquidação do recebível. Para a previsão de depósito bancário, use expected_payout_at.
string
Data de criação em formato ISO 8601.
string
Código ISO 4217 em minúsculas da moeda do saldo que recebeu o lançamento. Os valores do lançamento estão na menor unidade dessa moeda.
string | null
Rótulo derivado do movimento, quando aplicável (ex.: Installment 2/10, Refund, Dispute, Dispute reversal). Em uma comissão de afiliado, identifica a organização que vendeu e a descrição da venda, sem dados do comprador.
number | null
Taxa da moeda da venda para a moeda do saldo. Retorna null quando as moedas são iguais. A Chargefy só processa vendas em real neste momento, então o campo retorna null.
string | null
Previsão de depósito na conta bancária, em ISO 8601. Representa o dia à meia-noite de Brasília, sem prometer um horário de crédito. Inicialmente é calculada como D+1 após a previsão do recebível, pulando sábados e domingos. Quando uma transferência pode ser vinculada ao movimento, sua data substitui a estimativa, inclusive se a tentativa falhar. Feriados não são calculados pela regra inicial. null quando não há dados suficientes, quando o movimento não representa um recebível ou quando a venda foi estornada ou contestada (chargeback) antes de um depósito concluído, inclusive quando o depósito voltou do banco, porque esse dinheiro não chega à conta. Estornada ou contestada depois do depósito, a data continua sendo a do dia em que o valor caiu. Este campo não comprova depósito bancário.
integer
Total descontado do bruto, na menor unidade da moeda. 0 quando não há desconto. Nunca é negativo — é a soma exata dos itens de fee_details.
array
Decomposição tipada do fee_amount. Cada item descreve uma cobrança ou um incentivo aplicado ao movimento.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.
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, na menor unidade da moeda, 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 recebível liquidou de fato. null enquanto pendente. Não comprova depósito na conta bancária; a previsão bancária está em expected_payout_at.
string | null
O objeto que causou o movimento. É a ponte entre o extrato e o evento de negócio que o originou.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.Numa disputa a venda continua paid: ela foi paga, e quem tira o dinheiro é a disputa, num movimento próprio (adjustment com source na disputa).
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.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.

Comissões de afiliados

O movimento affiliate_fee pertence à organização afiliada: amount e net_amount são o valor recebido, sem desconto adicional. A venda da organização que vendeu mostra um desconto affiliate_fee em fee_details por afiliada, identificado por affiliation. Dados do comprador ficam com quem vendeu; a afiliada consulta apenas seus próprios movimentos.