Conciliação
Quick Reference
O que é conciliação
Conciliação é o processo de vincular cada cobrança no seu sistema ao seu registro de liquidação correspondente. Isso garante que cada pagamento recebido foi liquidado corretamente, que as taxas foram aplicadas conforme esperado e que nenhum fundo está faltando.
Fluxo de conciliação
Buscar cobranças liquidadas
Consulte a API de listagem de cobranças com filtros de status de liquidação para obter todas as cobranças liquidadas em um determinado período.
Comparar com depósitos bancários
Compare os registros de liquidação com o extrato bancário. Cada lote de liquidação deve corresponder a um depósito.
Verificar detalhamento de taxas
Confirme que MDR, interchange e taxas de processamento estão de acordo com os termos do seu contrato.
Sinalizar discrepâncias
Identifique cobranças pagas mas ainda não liquidadas, ou valores liquidados que não correspondem aos valores líquidos esperados.
Consultar cobranças liquidadas
/api/v1/bank/wallet/charge/Bearer TokenListar cobranças com filtros de liquidaçãoUse o endpoint de listagem de cobranças com parâmetros de consulta para filtrar por status de liquidação e intervalo de datas:
- cURL
- Python
curl -G https://core-manager.a55.tech/api/v1/bank/wallet/charge/ \
-H "Authorization: Bearer $ACCESS_TOKEN" \
--data-urlencode "status=paid" \
--data-urlencode "settled=true" \
--data-urlencode "settled_after=2026-01-01T00:00:00Z" \
--data-urlencode "settled_before=2026-01-31T23:59:59Z" \
--data-urlencode "page_size=100"
import requests
response = requests.get(
"https://core-manager.a55.tech/api/v1/bank/wallet/charge/",
headers={"Authorization": f"Bearer {access_token}"},
params={
"status": "paid",
"settled": "true",
"settled_after": "2026-01-01T00:00:00Z",
"settled_before": "2026-01-31T23:59:59Z",
"page_size": 100,
},
)
charges = response.json()["results"]
for charge in charges:
net = charge["gross_amount"] - charge["total_fees"]
assert abs(net - charge["net_amount"]) < 0.01, f"Mismatch on {charge['charge_uuid']}"
Campos do relatório de liquidação
Cada cobrança no relatório de liquidação inclui:
| Campo | Descrição |
|---|---|
charge_uuid | Identificador único da cobrança |
type | Método de pagamento (credit_card, pix, boleto, etc.) |
status | Status da cobrança (paid, refunded, etc.) |
gross_amount | Valor original da cobrança |
mdr_amount | Taxa MDR deduzida |
interchange_amount | Taxa de interchange (apenas pagamentos com cartão) |
processing_fee | Taxa de processamento por transação |
fx_fee | Taxa de conversão de moeda (apenas transações internacionais) |
net_amount | Valor depositado na sua conta |
settled_at | Data e hora em que a liquidação foi concluída |
settlement_batch_id | Agrupa cobranças liquidadas na mesma transferência bancária |
chargeback_amount | Valor deduzido devido a chargebacks (se houver) |
Tratamento de disputas
Deduções de chargeback
Quando um portador de cartão contesta uma cobrança e a disputa é perdida, o valor do chargeback é deduzido do próximo lote de liquidação:
| Componente da dedução | Descrição |
|---|---|
| Valor original da cobrança | Valor total da transação devolvido ao portador do cartão |
| Taxa de chargeback | Taxa administrativa por chargeback (depende do contrato) |
| Reversão do interchange | Interchange original devolvido ao emissor |
Taxas elevadas de chargeback (acima de 1% das transações) podem gerar taxas adicionais, retenções ou revisão da conta. Implemente medidas de prevenção a fraudes para minimizar disputas.
Boas práticas para conciliação automatizada
Conciliação diária
Execute a conciliação diariamente para detectar problemas cedo:
from datetime import date, timedelta
yesterday = date.today() - timedelta(days=1)
settled = fetch_settled_charges(date=yesterday)
deposits = fetch_bank_deposits(date=yesterday)
settled_total = sum(c["net_amount"] for c in settled)
deposit_total = sum(d["amount"] for d in deposits)
if abs(settled_total - deposit_total) > 0.01:
alert_finance_team(settled_total, deposit_total, yesterday)
Checklist de conciliação
| Verificação | O que verificar |
|---|---|
| Completude | Toda cobrança paid possui um registro de liquidação correspondente |
| Precisão | Valor líquido = bruto - MDR - interchange - processamento - FX |
| Pontualidade | Cobranças são liquidadas dentro da janela esperada para o método |
| Chargebacks | Todas as deduções de chargeback correspondem aos registros de disputa |
| Conferência bancária | Total de liquidações líquidas corresponde aos depósitos bancários do período |
Idempotência
Sempre realize a conciliação usando charge_uuid e settlement_batch_id como chaves únicas. Se você reprocessar um relatório de liquidação, esses IDs evitam lançamentos duplicados no seu sistema contábil.
Conciliação multi-provedor
A A55 agrega dados de liquidação de mais de 29 adquirentes, cada um com formatos de relatório e prazos diferentes. A API normaliza tudo isso em um esquema consistente. No entanto, alguns provedores liquidam semanalmente em vez de diariamente — se você notar uma lacuna nas liquidações diárias para um método de pagamento específico, verifique o ciclo de liquidação do provedor no seu contrato.