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: somarnet_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 emfee_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 emget, itens de list e em data.object dos webhooks transaction.*.
Percentual da comissão de afiliado em pontos-base. Presente nos lançamentos
da afiliada, inclusive nas devoluções;
null nas demais linhas.Organização que originou o movimento. Receber uma comissão de afiliado não
concede acesso aos pagamentos ou compradores dessa organização.
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 temamount: 11000; se a organização pagasse o juro, o comprador pagaria R$ 1.000,00 e cada movimento teriaamount: 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 temamount: -5000.
0: movimento sem dinheiro não vira lançamento.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.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.
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.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.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.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.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.
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.Pagamento que originou o movimento, quando houver. É por onde se chega na
venda como experiência: parcelas escolhidas, juros e desconto.
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.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.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).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.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 objetotransaction 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 movimentoaffiliate_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.
