# Pedágio de barreira **Quem é você.** Você opera praças de pedágio com cancela física — a cobrança ocorre no ato da passagem, com identificação do veículo por OCR, RFID ou apresentação do transponder. Cancela só libera com pagamento autorizado. **Problema.** Motoristas sem dinheiro em espécie ou com transponder inativo causam fila e atrito operacional. Integrar cada adquirente individualmente é caro — e pagamento manual no guichê é lento demais para o fluxo da praça. **Solução Movvia.** Você publica a cobrança no momento da passagem com TTL curto. A rede de canais (totem na própria praça, app de carteira do motorista, portal oficial) reserva e confirma em segundos. Você recebe o sinal de pagamento confirmado com `nsu`, `txid` e `origemLiquidacao` para liberar a cancela. ## Como encaixa no seu produto - Cobrança publicada no instante da identificação do veículo, com TTL configurado no onboarding (típico: 90s para fluxo de cancela; até 48h se tolerar pagamento pós-passagem). - Reserva atômica: enquanto um canal estiver tentando pagar, nenhum outro pode interferir — sem cobrança duplicada. - Confirmação de pagamento traz `metodoPagamento` e `origemLiquidacao` em tempo real, suficiente para automatizar a liberação da cancela. - Cobranças não pagas no TTL voltam ao seu fluxo pós-pago tradicional, com histórico das tentativas. ## Os 3 fluxos do protocolo via API Cada passagem na barreira passa pelos mesmos 3 pontos de integração — só o tempo entre eles muda (segundos em vez de dias). ### 1. Enviar cobrança no momento da passagem Sua estação de identificação (OCR no pórtico de entrada, leitura de transponder ou guichê) publica a cobrança imediatamente: ```http POST /ec-api/v1/passagens Authorization: Basic {credencial_ec} x-ec-id: {ec_id} Content-Type: application/json Idempotency-Key: BARREIRA-2026-00441 { "referenciaExterna": "BARREIRA-2026-00441", "placa": "XYZ9W87", "valor": 8.20, "tipo": "BARREIRA", "praca": { "id": "dutra-003", "nome": "Praça 3 — Via Dutra KM 132", "sentido": "SP-RJ" }, "categoria": 2, "categoriaDescricao": "Veículo comercial 2 eixos", "capturadoEm": "2026-04-23T11:17:04Z", "ttl": 90, "cancelaId": "cancela-3-faixa-2" } ``` **Resposta `201 Created`:** ```json { "passagemId": "01JVZA1G8K7M2N5P3Q6R9T8X4B", "status": "PENDENTE", "expiresAt": "2026-04-23T11:18:34Z", "criadaEm": "2026-04-23T11:17:04Z" } ``` Notas: - `ttl` em segundos. Após esse prazo a cobrança expira automaticamente; configure conforme seu modo de operação (`90` para liberação síncrona; `172800` = 48h para pós-pago). - `cancelaId` opcional: se enviado, é incluído nos webhooks subsequentes para você direcionar o sinal de liberação para a cancela correta. - `valor` em **reais com 2 decimais** (mesma convenção da API Parceiros). ### 2. Receber pedido de reserva (lock) Em segundos, um canal autorizado tenta pagar. Você recebe webhook informando o lock — útil para mostrar "processando" no painel da praça e travar tentativa concorrente: ```http POST {sua_url_webhook} x-movvia-signature: Content-Type: application/json { "evento": "pe.passagem.reservada", "versao": "2", "id": "evt_2b3c4d5e6f7a", "timestamp": "2026-04-23T11:17:08Z", "ecId": "ec_dutra_concessionaria", "dados": { "passagemId": "01JVZA1G8K7M2N5P3Q6R9T8X4B", "referenciaExterna": "BARREIRA-2026-00441", "placa": "XYZ9W87", "reservaId": "a78bc92d-1f3e-4c45-9012-bd56fa8e7c91", "cancelaId": "cancela-3-faixa-2", "valor": 8.20, "expiresAt": "2026-04-23T11:18:34Z", "canal": { "tipo": "TOTEM", "id": "totem-dutra-003-frente", "nome": "Totem Dutra Praça 3" } } } ``` Notas: - Para pedágio de barreira, `expiresAt` da reserva = `expiresAt` da cobrança (ambos terminam no fim do TTL). Não há renovação. - Se o canal não confirmar dentro do TTL, você recebe `pe.passagem.expirada` — fluxo manual no guichê. - `cancelaId` (se foi enviado no passo 1) está incluído no payload para você correlacionar com a cancela física. ### 3. Receber pagamento confirmado e liberar a cancela Confirmação chega tipicamente em segundos. Esse é o sinal para liberar a cancela: ```http POST {sua_url_webhook} x-movvia-signature: Content-Type: application/json { "evento": "pe.passagem.paga", "versao": "2", "id": "evt_4f5a6b7c8d9e", "timestamp": "2026-04-23T11:17:13Z", "ecId": "ec_dutra_concessionaria", "dados": { "passagemId": "01JVZA1G8K7M2N5P3Q6R9T8X4B", "referenciaExterna": "BARREIRA-2026-00441", "reservaId": "a78bc92d-1f3e-4c45-9012-bd56fa8e7c91", "cancelaId": "cancela-3-faixa-2", "valor": 8.20, "valorRepasseLiquido": 7.96, "comprovante": { "nsu": "000089432101", "txid": "TOT20260423111712CD9F8B2A", "metodoPagamento": "PIX", "origemLiquidacao": "TOTEM", "canalId": "totem-dutra-003-frente", "pagoEm": "2026-04-23T11:17:12Z" }, "protocoloMovvia": "MV-2026-04-23-00118" } } ``` Campos de `dados.comprovante`: | Campo | Descrição | | --- | --- | | `nsu` | Número Sequencial Único do pagamento (gerado pelo adquirente / arranjo de pagamento) | | `txid` | Identificador da transação no canal (PIX EndToEnd ID, autorização do cartão, etc.) | | `metodoPagamento` | `PIX`, `CARTAO_CREDITO`, `CARTAO_DEBITO` ou `DINHEIRO` | | `origemLiquidacao` | Onde o motorista pagou: `PORTAL` (portal oficial Movvia), `TOTEM` (terminal físico na praça) ou `PARCEIRO` (app de carteira/banco/frota) | | `canalId` | ID do canal específico dentro da origem | | `pagoEm` | Timestamp UTC do pagamento | Regra operacional para liberação síncrona da cancela: 1. Receber `pe.passagem.paga`. 2. Validar `x-movvia-signature` (HMAC) antes de processar — descarte payloads não assinados. 3. Verificar que `dados.cancelaId` corresponde à faixa que está aguardando. 4. Acionar abertura da cancela. Tempo total típico Movvia → seu sistema → cancela: < 1 segundo após confirmação. > Convenção dos eventos `pe..` é a mesma da API Parceiros: envelope `{evento, versao, id, timestamp, ecId}` + bloco `dados` específico. Ver [Webhooks Parceiros](/parceiros/guides/webhooks) para retry, HMAC e idempotência. ## Modelo de receita típico `valorRepasseLiquido` é repassado em D+0 — relevante para barreira porque o caixa operacional da praça precisa fechar todo dia. A taxa Movvia varia conforme `metodoPagamento` (PIX no totem é a mais barata; cartão de crédito é a mais cara) e `origemLiquidacao` (TOTEM costuma ser plano dedicado). ## Regras operacionais - **TTL curto exige resposta rápida do parceiro/totem.** Canais com latência média acima do TTL são despriorizados pela Movvia automaticamente — operação saudável da praça é prioridade. - **Atomicidade.** Cada cobrança de barreira gera no máximo 1 reserva ativa. Não há agrupamento por placa em barreira — diferente de free flow. - **Estorno.** Se a cancela falhar após `pe.passagem.paga` (ex.: defeito mecânico, motorista forçou), abra um ticket via endpoint de reversão; a Movvia notifica o canal para estorno ao motorista. Esse fluxo é exceção, não rotina. ## Próximo passo - [Publicar primeira cobrança](/estabelecimentos-comerciais/tutorials/publicar-primeira-cobranca) — tutorial passo-a-passo em sandbox. - [Validar webhooks com HMAC](/compartilhado/seguranca/hmac) — assinatura obrigatória de `pe.passagem.*`. - [Idempotência](/compartilhado/seguranca/idempotencia) — como tratar reenvios de webhooks no fluxo de cancela.