> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chargefy.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Conciliar pagamentos

> Conecte pedido, cobrança e extrato para explicar quanto foi pago, o que foi descontado e quando liquida.

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.

| Etapa | Objeto             | O que você reconcilia                       |
| ----- | ------------------ | ------------------------------------------- |
| 1     | Seu pedido         | A referência de negócio no seu sistema.     |
| 2     | `checkout.session` | A tentativa de compra ligada ao pedido.     |
| 3     | `payment_intent`   | O estado consolidado da cobrança.           |
| 4     | `charge`           | A tentativa concreta que aprovou ou falhou. |
| 5     | `transaction`      | Bruto, taxas e líquido; há uma por parcela. |
| 6     | Conta para saques  | A liquidação do valor líquido.              |

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

| Pergunta                                   | Fonte principal    | O que observar                                                                    |
| ------------------------------------------ | ------------------ | --------------------------------------------------------------------------------- |
| Qual compra o cliente iniciou?             | `checkout.session` | Itens, customer, metadata, `status` e `payment_status`.                           |
| Qual é o estado da cobrança?               | `payment_intent`   | Método, valor, `status`, `latest_charge` e erro mais recente.                     |
| O que aconteceu em cada tentativa?         | `charge`           | Aprovação, captura, falha e valor movimentado.                                    |
| Como a venda foi calculada?                | `payment_intent`   | Principal, juros, parcelas, repasse e total.                                      |
| Quanto entra na conta e quando?            | `transaction`      | Bruto, taxa detalhada, líquido, parcela, `available_at`, `settled_at` e `status`. |
| Qual ciclo recorrente originou a cobrança? | `invoice`          | Período, motivo, saldo, payment intent e assinatura.                              |

## 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](/api-reference/transactions/object) 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

<Steps>
  <Step title="Correlacione a venda">
    Envie sua referência de pedido em `client_reference_id` — no create da
    checkout session ou anexada à URL do payment link
    (`?client_reference_id=…`) — e ela volta no objeto da sessão e nos webhooks
    `checkout.session.*`. Use `metadata` para pares adicionais e persista os
    IDs públicos retornados: checkout session, payment intent, charge,
    transaction e invoice quando existirem.
  </Step>

  <Step title="Feche o resultado da cobrança">
    Use webhooks para atualizar o payment intent e suas charges. Uma tentativa
    falha não significa que o pedido terminou se o mesmo intent ainda pode
    receber outro método.
  </Step>

  <Step title="Importe a composição financeira">
    Consulte transactions pelo período e compare principal, juros, descontos,
    taxas e total com o pedido e seus relatórios internos.
  </Step>

  <Step title="Projete e confirme caixa">
    Liste transactions por `available_at` e status. Quando chegarem a `paid`,
    registre `settled_at` e compare o valor com a conta para saques.
  </Step>

  <Step title="Trate exceções">
    Separe falhas de cobrança, divergência de valor, movimento atrasado,
    reembolso e disputa em filas operacionais diferentes.
  </Step>
</Steps>

## Status que merecem atenção

| Sinal                                                | Leitura operacional                                                                                               |
| ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| Payment intent `succeeded`, sem movimento no extrato | Aguarde o processamento normal por um intervalo curto; se persistir, investigue a charge e o request relacionado. |
| Transaction `pending` antes de `available_at`        | Valor ainda dentro da agenda prevista.                                                                            |
| Transaction `pending` depois de `available_at`       | Exceção de liquidação; abra investigação com os IDs relacionados.                                                 |
| Transaction `paid`                                   | Valor liquidado; use `settled_at` para fechar o dia.                                                              |
| Transaction `canceled`                               | Valor não será liquidado. Verifique cancelamento, falha ou reversão da cobrança.                                  |
| Transaction `refunded`                               | A liquidação foi afetada por reembolso; reconcilie com o objeto refund e a charge.                                |

## 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](/api-reference/requests/object) mostra path, status HTTP, erro e objetos gerados com campos sensíveis mascarados. A página de [Eventos](/api-reference/events/object) ajuda a verificar quais transições foram emitidas.

<CardGroup cols={2}>
  <Card title="Transactions" icon="calculator" href="/api-reference/transactions/object">
    Consulte a matemática financeira de cada venda.
  </Card>

  <Card title="Transactions" icon="calendar-days" href="/api-reference/transactions/object">
    Acompanhe parcelas, previsão e liquidação.
  </Card>

  <Card title="Reembolsos" icon="arrow-rotate-left" href="/payments/refunds">
    Entenda como a devolução afeta o fluxo financeiro.
  </Card>

  <Card title="Request Logs" icon="magnifying-glass" href="/api-reference/requests/object">
    Investigue chamadas e objetos relacionados.
  </Card>
</CardGroup>