1. Webhook
Documentation: Botter Pay
  • Introduction
  • Acceppt payment
    • Create Invoice
      POST
    • Invoice status
      GET
    • Refund invoce
      POST
    • List invoices
      GET
  • Send payment
    • Send payment to upi
      POST
    • Payout status
      GET
  • Subscription
    • Create subscription
      POST
    • subscription status
      GET
    • cancel subscription
      POST
  • Webhook
    • Webhooks
  1. Webhook

Webhooks

🔔 Webhooks & Real-Time Event Notification Guide#

Our platform dispatches real-time HTTP POST webhook events to your configured webhook_url as soon as a payment, refund, payout, or subscription auto-debit event occurs.

âš¡ Webhook Delivery Architecture & Retry Guarantee#

Protocol: HTTP / HTTPS POST
Content-Type: application/json
User-Agent: PayU-Simplified-Webhook/2.0
Timeout: 10 seconds per attempt
Success Criteria: Your server must respond with an HTTP status in the 2xx range (e.g. 200 OK).

🔄 Automatic Retry Policy:#

If your endpoint times out, returns a 5xx/4xx error, or is unreachable:
1.
The failed delivery is recorded in the database audit log.
2.
The retry worker attempts delivery every 60 seconds.
3.
Automatic retries continue for up to 3 total attempts before marking the webhook as failed.

📋 Master Event Catalog#

Event NameCategoryTrigger Condition
payment.successInvoicesCustomer successfully completed payment on an invoice.
payment.failedInvoicesPayment failed, expired, or was declined by issuing bank.
payment.refundedInvoicesFull or partial refund was successfully processed.
subscription.authorizedSubscriptionsCustomer completed ₹1 trial / UPI AutoPay mandate setup.
subscription.chargedSubscriptionsScheduled recurring monthly/yearly renewal cycle debit succeeded.
subscription.failedSubscriptionsScheduled recurring debit failed (e.g. mandate error / insufficient balance).
subscription.cancelledSubscriptionsMandate was cancelled via API or Merchant Dashboard.
subscription.completedSubscriptionsFixed-cycle subscription completed all scheduled cycles.

📦 Event Payload Examples#

1. payment.success (Invoice Paid)#

{
  "event": "payment.success",
  "data": {
    "txnid": "INV_1001",
    "payu_txnid": "INV_1001_u1",
    "amount": "499.00",
    "status": "success",
    "payu_id": "403993715531478",
    "mode": "UPI",
    "bank_ref_num": "422912384912",
    "product_name": "Pro Membership",
    "customer": {
      "name": "Jane Doe",
      "email": "jane@example.com",
      "phone": "9876543210"
    }
  },
  "timestamp": "2026-08-20T08:15:00.000Z"
}

2. payment.failed (Invoice Payment Failed)#

{
  "event": "payment.failed",
  "data": {
    "txnid": "INV_1002",
    "payu_txnid": "INV_1002_u1",
    "amount": "499.00",
    "status": "failed",
    "error_code": "E301",
    "error_message": "Transaction declined by customer issuing bank",
    "customer": {
      "name": "Jane Doe",
      "email": "jane@example.com",
      "phone": "9876543210"
    }
  },
  "timestamp": "2026-08-20T08:15:00.000Z"
}

3. payment.refunded (Invoice Refunded)#

{
  "event": "payment.refunded",
  "data": {
    "txnid": "INV_1001",
    "payu_txnid": "INV_1001_u1",
    "amount": "499.00",
    "refund_amount": "499.00",
    "status": "refunded",
    "payu_id": "403993715531478",
    "payu_refund_id": "94218392",
    "reason": "Customer cancellation request"
  },
  "timestamp": "2026-08-20T08:20:00.000Z"
}

4. subscription.authorized (Mandate Setup / ₹1 Trial Authorized)#

