Integração da adquirente

Estorno de Transações

Como desfazer uma venda já enviada — e o que a BackMoney desfaz sozinha quando isso acontece.

Quando uma venda é cancelada ou estornada na maquininha, a adquirente envia um evento de estorno para o mesmo endpoint das vendas. A BackMoney localiza a venda original e desfaz tudo o que ela gerou: cashback, vouchers, milhas, comissões da rede, ganhos da loja, fatias da casa, fundos de sorteio, cupons e a liquidação.

Em uma frase

O estorno só precisa dizer QUAL venda ele desfaz. O valor e o estabelecimento são lidos da própria venda — a adquirente não repete (nem pode contradizer) esses dados.

O payload mínimo

Três informações bastam: um event_id novo, o tipo do evento e o transaction_code da venda que está sendo desfeita.

POST /api/webhooks/transactions

curl -X POST https://api.backmoney.com.br/api/webhooks/transactions \
  -H "Authorization: Bearer backmoney-SUA_CHAVE_AQUI" \
  -H "X-BackMoney-Signature: t=1751380000, kid=SEU_FINGERPRINT, sig=BASE64_DA_ASSINATURA" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "event_id": "12234455",
        "event_type": "pos.reversal",
        "data": {
          "transaction_code": "697000007"
        }
      }
    ]
  }'

Campo	Obrigatório	Descrição
event_id	sim	Novo e único — é a chave de idempotência. Nunca reaproveite o `event_id` da venda: reenviar um id já recebido é tratado como duplicado e ignorado.
event_type	sim	`pos.reversal`. Também valem `pos.refund`, `pos.cancellation` e `pos.chargeback` — todos desfazem a venda da mesma forma.
data.transaction_code	sim	O código/NSU da venda original. É o que liga o estorno a ela.
data.merchant_document	condicional	Só é necessário quando o mesmo `transaction_code` existe em mais de um estabelecimento (ver Quando o código se repete).
data.amount	não	Lido da venda original. Se for enviado, é aceito — mas não produz estorno parcial.
data.status	não	Diz se a operação deu certo (`approved`, `completed`). Não é onde se diz que é um estorno.

Resposta

200 OK

{
  "data": {
    "provider": "deltapay",
    "received": 1,
    "ingested": 1,
    "duplicates": 0,
    "skipped": 0,
    "unhandled": 0,
    "results": [
      { "event_id": "12234455", "event_type": "pos.reversal", "status": "ingested" }
    ]
  }
}

O erro mais comum

A operação é definida pelo event_type, nunca pelo status. Enviar uma venda (pos.sale) com status: "reversed" não estorna nada — e como reversed não é um resultado válido, o evento inteiro é descartado (skipped) e a venda continua valendo.

Não faça isso

{
  "event_id": "697000007-refund",
  "event_type": "pos.sale",          // ERRADO: continua sendo uma VENDA
  "data": {
    "transaction_code": "697000007",
    "status": "reversed"             // ERRADO: "reversed" não é um resultado
  }
}

Os dois campos têm papéis diferentes

event_type = QUE operação é (venda, estorno, chargeback). status = SE a operação deu certo. Um pos.refund com status declined significa 'tentamos estornar e falhou' — por isso o estorno não pode ser expresso pelo status.

Por compatibilidade, hoje aceitamos pos.reversed, pos.refunded e pos.cancelled como sinônimos, e reversed/refunded no status de um evento de estorno. Ainda assim, prefira pos.reversal com o status ausente ou approved.

Quando o código se repete

O transaction_code costuma ser o NSU do terminal, que se repete entre maquininhas e recicla com o tempo. Se o código informado corresponder a vendas de mais de um estabelecimento, a BackMoney recusa o evento em vez de adivinhar — estornar a venda da loja errada movimentaria dinheiro real de quem não tem nada a ver com a operação.

Nesse caso, informe também o estabelecimento:

Desambiguando pelo estabelecimento

{
  "events": [
    {
      "event_id": "12234455",
      "event_type": "pos.reversal",
      "data": {
        "transaction_code": "697000007",
        "merchant_document": "46.346.246/8010-01"
      }
    }
  ]
}

Regras do estorno

É sempre total. O estorno desfaz a venda inteira; não existe estorno parcial. Enviar um valor menor não reverte proporcionalmente.
É idempotente. Uma venda é revertida uma única vez. Reenviar o estorno (com um event_id novo) não desconta duas vezes.
A venda precisa existir. Um estorno cujo transaction_code não corresponde a nenhuma venda recebida é recusado, com o motivo na resposta.
Saldo já gasto não fica negativo. Se o cliente já usou o cashback, a diferença é absorvida pela BackMoney — a carteira dele não vai a negativo.
A devolução ao portador é da adquirente. A BackMoney desfaz os benefícios e as comissões; o dinheiro do cartão volta pelo fluxo da adquirente.

Como conferir

No backoffice, o extrato da venda passa a exibir o selo de estornada, e a listagem de transações mostra o evento de estorno logo abaixo da venda. O resumo da entrega (ingested / skipped) já indica na hora se o evento foi aceito.