Split Payment para desenvolvedores: o fluxo técnico, a API e o que fazer agora

Pra quem é programador, a Reforma Tributária não é só "mais um imposto novo", é um problema de integração de sistema distribuído, com validação síncrona, janela de consistência e um novo player obrigatório no meio do seu fluxo de pagamento. O que me fez escrever este artigo foi um vídeo do Mano Devyn (os devs já devem conhecer o chorume 😄), e acho que ele deu uma boa explicação sobre o Split Payment, recomendo assistir ele antes ou depois deste texto. Aqui eu pego o que ele mostrou, confirmo contra a documentação oficial e complemento com a leitura técnica de quem lida com XML de NF-e o dia inteiro.

Essa é a versão mais completa deste texto. Fui atrás de mais fontes, desenhei os fluxos do jeito que eu mesmo uso pra explicar pro meu time, e no fim deixo minha opinião pessoal, separada do factual, sobre o desenho que o governo escolheu. Se você só quer o resumo, ele está logo abaixo.

Resumo rápido, pra quem vai só passar o olho:

• o IBS e a CBS deixam de ser apurados depois e passam a ser segregados no momento da liquidação financeira, não mais no fim do mês
• o fluxo técnico é orquestrado por lote, com um ResourceId de correlação, não é uma chamada síncrona por venda
• a fase 1 começa em 2027, é opcional e vale só pra operações B2B via Pix, boleto, TED e TEF
• já dá pra testar a API agora, em sandbox, sem risco de multa até lá

Por que isso muda o mindset, não só o código

Hoje, emissão de NF-e e liquidação financeira são dois sistemas com domínios de falha completamente separados. Você emite a nota pelo webservice da SEFAZ, com a disponibilidade e a fila de contingência dela. Você recebe o pagamento pelo seu PSP, com a disponibilidade dele. E a apuração de imposto acontece depois, offline, normalmente uma vez por mês, como um job em lote que roda sobre os dados do seu próprio ERP. Três domínios independentes, cada um com seu próprio SLA, e nenhum deles bloqueia o outro em tempo real.

O Split Payment insere um quarto domínio, e esse é o ponto que eu acho que passa batido nas discussões mais rasas sobre o assunto: a disponibilidade de uma plataforma do governo passa a fazer parte, de forma não negociável, do caminho que confirma se uma transação está fiscalmente "resolvida". Não é uma chamada síncrona bloqueante (o desenho é em lote, como você vai ver adiante), mas é uma dependência externa obrigatória que antes não existia nesse ponto do fluxo. Isso é a definição técnica de acoplamento. A apuração de imposto deixa de ser um job noturno rodando contra seus próprios dados e passa a ser parte de um grafo de dependência que inclui um nó externo, único, e que você não escolhe trocar.

Pra quem já integrou com Pix, com adquirente de cartão, com qualquer gateway de pagamento, esse tipo de problema não é novo: idempotência, retry com backoff, reconciliação, estado parcial. A diferença é que aqui o "gateway" é o próprio estado, é obrigatório, e você não tem um segundo provedor pra rotear em caso de degradação. Vale desenhar com esse nível de seriedade desde o início, não como um webservice de nota fiscal a mais.

O fim do float fiscal, explicado pra quem pensa em sistema

Hoje o fluxo é simples: o comprador paga o valor cheio, o vendedor recebe tudo na conta, e o imposto é apurado e recolhido depois, em outro processo, em outro momento. Esse intervalo entre "receber" e "recolher" é o float fiscal, e é dinheiro em caixa que a empresa usa (de propósito ou não) até a data de pagamento do tributo. O Split Payment elimina essa janela: a segregação do IBS/CBS acontece no momento da liquidação financeira, antes do valor líquido chegar à conta do vendedor. Do ponto de vista de sistema, isso transforma um processo que era assíncrono e em lote (apurar impostos no fim do mês) em algo que precisa de uma decisão em tempo de transação. É uma mudança de arquitetura, não só de alíquota.

