Webhooks allow Braintree to push messages to your servers when you configure a webhook endpoint URL. If you support new Braintree account signups in your Braintree Auth integration, you can subscribe to webhooks that provide status on important changes to the connected merchant's account.
We currently provide two webhooks for new Braintree merchant accounts created via Braintree Auth: underwriting status and PayPal account linking status.
We plan to develop several other webhooks in the future.
If you are not using webhooks already, follow the general webhooks guide to configure webhooks in your gateway.
This webhook notifies you when a connected merchant's underwriting status has changed or they have submitted an application:
gateway = Braintree::Gateway.new( :environment => :sandbox, :merchant_id => "use_your_merchant_id", :public_key => "use_your_public_key", :private_key => "use_your_private_key", ) notification = gateway.webhook_notification.parse( bt_signature, bt_payload, ) notification.kind # Braintree::WebhookNotification::Kind::ConnectedMerchantStatusTransitioned notification.connected_merchant_status_transitioned.status # "approved" notification.connected_merchant_status_transitioned.merchant_public_id # "merchant_public_id" notification.connected_merchant_status_transitioned.oauth_application_client_id # "oauth_application_client_id"
The following status transitions trigger a webhook:
||A merchant has been approved for a Braintree account. All funds from settled transctions will be disbursed to the merchant's bank account.|
||A merchant has been denied. All settled transactions will be refunded.|
||A merchant has submitted their application to Braintree. The merchant can now accept payments to a limit - 25 transactions or up to $2500. Funds will not be disbursed until the merchant is approved.|
||A merchant application is being reviewed.|
||A merchant decided to not move forward with the underwriting process. This also occurs if a trial merchant has not submitted an application within 30 days of processing their first payment.|
This webhook notifies you when a connected merchant's PayPal account has been successfully linked or unlinked to their Braintree gateway.
gateway = Braintree::Gateway.new( :environment => :sandbox, :merchant_id => "use_your_merchant_id", :public_key => "use_your_public_key", :private_key => "use_your_private_key", ) notification = gateway.webhook_notification.parse( bt_signature, bt_payload ) notification.kind # Braintree::WebhookNotification::Kind::ConnectedMerchantPayPalStatusChanged notification.connected_merchant_paypal_status_changed.action # "link" notification.connected_merchant_paypal_status_changed.merchant_public_id # "merchant_public_id" notification.connected_merchant_paypal_status_changed.oauth_application_client_id # "oauth_application_client_id"
The following linking actions trigger a webhook:
||A connected merchant has connected a PayPal account to their gateway and can accept PayPal payments.|
||A connected merchant has disconnected the PayPal account from their gateway. They can no longer accept PayPal payments until they link another PayPal account to their gateway.|
Still have questions?
If you can’t find an answer, contact our Support team.