availability

Braintree Auth is in closed beta. To express interest, contact our Business Development team.

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 alert you to important events happening with the connected merchant's account.

We currently provide four webhooks for new Braintree merchant accounts created via Braintree Auth:

Before you get started

If you are not using webhooks already, follow the general webhooks guide to configure webhooks in your gateway.

note

The $btSignature and $btPayload variables in the code snippets below represent parameters received from the webhook POST request. For more information, read the documentation on parsing webhooks.

Connected merchant underwriting status

This webhook notifies you when a connected merchant's underwriting status has changed or they have submitted an application:

PHP
Copy
Copied
$gateway = new Braintree_Gateway([
    'environment' => 'sandbox'
    'merchantId' => 'use_your_merchant_id',
    'publicKey' => 'use_your_public_key',
    'privateKey' => 'use_your_private_key'
]);

$notification = $gateway->webhookNotification()->parse(
    $btSignature,
    $btPayload
);

$notification->kind
// Braintree_WebhookNotification::CONNECTED_MERCHANT_STATUS_TRANSITIONED;

$notification->connectedMerchantStatusTransitioned->status;
// "approved"

$notification->connectedMerchantStatusTransitioned->merchantId;
// "merchant_id"

$notification->connectedMerchantStatusTransitioned->oauthApplicationClientId;
// "oauth_application_client_id"

The following status transitions trigger a webhook:

Status Description
approved A merchant has been approved for a Braintree account. All funds from settled transctions will be disbursed to the merchant's bank account.
denied A merchant has been denied. All settled transactions will be refunded.
application_submitted 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.
under_review A merchant application is being reviewed.
inactive 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.

PayPal account status changed

This webhook notifies you when a connected merchant's PayPal account has been successfully linked or unlinked to their Braintree gateway.

PHP
Copy
Copied
$gateway = new Braintree_Gateway([
    'environment' => 'sandbox'
    'merchantId' => 'use_your_merchant_id',
    'publicKey' => 'use_your_public_key',
    'privateKey' => 'use_your_private_key'
]);

$notification = $gateway->webhookNotification()->parse(
    $btSignature,
    $btPayload
);

$notification->kind;
// Braintree_WebhookNotification::CONNECTED_MERCHANT_PAYPAL_STATUS_CHANGED

$notification->connectedMerchantPayPalStatusChanged->action;
// "link"

$notification->connectedMerchantPayPalStatusChanged->merchantId;
// "merchant_id"

$notification->connectedMerchantPayPalStatusChanged->oauthApplicationClientId;
// "oauth_application_client_id"

The following linking actions trigger a webhook:

Action Description

Disputes

This webhook notifies you when a connected merchant receives a dispute on a transaction.

important

You must request the oauth_app_receive_dispute_webhooks scope before you can receive these webhooks.

PHP
Copy
Copied
$gateway = new Braintree_Gateway([
    'environment' => 'sandbox'
    'merchantId' => 'use_your_merchant_id',
    'publicKey' => 'use_your_public_key',
    'privateKey' => 'use_your_private_key'
]);

$notification = $gateway->webhookNotification()->parse(
    $btSignature,
    $btPayload
);

$notification->kind;
// Braintree_WebhookNotification::DISPUTE_OPENED

$notification->sourceMerchantId;
// "source_merchant_id"

$notification->dispute->status;
// Braintree_Dispute::OPEN

Refer to the Dispute webhooks reference for all of the available properties on dispute objects.

OAuth access revoked

This webhook notifies you when the connected merchant has revoked access to their account.

PHP
Copy
Copied
$gateway = new Braintree_Gateway([
    'environment' => 'sandbox'
    'merchantId' => 'use_your_merchant_id',
    'publicKey' => 'use_your_public_key',
    'privateKey' => 'use_your_private_key'
]);

$notification = $gateway->webhookNotification()->parse(
    $btSignature,
    $btPayload
);

$notification->kind;
// Braintree_WebhookNotification::OAUTH_ACCESS_REVOKED

$notification->oauthAccessRevocation->merchantId;
// "merchant_id"

See also

Next Page: Merchant API →

Still have questions?

If you can’t find an answer, contact our Support team