API de pagamentos PIX na edge

Visão geral #

Esta é a API do seller da Reven — a superfície pública que integradores externos consomem. Toda requisição é autenticada por X-Api-Key (uma chave por workspace) e todo corpo/resposta segue o envelope { success, data } / { success, error }.

Endpoints

Credenciais & rate limit #

O admin gera uma API Key por workspace no painel. Ela vai no header de toda requisição:

X-Api-Key: sua_api_key_aqui

Barreira de flood (429)

Depois de 30 respostas 401 de credencial (header ausente ou chave inexistente) do mesmo IP em 5 minutos, as tentativas seguintes com chave ausente/inválida desse IP passam a receber 429 com Retry-After (segundos):

{ "success": false, "error": "Too many requests. Please try again later." }

Webhook Secret

Cada workspace tem também um Webhook Secret (no painel), usado para verificar a assinatura dos webhooks (§ Verificar assinatura) e assinar os saques (§ Criar saque).

Assinatura de requisição #

Distinta da assinatura de webhook. Quando requireSignature está ativo no seu workspace, além da X-Api-Key toda requisição que você envia precisa de assinatura HMAC — inclusive as de leitura.

X-Signature: <hmac_hex>
X-Timestamp: <epoch_ms>   # dentro de ±5 min
X-Nonce: <uuid_unico>     # nunca reutilizar

HMAC-SHA256 em hex, chave = sua API Key, mensagem canônica:

canonical = `${METHOD}\n${path}\n${body}\n${timestamp}\n${nonce}`
# body = "" em GET; path = pathname sem query (ex.: /api/gateway/charges)

Se o workspace não exige assinatura, omita X-Signature/X-Timestamp/X-Nonce e mantenha só a X-Api-Key. Exemplo completo em Node na § Criar cobrança.

Criar cobrança PIX #

curl -X POST 'https://app.revenpayments.com.br/api/gateway/charges' \
  -H 'X-Api-Key: SUA_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "product":  { "name": "Plano Pro", "value": 149.90 },
    "customer": {
      "name": "João Silva",
      "email": "joao@exemplo.com",
      "doc": "11122233344",
      "docType": "cpf",
      "phone": "11912345678"
    },
    "expiracaoSegundos": 3600,
    "callbackUrl": "https://seusite.com/webhooks/pix",
    "metadata": { "pedido_id": "A-1001" }
  }'

Corpo do request

Resposta 201

{
  "success": true,
  "data": {
    "transactionId": "b3f1…",
    "pixCode": "00020126580014br.gov.bcb.pix…",
    "expiresAt": "2026-07-23T13:00:00.000Z",
    "amount": 149.90,
    "feeAmount": 5.25,
    "netAmount": 144.65
  }
}

pixCode é o copia-e-cola (EMV) — gere o QR a partir dele. Erros seguem { "success": false, "error": "<mensagem>" }.

Exemplo Node — com assinatura de requisição

import { createHmac, randomUUID } from 'node:crypto'

const API = 'https://app.revenpayments.com.br/api'
const API_KEY = process.env.CHECKOUT_API_KEY!

async function createCharge(body) {
  const path = '/api/gateway/charges'
  const raw = JSON.stringify(body)
  const ts = Date.now().toString()
  const nonce = randomUUID()
  const canonical = `POST\n${path}\n${raw}\n${ts}\n${nonce}`
  const signature = createHmac('sha256', API_KEY).update(canonical).digest('hex')

  const res = await fetch(`${API}/gateway/charges`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Api-Key': API_KEY,
      'X-Signature': signature,   // omita se o workspace não exige assinatura
      'X-Timestamp': ts,
      'X-Nonce': nonce,
    },
    body: raw,
  })
  const json = await res.json()
  if (!json.success) throw new Error(json.error)
  return json.data
}

Rastreio de anúncio no metadata #

Chaves opcionais que a plataforma passa a ler e armazenar quando enviadas no metadata da cobrança. Como metadata sempre foi objeto livre, isto não altera o contrato — não mandar nenhuma = comportamento de hoje, byte a byte.

Deduplicação: use o transactionId

Se você também dispara a compra pelo pixel do navegador, use o mesmo transactionId devolvido pelo POST /gateway/charges no campo de dedupe. Sem isso, cada venda é contada duas vezes.

Identificadores de clique aceitos

Todos string. Envie só os que você tem; ausente e null equivalem. Só existem no momento do clique — se não capturar e enviar, não são recuperáveis depois.

Aceitamos a forma plana ou aninhada em trackingParameters — as duas produzem o mesmo resultado:

{ "metadata": { "pedido_id": "A-1001", "gclid": "Cj0KCQ…", "fbp": "fb.1.1690000000000.1234567890" } }
{ "metadata": { "pedido_id": "A-1001", "trackingParameters": { "gclid": "Cj0KCQ…" } } }

Listar transações #

Retorna as transações do seu workspace (paginado). Cada item traz status, amount, feeAmount, netAmount, endToEndId, paidAt, metadata. Use para reconciliação/polling se não puder receber webhook.

curl 'https://app.revenpayments.com.br/api/gateway/transactions?page=1&limit=20' \
  -H 'X-Api-Key: SUA_API_KEY'

Compare status exatamente em MAIÚSCULO (ex.: status === 'PAID'). Ver § Status & erros.

Receber o status por webhook #

Se você enviou callbackUrl, o gateway faz POST nessa URL a cada mudança de status. Headers: Content-Type: application/json, User-Agent: Reven-Webhook-Dispatcher/1.0 e X-Signature. Acompanham X-Webhook-Id, X-Timestamp e X-Signature-V2 (novos e opcionais — § V2).

{
  "event": "transaction.paid",
  "data": {
    "transactionId": "b3f1…",
    "acquirerTxId": "abc123",
    "endToEndId": "E1234567890202607231240abcdef123",
    "status": "PAID",
    "amount": 149.90,
    "feeAmount": 5.25,
    "netAmount": 144.65,
    "productName": "Plano Pro",
    "customer": { "name": "João Silva", "email": "joao@exemplo.com" },
    "metadata": { "pedido_id": "A-1001" },
    "paidAt": "2026-07-23T12:40:00.000Z",
    "createdAt": "2026-07-23T12:00:00.000Z"
  }
}

Verificar a assinatura (X-Signature) #

O X-Signature é o HMAC-SHA256 do corpo bruto (o JSON exatamente como recebido, sem re-serializar) com o Webhook Secret do workspace. Recompute e compare antes de confiar no evento:

import { createHmac, timingSafeEqual } from 'node:crypto'

const WEBHOOK_SECRET = process.env.CHECKOUT_WEBHOOK_SECRET! // do painel, por workspace

function verify(rawBody, signatureHeader) {
  const expected = createHmac('sha256', WEBHOOK_SECRET).update(rawBody).digest('hex')
  const a = Buffer.from(expected), b = Buffer.from(signatureHeader || '')
  return a.length === b.length && timingSafeEqual(a, b)
}

// No seu endpoint: leia o corpo CRU (string) antes de parsear.
// if (!verify(rawBody, req.headers['x-signature'])) return res.status(401).end()

Assinatura V2 do webhook (anti-replay) #

O X-Signature cobre só o corpo — e, como nada nele envelhece, uma entrega interceptada tem assinatura válida para sempre. Todo webhook passa a trazer também três headers novos. É recomendado, não obrigatório: quem só valida o X-Signature segue suportado, sem prazo de corte.

X-Webhook-Id:   <uuid da entrega>   # igual em todas as retentativas
X-Timestamp:    <epoch_ms>          # instante da assinatura
X-Signature-V2: <hmac_hex>

canonical = `${X-Timestamp}\n${X-Webhook-Id}\n${corpo bruto}`

function verifyV2(rawBody, h) {
  const ts = Number(h['x-timestamp'])
  if (!Number.isFinite(ts) || Math.abs(Date.now() - ts) > 5 * 60_000) return false // fora da janela
  const canonical = `${h['x-timestamp']}\n${h['x-webhook-id']}\n${rawBody}`
  const expected = createHmac('sha256', WEBHOOK_SECRET).update(canonical).digest('hex')
  const a = Buffer.from(expected), b = Buffer.from(h['x-signature-v2'] || '')
  return a.length === b.length && timingSafeEqual(a, b)
}

Rejeite X-Timestamp fora de ±5 min e guarde o X-Webhook-Id já processado (10 min bastam) para descartar repetição. Retentativa automática reusa o mesmo X-Webhook-Id; reenvio manual pedido ao suporte vem com id novo e deve ser processado.

Criar saque — cashout / PIX OUT #

Dispara um saque programático do seu saldo disponível para uma chave PIX. Diferente das cobranças, tem verificação de assinatura dedicada e sempre obrigatória — a X-Api-Key sozinha nunca saca.