E deixando bem claro: isso não é algo que vai valer pra todo mundo de uma vez. A primeira fase (2027) é opcional e restrita a operações entre empresas (B2B), não muda nada no fluxo com consumidor final nem pra quem está 100% dentro do Simples Nacional. Se quiser o cronograma completo por tipo de empresa, sem o exagero que costuma circular por aí, já desmentimos os boatos mais comuns sobre a reforma em outro artigo.

O fluxo técnico, com o que eu confirmei na documentação oficial

O Mano Devyn resume bem o caminho: comprador paga, o PSP consulta a Plataforma Pública de Split Payment antes de liquidar, a plataforma valida e instrui a fatia de IBS/CBS, e o PSP segrega automaticamente o valor entre Receita Federal, Comitê Gestor do IBS e o vendedor. Isso continua certo na essência, mas o nível de detalhe disponível mudou bastante: o Manual de Integração v1.0 (junho/2026) descrevia um fluxo simples de três passos. Em agosto de 2026 o CGIBS publicou uma minuta bem mais completa, a versão 1.1.0, com um Swagger/OpenAPI de verdade, que reorganiza tudo em uma família de fluxos de mensagens, não só um único fluxo de lote.

Nota sobre esta seção: o conteúdo abaixo é baseado no Manual de Integração v1.1.0 (agosto/2026), que ainda está marcado como "MINUTA" pelo próprio CGIBS, ou seja, ainda pode mudar antes de virar versão final. Vou tentar manter este artigo atualizado conforme novas revisões saírem, mas trate isso como o estado da arte de agosto/2026, não como verdade definitiva.

Pensar nisso como "três passos" já não é o modelo mental certo. A v1.1.0 descreve oito fluxos de mensagens diferentes entre o PSP (ou a Núclea, a câmara que hoje processa boleto) e a Plataforma Pública, cada um com seu próprio endpoint:

• Informe de Transação Iniciada: avisa que uma transação (boleto, Pix Dinâmico ou Pix Automático) começou a existir.
• Informe de Transação Atualizada: comunica mudança de dados de uma transação já iniciada (só boleto e Pix Dinâmico).
• Informe de Baixa (Exceto por Pagamento): encerra a transação por um motivo que não é pagamento, como cancelamento ou expiração.
• Informe Preliminar de Pagamento: aviso informativo, sem efeito vinculante, de que o pagamento foi identificado.
• Informe de Segregação: o fluxo que efetivamente separa e movimenta o dinheiro do imposto. É o núcleo técnico deste artigo.
• Retorno Super Inteligente: como o PSP fica sabendo do resultado do que enviou.
• Consulta Retroativa Super Inteligente: como recuperar mensagens que passaram batido.
• Mecanismo de Ocorrências (MOC): como lidar com transação suspeita ou pedido de estorno.

O restante desta seção foca no Informe de Segregação e depois cobre os outros três que interessam pra quem vai construir um cliente de verdade: Retorno Super Inteligente, Consulta Retroativa e MOC.

O Informe de Segregação continua em três passos, só que agora com endpoints e nomes de campo reais, confirmados no Swagger:

1. Passo 1, remessa iniciada: POST /api/v1/segregacao, abrindo uma remessa. A plataforma devolve um idInfSegr, o identificador de 34 caracteres, que o próprio manual ainda chama de forma genérica de "ResourceId" nos diagramas. Ele não é aleatório: é composto por ISPB do PSP, ISPB de quem está enviando, arranjo, data e um sequencial, dá pra decodificar informação só olhando pro identificador.
2. Passo 2, lotes: envia lotes de até 1.000 transações via POST /api/v1/{arranjo}/segregacao/{idInfSegr}/lotes, um endpoint diferente por arranjo (boleto, pix-dinamico, pix-automatico, pix-estatico, ted, tef). Diferente da maioria dos outros informes, aqui o lote é tudo ou nada: se um item tiver erro, o lote inteiro é rejeitado, não só aquele item. Reenviar o mesmo idLote atualiza o lote (HTTP 200), não duplica; o primeiro envio retorna HTTP 201.
3. Passo 3, finalização: POST /api/v1/segregacao/finalizacao, informando os totais esperados. Se baterem com a soma dos lotes enviados, a plataforma dispara o repasse financeiro pra Receita Federal e CGIBS, com prazo até meio-dia do dia seguinte, conforme o Manual de Tempos (também ainda em minuta). Se não baterem, o passo de finalização é rejeitado com HTTP 422, você corrige e reenvia.

