> For the complete documentation index, see [llms.txt](https://developers.kwikpaisa.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.kwikpaisa.com/v3-guide/webhooks/webhook-setup.md). # 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 {% tabs %} {% tab title="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 | | {% endtab %} | | {% tab title="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 | | {% endtab %} | | {% tab title="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 | | {% endtab %} | | | {% endtabs %} | | *** ## 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 ```json { "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 ```json { "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: 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 --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://developers.kwikpaisa.com/v3-guide/webhooks/webhook-setup.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.