1. X-Api-Key do workspace identifica você (middleware).
2. Allowlist de IP (opt-in) — IP fora da lista recebe 403. Sem cadastro, sem restrição.
3. Assinatura HMAC com o Webhook Secret (NÃO a api key) — assim uma api key vazada sozinha não saca. Headers X-Signature/X-Timestamp/X-Nonce.
4. Idempotency-Key (header obrigatório) — dedup atômico. Reenviar a MESMA key devolve o MESMO saque (200), sem debitar de novo.

Corpo do request

{ "amount": 100.00, "callbackUrl": "https://sua-loja.com/wh/saque", "pixKey": "loja@exemplo.com", "pixKeyType": "email" }

pixKeyType canônico ∈ cpf | cnpj | email | phone | random (case-insensitive). Aliases normalizados:

Assinatura do saque

Igual à assinatura de requisição, mas a chave é o Webhook Secret e o Idempotency-Key entra no canônico:

canonical = `${METHOD}\n${path}\n${body}\n${timestamp}\n${nonce}\n${idempotencyKey}`
X-Signature = HMAC-SHA256(chave = webhook_secret, mensagem = canonical)  # hex

import { createHmac, randomUUID } from 'node:crypto'

const API = 'https://app.revenpayments.com.br/api'
const API_KEY = process.env.CHECKOUT_API_KEY!
const WEBHOOK_SECRET = process.env.CHECKOUT_WEBHOOK_SECRET! // o mesmo do painel

async function withdraw(amount, dest) {
  const path = '/api/gateway/withdrawals'
  const raw = JSON.stringify({ amount, ...dest })
  const ts = Date.now().toString()
  const nonce = randomUUID()
  const idempotencyKey = randomUUID() // reusar no retry do MESMO saque
  const canonical = `POST\n${path}\n${raw}\n${ts}\n${nonce}\n${idempotencyKey}`
  const signature = createHmac('sha256', WEBHOOK_SECRET).update(canonical).digest('hex')

  const res = await fetch(`${API}/gateway/withdrawals`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Api-Key': API_KEY,
      'X-Signature': signature,
      'X-Timestamp': ts,
      'X-Nonce': nonce,
      'Idempotency-Key': idempotencyKey,
    },
    body: raw,
  })
  const json = await res.json()
  if (!json.success) throw new Error(json.error)
  return json.data // { withdrawalId, status, amount, feeAmount, netAmount } — reais
}

Taxa de saque (feeAmount / netAmount)

A plataforma pode cobrar taxa por saque, descontada do valor sacado. Campos aditivos e opcionais: com taxa zero (default) valem 0 e netAmount == amount — resposta idêntica à de sempre.

Webhooks do saque (se enviar callbackUrl): withdrawal.created, withdrawal.paid, withdrawal.failed — assinados no X-Signature com o mesmo Webhook Secret e com os headers V2. A pixKey vem mascarada no payload.

Consultar um saque #

Retorna o saque, desde que pertença à company da sua X-Api-Key (isolamento por workspace).

{
  "success": true,
  "data": {
    "withdrawalId": "…",
    "status": "ENVIADO",
    "amount": 100.00,
    "pixKeyType": "email",
    "createdAt": "2026-07-23T12:00:00.000Z"
  }
}

Allowlist de IP (opcional) #

Você pode restringir as rotas de saque (POST /gateway/withdrawals e GET /gateway/withdrawals/:id) a um conjunto de IPs de saída. IP fora da lista responde 403. Sem cadastro, nenhuma restrição.

Status & erros #

Status de transação (sempre MAIÚSCULO)

Status de saque

Códigos HTTP

Todo erro segue o envelope { "success": false, "error": "<mensagem>" }.

Checklist de integração #

• X-Api-Key e Webhook Secret guardados como segredo (env), nunca no cliente.
• POST /gateway/charges gerando pixCode e exibindo o QR/copia-e-cola.
• Valores tratados em reais (não centavos) no request e nas respostas/webhooks.
• Endpoint de callbackUrl verifica o X-Signature (HMAC do corpo bruto), responde 200 e é idempotente por transactionId.
• (Recomendado) X-Signature-V2 verificado, X-Timestamp dentro de ±5 min e X-Webhook-Id deduplicado.
• status comparado em MAIÚSCULO (PAID etc.); pedido liberado só em transaction.paid.
• metadata casa o pagamento com o pedido interno; endToEndId guardado para conciliação bancária.
• (Se exigido) assinatura HMAC de requisição implementada e testada na janela de ±5 min.
• Saque: assinatura com o Webhook Secret (não a api key) incluindo o Idempotency-Key no canônico; key reusada no retry; (opcional) IPs de saída na allowlist.