Notificações

Gerencie as notificações de eventos do gateway de pagamentos

Webhooks

O gateway de pagamentos envia notificações em tempo real sobre eventos importantes através de webhooks. Configure uma URL em seu sistema para receber estas notificações.

Eventos Disponíveis
  • PAYMENT_CREATED: Novo pagamento criado
  • PAYMENT_UPDATED: Status do pagamento atualizado
  • PAYMENT_CONFIRMED: Pagamento confirmado
  • PAYMENT_OVERDUE: Pagamento vencido
  • PAYMENT_DELETED: Pagamento removido
  • PAYMENT_RESTORED: Pagamento restaurado
  • PAYMENT_REFUNDED: Pagamento reembolsado
  • PAYMENT_RECEIVED: Pagamento recebido
  • PAYMENT_ANTICIPATED: Pagamento antecipado

POST /api/notifications/webhook

Endpoint para receber notificações de eventos do gateway.

Request Body
{
  "event": "string",           // Tipo do evento
  "payment": {                // Dados do pagamento
    "id": "string",
    "customerId": "string",
    "value": number,
    "status": "string",
    "billingType": "string",
    "dueDate": "string",
    "description": "string",
    "externalReference": "string",
    "asaasId": "string",
    "createdAt": "string",
    "updatedAt": "string"
  }
}
Exemplo
{
  "event": "PAYMENT_CONFIRMED",
  "payment": {
    "id": "123",
    "customerId": "456",
    "value": 99.90,
    "status": "CONFIRMED",
    "billingType": "CREDIT_CARD",
    "dueDate": "2024-03-15",
    "description": "Assinatura Premium",
    "externalReference": "SUB_123",
    "asaasId": "pay_123456",
    "createdAt": "2024-03-01T10:00:00Z",
    "updatedAt": "2024-03-01T10:05:00Z"
  }
}
Boas Práticas
  • Configure uma URL HTTPS para receber as notificações
  • Implemente um mecanismo de retry para casos de falha
  • Valide a autenticidade das notificações recebidas
  • Processe as notificações de forma assíncrona
  • Mantenha um log das notificações recebidas
  • Implemente tratamento de erros adequado
Segurança

Para garantir a autenticidade das notificações, o gateway inclui um cabeçalho de assinatura:

X-Asaas-Signature: sha256=hash

O hash é gerado usando o algoritmo SHA-256 com a chave secreta do seu token de acesso. Verifique a assinatura antes de processar a notificação.

Endpoints

GET /api/notifications

Lista todas as notificações registradas.

Parâmetros de Query
{
  "event": "string",          // Filtra por tipo de evento (opcional)
  "paymentId": "string",      // Filtra por ID do pagamento (opcional)
  "startDate": "string",      // Data inicial (opcional, YYYY-MM-DD)
  "endDate": "string",        // Data final (opcional, YYYY-MM-DD)
  "offset": number,           // Registros a pular (opcional, padrão: 0)
  "limit": number            // Máximo de registros (opcional, padrão: 10)
}
Resposta
[
  {
    "id": "string",
    "event": "string",
    "paymentId": "string",
    "status": "string",
    "payload": object,
    "createdAt": "string",
    "updatedAt": "string"
  }
]

GET /api/notifications/:id

Obtém detalhes de uma notificação específica.

Exemplo
curl -X GET "http://seu-servidor/api/notifications/123"

PATCH /api/notifications/:id

Atualiza o status de uma notificação.

Request Body
{
  "status": "string"  // PROCESSED, FAILED, PENDING
}
Exemplo
curl -X PATCH "http://seu-servidor/api/notifications/123" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "PROCESSED"
  }'