Fundamentos de sistemas de pagamento: livros-razão, compensação e liquidação

A maioria dos engenheiros de software conhece pagamentos por meio de uma API: você envia uma requisição, recebe um status de volta e torce para que diga ACCEPTED. Essa visão resiste até o primeiro incidente em produção — um débito em duplicidade, um pagamento preso dois dias em PENDING, um arquivo de conciliação que não fecha — e aí é preciso abrir a abstração. Por baixo da API existe uma cadeia de instituições, livros-razão, horários de corte e obrigações legais, e quase todo comportamento estranho de uma API de pagamentos é o reflexo fiel de algo real nessa cadeia.

Este guia constrói o modelo de baixo para cima. Ele deixa de fora, de propósito, os cartões, que têm sua própria coreografia de quatro partes e são tratados em pagamentos com cartão, e também o acesso regulado de terceiros introduzido pela legislação europeia, tratado em PSD2 e open banking. O que vem a seguir é a base sobre a qual tudo isso se apoia.

Um pagamento é uma transferência de obrigações

O saldo exibido em um app de banco não é uma caixa de dinheiro com seu nome. É um passivo: um valor que a instituição deve a você, exigível à vista. Quando você paga alguém em outra instituição, nenhum valor é teletransportado. Seu banco reduz o que deve a você e, ao mesmo tempo, assume uma obrigação com o banco do beneficiário; o banco do beneficiário aumenta o que deve ao cliente dele. Agora os dois bancos estão desequilibrados um em relação ao outro, e essa diferença precisa ser acertada separadamente.

Esse acerto acontece em moeda de banco central — os saldos que os bancos comerciais mantêm no banco central, o único direito de crédito do sistema que não carrega risco de contraparte. Tudo o que um cliente de varejo vivencia é moeda de banco comercial, um direito de crédito contra uma instituição privada. Essa distinção explica muita coisa: por que a quebra de um banco é contagiosa, por que os sistemas de liquidação são operados por instituições públicas e por que "o pagamento foi enviado" e "o pagamento é final" são afirmações diferentes.

Três papéis se repetem em todo esquema: o pagador (cuja conta é debitada), o recebedor ou beneficiário (cuja conta é creditada) e um ou mais prestadores de serviços de pagamento agindo em nome deles. Um esquema é o regulamento que os prestadores aceitam: formatos de mensagem, prazos, responsabilidades e o que acontece quando algo dá errado.

Contas, livros-razão e partidas dobradas

A estrutura de dados central de todo sistema de pagamento é o livro-razão (ledger), e a disciplina que o mantém honesto é o método das partidas dobradas. Todo evento econômico é registrado como dois ou mais lançamentos cujos valores com sinal somam zero. Nada é atualizado no lugar; correções são novos lançamentos. Um saldo não é uma coluna que você sobrescreve, e sim a soma dos lançamentos em uma conta.

Transaction T-8841 — customer pays 250.00 EUR to a supplier

  account                       debit     credit
  --------------------------------------------- 
  customer:4711                250.00
  clearing:sepa-outbound                  250.00
                               ------    ------
                               250.00    250.00     -> balanced

As convenções confundem quem está começando porque são escritas do ponto de vista da instituição: o depósito de um cliente é um passivo do banco, então creditar a conta do cliente aumenta o que o banco deve. Em vez de discutir sinais, a maioria dos times de engenharia armazena um inteiro com sinal em unidades menores (centavos, não floats) e um indicador de direção, e deriva a apresentação contábil depois.

Um schema de livro-razão que sobrevive a uma auditoria costuma ter esta cara:

CREATE TABLE ledger_entry (
  id             BIGSERIAL PRIMARY KEY,
  transaction_id UUID        NOT NULL,
  account_id     BIGINT      NOT NULL,
  amount_minor   BIGINT      NOT NULL,   -- signed, in minor units
  currency       CHAR(3)     NOT NULL,
  booked_at      TIMESTAMPTZ NOT NULL DEFAULT now(),
  value_date     DATE        NOT NULL
);
CREATE INDEX ON ledger_entry (account_id, booked_at);
-- invariant, enforced in the write path and re-checked by a nightly job:
--   SELECT transaction_id FROM ledger_entry
--   GROUP BY transaction_id, currency HAVING SUM(amount_minor) <> 0;

Dois detalhes importam mais do que parecem. Nunca misture moedas dentro de uma mesma transação balanceada sem uma conta de câmbio explícita; caso contrário, o invariante de soma zero perde o sentido. E diferencie booked_at (quando seu sistema registrou o lançamento) de value_date (quando o dinheiro passa a valer economicamente) — juros, horários de corte e disputas dependem da segunda, não da primeira. Bloqueios e autorizações são modelados como lançamentos em uma conta dedicada a fundos reservados, de modo que o saldo disponível é uma consulta ao livro-razão, e não um campo mutável que pode divergir. Essas considerações se sobrepõem bastante a modelagem e normalização de bancos de dados; tabelas append-only com agregados derivados são a norma.

As famílias de instrumentos

Os instrumentos diferem principalmente em quem inicia, quem assume o risco de estorno e quanto tempo leva até a finalidade.

