CNAB File Reader

What is CNAB?

CNAB is the Brazilian standard for banking interchange files, covering collection, payments and returns. Keep in mind that each bank ends up adopting small variations of its own.

Every line in the file is a fixed-width record (240 or 400 chars). The record type sits in the first character: 0=header, 1=batch header, 3=detail (with A/B/C/... sub-segments), 5=batch trailer, 9=trailer.

Here you can see the count per type and the content of the first lines, enough for a visual inspection. For an actual integration, reach for bank-specific libs.

What is CNAB and why it exists

CNAB stands for Centro Nacional de Automação Bancária (National Center for Banking Automation), a standardization committee created by FEBRABAN (Federação Brasileira de Bancos, the Brazilian Federation of Banks) to unify how Brazilian banks and corporate clients exchange financial information by file. Before CNAB, every bank had its own proprietary layout for collection slips, supplier payments and direct debit, forcing companies to maintain a different ERP integration for each institution. CNAB consolidates those layouts into a single positional text specification used by Banco do Brasil, Caixa, Itau, Bradesco, Santander, BTG Pactual, Banrisul, Sicoob, Sicredi, C6, Inter and dozens of other Brazilian banks.

A CNAB file is a plain-text ASCII file (no JSON, no XML, no delimiters) where every line, called a registro (record), has a fixed width and every field occupies fixed character positions. Numeric fields are right-aligned and zero-padded; alphanumeric fields are left-aligned and space-padded. There are no headers in the CSV sense and no field separators, which is why a parser that does not know the layout cannot interpret a single byte of the file. The trade-off is brutal compactness and deterministic parsing speed, properties banks valued in the 1980s when CNAB was conceived for mainframes and dial-up modems, and that still benefit modern high-volume batch processing.

This reader detects whether a file follows the 240-character or 400-character layout, splits it into records, identifies registro types and surfaces the key fields so you can audit a remessa before sending it to the bank or reconcile a retorno that just landed in your SFTP inbox.

CNAB 240 vs CNAB 400: differences and when each is used

The two layouts coexist because they were born for different generations of banking products. CNAB 400 is the older specification: each transaction is one flat 400-character line, with no concept of batches. It is simple, easy to parse with a single loop and is still the only layout some legacy collection wallets accept, especially in regional banks and older Itau and Bradesco contracts. CNAB 400 supports cobranca (boleto issuance and reconciliation), with limited room for additional services.

CNAB 240 is the modern hierarchical layout. Each line is 240 characters and records are organized into lotes (batches), so a single file can carry multiple product types: collection slips in lote 1, supplier payments in lote 2, payroll in lote 3, tax payments (DARF, GPS, FGTS) in lote 4, all under one file header and trailer. CNAB 240 also introduced segment records (P, Q, R, S, T, U, Y) inside the detail rows, which let banks add structured extensions without breaking the base layout.

Choosing between them

• CNAB 400: legacy boleto contracts, very small companies, banks that have not migrated a specific wallet.
• CNAB 240: anything new, anything with multiple product types, anything with PIX QR Code in the boleto, anything with sustained protest or negativacao instructions.
• FEBRABAN officially recommends CNAB 240 for all new integrations; CNAB 400 is maintained for backward compatibility.

Structure: file header, batch header, detail, batch trailer, file trailer

CNAB 240 organizes a file as a nested envelope. Every record has its type identified at position 8 (one digit), and parsers use that single byte to dispatch the rest of the line to the right field map:

• 0 - Header de Arquivo: one line at the top, carries bank code (3 digits), agreement number, company CNPJ, file generation date and time, file sequence number and layout version.
• 1 - Header de Lote: opens a batch, identifies the service type (cobranca, pagamento de fornecedores, folha) and the form of release (credit in current account, DOC, TED, PIX, boleto, OP).
• 3 - Detalhe: one or more lines per transaction, broken into segments (P with the boleto identification, Q with the payer, R with discount and interest, S with sacador avalista, T and U for retorno).
• 5 - Trailer de Lote: closes the batch, contains record count and sum of values for reconciliation.
• 9 - Trailer de Arquivo: one line at the bottom, total record count across all batches and a final integrity quantity.

In CNAB 400 the hierarchy is flatter: one header at position 1, sequential transaction rows (record type 1 in cobranca remessa, type 1 in retorno with different meaning), and a trailer with totals. There are no batches and no segments.

0  Header de Arquivo
1  Header de Lote 1
3 P Detalhe boleto 001
3 Q Detalhe sacado 001
3 P Detalhe boleto 002
3 Q Detalhe sacado 002
5  Trailer de Lote 1
9  Trailer de Arquivo

Remessa vs retorno

CNAB traffic flows in two directions and the format is the same in both, but the meaning of fields changes:

