Webhook for VAM Collection

Overview

Receive real-time notifications when payments are made to your Virtual Account Numbers, enabling immediate payment processing, automatic reconciliation, and enhanced customer experience.

Key Features (Planned)

• Instant Payment Alerts: Real-time collection notifications
• Comprehensive Data: Complete payment details
• Auto-reconciliation: Automatic payment matching
• Reliable Delivery: Guaranteed webhook delivery
• Security Verification: HMAC signature verification
• Duplicate Detection: Prevent duplicate processing

Expected Webhook Configuration

Setup Method

Webhooks will be sent to the callback_url provided during VAM generation via the VAM Generation API.

Required Field in VAM Generation Request:

{
  "callback_url": "https://your-website.com/webhook/vam-collection"
}

Expected Webhook Headers

Content-Type: application/json
User-Agent: Paywize-VAM-Webhook/1.0
X-Paywize-Signature: sha256=signature_hash
X-Paywize-Event: vam_payment_received
X-Paywize-Timestamp: 1640995200
X-Paywize-VAM-ID: VAM123456789

Expected Webhook Payload

Encrypted Payload

{
  "data": "encrypted_payload_using_AES_256_CBC"
}

Decrypted Payload Structure

{
  "event_type": "vam_payment_received",
  "payment_id": "VCP987654321",
  "vam_details": {
    "vam_id": "VAM123456789",
    "virtual_account_number": "919876543210001",
    "customer_id": "CUST123456",
    "purpose": "invoice_payment"
  },
  "payment_details": {
    "amount": "5000.00",
    "currency": "INR",
    "payment_mode": "UPI",
    "sender_vpa": "customer@paytm",
    "sender_name": "John Doe",
    "transaction_reference": "UPI789456123",
    "bank_reference": "BNK123789456"
  },
  "collection_info": {
    "expected_amount": "5000.00",
    "collected_amount": "5000.00",
    "amount_match": true,
    "collection_status": "FULL_PAYMENT",
    "remaining_amount": "0.00"
  },
  "timestamps": {
    "payment_time": "2026-01-15T10:30:00Z",
    "vam_created_at": "2026-01-15T09:00:00Z",
    "webhook_sent_at": "2026-01-15T10:30:01Z"
  },
  "metadata": {
    "invoice_number": "INV-2026-001",
    "customer_name": "John Doe",
    "order_id": "ORD789456",
    "department": "sales"
  }
}

Webhook Events

Payment Events

• PAYMENT_RECEIVED: Payment made to VAM
• PARTIAL_PAYMENT: Partial amount received
• OVERPAYMENT: Amount exceeds expected
• DUPLICATE_PAYMENT: Multiple payments received

VAM Events

• VAM_ACTIVATED: VAM ready for payments
• VAM_EXPIRED: VAM expired
• VAM_COMPLETED: Payment completed, VAM closed

Expected Payload Fields

Collection Status Types

Payment Status

• FULL_PAYMENT: Complete payment received
• PARTIAL_PAYMENT: Partial amount received
• OVERPAYMENT: Excess amount received
• UNDERPAYMENT: Insufficient amount received

VAM Status

• ACTIVE: VAM accepting payments
• COMPLETED: Payment completed
• EXPIRED: VAM expired
• SUSPENDED: VAM temporarily disabled

Security Verification

HMAC Signature Verification

const crypto = require('crypto');

function verifyVAMWebhookSignature(payload, signature, secret) {
  const computedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return `sha256=${computedSignature}` === signature;
}

// Usage
const isValid = verifyVAMWebhookSignature(
  webhookPayload,
  request.headers['x-paywize-signature'],
  'your_webhook_secret'
);

Duplicate Prevention

const processedPayments = new Set();

function handleVAMWebhook(payload) {
  const paymentId = payload.payment_id;

  if (processedPayments.has(paymentId)) {
    console.log('Duplicate webhook ignored');
    return { status: 'duplicate', processed: false };
  }

  processedPayments.add(paymentId);
  // Process payment
  return { status: 'success', processed: true };
}

Implementation Requirements

Endpoint Requirements

• HTTPS Only: Webhook URLs must use HTTPS
• Response Time: Respond within 30 seconds
• Response Code: Return 200 OK for successful processing
• Idempotency: Handle duplicate webhook deliveries safely

Processing Guidelines

• Immediate Response: Acknowledge receipt quickly
• Asynchronous Processing: Process payment details separately
• Error Handling: Handle processing failures gracefully
• Logging: Log all webhook receipts and processing

Auto-reconciliation Features

Payment Matching

function autoReconcilePayment(webhookData) {
  const {
    vam_id,
    payment_details,
    collection_info,
    metadata
  } = webhookData;

  // Match payment to invoice/order
  const invoice = findInvoiceByNumber(metadata.invoice_number);

  if (invoice && collection_info.amount_match) {
    // Mark invoice as paid
    markInvoiceAsPaid(invoice.id, payment_details.amount);

    // Update customer record
    updateCustomerPaymentHistory(
      webhookData.vam_details.customer_id,
      payment_details
    );

    // Trigger fulfillment
    triggerOrderFulfillment(metadata.order_id);
  }
}

Use Cases

E-commerce

• Order Payments: Instant order payment confirmation
• Customer Updates: Real-time payment notifications
• Inventory Management: Trigger stock allocation

B2B Payments

• Invoice Payments: Automatic invoice payment marking
• Vendor Payments: Supplier payment confirmations
• Contract Payments: Project payment tracking

Subscription Services

• Recurring Payments: Subscription payment processing
• Service Activation: Automatic service provisioning
• Account Management: Customer account updates

Best Practices

Security

• Signature Verification: Always verify webhook signatures
• IP Whitelisting: Restrict webhook source IPs
• Data Validation: Validate all webhook data
• Secure Storage: Encrypt sensitive payment data

Performance

• Async Processing: Process webhooks asynchronously
• Queue Management: Use message queues for reliability
• Error Recovery: Implement retry mechanisms
• Monitoring: Monitor webhook processing performance

Business Logic

• Duplicate Handling: Prevent duplicate payment processing
• Amount Validation: Verify payment amounts
• Status Tracking: Maintain payment status history
• Exception Handling: Handle payment discrepancies