Conciliar pagamentos

Conciliação responde três perguntas diferentes: o pagamento foi aprovado?, como o valor foi composto? e quanto entra na conta, em qual data? Nenhum objeto responde tudo sozinho. Uma cobrança direta pode começar no payment_intent, sem checkout session. Uma cobrança recorrente também se liga a subscription e invoice. O trecho financeiro a partir da charge continua o mesmo.

​

Qual objeto consultar

​

Entenda a matemática da venda

No payment intent, valores monetários são inteiros em centavos:

• principal_amount: valor do produto ou serviço, sem repasse de taxa nem juros;
• installment_interest_amount: juros pagos pelo comprador;
• installments: número de parcelas escolhido;
• surcharge_amount: repasse de taxa pago pelo comprador, quando houver;
• amount: total pago pelo comprador (principal_amount + surcharge_amount + installment_interest_amount).

A composição é resolvida no próprio intent quando o método e o parcelamento são escolhidos. A charge congela a mesma composição usada naquela tentativa.

​

Entenda o extrato

Cada transaction é um movimento de dinheiro. Uma venda em 10× gera 10 transactions — uma por parcela — e um estorno gera um movimento negativo. Cada uma traz:

• amount: bruto do movimento, com sinal (saídas são negativas);
• fee_amount e fee_details: o total descontado e a decomposição item a item;
• net_amount: o líquido, sempre amount - fee_amount;
• installment de installment_count: qual parcela é;
• available_at: previsão de liquidação; settled_at: quando liquidou;
• status: pending, paid, canceled ou refunded.

Como as saídas entram negativas, somar net_amount de uma listagem filtrada é somar o extrato — sem casos especiais. Use a referência de Transaction como contrato e não recalcule taxas a partir de percentuais comerciais: o movimento já traz os valores efetivamente aplicados. O valor é direcionado à conta para saques principal cadastrada; esse cadastro não garante o crédito. Confirme cada liquidação no extrato bancário e não modele uma fila de saques.

​

Fluxo diário de conciliação

​

Status que merecem atenção

​

Reembolsos e disputas

Não altere ou apague a venda original em seu razão interno. Registre reembolso e disputa como movimentos relacionados:

• ligue refund à charge e ao pedido;
• acompanhe o status do refund até seu estado final;
• atualize a previsão quando movimentos forem cancelados ou reembolsados;
• preserve valores originais da transaction para auditoria;
• mantenha evidências e prazos da disputa fora do fluxo de liquidação cotidiana.

​

Plataformas

Uma organização conectada enxerga a taxa única acordada com a plataforma. Cada movimento é visível para o seu dono: a organização vê a venda dela; a plataforma vê a própria platform_fee. Não tente reconstruir margens que o contrato não expõe ao contexto atual. Sempre mantenha o organization de origem junto aos IDs financeiros. Isso evita conciliar vendas de sellers diferentes na mesma linha ou aplicar um evento ao ledger errado.

​

Investigação

Quando houver divergência, comece pelo ID do seu pedido e atravesse os objetos relacionados. O recurso Request mostra path, status HTTP, erro e objetos gerados com campos sensíveis mascarados. A página de Eventos ajuda a verificar quais transições foram emitidas.