• Remessa (company to bank): instructions you send. Register a new boleto, change a due date, grant a discount, request a protest, cancel an instruction, schedule a supplier payment, debit a payroll batch. The codigo de movimento remessa (positions 16-17 in many layouts) tells the bank what action to take: 01 entrada de titulos, 02 pedido de baixa, 06 alteracao de vencimento, 09 protestar, and so on.
• Retorno (bank to company): the bank's response. Each line tells you what happened: title liquidated, title received in custody, instruction rejected (with a reason code), payment confirmed, debit returned. The codigo de movimento retorno uses a different code table from remessa.

File extensions you will commonly see: .REM or .TXT for remessa, .RET or .TXT for retorno. Many banks also accept .CRM and .CRT. The extension is informational; the bank validates the actual layout.

Applications

Cobranca bancaria (boleto)

The classic use case. The company sends a remessa registering boletos, the bank prints or delivers them digitally, payers pay through any channel, and the bank returns a retorno confirming liquidacao. CNAB powers the entire boleto-registrado ecosystem that processes billions of reais per day in Brazil.

Pagamento de fornecedores

A single CNAB 240 file can release hundreds of supplier payments via DOC, TED, transferencia interna or PIX, with each segment carrying the beneficiary's bank, agency, account and CNPJ. The retorno confirms which payments cleared and which were rejected.

Debito automatico

Utility companies, schools and gyms send debito automatico instructions to charge clients' accounts on a recurring basis. CNAB transports the authorization registration, the monthly debit batch and the rejection retorno when there is insufficient balance.

Folha de pagamento

Salaries are still released through CNAB 240 in most medium and large Brazilian companies. The HR system generates the file, the bank credits each employee's account on the agreed date and returns a retorno per credit.

How to interpret fields

Reading a CNAB file by hand requires a layout chart, but a few patterns recur in almost every record:

• Tipo de registro: position 8 in CNAB 240, identifies header, batch, detail or trailer.
• Codigo do banco: positions 1-3, the FEBRABAN bank code (001 BB, 104 Caixa, 237 Bradesco, 341 Itau, 033 Santander).
• Codigo de movimento: 2 digits that tell remessa what to do or retorno what happened.
• Valor: 15 numeric digits, zero-padded, last 2 are the centavos. A boleto of R$ 1.234,56 appears as 000000000123456.
• Data: 8 digits in DDMMAAAA. A due date of 15/08/2026 is 15082026.
• Nosso numero: identifier assigned by the bank to each title, 11 to 20 digits depending on the bank and wallet.

Migration to CNAB 240 with PIX, and the future

FEBRABAN added PIX support to CNAB 240 starting in 2020. A boleto can now carry a PIX QR Code payload inside dedicated detail segments, so the same paper or PDF can be paid by PIX or by traditional boleto channels. Supplier payment lotes also support PIX as a release mode, with the beneficiary's PIX key (CPF, CNPJ, email, phone or random EVP) replacing the agency and account fields.

The medium-term direction is API-first: banks increasingly expose REST APIs with OAuth and real-time webhooks, and the Open Finance Brasil specification standardizes those APIs across institutions. For low-volume real-time flows, APIs win on latency and observability. CNAB remains dominant for high-volume daily batches because parsing is fast, files are easy to retransmit and audit, and entire ERPs are wired around the batch model.

SPB (Sistema de Pagamentos Brasileiro) is being modernized in parallel, but the message formats (ISO 20022 over the SPB rails) sit beneath CNAB rather than replacing it for client-bank communication. Expect CNAB to keep evolving in versioned layouts (current CNAB 240 v10.11 from 2023) for at least the rest of the decade.

FAQ

Why does my file open as a single line in some editors?

CNAB files use CRLF (Windows line ending) by default. If you open one in an editor that only recognizes LF, the records collapse into one huge line. Re-save with proper line endings or use a CNAB-aware tool.

Can I edit a CNAB file in a spreadsheet?

Strongly discouraged. Spreadsheets strip leading zeros from numeric columns, convert long numbers to scientific notation and break fixed-width alignment. Always edit CNAB in a fixed-width text editor or regenerate from the source system.

Is CNAB the same at every bank?

The skeleton is. Specific positions for proprietary fields (occurrence codes, wallet identifiers, free-use areas) vary, which is why every bank publishes its own manual on top of the FEBRABAN baseline.

How does CNAB compare with OFX?

OFX (Open Financial Exchange) is an XML/SGML-based format used mainly for bank statement download to personal finance software. CNAB is positional text used for instruction batches between corporations and banks. They solve different problems and do not overlap in practice.

Does this reader send my file to a server?

No. Parsing happens entirely in your browser using local JavaScript. The file never leaves your machine, which matters because CNAB content includes CNPJs, account numbers and amounts.