API Docs
/
No Results Found
Run In Postman
Resources
Webhooks

Webhooks AI Tools

Open in ChatGPT

Open in ChatGPT to ask questions about this page

Open in Claude

Open in Claude to ask questions about this page

Copy as Markdown

Copy this page as markdown to use with AI assistants

View as Markdown

Open this page as markdown in a new tab

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.succeeded
  • payment.failed
Payment Link Webhooks
  • payment_link.paid
  • payment_link.expired
  • payment_link.canceled
Virtual Account Webhooks
  • virtual_account.paid
  • virtual_account.closed
Refund Webhooks
  • refund.succeeded
  • refund.failed
Payout Webhooks
  • payout.initiated
  • payout.paid
  • payout.failed

Payment Webhooks

Triggered when a payment is processed in Zoho Payments, notifying your system of its status (success, declined, or pending) and related details.

Note: For recurring payments, the mandate_id will be returned in the response along with the payment details. To set up recurring payments, refer to the API Document for Mandates.

payment.succeeded

Triggered when a payment succeeds, and provides payment details.

Example

{ "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": { "mandate_id": "3000000004001", "type": "upi", "upi": { "channel": "qr", "account_type": "bank_account", "upi_id": "akash@examplebank" } }, "meta_data": [ { "key": "Key1", "value": "Value1" } ] } } }

payment.failed

Triggered when a payment fails and includes the reason for failure.

Example

{ "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": { "mandate_id": "3000000004001", "type": "upi", "upi": { "channel": "qr", "account_type": "", "upi_id": "" } }, "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.

Example

{ "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", "type": "net_banking", "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.

Example

{ "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.

Example

{ "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" } } }

Virtual Account Webhooks

A virtual account webhook is triggered when a payment is received for a virtual account or when a virtual account is closed, notifying your system of the event along with virtual account details.

virtual_account.paid

Triggered when a payment is received for a virtual account, and provides the virtual account details and payment information.

Example

{ "event_id": 100000050155033, "event_type": "virtual_account.paid", "account_id": 93011022, "live_mode": true, "event_time": 1770712057594, "event_object": { "virtual_account": { "virtual_account_id": "1000004777777", "account_number": "ZOHOESAAAAH7HH97", "amount_paid": "1000.00", "description": "Test virtual Account", "maximum_amount": "1000", "minimum_amount": "100", "reference_number": "Order_kicwy0405", "ifsc_code": "ICIC0000106", "beneficiary_name": "Zoho Payments", "expires_at": "2026-03-12", "meta_data": [ { "key": "key_1", "value": "value_1" }, { "key": "key_2", "value": "value_2" } ], "currency": "INR", "payment": { "date": 1770712057, "amount": "102.00", "payment_id": "10050151435033", "status": "succeeded" }, "customer_id": "1000022342332323", "status": "active", "last_modified_time": 1770712057, "created_time": 1770708142 } } }

virtual_account.closed

Triggered when a virtual account is closed, and provides the virtual account details and status.

Example

{ "event_id": 4000000010015, "event_type": "virtual_account.closed", "account_id": 47257939, "live_mode": false, "event_time": 1770117820303, "event_object": { "virtual_account": { "account_number": "ZOHOESAAAADUNJJIZY6", "status": "closed", "amount_paid": "0.00", "description": "", "maximum_amount": 10000, "minimum_amount": "", "reference_number": "", "ifsc_code": "ICIC0000106", "beneficiary_name": "Zoho payments", "expires_at": "2026-03-05", "currency": "INR", "customer_id": "", "virtual_account_id": "4000000008119", "created_time": 1770100492, "last_modified_time": 1770117817 } } }

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.

Example

{ "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", "meta_data": [ { "key": "Key1", "value": "Value1" } ], "status": "succeeded" } } }

refund.failed

Triggered when a refund fails and provides the reason for failure.

Example

{ "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", "meta_data": [ { "key": "Key1", "value": "Value1" } ], "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.

Example

{ "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.

Example

{ "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.

Example

{ "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" } } }