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

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

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": "email@example.com",
      "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:

Read webhook payload
Extract X-SIGNATURE header
Extract X-TIMESTAMP header
Generate local signature
Compare generated signature with received signature
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