Webhooks
Webhooks are real-time notifications sent from Zoho Payments' servers to your servers when specific events occur. You can subscribe to a predefined set of events while configuring the URL to receive these notifications. This enables you to take appropriate actions swiftly, based on the events.
Zoho Payments supports the following webhooks:
| Webhook Category | Event Types |
|---|---|
| Payment Webhooks |
|
| Payment Link Webhooks |
|
| Refund Webhooks |
|
| Payout Webhooks |
|
Payment Webhooks
Triggered when a payment is processed in Zoho Payments, notifying your system of its status (success, declined, or pending) and related details.
payment.succeeded
Triggered when a payment succeeds, and provides payment details.
{
"event_id": 1987000003853347,
"event_type": "payment.succeeded",
"account_id": 105078477,
"live_mode": false,
"event_time": 1745558807514,
"event_object":
{
"payment": {
"payment_id": "1987000000724207",
"phone": "+91 0000000000",
"amount": "200.00",
"currency": "INR",
"payments_session_id": "1987000000724189",
"receipt_email": "xxx@abc.com",
"reference_number": "REF-12345",
"invoice_number": "INV-12345",
"amount_captured": "200.00",
"amount_refunded": "100.00",
"fee_amount": "4.00",
"net_tax_amount": "0.72",
"total_fee_amount": "4.72",
"net_amount": "95.28",
"status": "partially_refunded",
"statement_descriptor": "Zoho Payments",
"description": "Payment for INV-000008",
"date": 1715163045,
"payment_method": {
"type": "card",
"card": {
"card_holder_name": "Akash",
"last_four_digits": "3212",
"expiry_month": "01",
"expiry_year": "26",
"brand": "rupay",
"funding": "debit"
}
},
"meta_data": [
{
"key": "Key1",
"value": "Value1"
}
]
}
}
}
payment.failed
Triggered when a payment fails and includes the reason for failure.
{
"event_id": 1987000003853920,
"event_type": "payment.failed",
"account_id": 105078477,
"live_mode": false,
"event_time": 1745584986806,
"event_object":
{
"payment":
{
"date": 1745584960,
"description": "Payment for INV-000008",
"statement_descriptor": "Zoho Payments",
"payment_id": "1987000003853908",
"meta_data":
[
{
"key": "Key1",
"value": "Value1"
}
],
"currency": "INR",
"payments_session_id": "1987000003853885",
"tip": "Request the customer to try again or use a different payment method.",
"payment_method": {
"type": "card",
"card": {
"expiry_month": "01",
"country": "IN",
"funding": "debit",
"card_holder_name": "Akash",
"card_category": "retail",
"last_four_digits": "3212",
"brand": "rupay",
"expiry_year": "33"
}
},
"amount": "200.00",
"failure_code": "payment_authentication_failed",
"reference_number": "REF-12345",
"invoice_number": "INV-12345",
"phone": "+91 0000000000",
"receipt_email": "xxx@abc.com",
"next_action": "624",
"failure_category": "authentication_failed",
"status": "failed"
}
}
}
Payment Link Webhooks
Triggered when a payment is made through a Zoho Payments link, notifying your system of the link status (paid, canceled, or expired).
payment_link.paid
Triggered when a payment is completed via a payment link, and provides the link ID and status.
{
"event_id": 3000000040047,
"event_type": "payment_link.paid",
"account_id": 105078477,
"live_mode": false,
"event_time": 1744366673614,
"event_object": {
"payment_links": {
"created_time": 1744366612,
"amount": "10.00",
"amount_paid": "10.00",
"reference_id": "1234567890IUEGS",
"payment_link_id": "3000000040011",
"payments": [
{
"date": 1744366671,
"amount": "10.00",
"payment_id": "3000000040031",
"status_formatted": "Succeeded",
"status": "succeeded"
}
],
"description": "Payment for Order #12345",
"created_by": "Akash",
"url": "https://payments.zoho.in/paymentlink/b0ec9b455584e8ee1dc0fd479f7ad4601ea39169f8aaf9991b83",
"expires_at_formatted": "May 11, 2025, 03:46 PM",
"expires_at": "2025-05-11",
"phone": "+91 0000000000",
"last_modified_by_id": "173000002314885",
"return_url": "https://example.com/success",
"currency": "INR",
"created_by_id": "173000002314885",
"last_modified": "Akash",
"email": "xxx@abc.com",
"status": "paid"
}
}
}
payment_link.expired
Triggered when a payment link expires, with link ID and expiry details.
{
"event_id": 3000000040085,
"event_type": "payment_link.expired",
"account_id": 105078477,
"live_mode": false,
"event_time": 1744366883144,
"event_object": {
"payment_links": {
"created_time": 1744366378,
"amount": "100.00",
"amount_paid": "0.00",
"reference_id": "1234567890IUEGS",
"payment_link_id": "3000000040005",
"payments": [],
"description": "Payment for Order #12345",
"created_by": "Akash",
"url": "https://payments.zoho.in/paymentlink/b0ec9b455584e8ee1dc0fd479f7ad4601ea39169f8aaf9991b83",
"expires_at_formatted": "Apr 11, 2025, 03:46 PM",
"expires_at": "2025-04-11",
"phone": "+91 0000000000",
"last_modified_by_id": "173000002314885",
"return_url": "https://example.com/expired",
"currency": "INR",
"created_by_id": "173000002314885",
"last_modified": "Akash",
"email": "xxx@abc.com",
"status": "expired"
}
}
}
payment_link.canceled
Triggered when a payment link is canceled, with link ID and related details.
{
"event_id": 3000000040075,
"event_type": "payment_link.canceled",
"account_id": 105078477,
"live_mode": false,
"event_time": 1744366733109,
"event_object": {
"payment_links": {
"created_time": 1744366714,
"amount": "100.00",
"amount_paid": "0.00",
"reference_id": "1234567890IUEGS",
"payment_link_id": "3000000040071",
"payments": [],
"description": "Payment for Order #12345",
"created_by": "Akash",
"url": "https://payments.zoho.in/paymentlink/b0ec9b455584e8ee1dc0fd479f7ad4601ea39169f8aaf9991b83",
"expires_at_formatted": "May 11, 2025, 03:48 PM",
"expires_at": "2025-05-11",
"phone": "+91 0000000000",
"last_modified_by_id": "173000002314885",
"return_url": "https://example.com/cancelled",
"currency": "INR",
"created_by_id": "173000002314885",
"last_modified": "Akash",
"email": "xxx@abc.com",
"status": "canceled"
}
}
}
Refund Webhooks
A refund webhook is triggered when a refund is initiated or processed, notifying your system of its status (succeeded, failed, or pending) along with details such as the original payment ID and refunded amount.
refund.succeeded
Triggered when a refund succeeds, and provides the refund amount, payment ID, and reason.
{
"event_id": 170000000720053,
"event_type": "refund.succeeded",
"account_id": 105078477,
"live_mode": false,
"event_time": 1735275071716,
"event_object": {
"refund": {
"initiated_by": "Akash",
"network_reference_number": "436210787080",
"date": 1735275011,
"reason": "requested_by_customer",
"amount": "100.00",
"initiated_by_id": "170000000255003",
"description": "Refund for Payment (INV-000008)",
"failure_reason": "",
"type": "initiated_by_merchant",
"refund_id": "170000000720031",
"reference_number": "4113662000000240001",
"payment_id": "170000000721021",
"status": "succeeded"
}
}
}
refund.failed
Triggered when a refund fails and provides the reason for failure.
{
"event_id": 1987000001585091,
"event_type": "refund.failed",
"account_id": 105078477,
"live_mode": false,
"event_time": 1735213969550,
"event_object": {
"refund": {
"initiated_by": "Akash",
"network_reference_number": "",
"date": 1735213900,
"reason": "requested_by_customer",
"amount": "450.00",
"initiated_by_id": "1987000000039031",
"default_currency_amount": "450.00",
"description": "",
"failure_reason": "",
"type": "initiated_by_merchant",
"refund_id": "1987000001585075",
"reference_number": "4113662000000240001",
"payment_id": "1987000001582496",
"status": "failed"
}
}
}
Payout Webhooks
A payout webhook is triggered when a payout transaction is processed, notifying your system of its status (initiated, completed, or failed) along with details such as the payout ID, amount, and transaction summary.
payout.initiated
Triggered when a payout is initiated, and provides the payout ID, amount, and summary.
{
"event_id": 3400000000140041,
"event_type": "payout.initiated",
"live_mode": false,
"event_time": 1736769112751,
"event_object": {
"payout": {
"amount": "1466.000",
"failure_code": "",
"initiated_time": 1736769051,
"comments": [],
"processing_fee": 0,
"account_details": {
"country": "IN",
"account_holder": "Zylker Corporation",
"account_number_last_four_digits": "1453",
"bank_name": "ICICI BANK LIMITED",
"currency": "INR",
"routing_number": "ICIC0000001",
"type": "bank_account"
},
"failure_message": "",
"type": "deposit",
"statement_descriptor": "ZOHO PAYMENTS",
"payout_id": "3400000000140013",
"payout_bank_reference_id": "051850",
"transaction_summary": {
"charge": {
"amount": 1466,
"fee": 0,
"count": 6,
"tax": 0,
"net_amount": 1466,
"transaction_type": "charge"
},
"total_amount": 1466,
"adjustment": {
"amount": 0,
"fee": 0,
"count": 0,
"tax": 0,
"net_amount": 0,
"transaction_type": "adjustment"
"refund": {
"amount": 0,
"fee": 0,
"count": 0,
"tax": 0,
"net_amount": 0,
"transaction_type": "refund"
}
},
"currency": "INR",
"arrival_date": "1736854200",
"status": "initiated"
}
}
}
payout.paid
Triggered when a payout is completed, and provides the payout ID, amount, and summary.
{
"event_id": 3400000000140053,
"event_type": "payout.paid",
"live_mode": false,
"event_time": 1736769261115,
"event_object": {
"payout": {
"amount": "1466.000",
"failure_code": "",
"initiated_time": 1736769051,
"comments": [],
"processed_date": 1736855599,
"processing_fee": 0,
"account_details": {
"country": "IN",
"account_holder": "Zylker Corporation",
"account_number_last_four_digits": "1453",
"bank_name": "ICICI BANK LIMITED",
"currency": "INR",
"routing_number": "ICIC0000001",
"type": "bank_account"
},
"failure_message": "",
"type": "deposit",
"statement_descriptor": "ZOHO PAYMENTS",
"payout_id": "3400000000140013",
"payout_bank_reference_id": "051850",
"transaction_summary": {
"charge": {
"amount": 1466,
"fee": 0,
"count": 6,
"tax": 0,
"net_amount": 1466,
"transaction_type": "charge"
},
"total_amount": 1466,
"adjustment": {
"amount": 0,
"fee": 0,
"count": 0,
"tax": 0,
"net_amount": 0,
"transaction_type": "adjustment"
},
"refund": {
"amount": 0,
"fee": 0,
"count": 0,
"tax": 0,
"net_amount": 0,
"transaction_type": "refund"
}
},
"currency": "INR",
"status": "paid"
}
}
}
payout.failed
Triggered when a payout fails, and provides the payout ID, amount, summary, and failure reason.
{
"event_id": 2093000000279023,
"event_type": "payout.failed",
"live_mode": false,
"event_time": 1736928027466,
"event_object": {
"payout": {
"amount": "1424.220",
"failure_code": "contact_support",
"initiated_time": 1719308635,
"comments": [],
"processed_date": 1719261000,
"processing_fee": 0,
"account_details": {
"country": "IN",
"account_holder": "Zylker Corporation",
"account_number_last_four_digits": "1453",
"bank_name": "",
"currency": "INR",
"routing_number": "ICIC0000001",
"type": "bank_account"
},
"failure_message": "There was an error while processing the payout. Please contact support@zohopayments.com for further assistance.",
"type": "deposit",
"statement_descriptor": "ZOHO PAYMENTS",
"payout_id": "2093000000028003",
"payout_bank_reference_id": "",
"transaction_summary": {
"charge": {
"amount": 2532,
"fee": -71.84,
"count": 4,
"tax": 0,
"net_amount": 2447.23,
"transaction_type": "charge"
},
"total_amount": 1424.22,
"adjustment": {
"amount": 0,
"fee": 0,
"count": 0,
"tax": 0,
"net_amount": 0,
"transaction_type": "adjustment"
},
"refund": {
"amount": -1023.01,
"fee": 0,
"count": 3,
"tax": 0,
"net_amount": -1023.01,
"transaction_type": "refund"
}
},
"currency": "INR",
"status": "failed"
}
}
}