Webhook setup

KwikPaisa Webhooks allow merchants to receive real-time payment and payout notifications directly on their server without continuously polling APIs.

Webhooks are recommended for:

• Payment status updates
• Payout status updates
• Settlement notifications
• Transaction reconciliation
• Automated workflow processing

Using webhooks helps merchants build faster, scalable, and reliable transaction systems.

---

What are Webhooks?

A webhook is an HTTP callback sent by KwikPaisa to your server whenever a transaction event occurs.

Instead of repeatedly checking transaction status APIs, KwikPaisa automatically pushes updates to your configured webhook endpoint.

---

Supported Webhook Events

PG Orders Events

Event	Description
pg.order.created	Order created successfully
pg.order.updated	Order details updated
pg.order.pending	Order awaiting payment
pg.order.processing	Order is being processed
pg.order.completed	Order completed successfully
pg.order.failed	Order processing failed
pg.order.cancelled	Order cancelled
pg.order.expired	Order session expired
pg.order.closed	Order closed
pg.order.refund_initiated	Refund initiated for order
pg.order.refunded	Order refunded successfully
pg.order.partially_refunded	Partial refund processed for order
pg.order.dispute.created	Dispute created for order
pg.order.dispute.closed	Order dispute resolved/closed
pg.order.chargeback.created	Chargeback initiated for order
pg.order.payment.success	Payment received for order
pg.order.payment.failed	Payment attempt failed for order
pg.order.webhook.failed	Order webhook delivery failed
pg.order.webhook.retrying	Retrying failed order webhook delivery

PG Payments Events

Event	Description
pg.payment.created	Payment order created
pg.payment.pending	Payment pending from customer
pg.payment.processing	Payment is being processed
pg.payment.success	Payment completed successfully
pg.payment.failed	Payment failed
pg.payment.cancelled	Payment cancelled
pg.payment.expired	Payment session expired
pg.payment.refunded	Full refund processed
pg.payment.partially_refunded	Partial refund processed
pg.refund.created	Refund request created
pg.refund.processing	Refund under processing
pg.refund.success	Refund completed successfully
pg.refund.failed	Refund failed
pg.settlement.created	Settlement generated
pg.settlement.processed	Settlement processed successfully
pg.settlement.failed	Settlement processing failed
pg.dispute.created	Payment dispute created
pg.dispute.updated	Dispute details updated
pg.dispute.won	Dispute resolved in merchant favor
pg.dispute.lost	Dispute lost
pg.dispute.closed	Dispute closed
pg.dispute.fee.withdrawal	Dispute handling fee deducted
pg.dispute.fee.refunded	Dispute fee refunded
pg.chargeback.created	Chargeback initiated
pg.chargeback.processing	Chargeback under review
pg.chargeback.won	Chargeback resolved in merchant favor
pg.chargeback.lost	Chargeback lost
pg.chargeback.closed	Chargeback closed
pg.withdrawal.created	Wallet withdrawal initiated
pg.withdrawal.processing	Withdrawal under processing
pg.withdrawal.success	Withdrawal completed successfully
pg.withdrawal.failed	Withdrawal failed
pg.webhook.failed	Webhook delivery failed
pg.webhook.retrying	Webhook retry attempt in progress

Payout Events

Event	Description
po.payout.created	Payout request created
po.payout.queued	Payout added to processing queue
po.payout.processing	Payout is being processed
po.payout.success	Payout completed successfully
po.payout.failed	Payout failed
po.payout.reversed	Payout reversed back to wallet
po.payout.cancelled	Payout cancelled
po.payout.refunded	Payout amount refunded
po.payout.pending	Payout pending approval or processing
po.payout.on_hold	Payout temporarily placed on hold
po.payout.bank_rejected	Bank rejected payout request
po.payout.bank_processing	Bank is processing payout
po.payout.retrying	Payout retry attempt initiated
po.payout.timeout	Payout processing timed out
po.payout.webhook.failed	Payout webhook delivery failed
po.payout.webhook.retrying	Retrying failed payout webhook delivery

---

Webhook URL Requirements

Your webhook endpoint must:

• Be publicly accessible
• Support HTTPS
• Accept POST requests
• Return HTTP 200 OK quickly
• Handle JSON payloads properly

---

Example Webhook URL