{
  "event": "subscription.authorized",
  "timestamp": "2026-08-20T08:25:00.000Z",
  "subscription": {
    "sub_id": "sub_4fa9921b34e2c",
    "client_subid": "SUB_1001",
    "plan_name": "Pro Membership",
    "status": "active",
    "customer": {
      "name": "Jane Doe",
      "email": "jane@example.com",
      "phone": "9876543210"
    },
    "pricing": {
      "initial_amount": "1.00",
      "recurring_amount": "199.00",
      "currency": "INR",
      "interval": "monthly"
    },
    "cycles": {
      "completed": 0,
      "total": 12
    },
    "billing": {
      "current_period_start": "2026-08-20T08:25:00.000Z",
      "current_period_end": "2026-09-20T08:25:00.000Z",
      "next_billing_at": "2026-09-20T08:25:00.000Z"
    }
  },
  "payment": {
    "payment_id": 89,
    "cycle_number": 0,
    "initial_amount": "1.00",
    "payment_method": "UPI_AUTOPAY",
    "payu_payment_id": "AUTH_1782017942",
    "authorized_at": "2026-08-20T08:25:00.000Z"
  }
}

5. subscription.charged (Recurring Renewal Cycle Debited)#

{
  "event": "subscription.charged",
  "timestamp": "2026-09-20T08:25:00.000Z",
  "subscription": {
    "sub_id": "sub_4fa9921b34e2c",
    "client_subid": "SUB_1001",
    "plan_name": "Pro Membership",
    "status": "active",
    "customer": {
      "name": "Jane Doe",
      "email": "jane@example.com",
      "phone": "9876543210"
    },
    "pricing": {
      "initial_amount": "1.00",
      "recurring_amount": "199.00",
      "currency": "INR",
      "interval": "monthly"
    },
    "cycles": {
      "completed": 1,
      "total": 12
    },
    "billing": {
      "current_period_start": "2026-09-20T08:25:00.000Z",
      "current_period_end": "2026-10-20T08:25:00.000Z",
      "next_billing_at": "2026-10-20T08:25:00.000Z"
    }
  },
  "payment": {
    "payment_id": 142,
    "cycle_number": 1,
    "amount": "199.00",
    "currency": "INR",
    "payu_payment_id": "REC_1784609941",
    "paid_at": "2026-09-20T08:25:00.000Z"
  }
}

6. subscription.failed (Recurring Renewal Debit Failed)#

{
  "event": "subscription.failed",
  "timestamp": "2026-09-20T08:25:00.000Z",
  "subscription": {
    "sub_id": "sub_4fa9921b34e2c",
    "client_subid": "SUB_1001",
    "plan_name": "Pro Membership",
    "status": "active",
    "customer": {
      "name": "Jane Doe",
      "email": "jane@example.com",
      "phone": "9876543210"
    }
  },
  "payment": {
    "cycle_number": 1,
    "amount": "199.00",
    "error_code": "INSUFFICIENT_FUNDS",
    "error_message": "Mandate debit failed due to insufficient funds in customer bank account"
  }
}

7. subscription.cancelled (Mandate Terminated)#

{
  "event": "subscription.cancelled",
  "timestamp": "2026-09-21T10:00:00.000Z",
  "subscription": {
    "sub_id": "sub_4fa9921b34e2c",
    "client_subid": "SUB_1001",
    "plan_name": "Pro Membership",
    "status": "cancelled",
    "customer": {
      "name": "Jane Doe",
      "email": "jane@example.com",
      "phone": "9876543210"
    }
  },
  "payment": {
    "reason": "Cancelled by merchant via API"
  }
}

8. subscription.completed (All Fixed Cycles Finished)#

{
  "event": "subscription.completed",
  "timestamp": "2027-06-20T08:00:00.000Z",
  "subscription": {
    "sub_id": "sub_4fa9921b34e2c",
    "client_subid": "SUB_1001",
    "plan_name": "Pro Membership",
    "status": "completed",
    "customer": {
      "name": "Jane Doe",
      "email": "jane@example.com",
      "phone": "9876543210"
    },
    "cycles": {
      "completed": 12,
      "total": 12
    }
  }
}

💻 Sample Webhook Receiver Implementation#

Node.js / Express Example:#

Python / FastAPI Example:#

Test webhook#

You can test your webhook from https://webhook.site/#!/
Modified at 2026-08-20 04:31:14
Previous
cancel subscription
Built with