APIDocumentação

A API mais simples para Split Payment.

A instituição financeira realiza apenas quatro ações: informa o pagamento, recebe a Split Instruction, executa a segregação e confirma a execução. Todo o restante é responsabilidade da NexoSplit.

BASE URL

https://api.nexosplit.com.br

01Endpoints

Superfície mínima da API

Sete endpoints cobrem a ativação do estabelecimento e todo o ciclo do pagamento. Apenas um endpoint adicional é necessário para iniciar a operação do estabelecimento.

Método	Endpoint	Finalidade	Uso
POST	/v1/merchants	Ativar estabelecimento	Opcional
GET	/v1/merchants/{merchant_id}	Consultar ativação	Opcional
POST	/v1/payments	Registrar ou atualizar o ciclo de vida do pagamento	Obrigatório
GET	/v1/payments/{payment_id}	Consultar Split Instruction	Obrigatório
GET	/v1/payments/{payment_id}/details	Consultar operação completa	Opcional
POST	/v1/payments/{payment_id}/settlement	Confirmar liquidação	Obrigatório
POST	/v1/payments/{payment_id}/events	Informar ajuste ou estorno	Opcional

Apenas POST /v1/merchants é necessário para ativação. GET /v1/merchants/{merchant_id} é opcional e serve somente para acompanhamento.

POST/v1/merchants

Ativar estabelecimento

Ativa um estabelecimento na NexoSplit e envia o acesso ao responsável informado. O PSP envia apenas os dados mínimos — a NexoSplit consulta os dados cadastrais disponíveis, aplica a Regra Setorial e conduz o onboarding fiscal diretamente com o estabelecimento.

Requisição

{
  "external_id": "estabelecimento-123",
  "tax_id": "12345678000199",
  "responsible": {
    "name": "João Silva",
    "email": "joao@empresa.com.br",
    "phone": "+5531999999999"
  }
}

Resposta

{
  "merchant_id": "mer_01JNX123",
  "external_id": "estabelecimento-123",
  "tax_id": "12345678000199",
  "status": "active",
  "onboarding_status": "invitation_sent",
  "tax_source": "SECTOR_RULE"
}

Obrigatórios: external_id, tax_id, responsible.name, responsible.email, responsible.phone.
Ativação imediata: o estabelecimento já pode operar sob a Regra Setorial. Configuração fiscal nunca bloqueia pagamentos.
Convite enviado ao responsável por e-mail (e, quando disponível, por telefone) para concluir o Portal do Estabelecimento.
Idempotente por external_id — reenvios não criam duplicidade. O mesmo CPF/CNPJ não deve ser duplicado dentro da mesma instituição.

GET/v1/merchants/{merchant_id}

Consultar ativação

Consulta o status operacional, o andamento do onboarding e a fonte fiscal atualmente utilizada. Endpoint opcional — não participa do fluxo transacional de pagamentos.

Resposta

{
  "merchant_id": "mer_01JNX123",
  "external_id": "estabelecimento-123",
  "tax_id": "12345678000199",
  "status": "active",
  "onboarding_status": "completed",
  "tax_source": "FISCAL_DOCUMENT",
  "responsible": {
    "name": "João Silva",
    "email": "joao@empresa.com.br",
    "phone": "+5531999999999"
  }
}

status: active | blocked | inactive — indica se o estabelecimento pode operar.
onboarding_status: invitation_sent | pending | completed — indica se o responsável concluiu o acesso.
tax_source: SECTOR_RULE | CUSTOM_RULE | FISCAL_DOCUMENT — fonte atualmente utilizada para o cálculo.
Um estabelecimento pode estar active com onboarding_status = pending: opera normalmente sob a Regra Setorial.

POST/v1/payments

Registrar ou atualizar o ciclo de vida do pagamento

Endpoint único para registrar e atualizar o pagamento em qualquer estágio: criação, confirmação, pagamento, liquidação, cancelamento ou estorno. O PSP informa apenas o mínimo — a NexoSplit resolve o restante e devolve a Split Instruction. Idempotente por external_id.

Requisição

{
  "external_id": "transacao-123",
  "payment_method": "pix_dynamic",
  "lifecycle_stage": "created",
  "gross_amount": 100000,
  "merchant_tax_id": "12345678000199"
}