https://merchant.com/api/webhooks/kwikpaisa

Webhook Request Method

POST

---

Webhook Headers UNDER DEVELOPMENT

Content-Type: application/json
X-SIGNATURE: GENERATED_SIGNATURE
X-TIMESTAMP: GENERATED_TIMESTAMP

---

Webhook Security UNDER DEVELOPMENT

Every webhook request is signed using HMAC SHA256 signature verification.

Webhook signatures should always be validated before processing webhook data.

The signature is generated using:

HMAC_SHA256(payload + timestamp, secret_key)

---

Example Payment Webhook Payload

{
  "event": "pg.payment.success",
  "code": 200,
  "status": true,
  "message": "API authentication successful!",
  "data": {
    "kwikX_order_id": "kp_9b9e725b-b415-40fd-ac1c-068ab508f7e7",
    "order_id": "6873654104683",
    "payment_id": "pay_dgfdggdgdfg",
    "order_amount": "105.00",
    "order_currency": "INR",
    "order_status": "PAID",
    "order_source": "API",
    "created_at": null,
    "paymentDetails": {}
  }
}

---

Example Payout Webhook Payload

{
  "event": "po.payout.success",
  "data": {
    "order_id": "1778761734",
    "kwikx_payout_id": "payout_a782fdb71b5e1659",
    "status": "SUCCESS",
    "amount": "99",
    "currency": "INR",
    "utr_number": "UAT1778761735",
    "txnLog": {
      "account_transfer": {
        "account_number": "6760654654",
        "account_owner_name": "beneficiary name",
        "ifsc_code": "icici000143",
        "is_validate": "false",
        "payment_for": "salary payment"
      },
      "address": null,
      "beneficiary_id": null,
      "country_dialing_code": "91",
      "debit_account_type": "kwikx_wallet",
      "email": "[e-mail]",
      "kwikx_wallet_id": "2026-04-30 13:01:32",
      "mobile": "9896989698",
      "payout_order_id": 1778761734,
      "transfer_amount": "99",
      "transfer_mode": "imps",
      "transfer_type": "direct",
      "api_user_id": 472,
      "business_profile_id": 96,
      "api_key_id": 8,
      "mode": "sandbox"
    },
    "processed_at": "2026-05-14 12:28:55"
  }
}

---

Webhook Verification Process

Recommended verification steps:

1. Read webhook payload
2. Extract X-SIGNATURE header
3. Extract X-TIMESTAMP header
4. Generate local signature
5. Compare generated signature with received signature
6. Process webhook only if signatures match

---

Example Node.js Verification

const crypto = require('crypto');
const payload = JSON.stringify(req.body);
const timestamp = req.headers['x-timestamp'];
const receivedSignature = req.headers['x-signature'];
const generatedSignature = crypto
  .createHmac('sha256', 'YOUR_SECRET_KEY')
  .update(payload + timestamp)
  .digest('hex');
if (generatedSignature === receivedSignature) {
  console.log('Webhook verified');
} else {
  console.log('Invalid webhook signature');
}

---

Webhook Response Requirements

Your server should return:

HTTP 200 OK

immediately after successful webhook processing.

---

Retry Mechanism

If your server:

• Times out
• Returns non-200 responses
• Fails to respond

KwikPaisa may retry webhook delivery automatically.

---

Recommended Retry Handling

Your webhook system should:

• Handle duplicate events safely
• Store webhook logs
• Use idempotent processing
• Verify transaction status using APIs when needed

---

Best Practices

• Always validate webhook signatures
• Use HTTPS endpoints only
• Respond quickly with HTTP 200
• Process webhook logic asynchronously
• Store webhook payloads for audit logs
• Verify final transaction status server-side

---

Important Notes

• Webhooks should not be trusted without verification
• Duplicate webhook events may occur
• Payment status should always be verified server-side
• Webhooks complement APIs and do not replace verification APIs

---

Common Errors

Invalid Signature

Possible reasons:

• Incorrect secret key
• Payload modification
• Timestamp mismatch

---

Webhook Timeout

Possible reasons:

• Slow webhook processing
• Server downtime
• Network failures

---

Recommended Production Workflow

1. Receive webhook
2. Verify signature
3. Validate payload
4. Store webhook event
5. Verify transaction status using APIs
6. Update merchant system
7. Return HTTP 200 response