Webhooks

Receba notificações HTTP em tempo real sobre atualizações de cobrança.

Visão Geral

A API envia webhooks para cobranças Pix e Cartão de Crédito.

• O payload não usa o campo event
• O payload usa campos como status, txId, type e chargeType
• Hoje não há webhook dedicado para saques (withdraws)

Configuração

Conta Principal

curl -X PUT https://api.divipay.com.br/api/customer/webhook \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://seusite.com/webhook/divipay"
  }'

Sub-conta

curl -X PUT https://api.divipay.com.br/api/customer/5a4c2b18-8f01-49cc-9e3d-2b3b7f1d4e66/webhook \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://seusite.com/webhook/divipay"
  }'

Formato do Payload

Cobrança Aprovada

{
  "status": "APPROVED",
  "id": "8f7c6a2d-4a1b-4de8-9f2d-1e84f7b80c11",
  "txId": "E1234567890123456789012345678901",
  "transactionCode": "E1234567890123456789012345678901",
  "referenceId": "pedido-123",
  "amount": 100.00,
  "type": "PIX",
  "chargeType": "PIX"
}

Cobrança Cancelada

{
  "status": "CANCELLED",
  "id": "2f11b9f1-0c50-4cf3-a7dd-5df6d355a289",
  "txId": "7529356905",
  "transactionCode": "7529356905",
  "referenceId": "pedido-123",
  "amount": 100.00,
  "type": "CREDIT_CARD",
  "chargeType": "CREDIT_CARD"
}

Exemplo de Endpoint

const express = require('express');
const app = express();

app.use(express.json());

app.post('/webhook/divipay', async (req, res) => {
  const payload = req.body;

  // Responda rápido para evitar retentativas.
  res.status(200).send('OK');

  try {
    if (payload.status === 'APPROVED') {
      await handleApprovedCharge(payload);
      return;
    }

    if (payload.status === 'CANCELLED') {
      await handleCancelledCharge(payload);
      return;
    }

    console.log('Payload não tratado:', payload);
  } catch (error) {
    console.error('Erro ao processar webhook:', error);
  }
});

async function handleApprovedCharge(payload) {
  await db.orders.update({
    where: { id: payload.referenceId },
    data: {
      status: 'PAID',
      chargeId: payload.id,
      txId: payload.txId,
      paidAmount: payload.amount,
      paymentType: payload.type,
    },
  });
}

async function handleCancelledCharge(payload) {
  await db.orders.update({
    where: { id: payload.referenceId },
    data: {
      status: 'CANCELED',
      chargeId: payload.id,
      cancelTxId: payload.txId,
    },
  });
}

app.listen(3000);

Boas Práticas

1. Responda 200 OK rapidamente
2. Trate idempotência por txId e id
3. Faça validações de origem/autenticação no seu endpoint
4. Registre logs com payload bruto para auditoria

Teste Local

curl -X POST http://localhost:3000/webhook/divipay \
  -H "Content-Type: application/json" \
  -d '{
    "status": "APPROVED",
    "id": "8f7c6a2d-4a1b-4de8-9f2d-1e84f7b80c11",
    "txId": "E1234567890123456789012345678901",
    "transactionCode": "E1234567890123456789012345678901",
    "referenceId": "pedido-123",
    "amount": 100,
    "type": "PIX",
    "chargeType": "PIX"
  }'

Próximos Passos

• Webhook de Sub-conta
• Criar Cobrança Pix
• Consultar Cobrança