Skip to content

Webhooks ​

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

Visão Geral ​

  • A API envia webhooks para eventos de cobrança (Pix, Cartão e Boleto), conclusão de lote e ativação de sub-conta.
  • O payload de cobrança não usa o campo event. O evento é identificado pelo campo status (APPROVED / CANCELLED). Os eventos de lote e de sub-conta reaproveitam o campo type como nome do evento (charge_batch.completed, customer).
  • A entrega é um POST com Content-Type: application/json, sem cabeçalho de autenticação e sem assinatura (veja Verificação e Segurança).
  • Não há webhook para saques (withdraws), estornos/reembolsos ou chargebacks. O cancelamento só gera webhook para cartão via Mercado Pago.

Configuração ​

O webhook é configurado por conta. Uma cobrança individual também pode sobrescrever o destino com o campo callbackUrl no momento da criação.

Ordem de resolução da URL usada em cada envio: callbackUrl da cobrança → webhook do cliente/credencial → webhook da conta. Se nenhuma existir, nada é enviado.

Conta Principal ​

bash
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 ​

bash
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"
  }'

Regras da URL ​

  • Precisa ter protocolo http:// ou https:// e um domínio válido: seusite.com/webhook é recusado com 400.
  • Máximo de 200 caracteres.
  • "url": null remove o webhook (as notificações param, exceto onde a cobrança define callbackUrl).
  • Sub-conta inexistente ou que não pertence à conta autenticada retorna 404.

Eventos ​

EventoComo identificarQuando dispara
Cobrança pagastatus: "APPROVED"Pagamento confirmado de cobrança Pix, Boleto ou Cartão
Pix recebido sem cobrançastatus: "APPROVED", type: "PIX", sem idPix recebido (depósito) sem cobrança prévia associada
Cobrança canceladastatus: "CANCELLED"Cancelamento de cartão via Mercado Pago (Pix/Boleto não geram este evento)
Lote concluídotype: "charge_batch.completed"Processamento de um lote de cobranças terminou
Sub-conta ativadatype: "customer"Sub-conta passou de pendente (2) para ativa (1)

Formato do Payload ​

Cobrança Aprovada ​

json
{
  "status": "APPROVED",
  "id": "8f7c6a2d-4a1b-4de8-9f2d-1e84f7b80c11",
  "txId": "E1234567890123456789012345678901",
  "transactionCode": "E1234567890123456789012345678901",
  "referenceId": "pedido-123",
  "amount": 100.00,
  "type": "PIX",
  "chargeType": "PIX"
}
CampoTipoDescrição
statusstringSempre "APPROVED" neste evento
idstring (uuid)ID da cobrança na divipay. Ausente no evento "Pix recebido sem cobrança"
txIdstringIdentificador da transação. Pix → endToEndId; Boleto → ID do boleto; Cartão → ID do pagamento no adquirente
transactionCodestringCódigo da transação no adquirente (geralmente igual ao txId)
referenceIdstring | nullSeu ID externo enviado na criação da cobrança (null quando não há cobrança)
amountnumberValor em reais (ex.: 100.00)
typestringForma de pagamento (MovementsType): PIX, CREDIT_CARD, TICKET, OTHER
chargeTypestringTipo da cobrança (ChargeType): PIX, CREDIT_CARD, INVOICE, TICKET, BILLET, BROKER

type e chargeType nem sempre coincidem

Para boleto, o payload envia type: "TICKET" mas chargeType: "BILLET". Não assuma que os dois campos são iguais — use type para a forma de pagamento e chargeType para o tipo da cobrança.

Pix Recebido sem Cobrança ​

Enviado quando um Pix é liquidado sem uma cobrança prévia (depósito). Tem a mesma forma, porém sem o campo id e com referenceId sempre null:

json
{
  "status": "APPROVED",
  "txId": "E1234567890123456789012345678901",
  "transactionCode": "E1234567890123456789012345678901",
  "referenceId": null,
  "amount": 100.00,
  "type": "PIX",
  "chargeType": "PIX"
}

Cobrança Cancelada ​

Enviado apenas no cancelamento de cartão via Mercado Pago:

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

Lote Concluído ​

json
{
  "type": "charge_batch.completed",
  "batchId": "b6c1f0a2-2d3e-4f5a-8b9c-0d1e2f3a4b5c",
  "status": "COMPLETED",
  "totalItems": 100,
  "succeededItems": 98,
  "failedItems": 2
}
CampoTipoDescrição
typestringSempre "charge_batch.completed"
batchIdstring (uuid)ID do lote
statusstringCOMPLETED, FAILED ou PARTIALLY_COMPLETED
totalItemsnumberTotal de itens do lote
succeededItemsnumberItens processados com sucesso
failedItemsnumberItens que falharam

Sub-conta Ativada ​

Observe que status aqui é um número (1), não a string "APPROVED":

json
{
  "id": "5a4c2b18-8f01-49cc-9e3d-2b3b7f1d4e66",
  "email": "loja@exemplo.com",
  "status": 1,
  "webhookUrl": "https://vendedor.com/webhook",
  "companyId": "0d1e2f3a-4b5c-6d7e-8f90-1a2b3c4d5e6f",
  "type": "customer"
}

Entrega e Retentativas ​

  • Cada evento é entregue como um POST application/json com o corpo JSON acima e nenhum cabeçalho adicional.
  • A entrega é considerada bem-sucedida em qualquer resposta 2xx.
  • Em falha (timeout ou status não-2xx), o mesmo payload é reenviado: até 50 tentativas, com intervalo fixo de 120 segundos (~100 minutos no total).
  • Por isso seu endpoint deve ser idempotente — o mesmo evento pode chegar mais de uma vez.

Verificação e Segurança ​

Não há assinatura (HMAC) nos webhooks

Hoje a divipay não envia assinatura, HMAC, segredo compartilhado nem cabeçalho de autenticação junto com o webhook. O POST chega apenas com o corpo JSON. Portanto não é possível validar uma assinatura — trate o payload recebido como não confiável por si só.

Como o webhook não é assinado, valide a autenticidade confirmando a cobrança na fonte de verdade antes de liberar qualquer valor ou pedido:

  1. Reconsulte a cobrança (recomendado). Ao receber o webhook, chame o endpoint autenticado de Consultar Cobrança usando o id/txId recebido e confie apenas no status retornado por essa consulta. Este é o método mais seguro.
  2. URL secreta. Configure uma URL de webhook com um caminho/token difícil de adivinhar (ex.: https://seusite.com/webhook/divipay/9f3c...) e rejeite requisições em outros caminhos.
  3. Allowlist de IP. Se você conhece os IPs de origem da divipay, restrinja o acesso ao endpoint por IP.
  4. Idempotência. Deduplique por txId + id (o mesmo evento é reenviado em caso de falha).

Exemplo de Endpoint ​

O exemplo abaixo não confia no payload: ele reconsulta a cobrança antes de marcar o pedido como pago.

javascript
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) {
  // Não confie no webhook: confirme na fonte de verdade.
  const charge = await fetchChargeFromDivipay(payload.id ?? payload.txId);
  if (charge.status !== 'APPROVED') return;

  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 e processe de forma assíncrona
  2. Reconsulte a cobrança antes de liberar valor — o webhook não é assinado
  3. Trate idempotência por txId e id (o mesmo evento pode ser reenviado até 50 vezes)
  4. Não assuma que type e chargeType são iguais (boleto: TICKET vs BILLET)
  5. Registre logs com o payload bruto para auditoria

Teste Local ​

bash
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 ​

Documentação da API DiviPay