Envio de Transações

Toda transação processada nas maquininhas é enviada para a BackMoney pela própria adquirente/subadquirente, em tempo real, por webhook. O estabelecimento nunca lança transações manualmente — a fonte da verdade é o fluxo da adquirente. A partir de cada evento, a BackMoney concilia a venda e dispara os benefícios (cashback, vouchers, cupons, multinível).

Visão geral

• Direção: a adquirente envia (push) para a BackMoney — não somos nós que consultamos.
• Em lote: cada requisição leva um array events (1 ou mais eventos).
• Idempotente: cada evento tem um event_id único; reenviar o mesmo id é tratado como duplicado, sem dupla contagem.
• Identificação por chave: o parceiro é identificado pela própria API key — o provider é derivado dela, então não há como forjar a origem de outro.
• Resolução do lojista: a loja é resolvida pelo merchant_document do evento — CPF (11 dígitos) ou CNPJ (14), já que o estabelecimento pode ser pessoa jurídica ou pessoa física/MEI; um documento ainda desconhecido é cadastrado automaticamente.
• Sem perda de dados: um event_type sem tratamento é armazenado e reconhecido como unhandled (nada é descartado).

Endpoint

Corpo da requisição

O corpo é um envelope com o lote de eventos:

Objeto do evento

O objeto data (eventos pos.*)

Para eventos de maquininha (pos.*), o data traz:

Tipos de evento (event_type)

Exemplo — uma venda

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": "evt_9f2c7a13b8",
        "event_type": "pos.sale",
        "occurred_at": "2026-06-30T14:12:05Z",
        "data": {
          "device_serial": "PAX-A920-00237",
          "transaction_code": "NSU-882211",
          "amount": { "value": 10000, "currency": "BRL" },
          "payment_method": "credit_card",
          "card_brand": "visa",
          "installments": 1,
          "status": "approved",
          "merchant_document": "12.345.678/0001-90",
          "customer_cpf": "390.533.447-05",
          "customer_phone": "+5511987654321"
        }
      }
    ]
  }'

Resposta

A resposta vem no envelope padrão { "data": … }, com o resumo da entrega:

{
  "data": {
    "provider": "deltapay",
    "received": 2,
    "ingested": 1,
    "duplicates": 0,
    "skipped": 1,
    "unhandled": 0,
    "results": [
      { "event_id": "evt_abc123", "event_type": "pos.sale", "status": "ingested" },
      { "event_id": "evt_def456", "event_type": "pos.sale", "status": "skipped",
        "error": "payment_method must be one of: credit_card, debit_card, pix, boleto, wallet, cash, other" }
    ]
  }
}

O array results

Cada item traz o desfecho de um evento, para você agir sobre ele (corrigir um skip, notar um tipo sem tratamento) — não só ver o total:

Envio em lote

Você pode agrupar vários eventos numa única entrega — recomendado para reduzir chamadas. Cada evento é processado de forma independente; o resumo da resposta soma os resultados.

{
  "events": [
    { "event_id": "evt_001", "event_type": "pos.sale",   "data": { /* ... */ } },
    { "event_id": "evt_002", "event_type": "pos.sale",   "data": { /* ... */ } },
    { "event_id": "evt_003", "event_type": "pos.refund", "data": { /* ... */ } }
  ]
}

Idempotência, reentrega e erros

• Idempotência: reenviar um event_id já processado retorna como duplicates — não gera nova transação nem benefícios em dobro.
• Reentrega: em caso de 5xx ou timeout, reenvie o lote inteiro; os eventos já recebidos serão deduplicados.
• Parcial: um evento inválido não derruba o lote — ele entra como skipped e os demais seguem.