Payouts Webhooks

Webhook is the http call-back or a way to be notified about the status of an event. These webhooks are maintained at third party users who don’t always hold any connection with the originator of the event.

• Individual Webhook: You can set an individual webhook to listen to a particular event. 
• Default Webhook: PayU offers a solution for setting up a default webhook to listen events for which individual webhook has not been set.

Example:

If you want to listen to Payouts transfer success event, You need to create an HTTP POST API at the merchant’s server end. If you have IP whitelisting enabled at your end, do not forget to whitelist PayU IP address so PayU can access your webhook URL. 

PayU IP addresses for webhooks

📘

Note:

If you are facing issues with setting up webhooks, contact PayU Support.

How webhooks works?

When an event is initiated at PayU’s end, a webhook (that is, an API maintained at your end) is called to check and notify you about the status of the event. You can either create a separate webhook for each event or choose to listen to all events using a default webhook.

Types of events

You can create webhooks for following events so that you can obtain the callback from PayU. For more information on how to configure webhoooks using Set Webhook API, refer to Set Webhook API.

Things you should know

• If you do not set any webhooks, that is, neither individual nor default webhook then you will not get any events.
• If you set only the default webhook then you will get all the events on the default webhook.
• If you set a few webhooks along with the default webhook, you will get individual events to the set webhooks and default webhook will be called for the events that have not been set by you. 

For example, If you have set the default webhooks, transfer success and transfer failed webhooks only, the transfer success/failed events will be pushed to the set webhooks corresponding to transfer success/failure . The remaining events such as deposit, low balance will be sent to the default webhooks.

• If you set the certain webhooks but not the default webhook, you will receive the events on individual webhooks. Unset events will not be pushed as default webhook is not known to us.

Webhooks events

There are various events for which you can configure webhooks. You can either create Individual Webhook URLs for each event or listen to them using the Default Webhook.

Following table describes such events:

Types of Webhooks

Webhooks are of various types and each webhook has a distinct body. 

📘

Note: Webhook retry

On trigger of webhooks, merchants are expected to return http status code 200 within 10 seconds window. If any other response codes received or the request times out, it is considered as failure. On failure, the webhook is re-tried maximum 2 more times with same protocol.

Low balance webHook

WebHook event is generated when the merchant account has a low balance. The event signals to deposit money in the merchant virtual account so that upcoming transfer requests can be quickly processed

Sample payload

{
  "event": "LOW_BALANCE_ALERT","msg": "Low Balance",
  "currentBalance": "4806229.19",
  "alertTime": "28 September 2023 05:41 PM",
  "authorization": "",
  "payoutMerchantId": "1117587"
}

Deposit webhook

WebHook event is generated to signal that a deposit has been successfully processed in the merchant virtual account. The money in the account can be used to do payouts to various beneficiary accounts.

Sample payload

{
  "event": "DEPOSIT_SUCCESS",
  "msg": "Deposited",
  "transferId": "AXISCN0123456275",
  "referenceId": "573951",
  "amount": 740311.67,
  "authorization": "",
  "payoutMerchantId": "1117587"
}

Request processing failed webhook

WebHook event is generated to signal that a transfer request has failed processing.

Sample payload

{
"event" : "REQUEST_PROCESSING_FAILED",
"msg" : "",
"payuRefId" : "3212312ds",
"merchantReferenceId" : "3212312ds"
}

Transfer success webhook

WebHook event is generated to signal that a transfer has been successful.

Sample Payload

{
  "event": "TRANSFER_SUCCESS",
  "msg": "Success",
  "payuRefId": "16958123456787V",
  "merchantReferenceId": "991014001234592537",
  "bankReferenceId": "327012345470",
  "authorization": "",
  "payoutMerchantId": "1117587"
}

Transfer failed webhook

WebHook event is generated to signal that a transfer has failed.

Sample Payload

{
  "event": "TRANSFER_FAILED",
  "msg": "Transfer failed due to technical decline. Please reinitiate the transaction",
  "payuRefId": "1691234569025s3",
  "merchantReferenceId": "116911131",
  "authorization": "",
  "payoutMerchantId": "1117587"
}

Transfer reversed webhook

Webhook event is generated to signal that a transfer was successful but reversed after few days due to different reasons.

Sample Payload

{
  "event": "TRANSFER_REVERSED",
  "msg": "Transaction Successful",
  "payuRefId": "1667388287123QJ",
  "merchantReferenceId": "26387449",
  "bankReferenceId": "231234542261",
  "authorization": "",
  "payoutMerchantId": "1117587"
}