Resposta

{
  "payment_id": "pay_01JNY456",
  "status": "ready",
  "merchant": {
    "merchant_id": "mer_01JNX123",
    "onboarding_status": "contact_required",
    "tax_source": "SECTOR_RULE"
  },
  "split_instruction": {
    "instruction_id": "inst_01JNZ789",
    "version": 1,
    "status": "ready",
    "cbs_amount": 900,
    "ibs_amount": 100,
    "merchant_amount": 99000,
    "calculation_rule": "SECTOR_RULE"
  }
}

Obrigatórios mínimos: external_id, payment_method, lifecycle_stage, gross_amount, merchant_tax_id. Todo o restante é opcional — inclusive participantes, documento fiscal, txid, e2eid, datas e referências.
Identificação do estabelecimento: aceita merchant_tax_id (CPF/CNPJ) ou merchant_id. Se o estabelecimento ainda não estiver cadastrado, a NexoSplit cria um registro provisório e aplica a Regra Setorial — o pagamento não é bloqueado.
Idempotente: reenviar o mesmo external_id atualiza o pagamento existente, sem duplicar registros.
lifecycle_stage: created | authorized | paid | settled | cancelled | expired | refunded.
Resposta imediata: status = ready traz a split_instruction pronta; status = processing indica que a instrução será entregue via webhook split_instruction.ready.
Não é obrigatório esperar o webhook: o PSP pode consultar GET /v1/payments/{id} a qualquer momento.

GET/v1/payments/{payment_id}

Consultar Split Instruction

Endpoint operacional do dia a dia. Retorna status, ação necessária e a versão mais recente da Split Instruction, pronta para execução.

Resposta

{
  "payment_id": "pay_01JNY456",
  "status": "ready",
  "action_required": "execute_split",
  "split_instruction": {
    "instruction_id": "inst_01JNZ789",
    "version": 2,
    "status": "ready",
    "cbs_amount": 900,
    "ibs_amount": 100,
    "merchant_amount": 99000,
    "calculation_rule": "FISCAL_DOCUMENT"
  }
}

action_required: execute_split | wait | none.
Fechamento: cbs_amount + ibs_amount + merchant_amount = gross_amount.
Sempre utilizar a versão mais recente (split_instruction.version) — a NexoSplit versiona sempre que houver ajuste.
Cenários com múltiplos recebedores (marketplace, hospital+médico, holding) recebem additional_allocations[] neste mesmo bloco. Para o detalhamento completo consulte GET /v1/payments/{id}/details.

GET/v1/payments/{payment_id}/details

Consultar operação completa

Visão consolidada e somente leitura para auditoria, suporte e integrações avançadas. Não deve ser utilizado no fluxo transacional — para o dia a dia, use GET /v1/payments/{id}.

Resposta

