Princípio central: quem errou, paga. A Movvia não distribui o custo do erro igualmente — identifica a causa e atribui a responsabilidade ao responsável.
| Causa do erro | Quem absorve | Mecanismo |
|---|---|---|
| Erro de OCR / categoria incorreta | EC (concessionária) | EC solicita estorno via API |
| Erro de sistema da Movvia | Movvia | Estorno automático por referenciaExterna |
| Fraude do cidadão | Liquidante | Liquidante absorve (é cliente dele, risco dele) |
| Placa clonada | EC investiga, Movvia executa | EC confirma e solicita estorno |
| Cobrança duplicada (sua) | EC | EC cancela via DELETE /ec/cobrancas/{id} antes da liquidação |
| Cobrança duplicada (Movvia) | Movvia | Estorno automático, você é notificado |
Você precisa do passagemId (retornado na criação) ou do referenciaExterna (seu ID).
GET /ec-api/v1/passagens?referenciaExterna=PASS-2026-0009871
Authorization: Basic {credencial_ec}
x-ec-id: {ec_id}POST /ec-api/v1/passagens/{passagemId}/estornar
Authorization: Basic {credencial_ec}
x-ec-id: {ec_id}
Content-Type: application/json
{
"motivo": "ERRO_OCR",
"descricao": "Placa lida incorretamente pelo sensor da praça 9f2c.",
"valorEstorno": 12.50
}Motivos aceitos: ERRO_OCR, CATEGORIA_INCORRETA, PLACA_CLONADA, COBRANCA_INDEVIDA, OUTROS.
{
"evento": "pe.passagem.estornada",
"passagemId": "cob_9f2c7e1a",
"referenciaExterna": "PASS-2026-0009871",
"valorEstornado": 12.50,
"debitadoDa": "subconta_ec",
"estornadoEm": "2026-04-24T09:00:00Z"
}O valor é debitado da sua subconta e devolvido ao liquidante, que devolve ao cidadão.
| Tipo | SLA de análise | SLA de execução |
|---|---|---|
| Erro de OCR (EC solicita) | Imediato (automático) | Até 2h úteis |
| Fraude / placa clonada | 3 dias úteis | Após confirmação da investigação |
| Erro Movvia | Imediato (automático) | Até 1h |
SLAs com penalidade para erros da Movvia são definidos no contrato enterprise.
Se apenas parte do valor foi cobrado indevidamente (ex.: categoria 1 cobrada, deveria ser categoria 2), o campo valorEstorno aceita valor menor que o valorLiquidado original.
Cobranças com status EXPIRADA não podem ser estornadas — nunca houve liquidação. Se você gerou uma cobrança indevida que expirou, nenhuma ação é necessária.
O liquidante pode abrir disputa sobre uma cobrança que ele já liquidou (ex.: cidadão alega que não passou). Nesse caso:
- Você recebe
ec.disputa.abertano webhook. - Você tem o prazo definido no contrato para apresentar evidência (foto, log de sensor).
- A Movvia avalia e decide.
- Se a disputa for procedente, o estorno é executado com débito na sua subconta.
{
"evento": "ec.disputa.aberta",
"passagemId": "cob_9f2c7e1a",
"referenciaExterna": "PASS-2026-0009871",
"abertaPor": "liq_banco_xyz",
"motivo": "CIDADAO_CONTESTA",
"prazoResposta": "2026-04-27T23:59:59Z"
}- Reconciliação — como estornos aparecem no extrato e afetam a conciliação.