Smart send detail submitted Webhook

WebHook event is generated to signal that a beneficiary has added their account details on the smart send link.

Sample payload

{
"event" : " SMART_SEND_DETAIL_SUBMITTED",
"msg" : "Detail filled",
"linkId" : "3212312ds",
"merchantReferenceId" : "3212312ds",
"merchantMiscId" : "3212312ds"
}

Schedule downtime webhook

Webhook event generated when scheduled downtime is planned at partner bank end.

Sample payload

{
  "event": "SCHEDULED_DOWNTIME",
  "msg": "There is a scheduled downtime for maintenance at bank end. Transactions initiated during downtime will either get Queued or Failed as per Dashboard config setup. Once downtime is over we will initiate the transactions for payout.",
  "module": "IMPS",
  "startTime": "2023-02-24 18:08:00",
  "endTime": "2023-02-24 18:15:00",
  "bank": "YES_BANK",
  "authorization": "",
  "payoutMerchantId": "1111157"
}

Bulk smart send file processed webhook

Webhook event generated when file uploaded for smart send is successfully processed.

Sample payload

Webhook details
{
  "event": "BULK_SMART_SEND_FILE_PROCESSED",
  "msg": "File processed",
  "fileId": 136,
  "totalRows": 1001,
  "successfulRows": 1000,
  "failedRows": 1,
  "status": "COMPLETED",
  "authorization": "",
  "payoutMerchantId": "1111157"
}

Transfer success webhook – Penny with name match

WebHook event is generated to signal that a Penny with name match verification has been successful.

Sample payload

{
   "event": "TRANSFER_SUCCESS",
   "msg": "Success",
   "payuRefId": "PAYOUT1686459872847Ahx610a8fKn",
   "merchantReferenceId": "4Y5MGYUGCXV8NLKJMIXC55XZXHR705",
   "bankReferenceId": "PAYOUT1686459872847Ahx610a8fKn",
   "nameMatch": 85,
   "nameWithBank": "CC",
   "authorization": "",
   "payoutMerchantId": "1111157"
}

Transfer success webhook – Penny deposit

WebHook event is generated to signal that a Penny verification has been successful.

Sample payload

{
   "event": "TRANSFER_SUCCESS",
   "msg": "Success",
   "payuRefId": "PAYOUT1686459872847Ahx610a8fKn",
   "merchantReferenceId": "4Y5MGYUGCXV8NLKJMIXC55XZXHR705",
   "bankReferenceId": "PAYOUT1686459872847Ahx610a8fKn",
   "nameWithBank": "CC",
   "authorization": "",
   "payoutMerchantId": "1111157"
}

Smart Send Expired Webhook

When the Smart Send link status changes to expired, a webhook will be triggered to notify the merchant about the Smart Send link expiration.

Sample Payload

{  
"event": "SMART_SEND_EXPIRED",  
  "msg": "Smart send link expired, create a new link.",  
  "expireOn": "2023-10-01 16: 45: 30",  
  "merchantReferenceId": "26383437449",  
  "authorization": "",  
  "payoutMerchantId": "1117587"  
  }

Smart Send Cancelled Webhook

When the Smart Send link status changes to cancelled, a webhook will be triggered to notify the merchant about the Smart Send link cancellation.

Sample Payload

{  
  "event": "SMART_SEND_CANCELLED",  
  "msg": "Smart Send Link cancelled by the merchant, create a new link.",  
  "expireOn": "2023-10-01 16: 45: 30",  
  "merchantReferenceId": "26383437449",  
  "authorization": "",  
  "payoutMerchantId": "1117587"  
  }

Smart Send Rejected Webhook

When the Smart Send link status changes to rejected, a webhook will be triggered to notify the merchant about the Smart Send link rejection.

Sample Payload

  {  
   "event": "SMART_SEND_REJECTED",  
  "msg": "Smart Send approval rejected, check with the approver.",  
  "expireOn": "2023-10-01 16: 45: 30",  
  "merchantReferenceId": "26383437449",  
  "authorization": "",  
  "payoutMerchantId": "1117587"  
  }

System Rejections Tracking 

You can trace the payout to phone requests that are getting auto-rejected for safeguarding transfer to intended beneficiary for the below cases through transfer status and sub-status passed in Status Check API, Dashboard