Webhooks

A APIX avisa o seu sistema toda vez que uma transação muda de status. É o caminho recomendado para liberar o pedido.

Cadastrar a URL

No painel, em Integrações & APIs, cadastre a URL que vai receber os eventos. Você pode proteger o endpoint com Basic Auth ou Bearer Token: a APIX envia o header de autenticação junto. Dá para cadastrar mais de uma URL; todas recebem o mesmo evento.

Como o envio funciona

Regra	Comportamento
Quando dispara	A cada mudança de status da transação (pago, estornado, em disputa, cancelado)
Método	POST com JSON
Confirmação	Responda 2xx. Qualquer outra resposta conta como falha
Retentativa	Até 3 tentativas, com 15 segundos entre elas
Ordem	Não é garantida: trate o evento pelo status recebido, não pela ordem de chegada
Repetição	O mesmo status pode chegar mais de uma vez; o processamento precisa ser idempotente

Conteúdo do evento

Payload

{
  "transaction_id": "A1B2C3D4E5F6",
  "total_value": 99.90,
  "fee": 4.99,
  "net_value": 94.91,
  "status": "AUTHORIZED",
  "payment_method": "PIX",
  "product": { "id": "uuid", "title": "Nome do produto" },
  "producer": { "name": "Loja Exemplo", "email": "suporte@loja.com" },
  "payment_data": {
    "payment_id": "id-da-cobranca-no-provedor",
    "pix_key": "00020101021226790014br.gov.bcb.pix..."
  },
  "customer": {
    "name": "João da Silva",
    "email": "joao@email.com",
    "document": "12345678901",
    "phone": "+5511999999999",
    "birth_date": null,
    "address": null
  }
}

Campo	Descrição
transaction_id	Identificador da transação na APIX; use para conciliar com o seu pedido
status	Status novo da transação
total_value	Valor da venda em reais
fee	Taxas da plataforma
net_value	Valor líquido do vendedor
payment_method	PIX, CREDIT_CARD ou BANK_SLIP
payment_data	Dados do pagamento (inclui o PIX copia e cola quando houver)
customer	Dados do comprador
product	Produto da venda, quando a cobrança veio de um produto cadastrado

Recebendo com segurança

Node.js (Express)

import express from 'express';

const app = express();
app.use(express.json());

app.post('/webhooks/apix', async (req, res) => {
  // 1. Responda rápido: a APIX tenta 3 vezes, com 15s entre as tentativas
  res.sendStatus(200);

  const { transaction_id, status } = req.body;

  // 2. O mesmo evento pode chegar mais de uma vez — trate por transaction_id + status
  if (status === 'AUTHORIZED' || status === 'APPROVED') {
    await liberarPedido(transaction_id);
  }

  if (status === 'REFUNDED' || status === 'CHARGEBACK' || status === 'IN_DISPUTE') {
    await bloquearAcesso(transaction_id);
  }
});

app.listen(3000);

Responda antes de processar. Se o seu endpoint demorar, a APIX considera falha e reenvia o evento.

Antes de liberar o pedido, confira o valor recebido e trate estorno e disputa (REFUNDED, CHARGEBACK, IN_DISPUTE) revogando o acesso.