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 campostatus(APPROVED/CANCELLED). Os eventos de lote e de sub-conta reaproveitam o campotypecomo nome do evento (charge_batch.completed,customer). - A entrega é um
POSTcomContent-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
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"
}'Regras da URL
- Precisa ter protocolo
http://ouhttps://e um domínio válido:seusite.com/webhooké recusado com400. - Máximo de 200 caracteres.
"url": nullremove o webhook (as notificações param, exceto onde a cobrança definecallbackUrl).- Sub-conta inexistente ou que não pertence à conta autenticada retorna
404.
Eventos
| Evento | Como identificar | Quando dispara |
|---|---|---|
| Cobrança paga | status: "APPROVED" | Pagamento confirmado de cobrança Pix, Boleto ou Cartão |
| Pix recebido sem cobrança | status: "APPROVED", type: "PIX", sem id | Pix recebido (depósito) sem cobrança prévia associada |
| Cobrança cancelada | status: "CANCELLED" | Cancelamento de cartão via Mercado Pago (Pix/Boleto não geram este evento) |
| Lote concluído | type: "charge_batch.completed" | Processamento de um lote de cobranças terminou |
| Sub-conta ativada | type: "customer" | Sub-conta passou de pendente (2) para ativa (1) |
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"
}| Campo | Tipo | Descrição |
|---|---|---|
status | string | Sempre "APPROVED" neste evento |
id | string (uuid) | ID da cobrança na divipay. Ausente no evento "Pix recebido sem cobrança" |
txId | string | Identificador da transação. Pix → endToEndId; Boleto → ID do boleto; Cartão → ID do pagamento no adquirente |
transactionCode | string | Código da transação no adquirente (geralmente igual ao txId) |
referenceId | string | null | Seu ID externo enviado na criação da cobrança (null quando não há cobrança) |
amount | number | Valor em reais (ex.: 100.00) |
type | string | Forma de pagamento (MovementsType): PIX, CREDIT_CARD, TICKET, OTHER |
chargeType | string | Tipo 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:
{
"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:
{
"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
{
"type": "charge_batch.completed",
"batchId": "b6c1f0a2-2d3e-4f5a-8b9c-0d1e2f3a4b5c",
"status": "COMPLETED",
"totalItems": 100,
"succeededItems": 98,
"failedItems": 2
}| Campo | Tipo | Descrição |
|---|---|---|
type | string | Sempre "charge_batch.completed" |
batchId | string (uuid) | ID do lote |
status | string | COMPLETED, FAILED ou PARTIALLY_COMPLETED |
totalItems | number | Total de itens do lote |
succeededItems | number | Itens processados com sucesso |
failedItems | number | Itens que falharam |
Sub-conta Ativada
Observe que status aqui é um número (1), não a string "APPROVED":
{
"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/jsoncom 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:
- Reconsulte a cobrança (recomendado). Ao receber o webhook, chame o endpoint autenticado de Consultar Cobrança usando o
id/txIdrecebido e confie apenas no status retornado por essa consulta. Este é o método mais seguro. - 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. - Allowlist de IP. Se você conhece os IPs de origem da divipay, restrinja o acesso ao endpoint por IP.
- 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.
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
- Responda
200 OKrapidamente e processe de forma assíncrona - Reconsulte a cobrança antes de liberar valor — o webhook não é assinado
- Trate idempotência por
txIdeid(o mesmo evento pode ser reenviado até 50 vezes) - Não assuma que
typeechargeTypesão iguais (boleto:TICKETvsBILLET) - Registre logs com o 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"
}'