A divisão de responsabilidade também é clara, e isso é uma boa notícia pra quem vai integrar: a Plataforma Pública não calcula alíquota nenhuma. O papel dela é validação sintática e semântica do que foi enviado, geração do identificador único de rastreabilidade, e roteamento dos valores já calculados para o destinatário certo (RFB ou CGIBS).

O cálculo de quanto é IBS e quanto é CBS continua sendo responsabilidade total do sistema do contribuinte, ou seja, do seu ERP, do seu emissor de nota, do seu backend. Isso segue o princípio de baixo acoplamento que aparece no próprio manual de integração: a plataforma é hub de transporte e auditoria, não motor de regra de negócio.

O paralelo que eu uso pra explicar pro time

Se você já mexeu com padrão saga ou com two-phase commit, o modelo mental é parecido: você reserva (Passo 1), confirma em partes (Passo 2) e só depois fecha com uma confirmação final (Passo 3) que pode dar certo ou errado pro lote inteiro. E igual num saga de verdade, existe uma ação compensatória formal: o Mecanismo de Ocorrências tem uma Solicitação de Estorno, usada quando o CBS/IBS já foi segregado por engano, por incidente de segurança ou falha operacional. Quem decide quando abrir esse estorno, porém, é você: a plataforma não reverte nada sozinha.

Como o PSP fica sabendo do resultado: Retorno Super Inteligente

Depois que você manda os dados, como você sabe se deu certo? A resposta é o Retorno Super Inteligente, um mecanismo de long polling. O PSP abre até 6 conexões HTTPS simultâneas contra a plataforma; ela segura a conexão aberta por até 6 segundos esperando ter algo novo pra mandar; se não tiver, devolve HTTP 204 sem conteúdo e o PSP pergunta de novo. Cada resposta vem com um token de posição que você usa na próxima chamada, isso garante que você não perde nem repete mensagem mesmo se sua conexão cair no meio.

Recuperando o que passou batido: Consulta Retroativa

Em vez de inventar sua própria lógica de conciliação contra a plataforma, existe um endpoint oficial pra isso: a Consulta Retroativa Super Inteligente, que devolve mensagens já entregues antes, filtrando por intervalo de NSU (Número Sequencial Único). Serve exatamente pro cenário que todo sistema de liquidação financeira eventualmente enfrenta: sua aplicação caiu, perdeu uma mensagem, ou precisa reconstruir histórico pra auditoria.

Quando algo dá errado de verdade: o Mecanismo de Ocorrências (MOC)

O MOC cobre dois cenários que não são bug de integração, são situações de negócio: a Notificação de Transação em Análise, usada quando uma transação já liquidada é retida por suspeita de fraude ou outro motivo não contratual antes de entrar no Informe de Segregação; e a Solicitação de Estorno, usada quando o CBS/IBS já foi segregado e precisa ser desfeito, por incidente de segurança ou falha operacional. Os dois têm endpoint próprio de envio e um endpoint de consulta paginada pra acompanhar o status.

A API pra quem quer testar agora

A documentação técnica completa (manual de integração + OpenAPI v1.1.0) está publicada em cgibs.gov.br/split-payment, com download direto do PDF e de um ZIP com o Swagger.

Abrindo o Swagger, a base é /api/v1, e os endpoints batem com os fluxos que descrevi acima:

• Fluxo principal (Informe de Segregação): POST /segregacao, POST /{arranjo}/segregacao/{idInfSegr}/lotes, POST /segregacao/finalizacao
• Retorno Super Inteligente: GET/DELETE /out/{arranjo}/{cnpj}/transacoes/stream/...
• Consulta Retroativa: GET/DELETE /retroativo/{arranjo}/{cnpj}/transacoes/stream/...
• Mecanismo de Ocorrências (MOC): POST /moc/notificacao, POST /moc/solicitacao, GET /moc/{cnpj}/ocorrencias

