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
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 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": 9973000000138072,
"event_type": "payment.succeeded",
"account_id": 105078477,
"live_mode": false,
"event_time": 1756096975624,
"event_object": {
"payment": {
"date": 1756096972,
"fraud_alert": "no_alert",
"transaction_reference_number": "123456543XXXX",
"fee_bearer_formatted": "Merchant",
"fee_details": {
"processing_fee": {
"fee_amount": "5.88",
"is_refunded": false,
"fcy_fee_amount": "5.88",
"fee_type": "processing_fee"
}
},
"description": "Test payment made from the Zoho Payments web app.",
"default_currency_balance": "200.00",
"net_fee_amount": "5.88",
"amount_refunded": "0.00",
"refunds": [],
"statement_descriptor": "Zoho Pay",
"default_currency_net_amount": "194.12",
"balance": "200.00",
"payment_id": "9973000000138051",
"default_currency_processing_fee_amount": "5.88",
"meta_data": [],
"default_currency_net_fee_amount": "5.88",
"currency": "USD",
"default_currency_fee_amount": "5.88",
"invoice_number": "",
"processing_fee_amount": "5.88",
"payment_method": {
"billing_address": {
"country": "US",
"address_line2": "",
"address_line1": "1409 Graymalkin lane",
"city": "Westchester County",
"name": "Akash",
"state": "New York",
"postal_code": "10560"
},
"type": "card",
"card": {
"expiry_month": "2",
"country": "US",
"funding": "credit",
"card_holder_name": "Akash",
"last_four_digits": "4242",
"brand": "visa",
"expiry_year": "2034",
"issuer": "Stripe Payments UK Limited"
}
},
"amount": "200.00",
"default_currency_amount_refunded": "0.00",
"exchange_rate": 1,
"default_currency_amount": "200.00",
"amount_captured": "200.00",
"reference_number": "",
"default_currency_amount_captured": "200.00",
"fee_amount": "5.88",
"phone": "",
"receipt_email": "xxx@abc.com",
"total_fee_amount": "5.88",
"net_amount": "194.12",
"fee_bearer": "merchant",
"default_currency": "USD",
"status": "succeeded"
}
}
}
payment.failed
Triggered when a payment fails and includes the reason for failure.
{
"event_id": 9973000000145064,
"event_type": "payment.failed",
"account_id": 105078477,
"live_mode": false,
"event_time": 1756194471626,
"event_object": {
"payment": {
"date": 1756194470,
"fraud_alert": "no_alert",
"transaction_reference_number": "",
"description": "Test payment made from the Zoho Payments web app.",
"net_fee_amount": "",
"refunds": [],
"statement_descriptor": "Zoho Pay",
"default_currency_net_amount": "",
"payment_id": "9973000000145059",
"default_currency_processing_fee_amount": "",
"meta_data": [],
"default_currency_net_fee_amount": "",
"currency": "USD",
"tip": "Request the customer to contact the card issuer for further details.",
"default_currency_fee_amount": "",
"invoice_number": "",
"processing_fee_amount": "",
"payment_method": {
"billing_address": {
"country": "US",
"address_line2": "",
"address_line1": "1409 Graymalkin lane",
"city": "Westchester County",
"name": "Akash",
"state": "New York",
"postal_code": "10560"
},
"type": "card",
"card": {
"expiry_month": "12",
"country": "US",
"funding": "credit",
"card_holder_name": "Akash",
"last_four_digits": "0002",
"brand": "visa",
"expiry_year": "2034",
"issuer": "Stripe Test (multi-country)"
}
},
"amount": "200.00",
"failure_code": "card_declined_unknown_reason",
"default_currency_amount": "200.00",
"reference_number": "",
"fee_amount": "",
"phone": "",
"receipt_email": "xxx@abc.com",
"next_action": "405",
"failure_category": "declined_by_issuer",
"net_amount": "",
"default_currency": "USD",
"status": "failed"
}
}
}
payment.pending
Triggered when a payment that takes time to process (e.g., ACH) is initiated, and includes the payment details.
{
"event_id": 9973000000145108,
"event_type": "payment.pending",
"account_id": 105078477,
"live_mode": false,
"event_time": 1756194809423,
"event_object": {
"payment": {
"date": 1756194809,
"fraud_alert": "no_alert",
"transaction_reference_number": "",
"fee_bearer_formatted": "Merchant",
"fee_details": {
"processing_fee": {
"fee_amount": "1.60",
"is_refunded": false,
"fcy_fee_amount": "1.60",
"fee_type": "processing_fee"
}
},
"description": "Test payment made from the Zoho Payments web app.",
"net_fee_amount": "1.60",
"refunds": [],
"statement_descriptor": "Zoho Pay",
"default_currency_net_amount": "198.40",
"payment_id": "9973000000145097",
"default_currency_processing_fee_amount": "1.60",
"meta_data": [],
"default_currency_net_fee_amount": "1.60",
"currency": "USD",
"default_currency_fee_amount": "1.60",
"invoice_number": "",
"processing_fee_amount": "1.60",
"payment_method": {
"ach_debit": {
"account_type": "checking",
"account_holder_name": "Akash",
"account_holder_type": "individual",
"bank_name": "STRIPE TEST BANK",
"last_four_digits": "6789",
"routing_number": "110000000"
},
"type": "ach_debit"
},
"amount": "200.00",
"default_currency_amount": "200.00",
"reference_number": "",
"fee_amount": "1.60",
"phone": "",
"receipt_email": "xxx@abc.com",
"customer_email": "",
"total_fee_amount": "1.60",
"customer_name": "Zylker",
"net_amount": "198.40",
"fee_bearer": "merchant",
"customer_id": "9973000000146005",
"default_currency": "USD",
"status": "pending"
}
}
}
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": 9973000000146040,
"event_type": "payment_link.paid",
"account_id": 105078477,
"live_mode": false,
"event_time": 1756194904548,
"event_object": {
"payment_links": {
"created_time": 1756194876,
"amount": "10.00",
"amount_paid": "10.00",
"reference_id": "",
"phone_country_code": "",
"payment_link_id": "9973000000145119",
"payments": [
{
"date": 1756194900,
"amount": "10.00",
"payment_id": "9973000000146015",
"status_formatted": "Succeeded",
"status": "succeeded"
}
],
"description": "Test",
"created_by": "Akash",
"url": "https://payments.zoho.com/paymentlinks/274ca8c3ffa7de3473c30cadee4b7f2d6004321864bc367149169286998276e8e1250afdc3df80c0341ca67d117c140c92fb0a85b228e1a8162699fc55716549",
"expires_at_formatted": "Sep 25, 2025, 03:54 AM",
"expires_at": "2025-09-25",
"phone": "",
"last_modified_by_id": "9973000000026005",
"return_url": "",
"currency": "USD",
"created_by_id": "9973000000026005",
"last_modified": "Akash",
"email": "",
"phone_dialing_code": "",
"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.com/paymentlink/b0ec9b455584e8ee1dc0fd479f7ad4601ea39169f8aaf9991b83",
"expires_at_formatted": "Apr 11, 2025, 03:46 PM",
"expires_at": "2025-04-11",
"phone": "",
"last_modified_by_id": "173000002314885",
"return_url": "https://example.com/expired",
"currency": "USD",
"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": 9973000000145128,
"event_type": "payment_link.canceled",
"account_id": 105078477,
"live_mode": false,
"event_time": 1756195082908,
"event_object": {
"payment_links": {
"created_time": 1756195075,
"amount": "10.00",
"amount_paid": "0.00",
"reference_id": "",
"phone_country_code": "",
"payment_link_id": "9973000000145123",
"payments": [],
"description": "Test",
"created_by": "Akash",
"url": "https://payments.zoho.com/paymentlinks/274ca8c3ffa7de3473c30cadee4b7f2d6004321864bc367149169286998276e8fc590de859d680bd66db902910cfb81bc796a587752dd0ef93f8363c37b0a095",
"expires_at_formatted": "Sep 25, 2025, 03:57 AM",
"expires_at": "2025-09-25",
"phone": "",
"last_modified_by_id": "9973000000026005",
"return_url": "",
"currency": "USD",
"created_by_id": "9973000000026005",
"last_modified": "Akash",
"email": "",
"phone_dialing_code": "",
"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": 9973000000145156,
"event_type": "refund.succeeded",
"account_id": 105078477,
"live_mode": false,
"event_time": 1756195177661,
"event_object": {
"refund": {
"initiated_by": "Akash",
"network_reference_number": "",
"date": 1756195173,
"reason": "requested_by_customer",
"amount": "1.00",
"initiated_by_id": "9973000000026005",
"default_currency_amount": "1.00",
"description": "",
"failure_reason": "",
"type": "initiated_by_merchant",
"refund_id": "9973000000145131",
"reference_number": "",
"payment_id": "9973000000138051",
"meta_data": [
{
"key": "Key1",
"value": "Value1"
}
],
"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",
"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.
{
"event_id": 2716000000906063,
"event_type": "payout.initiated",
"account_id": 77507325,
"live_mode": false,
"event_time": 1756201138438,
"event_object": {
"payout": {
"amount": "4767.910",
"failure_code": "",
"initiated_time": 1756201134,
"comments": [],
"fee": "0.00",
"processing_fee": 0,
"account_details": {
"country": "US",
"account_holder": "Zylker Corporation",
"account_number_last_four_digits": "1116",
"bank_name": "TEST BANK",
"currency": "USD",
"routing_number": "110000000",
"type": "bank_account"
},
"failure_message": "",
"type": "deposit",
"payout_method": "standard",
"fee_rate": 0,
"statement_descriptor": "ZOHO PAYMENTS",
"payout_id": "2716000000906003",
"payout_bank_reference_id": "",
"transaction_summary": {
"charge": {
"amount": 4910,
"fee": -142.09,
"count": 17,
"net_amount": 4767.91,
"transaction_type": "charge"
},
"total_amount": 4767.91,
"reserve": {
"amount": 0,
"fee": 0,
"count": 3,
"net_amount": 0,
"transaction_type": "reserve"
},
"adjustment": {
"amount": 0,
"fee": 0,
"count": 0,
"net_amount": 0,
"transaction_type": "adjustment"
},
"refund": {
"amount": 0,
"fee": 0,
"count": 0,
"net_amount": 0,
"transaction_type": "refund"
}
},
"currency": "USD",
"arrival_date": "1756217100",
"status": "initiated"
}
}
}
payout.paid
Triggered when a payout is completed, and provides the payout ID, amount, and summary.
{
"event_id": 6166000001134015,
"event_type": "payout.paid",
"account_id": 72949175,
"live_mode": false,
"event_time": 1756201900492,
"event_object": {
"payout": {
"amount": "194.500",
"failure_code": "",
"initiated_time": 1756201787,
"comments": [],
"processed_date": 1756217100,
"fee": "0.00",
"processing_fee": 0,
"account_details": {
"country": "US",
"account_holder": "Akash",
"account_number_last_four_digits": "6789",
"bank_name": "TEST BANK",
"currency": "USD",
"routing_number": "110000000",
"type": "bank_account"
},
"failure_message": "",
"type": "deposit",
"payout_method": "standard",
"fee_rate": 0,
"statement_descriptor": "ZOHO PAYMENTS",
"payout_id": "6166000001133009",
"payout_bank_reference_id": "7UF6L35XU4ww6sM4Y451O3gm4Y56oK4MC7c33p61H",
"transaction_summary": {
"charge": {
"amount": 200,
"fee": -5.5,
"count": 1,
"net_amount": 194.5,
"transaction_type": "charge"
},
"total_amount": 194.5,
"adjustment": {
"amount": 0,
"fee": 0,
"count": 0,
"net_amount": 0,
"transaction_type": "adjustment"
},
"refund": {
"amount": 0,
"fee": 0,
"count": 0,
"net_amount": 0,
"transaction_type": "refund"
}
},
"currency": "USD",
"status": "paid"
}
}
}
payout.failed
Triggered when a payout fails, and provides the payout ID, amount, summary, and failure reason.
{
"event_id": 2716000000909025,
"event_type": "payout.failed",
"account_id": 77507325,
"live_mode": false,
"event_time": 1756201165745,
"event_object": {
"payout": {
"amount": "4767.910",
"failure_code": "no_account",
"initiated_time": 1756201134,
"comments": [],
"processed_date": 1756201163,
"fee": "0.00",
"processing_fee": 0,
"account_details": {
"country": "US",
"account_holder": "Akash",
"account_number_last_four_digits": "1116",
"bank_name": "TEST BANK",
"currency": "USD",
"routing_number": "110000000",
"type": "bank_account"
},
"failure_message": "The bank account (••••1116) could not be located.",
"type": "deposit",
"payout_method": "standard",
"fee_rate": 0,
"statement_descriptor": "ZOHO PAYMENTS",
"payout_id": "2716000000906003",
"payout_bank_reference_id": "",
"transaction_summary": {
"charge": {
"amount": 4910,
"fee": -142.09,
"count": 17,
"net_amount": 4767.91,
"transaction_type": "charge"
},
"total_amount": 4767.91,
"reserve": {
"amount": 0,
"fee": 0,
"count": 3,
"net_amount": 0,
"transaction_type": "reserve"
},
"adjustment": {
"amount": 0,
"fee": 0,
"count": 0,
"net_amount": 0,
"transaction_type": "adjustment"
},
"refund": {
"amount": 0,
"fee": 0,
"count": 0,
"net_amount": 0,
"transaction_type": "refund"
}
},
"currency": "USD",
"status": "failed"
}
}
}