Braintree Webhook for Payment failure to Submerchant

Question

As per documentation what I had understood is, when we release funds from escrow, if there is any issue with sub-merchant if we setup a webhook for Disbursement Exception then it will be notified to us. Braintree will hit the endpoint url which we have configured in control panel with request parameters, I want to find for which transactions & sub-merchant issue is raised. From this doc its clear that transactions ids they will send in request parameters but its not clearly given about sub-merchant details anywhere in the doc.

I tried even sample payload, payload doesn't reflect actual request parameters. To know myself what parameters will be sent by Braintree when Disbursement Exception occurs I created a sub-merchant in sandbox using PHP SDK with destination as Braintree_Test_MerchantAccount::$bankRejectedUpdateFundingInformation, after that I created few sale transactions where funds has to release from escrow to newly create sub-merchant. From two days I'm waiting for that Braintree will hit endpoint url which I configured in control panel when it tries to release funds to sub-merchant but Braintee never hit endpoint url and still escrow status is Release Pending.

My question in-short: How to know for which sub-merchant disbursement exception is occurred when braintree webhook hit the endpoint url ?

Answer 1

_{Full disclosure: I work at Braintree. If you have any further questions, feel free to contact support.}

In the case of a disbursement exception, the resulting webhook payload will still contain a disbursement object. The disbursement object will have a merchantAccount parameter, which contains info about the submerchant account for which disbursement failed, including id, the submerchant's merchant account ID. Here's the relevant page in the Braintree dev docs.

In code, here's what that looks like: once you've parsed the webhook notification and confirmed that $webhookNotification->kind is Braintree_WebhookNotification::DISBURSEMENT_EXCEPTION, then you can use

$webhookNotification->disbursement->merchantAccount->id

to get the ID. On the disbursement object, you also can get the reason for the failure with exceptionMessage, the list of transactions in the failed disbursement with transactionIds, and a suggested next step with followUpAction.

If you're using the latest version of the Braintree PHP SDK (currently 3.22.0), then on a sample notification, $webhookNotification->disbursement->merchantAccount->id will be set to "merchant_account_token".