API Docs
/
No Results Found
Webhooks

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.succeeded
  • payment.failed
  • payment.pending
Payment Link Webhooks
  • payment_link.paid
  • payment_link.expired
  • payment_link.canceled
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.

payment.succeeded

Triggered when a payment succeeds, and provides payment details.

Example

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

Example

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

Example

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

Example

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

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

Example

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

Example

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

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

Example

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

Example

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