🔄 Webhook de Transação

📋 Visão Geral

Os webhooks de transação são notificações HTTP POST enviadas automaticamente para sua aplicação sempre que ocorrem eventos relacionados a transações. Isso permite que você mantenha seu sistema sincronizado com o status das transações em tempo real.

📦 Estrutura do Payload

Exemplo Completo

{
  "type": "transaction",
  "objectId": "5f5d22ab-34e2-4c9b-832b-9a87b6e5b798",
  "url": "https://webhook.example.com/transaction",
  "data": {
    "id": "5f5d22ab-34e2-4c9b-832b-9a87b6e5b798",
    "ip": "192.168.1.10",
    "fee": 350,
    "pix": {
      "qrcode": "00020126780014BR.GOV.BCB.PIX0123456789012345670400005303986540625.005802BR...",
      "receiptUrl": "https://example.com/pix/receipt/5f5d22ab-34e2-4c9b-832b-9a87b6e5b798",
      "expirationDate": "2025-01-15T23:59:59Z"
    },
    "boleto": {
      "url": "https://example.com/boleto/5f5d22ab-34e2-4c9b-832b-9a87b6e5b798",
      "barcode": "34191750090000012345678901234567890123456789",
      "digitableLine": "34191.75009 00000.123456 78901.234567 8 901234567890",
      "instructions": "Pagamento válido até a data de vencimento.",
      "expirationDate": "2025-01-15T23:59:59Z"
    },
    "card": {
      "brand": "VISA",
      "lastDigits": "1234",
      "holderName": "John Doe",
      "expiryDate": "01/25"
    },
    "items": [
      {
        "id": "item-01",
        "title": "Produto A",
        "quantity": 2,
        "unitPrice": 5000,
        "tangible": true
      },
      {
        "id": "item-02",
        "title": "Produto B",
        "quantity": 1,
        "unitPrice": 3000,
        "tangible": true
      }
    ],
    "payer": {
      "name": "John Doe",
      "documentNumber": "12345678901"
    },
    "amount": 13500,
    "paidAt": "2025-01-10T15:30:00Z",
    "status": "paid",
    "refunds": [
      {
        "id": "refund-001",
        "amount": 5000,
        "preChargeback": false,
        "manualRefund": true,
        "providerRefund": false,
        "createdAt": "2025-01-10T15:40:00Z"
      }
    ],
    "customer": {
      "id": "cust-12345",
      "name": "John Doe",
      "email": "john.doe@example.com",
      "phone": "+5511999999999",
      "address": {
        "street": "Av. Brasil",
        "streetNumber": "123",
        "city": "São Paulo",
        "state": "SP",
        "zipCode": "01000-000",
        "country": "BR"
      },
      "document": {
        "type": "CPF",
        "number": "12345678901"
      },
      "createdAt": "2025-01-05T12:00:00Z",
      "externalRef": "external-12345"
    },
    "delivery": {
      "status": "delivered",
      "trackingCode": "TRACK12345"
    },
    "metadata": {
      "customField1": "Value1",
      "customField2": "Value2"
    },
    "secureId": "secure-67890",
    "shipping": {
      "fee": 1000,
      "address": {
        "street": "Av. Brasil",
        "streetNumber": "123",
        "city": "São Paulo",
        "state": "SP",
        "zipCode": "01000-000",
        "country": "BR"
      }
    },
    "companyId": "company-12345",
    "traceable": true,
    "updatedAt": "2025-01-10T16:00:00Z",
    "externalRef": "external-transaction-12345",
    "postbackUrl": "https://webhook.example.com/transaction",
    "installments": 3,
    "paymentMethod": "credit_card",
    "refusedReason": null,
    "refundedAmount": 5000,
    "returnUrl": "https://example.com/return",
    "currency": "BRL",
    "qrCode": "12345678901234567890",
    "barcode": "34191750090000012345678901234567890123456789",
    "payUrl": "https://example.com/pay/5f5d22ab-34e2-4c9b-832b-9a87b6e5b798",
    "webUrl": "https://example.com/transaction/5f5d22ab-34e2-4c9b-832b-9a87b6e5b798",
    "appUrl": "myapp://transaction/5f5d22ab-34e2-4c9b-832b-9a87b6e5b798"
  }
}

Descrição dos Status de Transação

Status	Descrição	Próximos status possíveis
PROCESSING	🔄 Transação sendo processada	AUTHORIZED, REFUSED, CANCELED, PAID
WAITING_PAYMENT	⏳ Aguardando pagamento	PAID, CANCELED, REFUSED, IN_ANALYSIS
IN_ANALYSIS	🔍 Transação em análise	PAID, CANCELED, REFUSED, AUTHORIZED
AUTHORIZED	✅ Pagamento autorizado	PAID, CANCELED, REFUSED
PAID	💰 Pagamento confirmado	REFUNDED, IN_PROTEST, CHARGEDBACK
IN_PROTEST	⚠️ Transação em contestação	REFUNDED, CHARGEDBACK
REFUNDED	↩️ Valor devolvido ao cliente	-
CHARGEDBACK	⚠️ Contestação do cliente	-
REFUSED	❌ Pagamento recusado	-
CANCELED	🚫 Transação cancelada	-

Status de Entrega

Status	Descrição	Ação recomendada
WAITING	📋 Aguardando processamento	Preparar pedido
IN_TRANSIT	🚚 Em trânsito	Acompanhar entrega
DELIVERED	✅ Entregue	Confirmar com cliente

🧪 Testando Webhooks

Ferramenta de Debug

Recomendamos usar ngrok para testar webhooks localmente:

# Expor seu servidor local
ngrok http 3000

# Use a URL gerada
# https://abc123.ngrok.io/webhook/transaction

Payload de Teste

Use este payload para testar seu endpoint localmente:

{
  "type": "transaction",
  "objectId": "test-transaction-001",
  "url": "https://webhook.example.com/transaction",
  "data": {
    "id": "test-transaction-001",
    "status": "paid",
    "amount": 10000,
    "currency": "BRL",
    "paymentMethod": "credit_card",
    "externalRef": "TEST-001",
    "customer": {
      "name": "Teste Silva",
      "email": "test@example.com",
      "document": {
        "type": "CPF",
        "number": "00000000000"
      }
    },
    "paidAt": "2025-01-10T15:30:00Z",
    "updatedAt": "2025-01-10T15:30:00Z"
  }
}

❓ FAQ

Quanto tempo leva para receber o webhook?

• Evento created: Imediato (< 1 segundo)
• Evento authorized: 1-5 segundos
• Evento paid: 5-30 segundos (depende do método)
• Evento refused: Imediato após a recusa

O que fazer se não receber um webhook?

1. Verifique a URL: Certifique-se de que está correta e acessível
2. Valide HTTPS: Webhooks só são enviados para URLs HTTPS

---

📚 Próximos passos: Webhook de Cashout | Webhook de Infração