Arquivo da Carta de Circularização

Este documento descreve a estrutura do arquivo gerado pela carta de circularização — a demonstração dos valores a receber de um estabelecimento comercial em uma data-base — e explica como solicitar, acompanhar e baixar o arquivo pela API.

---

#1. Introdução

#1.1 Objetivo

A carta de circularização é o documento que demonstra, para um estabelecimento comercial (EC), quanto ele tem a receber da subadquirente em uma data-base — o saldo da agenda de recebíveis, totalizado por arranjo de pagamento. É usada tipicamente para conferência contábil e para confirmação de saldos junto à auditoria.

Este documento descreve o layout do arquivo e o fluxo de geração. Ele não descreve o detalhamento transação a transação: para isso existe o arquivo Detalhes da circularização, cuja estrutura está descrita no documento Arquivo de Agenda e Liquidação SC3.

#1.2 O que a carta informa

Cada linha do arquivo é um arranjo de pagamento (Visa crédito, Mastercard crédito, Elo débito etc.) com três informações consolidadas: o valor bruto a receber, o valor líquido a receber e a data do último recebível daquele arranjo na agenda. Não há detalhamento por transação, por parcela nem por data.

#1.3 Nomenclatura e convenções

• O arquivo é .CSV, codificado em UTF-8, e existe em dois formatos — um por lojista e um consolidado mensal, descritos nas seções 3 e 4. O separador e a unidade dos valores mudam entre os dois formatos.

• As duas primeiras linhas são de controle: a primeira traz os parâmetros da geração e a segunda os nomes das colunas. As linhas seguintes são de detalhe, uma por arranjo.

• Datas seguem o padrão AAAA-MM-DD; data e hora seguem AAAA-MM-DDTHH:MM:SS, no fuso da subadquirente.

• A geração é assíncrona: a solicitação responde imediatamente com o nome do arquivo, que passa a existir alguns instantes depois (seção 2).

---

#2. Como obter o arquivo

O passo 2 é opcional para quem só quer o arquivo, mas é o caminho mais rápido para quem quer apenas os números: a listagem já devolve os valores por arranjo e o totalizador, sem precisar baixar e interpretar o CSV.

#2.1 Correspondência entre os campos da API e o arquivo

⚠️ Atenção aos nomes. Na API, adjusted_amount é o valor bruto e constituted_amount é o valor líquido. Os nomes não correspondem aos conceitos de “valor ajustado” e “valor constituído” usados pelas registradoras de recebíveis.

---

#3. Formato 1 — Carta por lojista

É o formato gerado quando a carta é solicitada para um CPF/CNPJ específico, pela API ou pelo Portal do Lojista. Contém apenas os arranjos daquele lojista e não tem linha de totais.

Carta de circularização - ,71673990000177,Data inicial de pesquisa: 2026-08-01
Data do ultimo recebivel,Arranjo,Valor liquido,Valor bruto
2026-11-11,MCC,208629,92,211940,10
2026-08-20,VCC,542,67,551,30
2026-09-03,ECD,1204,55,1204,55

#3.1 Linha 1 — parâmetros da geração

#3.2 Linha 2 — cabeçalho das colunas

Texto fixo: Data do ultimo recebivel,Arranjo,Valor liquido,Valor bruto. Observe que, neste formato, o valor líquido vem antes do valor bruto.

#3.3 Linhas de detalhe — uma por arranjo

⚠️ Importante para quem automatiza a leitura. Neste formato o valor usa vírgula como separador decimal e o arquivo também é separado por vírgula. Consequência prática: cada valor ocupa duas posições ao abrir o arquivo sem tratamento, e uma linha de detalhe tem 6 posições, não 4. Ao interpretar o arquivo, reagrupe as posições 3–4 (valor líquido) e 5–6 (valor bruto), ou prefira consumir os valores pela API (seção 2), onde vêm em centavos e sem ambiguidade.

---

#4. Formato 2 — Carta mensal consolidada

É o formato gerado automaticamente no primeiro dia de cada mês, para as subadquirentes que têm a geração mensal habilitada. Consolida vários lojistas em um único arquivo — um bloco de linhas por CPF/CNPJ — e traz uma linha de totais no final.

Carta de circularização;2;2026-08-01T02:00:00;2026-08-02
CPF/CNPJ;Arranjo;Valor bruto;Valor liquido
71673990000177;MCC;21194010;20862992
71673990000177;VCC;55130;54267
24276000000119;MCC;3410055;3355120
;;24659195;24272379

#4.1 Linha 1 — parâmetros da geração

#4.2 Linha 2 — cabeçalho das colunas

Texto fixo: CPF/CNPJ;Arranjo;Valor bruto;Valor liquido. Neste formato o valor bruto vem antes do valor líquido — ordem inversa à do formato 1.

#4.3 Linhas de detalhe — uma por lojista e arranjo

#4.4 Última linha — totais

A última linha traz as duas primeiras posições vazias e, nas posições 3 e 4, a soma do valor bruto e do valor líquido de todos os lojistas e arranjos do arquivo, em centavos: ;;24659195;24272379.

---

#5. Diferenças entre os dois formatos

Como os dois formatos compartilham o mesmo padrão de nome de arquivo, quem automatiza a leitura deve identificar o formato pelo separador da primeira linha, e não pelo nome.

---

#6. Tabela 1 — Códigos de arranjo

A coluna Arranjo usa a sigla do arranjo de pagamento, conforme definido pela Resolução BCB nº 3.952, mais PVT para cartão private. Siglas em uso na plataforma:

---

#7. Tabela 2 — Status da carta

---

#8. Regras de composição dos valores

• O que entra. Todos os recebíveis do lojista com data de agenda igual ou posterior à data-base da pesquisa, agrupados por arranjo.

• Devoluções não entram. Recebíveis do arranjo de devolução (RFD) são desconsiderados na composição da carta.

• A carta é uma posição, não um histórico. Os valores refletem o estado da agenda no momento da geração. Duas cartas geradas em datas diferentes para a mesma data-base podem divergir se houver cancelamento, ajuste ou antecipação no intervalo — e a carta não reconstitui a posição de uma data passada.

• Valor bruto e valor líquido. O bruto é o valor da venda antes das taxas; o líquido é o valor a ser efetivamente pago ao lojista. A diferença corresponde ao MDR, às taxas de antecipação e às retenções aplicáveis.

• Antecipação. Recebíveis já antecipados deixam a agenda futura e, portanto, não compõem mais o valor a receber demonstrado na carta.

• Endereço de download temporário. A URL devolvida pelo endpoint de download expira em 5 minutos. Gere-a no momento do download em vez de armazená-la.

---

#9. Histórico de revisões