{
  "payment": {
    "payment_id": "pay_01JNY456",
    "external_id": "transacao-123",
    "payment_method": "pix_dynamic",
    "gross_amount": 100000,
    "merchant_tax_id": "12345678000199",
    "occurred_at": "2026-07-17T14:30:00-03:00",
    "status": "reconciled",
    "payment_reference": {
      "end_to_end_id": "E123456789202607171430ABC",
      "txid": "PEDIDO-98765"
    }
  },
  "fiscal_reconciliation": {
    "status": "matched",
    "payment_amount": 100000,
    "fiscal_documents_amount": 100000,
    "difference_amount": 0,
    "documents": [
      {
        "document_id": "fdoc_001",
        "type": "NFSE",
        "key": "NFSE-MEDICO-001",
        "status": "authorized",
        "issued_at": "2026-07-17T14:20:00-03:00",
        "document_amount": 60000,
        "match_method": "fiscal_document_key",
        "match_confidence": 1.0,
        "participants": [
          {
            "participant_external_id": "medico-123",
            "allocated_amount": 60000
          }
        ]
      },
      {
        "document_id": "fdoc_002",
        "type": "NFSE",
        "key": "NFSE-HOSPITAL-001",
        "status": "authorized",
        "issued_at": "2026-07-17T14:27:00-03:00",
        "document_amount": 40000,
        "match_method": "fiscal_document_key",
        "match_confidence": 1.0,
        "participants": [
          {
            "participant_external_id": "hospital-456",
            "allocated_amount": 40000
          }
        ]
      }
    ],
    "participants": [
      {
        "participant_external_id": "medico-123",
        "gross_amount": 60000,
        "fiscal_documents_amount": 60000,
        "difference_amount": 0,
        "status": "matched"
      },
      {
        "participant_external_id": "hospital-456",
        "gross_amount": 40000,
        "fiscal_documents_amount": 40000,
        "difference_amount": 0,
        "status": "matched"
      }
    ]
  },
  "taxes": {
    "status": "confirmed",
    "cbs_amount": 900,
    "ibs_amount": 100,
    "source": "government_response"
  },
  "instructions": [
    {
      "instruction_id": "inst_01JNZ789",
      "version": 1,
      "status": "executed",
      "gross_amount": 100000,
      "created_at": "2026-07-17T14:30:01-03:00",
      "allocations": [
        { "type": "CBS", "amount": 900, "destination": "RFB" },
        { "type": "IBS", "amount": 100, "destination": "CGIBS" },
        { "type": "MERCHANT", "amount": 99000, "destination_reference": "merchant-123" }
      ]
    }
  ],
  "settlements": [
    {
      "external_settlement_id": "liq-123456",
      "instruction_id": "inst_01JNZ789",
      "status": "completed",
      "settled_at": "2026-07-17T14:30:03-03:00",
      "reconciliation_status": "matched"
    }
  ],
  "government_reports": [
    {
      "report_id": "govrep_001",
      "type": "PAYMENT_PRELIMINARY",
      "status": "accepted",
      "protocol": "GOV-2026-000121",
      "sent_at": "2026-07-17T14:30:01-03:00",
      "responded_at": "2026-07-17T14:30:02-03:00"
    },
    {
      "report_id": "govrep_002",
      "type": "SEGREGATION_COMPLETED",
      "status": "accepted",
      "protocol": "GOV-2026-000122",
      "sent_at": "2026-07-17T14:30:04-03:00",
      "responded_at": "2026-07-17T14:30:05-03:00"
    }
  ],
  "exceptions": [],
  "timeline": [
    { "type": "payment.received",           "occurred_at": "2026-07-17T14:30:00-03:00" },
    { "type": "fiscal_document.matched",    "occurred_at": "2026-07-17T14:30:00-03:00" },
    { "type": "government_report.accepted", "reference_id": "govrep_001", "occurred_at": "2026-07-17T14:30:02-03:00" },
    { "type": "settlement.completed",       "reference_id": "liq-123456", "occurred_at": "2026-07-17T14:30:03-03:00" },
    { "type": "government_report.accepted", "reference_id": "govrep_002", "occurred_at": "2026-07-17T14:30:05-03:00" },
    { "type": "payment.reconciled",         "occurred_at": "2026-07-17T14:30:06-03:00" }
  ]
}

Suporta 1:1, 1:N e N:N entre notas e participantes.
Substitui múltiplas consultas: nota, tributo, instrução, liquidação, informe e protocolo.

POST/v1/payments/{payment_id}/settlement

Confirmar liquidação

A instituição executora confirma a execução da Split Instruction. A NexoSplit compara instruído × executado, gera e transmite o informe de segregação.

Requisição

{
  "instruction_id": "inst_01JNZ789",
  "instruction_version": 1,
  "external_settlement_id": "liq-123456",
  "status": "completed",
  "settled_at": "2026-07-17T14:30:03-03:00"
}

Resposta

{
  "payment_id": "pay_01JNY456",
  "instruction_id": "inst_01JNZ789",
  "external_settlement_id": "liq-123456",
  "status": "settled",
  "settled_at": "2026-07-17T14:30:03-03:00"
}

A NexoSplit já conhece a instrução emitida — o PSP não precisa reenviar CBS, IBS e Merchant.
allocations[] permanece opcional para instituições que desejarem informar a distribuição efetivamente realizada.

POST/v1/payments/{payment_id}/events

Informar ajuste ou estorno

Concentra todos os eventos posteriores ao registro inicial: confirmação de pagamento, liquidação financeira, cancelamento, expiração, estornos, chargebacks e ajustes. A NexoSplit converte cada evento nos informes exigidos pelo governo.

Requisição