A distinção push versus pull é a que você precisa internalizar. Um instrumento push não consegue deixar no negativo uma conta que o pagador não controla, então a fraude tende a ser engenharia social. Um instrumento pull permite que um lojista tire dinheiro de uma conta, e os esquemas compensam isso com mandatos, pré-notificação e direitos generosos de reembolso — é por isso que uma cobrança por débito direto não é receita que você possa reconhecer com segurança no primeiro dia. Uma carteira digital não é um trilho à parte: é uma experiência de usuário montada sobre cartões, transferências ou um saldo armazenado, e seu perfil de risco é o do que estiver por baixo.

Compensação versus liquidação

Compensação (clearing) é a troca e a validação de ordens entre instituições, incluindo o cálculo de quem deve o quê. Liquidação (settlement) é a extinção final dessas obrigações. Os sistemas diferem na forma como combinam as duas.

Um sistema de liquidação bruta em tempo real (RTGS) liquida cada ordem individualmente e de imediato em moeda de banco central. Não há netting nem exposição de crédito entre participantes, mas cada pagamento precisa ter fundos no momento em que é feito, então os participantes precisam de muita liquidez intradia. Pagamentos de alto valor e urgentes funcionam assim.

Um sistema de liquidação líquida diferida acumula ordens ao longo de um ciclo e liquida apenas as posições líquidas.

Gross obligations during one clearing cycle (millions)

  A -> B  40      B -> A  25      A -> C  30
  C -> A  15      B -> C  20      C -> B  35

Multilateral net positions
  A:  pays 70, receives 40  ->  -30   (must fund 30)
  B:  pays 60, receives 75  ->  +15
  C:  pays 50, receives 65  ->  +15
                                ----
  sum of net positions            0   (always true)

Gross value exchanged 165, actual settlement 30 -> ~82% liquidity saving

O netting é extremamente eficiente e, na mesma medida, arriscado: entre o momento em que uma ordem é compensada e o momento em que o ciclo é liquidado, os participantes ficam expostos uns aos outros. Sistemas modernos mitigam isso com pré-financiamento, garantias, regras de divisão de perdas e ciclos mais curtos. Sempre que você encontrar uma restrição incomum em um esquema de pagamento — horários de corte, tetos de valor, pré-financiamento obrigatório —, ela quase sempre remonta à gestão dessa janela.

Identificando a conta: IBAN e BIC

Um IBAN identifica uma conta internacionalmente: um código de país de duas letras, dois dígitos verificadores e depois o identificador nacional da conta (o BBAN), com até 34 caracteres. Sua maior vantagem é que um erro de digitação pode ser detectado no cliente, antes de qualquer dinheiro se mover, com uma verificação módulo 97 definida na norma ISO.

IBAN:  GB11 ABCD 1234 5678 9012 34

1. Move the first four characters to the end:
   ABCD12345678901234 GB11
2. Replace each letter by its position in the alphabet + 9 (A=10 ... Z=35):
   1011121312345678901234161111
3. Take that (very large) integer modulo 97:
   1011121312345678901234161111 mod 97 = 1
4. A remainder of exactly 1 means the check digits are consistent.

Para gerar os dígitos verificadores em vez de verificá-los, coloque 00 na posição deles, calcule o resto da string reorganizada e use 98 - remainder. Como o número excede qualquer tipo inteiro nativo, as implementações o processam em blocos:

static int mod97(String rearranged) {
    int remainder = 0;
    for (int i = 0; i < rearranged.length(); i++) {
        char c = rearranged.charAt(i);
        int value = Character.isDigit(c) ? c - '0' : c - 'A' + 10;
        remainder = (remainder * (value > 9 ? 100 : 10) + value) % 97;
    }
    return remainder;
}
// valid when mod97(iban.substring(4) + iban.substring(0, 4)) == 1

Dígitos verificadores válidos provam apenas que a string é internamente consistente — não que a conta existe, está aberta ou pertence à pessoa informada. Um BIC (às vezes ainda chamado de código SWIFT) identifica a instituição, e não a conta: quatro letras para a instituição, duas para o país, duas para a localidade e um sufixo opcional de agência com três caracteres. Em muitos fluxos domésticos e europeus, o BIC hoje é derivado em vez de informado.

SEPA, correspondent banking e ISO 20022

Na zona do euro, a Área Única de Pagamentos em Euros (SEPA) harmonizou os pagamentos em euro em um pequeno conjunto de esquemas regidos por regulamentos públicos: um esquema de transferência a crédito, um esquema de débito direto nas variantes core e business-to-business, e um esquema de transferência instantânea que entrega os fundos em segundos, 24 horas por dia, até um teto definido pelo esquema. A consequência técnica dos esquemas instantâneos é pesada: não existe mais uma janela de processamento noturno para rodar checagens antifraude, triagem de sanções e gestão de liquidez, então tudo precisa acontecer inline, em algumas centenas de milissegundos, sem a opção de dizer "a gente corrige amanhã".

