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": 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",
"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": 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"
}
}
}