For the complete documentation index, see llms.txt. This page is also available as Markdown.

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

Webhook Request Method


Webhook Headers UNDER DEVELOPMENT


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:


Example Payment Webhook Payload


Example Payout Webhook Payload


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


Webhook Response Requirements

Your server should return:

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.


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


  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

Last updated