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_cnpj do evento; um CNPJ ainda desconhecido é cadastrado automaticamente.
• Sem perda de dados: um event_type sem tratamento é armazenado e reconhecido como unhandled (nada é descartado).

Autenticação

A requisição é autenticada com um token Bearer (a API key da adquirente, no formato backmoney-…), que precisa ter a permissão webhooks:ingest. Uma única chave recebe os eventos de todos os estabelecimentos atendidos por aquela adquirente.

Authorization: Bearer backmoney-SUA_CHAVE_AQUI

Assinatura da requisição

Além da API key, a BackMoney pode exigir que cada envio seja assinado com a chave privada do certificado do adquirente — dando integridade, proteção contra replay e não-repúdio. Quando a exigência está ligada, requisições sem assinatura válida recebem 401.

Como assinar

1. Monte a string canônica: <t>.<MÉTODO>.<CAMINHO>.<sha256hex(corpo)> — onde t é o timestamp Unix (segundos), MÉTODO é POST, CAMINHO é /api/webhooks/transactions (sem query string) e o hash é o SHA-256 do corpo exatamente como enviado.
2. Assine a string canônica com a chave privada (ECDSA P-256, hash SHA-256). A assinatura é ASN.1/DER, codificada em base64.
3. Envie no header X-BackMoney-Signature com t, kid (o fingerprint do certificado) e sig.

X-BackMoney-Signature: t=1751303525, kid=7125327055e6fd14a1b2…, sig=MEUCIQDk…

Exemplos de assinatura

import crypto from 'node:crypto'
import fs from 'node:fs'

const privateKey = crypto.createPrivateKey(fs.readFileSync('private-key.pem'))
const ts = Math.floor(Date.now() / 1000)
const bodyHash = crypto.createHash('sha256').update(body).digest('hex')
const canonical = `${ts}.POST./api/webhooks/transactions.${bodyHash}`

// ECDSA P-256 + SHA-256, assinatura ASN.1/DER em base64
const sig = crypto
  .sign('sha256', Buffer.from(canonical), { key: privateKey, dsaEncoding: 'der' })
  .toString('base64')

const header = `t=${ts}, kid=${fingerprint}, sig=${sig}`

Endpoint

Base de produção: https://api.backmoney.com.br · homologação: https://api-development.backmoney.com.br.

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 "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_cnpj": "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": 1,
    "ingested": 1,
    "duplicates": 0,
    "skipped": 0,
    "unhandled": 0
  }
}

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.

Boas práticas

• Sempre via HTTPS; envie o amount.value em centavos (inteiro).
• Use um event_id estável e único por transação (ex.: o NSU + adquirente).
• Inclua card_brand e installments — eles definem a taxa da maquininha (MDR).
• Implemente retry com backoff em 5xx/timeout; confie na idempotência.
• Acompanhe as entregas em GET /api/v1/webhooks/events (status por evento).