{
  "external_event_id": "evento-123",
  "type": "refund",
  "amount": 10000,
  "occurred_at": "2026-07-18T10:00:00-03:00",
  "reason": "customer_request",
  "reference": {
    "settlement_id": "liq-123456",
    "instruction_id": "inst_01JNZ789"
  },
  "participants": [
    {
      "participant_external_id": "medico-123",
      "amount": 6000
    },
    {
      "participant_external_id": "hospital-456",
      "amount": 4000
    }
  ]
}

Resposta

{
  "payment_id": "pay_01JNY456",
  "event_id": "evt_01JNXYZ",
  "external_event_id": "evento-123",
  "type": "refund",
  "status": "accepted",
  "split_instruction": {
    "instruction_id": "inst_01JP0001",
    "version": 2,
    "status": "ready",
    "cbs_amount": 810,
    "ibs_amount": 90,
    "merchant_amount": 89100,
    "calculation_rule": "FISCAL_DOCUMENT"
  }
}

Tipos: payment_confirmed, financial_settlement, cancelled, expired, updated, refund, partial_refund, chargeback, chargeback_reversal, settlement_adjustment.
A NexoSplit calcula os reflexos, versiona a split_instruction e emite o informe governamental correspondente.

02Visão geral

Divisão de responsabilidades

A NexoSplit atua como Prestador de Serviço de Conexão entre a instituição financeira e a Plataforma Pública do Split Payment, assumindo toda a orquestração operacional, tributária e regulatória da integração.

Origem fiscal

ERP

Nota Fiscal

Camada NexoSplit

NEXOSPLIT

· Busca NF

· Calcula CBS

· Calcula IBS

· Gera Split

· Concilia

· Informa Governo

POST /v1/payments

Split Instruction

Execução financeira

PSP / Banco

Segregação · POST /settlement

Destino regulatório

Plataforma Pública

O ERP entrega a informação fiscal. O PSP entrega a informação financeira. A NexoSplit une os dois mundos.

Instituição financeira

1. informar o pagamento;
2. receber a Split Instruction;
3. executar a segregação;
4. confirmar o resultado.

NexoSplit

· localiza ou recebe o documento fiscal;
· calcula CBS e IBS;
· gera e versiona a Split Instruction;
· transmite os informes governamentais;
· concilia instruído × executado;
· mantém trilha completa de auditoria.

03Integração em 15 minutos

Do primeiro token ao settlement conciliado

Cinco passos objetivos. Cada um corresponde a uma única chamada da API.

Passo 1
Credenciais OAuth
Client Credentials + escopos.
Passo 2
Enviar Payment
POST /v1/payments.
Passo 3
Receber Split
Resposta ready ou webhook.
Passo 4
Executar segregação
PSP aplica CBS, IBS, Merchant.
Passo 5
Confirmar Settlement
POST /settlement — pronto.

04Autenticação

OAuth 2.0 · Client Credentials

Todas as chamadas exigem um Bearer token obtido no fluxo Client Credentials, com escopos por participante e mTLS opcional em produção.

Authorization: Bearer <access_token>
Content-Type: application/json
Idempotency-Key: 886d18fd-6240-4b7e-8e58-bf3c9ccda521

05Convenções

Regras que valem para toda a API

Valores

Sempre em centavos, inteiros positivos.

Datas

ISO 8601 com offset (ex.: 2026-07-17T14:30:00-03:00).

Identificadores

external_id único por participante; Idempotency-Key em toda escrita.

payment_method

credit_cardFuturedebit_cardFutureprepaid_cardFuturepix_dynamicFase 1pix_staticFase 1pix_automaticFase 1boletoFase 1tedFase 1book_transferFase 1otherFase 1

Fase 1 da Reforma Tributária; Future Phase — cartões previstos para próximas etapas.

payment.status

processingreadysettledcancelledexception

06Estados do Payment

Ciclo de vida em um único recurso

O Payment percorre uma sequência previsível. Cada transição é registrada via lifecycle_stage no mesmo endpoint POST /v1/payments.

Estado	Descrição
created	Pagamento registrado. Aguardando confirmação do PSP.
authorized	Pagamento autorizado. Ainda não liquidado.
paid	Pagamento confirmado pelo pagador.
settled	Segregação executada e conciliada.
refunded	Estorno total ou parcial processado.
cancelled	Pagamento cancelado antes da liquidação.