Pagamentos internacionais fora de um esquema comum usam correspondent banking (bancos correspondentes). Um banco que não tem conta no banco de destino roteia por um intermediário no qual mantém contas — uma conta nostro (nosso dinheiro com eles) espelhada pela conta vostro deles. Cada salto acrescenta uma tarifa, um horário de corte e uma etapa de triagem, e é por isso que pagamentos internacionais tradicionais são lentos e que rastreá-los é um produto por si só.

A troca de mensagens em todos esses sistemas está convergindo para o ISO 20022, um dicionário de dados mais definições de mensagens em XML (e cada vez mais em JSON) com nomes como pain.001 (iniciação de transferência pelo cliente), pacs.008 (transferência interbancária) e camt.053 (extrato do banco para o cliente). Em comparação com os formatos antigos de linhas fixas herdados da era do telex, ele carrega partes estruturadas, informações de remessa e códigos de finalidade detalhados, o que torna a conciliação automática e a triagem muito mais precisas.

<CdtTrfTxInf>
  <PmtId><EndToEndId>INV-2026-000871</EndToEndId></PmtId>
  <Amt><InstdAmt Ccy="EUR">1250.00</InstdAmt></Amt>
  <Cdtr><Nm>Beneficiary Company Ltd</Nm></Cdtr>
  <CdtrAcct><Id><IBAN>GB11ABCD12345678901234</IBAN></Id></CdtrAcct>
  <RmtInf><Ustrd>Invoice 2026-000871</Ustrd></RmtInf>
</CdtTrfTxInf>

Repare no EndToEndId: uma referência escolhida pelo originador que toda instituição deve repassar sem alterações até o beneficiário. É o gancho que torna possível a conciliação de ponta a ponta, e colocar ali um UUID aleatório em vez da sua própria referência de negócio é um erro do qual você vai se arrepender no fechamento do mês.

Escrevendo software de pagamento que se sustenta

Um serviço de pagamento é um sistema distribuído em que um dos participantes — o mundo externo — nunca faz rollback. Quatro hábitos fazem a maior parte do trabalho.

Seja idempotente na fronteira. Toda ordem carrega uma chave fornecida pelo cliente; o servidor a armazena junto com o pagamento resultante e devolve a resposta original a qualquer nova tentativa. Sem isso, um timeout de socket vira um débito em duplicidade.

POST /v1/payments HTTP/1.1
Content-Type: application/json
Idempotency-Key: 4f0a2c1e-9d3b-4a77-8c0e-6a1f7b2d5c93

{"debtorAccount":"GB11ABCD12345678901234",
 "amount":{"currency":"EUR","value":"1250.00"},
 "endToEndId":"INV-2026-000871"}

Modele o pagamento como uma máquina de estados explícita. RECEIVED → VALIDATED → SUBMITTED → SETTLED, com REJECTED e RETURNED como ramos terminais, e cada transição gravada no livro-razão e em um log de auditoria. Resista à tentação de fundir estados: "enviado ao esquema" e "confirmado pelo esquema" implicam responsabilidades diferentes.

Nunca confie em um único sistema de registro. Concilie seu livro-razão com os extratos que o esquema ou o correspondente envia, todos os dias, automaticamente, e gere alerta para qualquer divergência item a item, e não apenas para diferenças nos totais — dois erros em sentidos opostos podem se anular e continuar sendo dois erros. É aqui que um EndToEndId estruturado mostra seu valor.

Prefira uma semântica de mensageria que você consiga defender. Os trilhos de pagamento entregam at-least-once e, às vezes, fora de ordem; deduplicação e ordenação são problema seu, exatamente como descrito em padrões e garantias de mensageria. Quando uma operação de negócio atravessa vários serviços, use transações de compensação em vez de commit em duas fases cruzando fronteiras entre instituições, como discutido em transações distribuídas e consistência.

Dois alertas para fechar. Dinheiro nunca é um número de ponto flutuante: armazene unidades menores como inteiros e leve a moeda junto, porque as regras de arredondamento variam por moeda e por esquema. E trate o cancelamento como um pedido, não como um comando — depois que uma instrução foi repassada a um esquema, a única API honesta é "recall solicitado", cujo resultado depende da boa vontade de outra instituição.

Principais conclusões

• Um pagamento transfere uma obrigação entre instituições; o que de fato circula entre elas é uma mensagem, e o desequilíbrio é acertado depois em moeda de banco central.
• Livros-razão de partidas dobradas, com lançamentos append-only em unidades menores inteiras, entregam saldos, bloqueios, estornos e uma trilha de auditoria que concilia.
• Instrumentos push protegem o pagador; instrumentos pull protegem o recebedor com mandatos e prazos de reembolso — escolha pensando no risco de estorno.
• A compensação define quem deve o quê; a liquidação extingue a dívida. A liquidação bruta elimina o risco de crédito ao custo de liquidez; o netting faz o inverso.
• Os dígitos verificadores do IBAN pegam erros de digitação no cliente, e as mensagens ISO 20022 carregam as referências estruturadas que tornam a conciliação automática.
• Chaves de idempotência, máquinas de estados explícitas, conciliação diária e transações de compensação são os quatro hábitos que mantêm um serviço de pagamento honesto.