How it works at PayZu

The webhook flow at PayZu is delivered through a POST request to the callbackUrl provided when creating the order. Each status change triggers a new webhook with the complete order object, allowing you to track the transaction lifecycle in real-time.

Your endpoint should return an HTTP 200 status code to acknowledge receipt. Any other response code will trigger a retry.

Webhook Payload

When an order status changes, the following payload is sent to your endpoint:

{
  "event": "order.updated",
  "timestamp": "2026-02-13T13:15:00Z",
  "order": {
    "id": "660e8400-e29b-41d4-a716-446655440001",
    "status": "COMPLETED",
    "source": {
      "amount": "100.00",
      "currency": "BRL"
    },
    "destination": {
      "amount": "18.50",
      "asset": "USDT",
      "network": "TRX",
      "address": "TXyz1234567890abcdef",
      "txHash": "abc123def456789..."
    },
    "exchangeRate": "5.4054",
    "reference": "my-ref-123",
    "metadata": {
      "userId": "user_123"
    },
    "createdAt": "2026-02-13T13:00:00Z",
    "updatedAt": "2026-02-13T13:15:00Z"
  }
}

Conceptual Flow of Webhooks

 _______________________________________________
|  Order created                                |
|  POST /v1/orders                              |
|_______________________________________________|
                      |
                      ▼
 _______________________________________________
|  Status changes                               |
|  (PENDING_DEPOSIT → DEPOSIT_RECEIVED → ...)   |
|_______________________________________________|
                      |
                      ▼
 _______________________________________________
|  Webhook sent to callbackUrl                  |
|  POST https://your-server.com/webhook         |
|_______________________________________________|
                      |
                      ▼
 _______________________________________________
|  Your server processes the webhook            |
|  Updates internal records                     |
|_______________________________________________|
                      |
                      ▼
 _______________________________________________
|  Return HTTP 200 to acknowledge               |
|  (Any other status triggers retry)            |
|_______________________________________________|

Available Events

Event	Description
`order.updated`	Order status changed

Retry Policy

If your endpoint does not return HTTP 200, the webhook is retried with exponential backoff:

Attempt	Delay After Failure
1	Immediate
2	1 minute
3	5 minutes
4	15 minutes
5	1 hour
6	4 hours

After 6 failed attempts, the webhook is marked as failed and no further retries are made.

Best Practices

Return 200 quickly: Acknowledge the webhook immediately, then process asynchronously
Implement idempotency: You may receive the same webhook multiple times; use the order id and updatedAt to detect duplicates
Verify the payload: Validate that the order exists in your system before processing
Log everything: Store raw webhook payloads for debugging and audit purposes
Use the reference field: Include a reference when creating orders to easily match webhooks to your internal records

Example: Handling a Webhook

app.post('/webhook/crypto', (req, res) => {
  // Acknowledge immediately
  res.status(200).send('OK');
  
  // Process asynchronously
  const { event, order } = req.body;
  
  if (event === 'order.updated') {
    // Update your database
    updateOrderStatus(order.id, order.status);
    
    // Notify user if completed
    if (order.status === 'COMPLETED') {
      notifyUser(order.reference, order.destination.txHash);
    }
  }
});

Testing Webhooks

During development, you can use tools like webhook.site or ngrok to receive webhooks on your local machine.