API Reference
Webhooks
Payin Webhook

Payin Webhooks

The Payin webhook allows you to receive real-time notifications about the status of your payin transactions. You can configure your webhook URL in the dashboard under Dev Settings.

Webhook Configuration

  1. Go to your dashboard
  2. Click on "Dev Settings" tab
  3. Find the "Webhook Configuration" section
  4. Enter your webhook URL
  5. Save the configuration

Webhook Payload

When a payin transaction status changes, you'll receive a POST request to your configured webhook URL with the following payload:

{
  "type": "payin",
  "payload": {
    "order_id": "123456789012345",
    "amount": 10,
    "status": "SUCCESS",
    "utr": "UTR24031545789",
    "upi": "user@okaxis",
    "code": "PAYMENT_SUCCESS"
  }
}

Payload Fields

FieldTypeDescription
typestringAlways "payin" for payin webhooks
payload.order_idstringYour merchant order ID for reference
payload.amountnumberAmount of the transaction
payload.statusstringTransaction status (SUCCESS, FAILED, PENDING)
payload.utrstringUTR number for successful transactions
payload.upistringUPI ID used for payment
payload.codestringTransaction response code

Headers

Each webhook request includes the following headers:

HeaderValue
Content-Typeapplication/json
X-Webhook-SourcePayVanta

Response

Your webhook endpoint should return a 2xx status code to acknowledge receipt of the webhook. Any other status code will be considered a failure, and we may retry the webhook delivery.

Security

To ensure the webhook is coming from PayVanta:

  1. Verify the X-Webhook-Source header is set to "PayVanta"
  2. Implement IP whitelisting for PayVanta's webhook servers
  3. Use HTTPS for your webhook endpoint

Example Implementation

const express = require('express');
const app = express();
 
app.post('/webhook', (req, res) => {
  // Verify webhook source
  if (req.headers['x-webhook-source'] !== 'PayVanta') {
    return res.status(401).json({ error: 'Invalid webhook source' });
  }
 
  const { type, payload } = req.body;
 
  // Handle payin webhook
  if (type === 'payin') {
    console.log('Received payin webhook:', {
      orderId: payload.order_id,
      amount: payload.amount,
      status: payload.status,
      utr: payload.utr,
      upi: payload.upi,
      code: payload.code
    });
 
    // Process the webhook data
    // Update your database, notify users, etc.
  }
 
  // Always return 200 to acknowledge receipt
  res.status(200).send('Webhook received');
});
 
app.listen(3000, () => {
  console.log('Webhook server listening on port 3000');
});

Best Practices

  1. Always respond quickly to webhook requests (within 5 seconds)
  2. Implement idempotency to handle duplicate webhooks
  3. Log all webhook requests for debugging
  4. Use HTTPS for your webhook endpoint
  5. Implement proper error handling
  6. Store webhook data in your database for record-keeping
WebhooksPayout Webhook