Um requisito novo na v1.1.0 que eu não veria vindo se não tivesse lido o manual inteiro: toda requisição e toda resposta precisam vir com um cabeçalho X-JWS-Signature, uma assinatura digital no formato JWS Compact Detached (RFC 7515), com o payload canonicalizado antes via JCS (RFC 8785) e algoritmo RS256. Na prática isso quer dizer que seu cliente HTTP não é só um cliente HTTP: ele precisa de infraestrutura de chave privada e assinatura digital rodando em cada chamada, dos dois lados. Se seu time nunca implementou algo assim, vale olhar isso com prioridade, é trabalho de verdade, não é só configurar um header de autenticação.

Um ponto que eu prestaria atenção antes de começar a integrar: como o fluxo de segregação é por lote e por idInfSegr, o desenho natural do seu lado é um worker/job que acumula transações, monta o lote, chama o Passo 1, transmite, e só marca as transações como "seguras" depois do Passo 3 confirmado, não depois de cada item individual. Se seu sistema hoje pensa em split payment como "resposta síncrona por venda", vai ter que redesenhar esse pedaço.

Eu trataria o monitoramento disso exatamente como trato qualquer fila assíncrona em produção, com observabilidade desde o dia 1. A própria política de erros da plataforma já ajuda: HTTP 429 com header Retry-After pra rate limit, HTTP 503 com X-Circuit-Breaker quando ela está protegendo a própria fila interna, HTTP 410 Gone quando uma stream de long polling expirou e precisa ser reaberta. Eu montaria alerta em cima desses três casos específicos, mais os clássicos:

• alerta pra lote parado no Passo 2 por mais tempo do que o normal
• alerta pra taxa de rejeição HTTP 422 no Passo 3 acima de um limiar aceitável
• dashboard com quantos idInfSegr estão pendentes de finalização, por quanto tempo cada um
• log estruturado correlacionando cada idInfSegr com as transações internas do seu sistema, pra reconciliação (agora via Consulta Retroativa) não virar arqueologia

Onde isso te alcança se você já mexe com NF-e

Se seu sistema já emite ou lê XML de NF-e/NFC-e, o Split Payment não chega sozinho, ele vem de mãos dadas com a Nota Técnica 2025.002-RTC, que já reestruturou o XML pra reforma desde 2025 e ganhou notas complementares específicas de split payment (NT 2026.006-RTC, sobre vinculação de pagamento, e o Informe Técnico 2026.001, sobre os códigos de meio de pagamento usados nessa vinculação) publicadas em agosto de 2026. Na prática, o item da NF-e ganhou um grupo IBSCBS inteiro, com campos como:

• cClassTrib: código de classificação tributária, basicamente o "CST da reforma"
• gIBSUF.vIBSUF e gIBSMun.vIBSMun: valor do IBS por competência estadual e municipal
• gCBS.vCBS: valor da CBS
• IBSCBSTot.vBCIBSCBS: base de cálculo total agregada na nota

A gente já implementou a extração completa desse grupo (incluindo cClassTrib e os totais) na nossa DANFE Completa. Se você quer ver como fica isso num XML real sem precisar gerar um do zero, preparei um XML de exemplo (homologação) já com o grupo IBSCBS preenchido, é só baixar e subir direto na ferramenta pra testar. O gap que a gente ainda não fechou, e vale você também mapear no seu sistema: os códigos de meio de pagamento do Informe Técnico 2026.001, que são recentes (agosto de 2026) e ainda não viraram padrão em praticamente nenhum emissor de mercado.

Cronograma pro backlog do seu time

• 2026: ano de homologação em sandbox. É a janela pra integrar e testar sem risco de multa, exatamente como o Mano Devyn recomenda no vídeo.
• 2027: fase 1 em produção, só B2B, só Pix/boleto/TED/TEF. Bom momento pra já estar rodando em sandbox há meses, não pra começar do zero.
• 2033: regime pleno e obrigatório de Split Payment, cobrindo o que ficou de fora da fase 1.

