Conciliação de pagamentos com várias adquirentes

Conciliação de pagamentos é conferir se cada valor recebido corresponde a um pedido do seu sistema e a um lançamento no extrato, com o valor e a taxa certos. Com várias adquirentes, o trabalho costuma dobrar: cada uma tem o próprio formato de dados, de webhook e de extrato. Na xFlow Payments, as cobranças passam por 11 adquirentes, mas voltam sempre no mesmo formato, com os campos que amarram a conciliação de ponta a ponta.

Por que conciliar fica difícil com várias adquirentes

• Formatos diferentes. Cada adquirente nomeia campos e status de um jeito.
• Identificadores diferentes. O id da cobrança de uma não conversa com o da outra.
• Webhooks diferentes. Cada uma avisa o pagamento num formato próprio.
• Taxas em lugares diferentes. Saber o líquido de cada venda exige cruzar relatórios.

Quando a orquestração de pagamentos padroniza as respostas, a conciliação passa a ter um formato só.

Os campos que amarram a conciliação na xFlow

customer e payer não são a mesma coisa

customer é o que você informou. payer é quem pagou de fato, segundo o provedor na confirmação. Um pedido pode estar no nome de uma pessoa e ser pago por outra. Para conciliar com o extrato, use payer junto com pix.endToEnd, o End-to-end ID do Pix.

Passo a passo de uma conciliação diária

1. Dê baixa pelo webhook. Ao receber transaction.paid, valide a assinatura, confira livemode: true e marque o pedido do external_reference como pago. O guia de webhook Pix mostra a validação.
2. Liste as cobranças pagas do dia. Chame GET /api/v1/charges?status=paid&from=...&to=... e percorra as páginas com o cursor.
3. Cruze com os seus pedidos. Cada cobrança paga precisa de um pedido pago no seu sistema, pelo external_reference. Diferenças indicam webhook perdido ou baixa manual.
4. Cruze com o extrato. Use pix.endToEnd e payer para ligar cada cobrança ao lançamento correspondente.
5. Confira os estornos. Liste status=refunded no período e consulte o campo refund de cada cobrança em GET /api/v1/charges/{id}.
6. Confira os saques. Liste os saques concluídos com GET /api/v1/transfers?status=completed&from=...&to=....
7. Feche o saldo. Compare o resultado com GET /api/v1/balance, que mostra o saldo disponível e o reservado.

Exemplo: listar as cobranças pagas de um período

curl "https://app.xflowpayments.com/api/v1/charges?status=paid&from=2026-10-24&to=2026-10-25&limit=100" \
  -u "pk_live_...:sk_live_..."

A resposta traz data e has_more. Enquanto has_more for true, repita a chamada com starting_after igual ao id do último item:

async function cobrancasPagas(de, ate, cred) {
  const todas = [];
  let cursor = null;
  do {
    const url = new URL("https://app.xflowpayments.com/api/v1/charges");
    url.searchParams.set("status", "paid");
    url.searchParams.set("from", de);
    url.searchParams.set("to", ate);
    url.searchParams.set("limit", "100");
    if (cursor) url.searchParams.set("starting_after", cursor);
    const res = await fetch(url, { headers: { Authorization: "Basic " + cred } });
    const pagina = await res.json();
    todas.push(...pagina.data);
    cursor = pagina.has_more ? pagina.data[pagina.data.length - 1].id : null;
  } while (cursor);
  return todas;
}

A listagem traz os dados de conciliação (payer, pix.endToEnd e paidAt), mas não traz o QR Code, o copia e cola nem o campo refund, que aparecem só na consulta por id. O limite por página vai de 1 a 100.

Conciliar saques

Cada saque tem id, status, amount, net_amount e fee. Os status são requested, processing, completed e rejected. Os webhooks withdrawal.processing, withdrawal.completed e withdrawal.failed avisam cada mudança. A listagem GET /api/v1/transfers usa a mesma paginação por cursor das cobranças. No saque por chave Pix, a taxa sai do próprio valor; no saque por QR Code, a taxa é debitada por cima do valor do QR. O guia de API de saque Pix explica os dois casos.

Conciliar estornos

O estorno é assíncrono. A resposta 202 com status: "pending" significa que o provedor aceitou o pedido, mas o dinheiro ainda não voltou ao pagador. Enquanto o estorno está pendente, o valor líquido fica retido do saldo disponível. O desfecho chega por webhook:

• transaction.refunded: a devolução concluiu e a cobrança passa a refunded;
• transaction.refund_failed: o provedor recusou, a cobrança continua paid e o valor retido volta ao saldo.

Taxas e reserva

GET /api/v1/company traz as taxas da sua conta, como o percentual e o valor fixo do Pix e do saque, além do percentual e do prazo de reserva. Use esses dados para conferir o fee de cada cobrança e o saldo reservado.

No painel

Se a conciliação for feita por alguém sem acesso à API, o painel mostra vendas, recebimentos, saques e indicadores em um só lugar. Em Integrações > Logs da API, cada chamada fica registrada por 30 dias, com status, duração e código de erro.

Erros comuns na conciliação

• Dar baixa com evento de teste. Eventos do sandbox chegam com livemode: false. Filtre antes de marcar pedido real como pago.
• Confiar só no customer. Quem pagou está em payer, que pode ser outra pessoa.
• Esquecer a paginação. Sem seguir o has_more, a lista fica incompleta.
• Ler payer cedo demais. Ele fica null enquanto a cobrança está pendente.

Para entender por que o formato único importa quando o Pix passa por vários provedores, leia orquestração de Pix com vários PSPs. Os endpoints completos estão na documentação e na página da API Pix.