🔔 Estrutura do Webhook
O sistema envia webhooks para a postbackUrl configurada na requisição de pagamento sempre que o status da transação muda.
Payload do Webhook
Valor da transação em centavos
Moeda da transação (sempre “BRL”)
Método de pagamento utilizado
Dados de rastreamento UTM
Exemplo de Payload
{
"transactionId": "14d486a6-7c9d-4e75-919c-b0a2d1bf49ae",
"status": "approved",
"customer": {
"email": "[email protected]",
"name": "João Silva",
"document": "12345678901",
"phone": "11999999999"
},
"amount": 10000,
"currency": "BRL",
"paymentMethod": "credit_card",
"utm": {
"source": "google",
"medium": "cpc",
"campaign": "summer_sale",
"term": "pagamentos",
"content": "ad_variant_1"
}
}
📊 Status Possíveis
| Status | Descrição |
|---|
initial | Transação iniciada |
pending | Aguardando pagamento |
approved | Pagamento aprovado |
declined | Pagamento recusado |
refund | Estorno processado |
chargeback | Chargeback realizado |
expired | Pagamento expirado |
paid | Pagamento confirmado |
cancelled | Pagamento cancelado |
🔧 Configuração
Para receber notificações de mudança de status:
- Configure uma URL que aceite POST requests
- Inclua
postbackUrl na requisição de pagamento
- Processe o payload JSON recebido
- Retorne status HTTP 200 para confirmar recebimento
Exemplo de Endpoint de Webhook
// Exemplo em Node.js/Express
app.post('/webhook', (req, res) => {
const {
transactionId,
status,
customer,
amount,
currency,
paymentMethod,
utm
} = req.body;
// Processar a mudança de status
console.log(`Transação ${transactionId} mudou para status: ${status}`);
console.log(`Cliente: ${customer?.name} (${customer?.email})`);
console.log(`Valor: R$ ${(amount / 100).toFixed(2)}`);
console.log(`Método: ${paymentMethod}`);
// Atualizar status no banco de dados
// Enviar notificação ao usuário
// Processar dados UTM para analytics
// etc.
// Sempre retornar 200 para confirmar recebimento
res.status(200).json({ received: true });
});
⚠️ Importante
- O webhook será enviado sempre que o status da transação mudar
- Você deve retornar HTTP 200 para confirmar o recebimento
- Em caso de falha (timeout ou erro), o sistema pode tentar reenviar o webhook
- Recomenda-se implementar idempotência no processamento dos webhooks
Available options:
initial,
pending,
approved,
declined,
refund,
chargeback,
expired,
paid,
cancelled
Valor da transação em centavos
Método de pagamento utilizado
Webhook recebido com sucesso