E um ponto que o próprio cronograma público já deixa claro: o "início em 2027" não é "tudo funcionando em 2027". A primeira fase é opcional e limitada a operações B2B via Pix, boleto, TED e TEF, fora do consumidor final e fora de quem está inteiramente no Simples Nacional. Isso dá um respiro real pra maturar a integração antes do modelo virar regra geral em 2033, mas também significa que testar cedo em sandbox (2026) é a única forma de não ser pego de surpresa quando a obrigatoriedade também alcançar seu tipo de operação.

Na prática, isso quer dizer: se você é dev ou lidera um time técnico numa empresa que fatura, o estudo do Swagger e o mapeamento dos seus PSPs deveria estar no seu roadmap de 2026, não de 2027. Ler o manual, testar em sandbox, confirmar que seu emissor de NF-e já suporta a NT 2025.002 completa, e principalmente perguntar pros seus provedores de pagamento qual é o roadmap deles de integração com o hub do governo, isso é exatamente o passo a passo que o vídeo do Mano Devyn recomenda, e eu concordo com cada item.

Se você quer o cronograma completo da reforma além do split payment, ou prefere mandar pra alguém do time de produto/negócio uma explicação sem jargão técnico, temos o calendário completo da reforma e o artigo separando boato de fato sobre a reforma.

Minha opinião, sem meias palavras

Até aqui tentei ficar só no factual: o que a documentação diz, o que muda no seu sistema, o que eu testaria primeiro. Essa parte é diferente, é opinião pessoal minha, não da Receita Federal e não do Gerador DANFE como produto. Acho importante deixar isso separado e explícito.

Eu não pactuo muito com a ideia dar mais ferramenta de controle financeiro em tempo real pro estado. Sou uma pessoa mais liberal, cética com o tamanho do estado, e desconfio de qualquer coisa que aumente a vigilância sobre o caixa de quem trabalha e empreende. Dito isso, seria intelectualmente desonesto fingir que o Brasil não tem um histórico grande de sonegação estruturada, nota fria, empresa de fachada, disputa via crédito acumulado de ICMS. Um mecanismo de captura na fonte resolve, de um jeito bem mais elegante do que fiscalização a posteriori, um problema real que qualquer um que já concorreu com um concorrente sonegador conhece na prática.

O que eu questiono não é a existência do mecanismo, é o desenho centralizado dele: um único hub público, operado pelo próprio ente que arrecada, virando ponto único de falha e ponto único de visibilidade sobre todo pagamento B2B do país. Eu preferiria um modelo mais auditável e mais distribuído, com trilha pública de auditoria, em vez de um sistema fechado que a gente só enxerga pelo Swagger. Mas entendo a lógica de engenharia por trás da escolha: operar uma plataforma unificada é mais simples que coordenar dezenas de PSPs num protocolo federado, e o fato da fase 1 ser opcional e limitada a B2B sugere que, pelo menos dessa vez, tentaram rodar com cautela em vez de empurrar tudo de uma vez.

Créditos e fontes

Este artigo usa como referência principal o vídeo A API DO GOVERNO QUE VAI MUDAR TODO SISTEMA DE PAGAMENTO | SPLIT PAYMENT EXPLICADO PRA DEV no YouTube, que recomendo assistir na íntegra para o contexto completo. As afirmações técnicas foram checadas contra as fontes oficiais abaixo:

• Receita Federal: Receita Federal e CGIBS publicaram a documentação técnica da Plataforma Pública do Split Payment
• CGIBS: Plataforma Pública de Split Payment, Manual de Integração v1.0 (PDF, junho/2026, superado pela v1.1.0 abaixo)
• CGIBS: Plataforma Pública de Split Payment, Manual de Integração v1.1.0 - Minuta (PDF, agosto/2026)
• CGIBS: OpenAPI/Swagger v1.1.0 da Plataforma Pública de Split Payment (ZIP)
• Legisweb: Reforma Tributária, Receita Federal e CGIBS publicam a documentação técnica da Plataforma Pública do Split Payment
• Tecnospeed: Manual do Split Payment, Documentação da Plataforma Pública
• Contabeis.com.br: Split payment não começa em janeiro de 2027; entenda