Sua cobrança em toda carteira.

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude
• Connect to Cursor

  Install MCP server on Cursor
• Connect to VS Code

  Install MCP server on VS Code

Você opera um serviço que cobra do motorista ou cidadão em trânsito. A Movvia conecta sua cobrança a dezenas de apps, carteiras digitais e bancos — sem você negociar com cada um.

Pedir credenciais de sandbox

Quem é o Estabelecimento Comercial

Você é um Estabelecimento Comercial (EC) se:

• Emite cobrança para o usuário final (motorista, empresa, cidadão).
• Opera pedágio free flow, pedágio de barreira, balsa, estacionamento, serviço portuário ou zona azul.
• Quer receber pela rede sem negociar individualmente com carteiras e bancos.
• Detém o relacionamento com o pagador e a responsabilidade pelo título da cobrança.
• Precisa de observabilidade em tempo real sobre cada cobrança (status, liquidante, valor repasado).

Se você liquida cobranças em nome de outros ECs (app, banco, carteira), o papel correto é Parceiro — veja a página do Parceiro.

Como funciona em 3 passos

1. Publique a passagem

Cada evento que gera um título (passagem detectada, ticket, embarque) vira uma chamada à API:

POST /ec-api/v1/passagens
Authorization: Basic {credencial_ec}
x-ec-id: {ec_id}
Content-Type: application/json
Idempotency-Key: PASS-2026-0009871

{
  "referenciaExterna": "PASS-2026-0009871",
  "placa": "ABC1D23",
  "valor": 12.50,
  "tipo": "FREEFLOW",
  "praca": { "id": "imigrantes-km245", "nome": "Imigrantes KM 245", "sentido": "SUL" },
  "categoria": 1,
  "capturadoEm": "2026-04-23T14:32:10Z"
}

2. Receba pedido de reserva (lock)

Quando um canal autorizado (portal, totem ou parceiro) reserva a passagem para pagamento, você recebe webhook assinado:

{
  "evento": "pe.passagem.reservada",
  "versao": "2",
  "id": "evt_8a3f1b2c9d4e",
  "timestamp": "2026-04-23T14:35:00Z",
  "ecId": "ec_imigrantes_concessionaria",
  "dados": {
    "passagemId": "01JVZ8F4WH9R2T7K5M3N8P6Q4X",
    "referenciaExterna": "PASS-2026-0009871",
    "reservaId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "valor": 12.50,
    "expiresAt": "2026-04-23T14:50:00Z",
    "canal": { "tipo": "PARCEIRO", "id": "carteira-banco-xyz" }
  }
}

3. Receba pagamento confirmado

Quando o canal confirma pagamento, você recebe o evento final com nsu, txid, metodoPagamento, origemLiquidacao e o reservaId para correlação:

{
  "evento": "pe.passagem.paga",
  "versao": "2",
  "id": "evt_3c4d5e6f7a8b",
  "timestamp": "2026-04-23T14:38:11Z",
  "ecId": "ec_imigrantes_concessionaria",
  "dados": {
    "passagemId": "01JVZ8F4WH9R2T7K5M3N8P6Q4X",
    "reservaId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "valor": 12.50,
    "valorRepasseLiquido": 12.13,
    "comprovante": {
      "nsu": "000132547890",
      "txid": "MV20260423143810AB7F2C9D",
      "metodoPagamento": "PIX",
      "origemLiquidacao": "PARCEIRO",
      "canalId": "carteira-banco-xyz",
      "pagoEm": "2026-04-23T14:38:10Z"
    }
  }
}

Valores liquidados entram no ciclo de repasse combinado em contrato. Conciliação automática por referenciaExterna. Detalhes no extrato:

GET /ec-api/v1/extrato?desde=2026-04-01
Authorization: Basic {credencial_ec}
x-ec-id: {ec_id}

Casos de uso

Vision Dados — monetização do acervo de imagens

Se você opera captura de placas (câmera própria em rodovia, estacionamento ou ponto fiscal), pode rentabilizar o acervo via Vision Dados, mais um caso de uso da plataforma EC. Modelo de receita inverso: a Movvia paga você por passagem ingerida e aceita por clientes B2B.

Ver caso de uso Vision Dados →

Movvia vs. integração direta com carteiras

Três pilares da plataforma EC

Captura automática. Qualquer evento que você gera (passagem, ticket, embarque) vira cobrança publicada na rede em segundos, sem filas manuais.

Modelo trustee. A Movvia custodia os recursos em conta master com subcontas por EC. Saldo auditável em tempo real. Você não precisa virar instituição de pagamento.

Reconciliação nativa. Cada cobrança carrega referenciaExterna — campo seu, imutável. O extrato e os repasses batem exatamente com seu sistema de origem, sem planilha intermediária.

Developer experience

• Autenticação: Basic Auth + header x-ec-id (credencial por ambiente).
• Webhooks assinados com HMAC-SHA256 — valide antes de processar.
• Idempotência por referenciaExterna — envio duplicado não gera cobrança dupla.
• Sandbox disponível em minutos após solicitação.
• Referência da API: OpenAPI 3.1 com exemplos em cURL, Node e Python.
• Status da API EC: em produção.

Preços

Repasse em D+0 ou D+1 conforme plano. Taxa deduzida no momento da liquidação — você paga só sobre valor efetivamente recebido.

Perguntas frequentes

Próximo passo

1. Leia o guia de modelo trustee para entender a custódia de recursos.
2. Leia o ciclo de repasse para entender quando e como o dinheiro chega.
3. Siga o tutorial Publicar primeira cobrança para validar o fluxo em sandbox.
4. Abra a Referência da API para ver todos os endpoints, schemas e eventos de webhook.