created → authorized → paid → settled
                       ↘ cancelled
                       ↘ refunded

07Idempotência

Reenvie sem medo de duplicar

Toda escrita aceita o header Idempotency-Key. Além disso, o Payment é idempotente por natureza através do external_id.

Regra

Mesmo external_id
  ↓
Mesmo Payment
  ↓
Sem duplicidade

Comportamento

· Retentativas devolvem sempre a mesma resposta (mesma versão da Split Instruction).
· Alterações de dados exigem novo external_id ou evento explícito via /events.
· Idempotency-Key tem validade de 24h por endpoint.

08Versionamento da Split Instruction

O PSP executa sempre a versão mais recente

Sempre que um insumo muda — alíquota, documento fiscal, evento posterior — a NexoSplit versiona a Split Instruction. A versão anterior é preservada para auditoria; a execução deve utilizar a versão corrente.

v1  →  Instrução inicial gerada a partir da NF e das alíquotas vigentes.
  ↓
Governo altera imposto  |  NF é retificada  |  Estorno parcial
  ↓
v2  →  Nova instrução, mesmo instruction_id, version incrementada.
  ↓
PSP executa SEMPRE a maior version.

· Consulte GET /v1/payments/{id} antes da execução para garantir a versão atual.
· Tentativas de settlement com versão obsoleta retornam 409 instruction_outdated.
· A NexoSplit notifica novas versões pelo webhook split_instruction.updated.

09Fluxo operacional

O mesmo fluxo para qualquer meio de pagamento

Um único caminho, previsível, do registro do pagamento até a conciliação da liquidação.

Passo 01
POST /v1/payments
Informa o pagamento (qualquer estágio).
Passo 02
processing ou ready
Recebe a resposta imediata — webhook é opcional.
Passo 03
GET /v1/payments/{id}
Consulta a Split Instruction.
Passo 04
Executa a segregação
PSP aplica CBS, IBS e valor do estabelecimento.
Passo 05
POST /settlement
Confirma a execução. A NexoSplit concilia e informa o governo.

10Ativação de Estabelecimentos

Ative um estabelecimento em uma chamada. Nunca dependa de configuração fiscal para operar.

O PSP envia POST /v1/merchants com os dados mínimos do estabelecimento. A NexoSplit ativa imediatamente aplicando a Regra Setorial padrão, envia o convite ao responsável e passa a aceitar pagamentos. A configuração fiscal evolui em paralelo, no Portal da Empresa, sem qualquer alteração na integração do PSP.

Ativação imediata

Nenhum documento, certificado ou configuração fiscal é exigido do PSP para começar a operar.

Fonte fiscal automática

A NexoSplit escolhe a melhor fonte disponível para calcular CBS e IBS de cada pagamento.

Evolução sem re-integração

Quando o estabelecimento amadurece a configuração fiscal, o PSP continua chamando a mesma API.

Hierarquia de fontes fiscais

Em cada pagamento, o Tax Engine avalia as três fontes na ordem abaixo e utiliza a primeira disponível. A transição entre elas é automática e transparente para o PSP.

Prioridade 1

Documento Fiscal

Maior precisão

Quando o estabelecimento autoriza acesso aos seus documentos fiscais, a NexoSplit lê CBS e IBS diretamente da nota emitida para a operação.

·certificado digital
·procuração eletrônica
·integração com o ERP
·credenciais ou integração da prefeitura
·outros mecanismos compatíveis

Recomendado para empresas que buscam máxima precisão tributária e conciliação fiscal completa.

Prioridade 2

Regra Padrão do Estabelecimento

Configuração própria

O estabelecimento ou seu contador cadastra alíquotas próprias no Portal da Empresa, utilizadas sempre que não houver documento fiscal para o pagamento.

·CBS: 3%
·IBS: 7%

Recomendado para implantação rápida com baixa variação tributária.

Prioridade 3 · Padrão

Regra Setorial da NexoSplit

Ativação imediata

Fonte padrão aplicada no momento da ativação. Sem qualquer configuração, a NexoSplit calcula CBS e IBS a partir do perfil do estabelecimento.

·segmento de atuação
·CNAE
·regime tributário
·histórico fiscal
·demais critérios NexoSplit

Garante que o pagamento nunca fique bloqueado por ausência de configuração fiscal.

Fluxo de ativação

Uma única chamada resolve a ativação. A partir daí, o estabelecimento já aparece como ativo para o PSP — mesmo antes de qualquer configuração fiscal ser feita pelo responsável.

PSP chama POST /v1/merchants

Existe Documento Fiscal?

Sim

Documento Fiscal

Não

Existe Regra Padrão?

Sim

Regra Padrão

Não

Regra Setorial

Estabelecimento ativo

PSP começa a informar pagamentos

O que cabe a cada participante

PSP · Instituição financeira

Chama POST /v1/merchants com dados mínimos e informa os pagamentos. Não gerencia certificados, alíquotas ou documentos fiscais.

Estabelecimento

Recebe o convite, faz o primeiro acesso ao Portal da Empresa e, quando quiser, evolui para Regra Própria ou Documento Fiscal.

NexoSplit

Ativa o merchant, aplica a Regra Setorial, conduz o onboarding fiscal e escolhe a melhor fonte de cálculo em cada pagamento.

Diferencial competitivo

Comece em minutos. Evolua sem mudar a integração.

Um estabelecimento pode iniciar com a Regra Setorial da NexoSplit e, quando desejar, evoluir para uma Regra Própria ou para a Conciliação por Documento Fiscal. Em todos os casos, o PSP continua utilizando exatamente a mesma API, sem qualquer alteração técnica. O PSP integra uma única vez — a maturidade fiscal dos estabelecimentos evolui sem impacto na integração.

11Webhooks

Eventos assíncronos da NexoSplit

A instituição cadastra uma URL para receber os eventos de ciclo de vida do pagamento, versões de instrução e retornos governamentais. Entrega com retry exponencial e assinatura HMAC.

Payload

{
  "event": "split_instruction.ready",
  "payment_id": "pay_01JNY456",
  "external_id": "transacao-123",
  "split_instruction": {
    "instruction_id": "inst_01JNZ789",
    "version": 1,
    "status": "ready",
    "cbs_amount": 900,
    "ibs_amount": 100,
    "merchant_amount": 99000,
    "calculation_rule": "FISCAL_DOCUMENT"
  }
}

Eventos disponíveis

split_instruction.ready
split_instruction.updated
payment.paid
payment.settled
payment.cancelled
reconciliation.completed
merchant.activated
merchant.onboarding_completed

12Códigos de erro

Respostas de erro padronizadas

Toda resposta de erro segue o mesmo envelope, com code, message e, quando aplicável, details[] apontando o campo em falha.

HTTP	Code	Descrição
400	validation_error	Payload inválido ou fora do schema.
401	invalid_token	Access token ausente, expirado ou sem escopo.
404	payment_not_found	Payment inexistente para o identificador informado.
404	merchant_not_found	Estabelecimento não encontrado.
409	instruction_outdated	Versão da Split Instruction obsoleta — consulte a mais recente.
409	merchant_already_exists	CPF ou CNPJ já cadastrado nessa instituição.
422	invalid_lifecycle	Transição de lifecycle_stage não permitida.
422	invalid_tax_id	CPF ou CNPJ inválido.
422	invalid_responsible_contact	E-mail ou telefone do responsável inválido.
429	rate_limited	Limite de chamadas excedido. Aguarde e reenvie.
500	internal_error	Erro interno da NexoSplit. Reenvio idempotente é seguro.

Envelope

{
  "error": {
    "code": "instruction_outdated",
    "message": "The split instruction version is outdated. Fetch the latest version before executing.",
    "details": [
      { "field": "instruction_version", "expected": 2, "received": 1 }
    ]
  }
}

13Responsabilidade

Papéis regulatórios

A NexoSplit atua como Prestador de Serviço de Conexão e plataforma de orquestração. A responsabilidade regulatória perante a Plataforma Pública permanece com o PSP Recebedor Direto.

14Referências

Próximos passos

Recursos

Documentos técnicos e regulatórios

Guia de integração completo, catálogo de mensageria e fontes oficiais do governo.

Acessar →

Sandbox

Solicitar credenciais e acesso à sandbox

Participantes recebem credenciais OAuth, URLs de ambiente e catálogo de webhooks.

Solicitar acesso →