asyncapi: 2.6.0 info: title: Braintree Webhooks description: >- Braintree Webhooks deliver automated HTTP POST notifications to a merchant-configured destination URL when specific events occur within the payment gateway. Webhook notifications are triggered by transaction settlements, subscription lifecycle changes, dispute events, disbursements, sub-merchant account updates, and other gateway events. Each notification payload is sent as a form-encoded POST with a bt_signature field and a bt_payload field, where the payload is a Base64-encoded signed XML document. Merchants must verify the signature using their API keys before processing the payload. Webhooks are configured in the Braintree Control Panel by specifying a destination URL and selecting the event types to monitor. version: '1.0' contact: name: Braintree Developer Support url: https://developer.paypal.com/braintree/docs/ servers: merchantServer: url: '{webhookDestinationUrl}' protocol: https description: >- The merchant-configured HTTPS endpoint that receives webhook notifications from Braintree. The URL is set in the Braintree Control Panel and must be publicly accessible. variables: webhookDestinationUrl: description: The HTTPS URL of the merchant's webhook handler endpoint. channels: /webhook: description: >- The merchant's webhook endpoint that receives HTTP POST notifications from Braintree. All event types are delivered to the same configured URL. The bt_payload contains a Base64-encoded, signed XML document with the event details. Merchants must verify the bt_signature against the payload using their private API key before processing. publish: operationId: receiveBraintreeWebhook summary: Receive a Braintree webhook notification description: >- Braintree sends an HTTP POST to the configured webhook URL when a monitored event occurs. The request is form-encoded with two fields: bt_signature (HMAC-SHA1 signature) and bt_payload (Base64-encoded XML). Merchants parse the notification using a Braintree server SDK to obtain the notification kind and associated object. A 200 response from the destination URL is required to acknowledge receipt; non-200 responses cause Braintree to retry delivery. message: oneOf: - $ref: '#/components/messages/SubscriptionChargedSuccessfully' - $ref: '#/components/messages/SubscriptionChargedUnsuccessfully' - $ref: '#/components/messages/SubscriptionWentActive' - $ref: '#/components/messages/SubscriptionWentPastDue' - $ref: '#/components/messages/SubscriptionExpired' - $ref: '#/components/messages/SubscriptionCanceled' - $ref: '#/components/messages/SubscriptionTrialEnded' - $ref: '#/components/messages/SubscriptionBillingSkipped' - $ref: '#/components/messages/TransactionSettled' - $ref: '#/components/messages/TransactionSettlementDeclined' - $ref: '#/components/messages/DisputeOpened' - $ref: '#/components/messages/DisputeWon' - $ref: '#/components/messages/DisputeLost' - $ref: '#/components/messages/DisputeAccepted' - $ref: '#/components/messages/DisputeAutoAccepted' - $ref: '#/components/messages/DisputeDisputed' - $ref: '#/components/messages/DisputeExpired' - $ref: '#/components/messages/DisputeUnderReview' - $ref: '#/components/messages/Disbursement' - $ref: '#/components/messages/TransactionDisbursed' - $ref: '#/components/messages/SubMerchantAccountApproved' - $ref: '#/components/messages/SubMerchantAccountDeclined' components: securitySchemes: hmacSignature: type: httpApiKey in: header name: bt_signature description: >- HMAC-SHA1 signature computed over the bt_payload value using the merchant's private API key. Merchants must verify this signature before processing any webhook payload to prevent forgery. messages: SubscriptionChargedSuccessfully: name: subscription_charged_successfully title: Subscription Charged Successfully summary: A subscription billing cycle completed with a successful charge. description: >- Sent when a subscription advances to its next billing cycle and the associated transaction is successfully authorized. Also sent when a mid-cycle upgrade generates a prorated charge. The notification payload includes the full subscription object with up to 20 recent transactions. contentType: application/x-www-form-urlencoded payload: $ref: '#/components/schemas/SubscriptionNotificationPayload' headers: $ref: '#/components/schemas/WebhookHeaders' SubscriptionChargedUnsuccessfully: name: subscription_charged_unsuccessfully title: Subscription Charged Unsuccessfully summary: A subscription billing cycle charge attempt failed. description: >- Sent when a subscription billing cycle charge fails, such as when the customer's payment method is declined. The subscription transitions to Past Due status. The notification includes the subscription object with the failed transaction. contentType: application/x-www-form-urlencoded payload: $ref: '#/components/schemas/SubscriptionNotificationPayload' headers: $ref: '#/components/schemas/WebhookHeaders' SubscriptionWentActive: name: subscription_went_active title: Subscription Went Active summary: A subscription transitioned to Active status. description: >- Sent when a subscription's first authorized transaction is created, or when a subscription transitions from Past Due back to Active status. Indicates the subscription is in good standing and billing normally. contentType: application/x-www-form-urlencoded payload: $ref: '#/components/schemas/SubscriptionNotificationPayload' headers: $ref: '#/components/schemas/WebhookHeaders' SubscriptionWentPastDue: name: subscription_went_past_due title: Subscription Went Past Due summary: A subscription transitioned from Active to Past Due status. description: >- Sent when a subscription fails to charge successfully and moves from Active to Past Due status. Merchants should use this event to notify customers and prompt them to update their payment method. contentType: application/x-www-form-urlencoded payload: $ref: '#/components/schemas/SubscriptionNotificationPayload' headers: $ref: '#/components/schemas/WebhookHeaders' SubscriptionExpired: name: subscription_expired title: Subscription Expired summary: A subscription reached its configured number of billing cycles. description: >- Sent when a subscription completes all of its configured billing cycles and expires. The subscription status transitions to Expired. No further charges will be made. Merchants may create a new subscription to continue billing. contentType: application/x-www-form-urlencoded payload: $ref: '#/components/schemas/SubscriptionNotificationPayload' headers: $ref: '#/components/schemas/WebhookHeaders' SubscriptionCanceled: name: subscription_canceled title: Subscription Canceled summary: A subscription was canceled. description: >- Sent when a subscription is canceled either by the merchant via the API or Control Panel. The subscription status transitions to Canceled and no further charges will be made. contentType: application/x-www-form-urlencoded payload: $ref: '#/components/schemas/SubscriptionNotificationPayload' headers: $ref: '#/components/schemas/WebhookHeaders' SubscriptionTrialEnded: name: subscription_trial_ended title: Subscription Trial Ended summary: A subscription's trial period ended. description: >- Sent when a subscription's trial period concludes. This event fires before the first billing charge occurs, allowing merchants to send advance notice to customers that billing is about to begin. contentType: application/x-www-form-urlencoded payload: $ref: '#/components/schemas/SubscriptionNotificationPayload' headers: $ref: '#/components/schemas/WebhookHeaders' SubscriptionBillingSkipped: name: subscription_billing_skipped title: Subscription Billing Skipped summary: A subscription billing cycle was skipped due to a zero or negative balance. description: >- Sent when a subscription's billing cycle is skipped because the customer has a credit balance from previous add-ons or discounts that covers the entire cost of the subscription for that cycle. contentType: application/x-www-form-urlencoded payload: $ref: '#/components/schemas/SubscriptionNotificationPayload' headers: $ref: '#/components/schemas/WebhookHeaders' TransactionSettled: name: transaction_settled title: Transaction Settled summary: A transaction settled successfully. description: >- Sent when an ACH or SEPA Direct Debit transaction completes settlement. This webhook fires after the funds have moved. Applicable specifically to ACH and SEPA Direct Debit sale and refund transactions where settlement is asynchronous. contentType: application/x-www-form-urlencoded payload: $ref: '#/components/schemas/TransactionNotificationPayload' headers: $ref: '#/components/schemas/WebhookHeaders' TransactionSettlementDeclined: name: transaction_settlement_declined title: Transaction Settlement Declined summary: Settlement for a transaction was declined. description: >- Sent when settlement is declined for an ACH or SEPA Direct Debit transaction. May also fire after a transaction_settled event if the customer's bank returns the funds after initial settlement. The original transaction status updates to settlement_declined. contentType: application/x-www-form-urlencoded payload: $ref: '#/components/schemas/TransactionNotificationPayload' headers: $ref: '#/components/schemas/WebhookHeaders' DisputeOpened: name: dispute_opened title: Dispute Opened summary: A new dispute was opened against a transaction. description: >- Sent when a cardholder or issuing bank initiates a chargeback or retrieval against one of the merchant's transactions. The notification includes the dispute object with the associated transaction, disputed amount, reason, and reply-by deadline. contentType: application/x-www-form-urlencoded payload: $ref: '#/components/schemas/DisputeNotificationPayload' headers: $ref: '#/components/schemas/WebhookHeaders' DisputeWon: name: dispute_won title: Dispute Won summary: A dispute was resolved in the merchant's favor. description: >- Sent when a dispute is resolved in the merchant's favor, meaning the funds are returned to the merchant. The dispute status transitions to Won. contentType: application/x-www-form-urlencoded payload: $ref: '#/components/schemas/DisputeNotificationPayload' headers: $ref: '#/components/schemas/WebhookHeaders' DisputeLost: name: dispute_lost title: Dispute Lost summary: A dispute was resolved in the cardholder's favor. description: >- Sent when a dispute is resolved in the cardholder's favor, meaning the merchant loses the disputed funds. The dispute status transitions to Lost. contentType: application/x-www-form-urlencoded payload: $ref: '#/components/schemas/DisputeNotificationPayload' headers: $ref: '#/components/schemas/WebhookHeaders' DisputeAccepted: name: dispute_accepted title: Dispute Accepted summary: A dispute was accepted by the merchant. description: >- Sent when a merchant explicitly accepts a dispute without contesting it. The dispute status transitions to Accepted and the funds are surrendered to the cardholder. contentType: application/x-www-form-urlencoded payload: $ref: '#/components/schemas/DisputeNotificationPayload' headers: $ref: '#/components/schemas/WebhookHeaders' DisputeAutoAccepted: name: dispute_auto_accepted title: Dispute Auto-Accepted summary: A dispute was automatically accepted after the reply deadline passed. description: >- Sent when a dispute is automatically accepted because the reply-by deadline passed without the merchant submitting a response or evidence. The dispute status transitions to Accepted. contentType: application/x-www-form-urlencoded payload: $ref: '#/components/schemas/DisputeNotificationPayload' headers: $ref: '#/components/schemas/WebhookHeaders' DisputeDisputed: name: dispute_disputed title: Dispute Disputed summary: Evidence was submitted and the dispute is under review. description: >- Sent when the merchant submits evidence to contest a dispute and the dispute transitions to the Disputed status, indicating it is being reviewed by the card network. contentType: application/x-www-form-urlencoded payload: $ref: '#/components/schemas/DisputeNotificationPayload' headers: $ref: '#/components/schemas/WebhookHeaders' DisputeExpired: name: dispute_expired title: Dispute Expired summary: A dispute expired without resolution. description: >- Sent when a dispute expires without being resolved or responded to within the allowed timeframe. The dispute status transitions to Expired. contentType: application/x-www-form-urlencoded payload: $ref: '#/components/schemas/DisputeNotificationPayload' headers: $ref: '#/components/schemas/WebhookHeaders' DisputeUnderReview: name: dispute_under_review title: Dispute Under Review summary: A dispute is under internal review with PayPal. description: >- Sent when a dispute enters an internal review state with PayPal. This status indicates Braintree or PayPal is actively investigating the dispute before it is presented to the card network. contentType: application/x-www-form-urlencoded payload: $ref: '#/components/schemas/DisputeNotificationPayload' headers: $ref: '#/components/schemas/WebhookHeaders' Disbursement: name: disbursement title: Disbursement summary: Funds were disbursed to the merchant's bank account. description: >- Sent once per merchant account per day when Braintree sends a disbursement to the merchant's bank account. Applicable only to Braintree-funded merchant accounts. The notification includes a disbursement object with the total amount and transaction count. contentType: application/x-www-form-urlencoded payload: $ref: '#/components/schemas/DisbursementNotificationPayload' headers: $ref: '#/components/schemas/WebhookHeaders' TransactionDisbursed: name: transaction_disbursed title: Transaction Disbursed summary: >- A transaction was marked for disbursement. Deprecated in favor of the Disbursement event. description: >- Deprecated. Sent when a transaction is marked for disbursement from Braintree's bank account to the merchant. This event type is superseded by the Disbursement event and is only sent for legacy Braintree-funded merchant accounts. contentType: application/x-www-form-urlencoded payload: $ref: '#/components/schemas/TransactionNotificationPayload' headers: $ref: '#/components/schemas/WebhookHeaders' SubMerchantAccountApproved: name: sub_merchant_account_approved title: Sub-Merchant Account Approved summary: A Braintree Marketplace sub-merchant account was approved. description: >- Sent when a sub-merchant account created through the Braintree Marketplace API completes underwriting review and is approved for payment processing. The notification includes the merchant account object for the approved sub-merchant. contentType: application/x-www-form-urlencoded payload: $ref: '#/components/schemas/MerchantAccountNotificationPayload' headers: $ref: '#/components/schemas/WebhookHeaders' SubMerchantAccountDeclined: name: sub_merchant_account_declined title: Sub-Merchant Account Declined summary: A Braintree Marketplace sub-merchant account application was declined. description: >- Sent when a sub-merchant account created through the Braintree Marketplace API is declined during underwriting review. The notification includes the merchant account object and the reason for the decline. contentType: application/x-www-form-urlencoded payload: $ref: '#/components/schemas/MerchantAccountNotificationPayload' headers: $ref: '#/components/schemas/WebhookHeaders' schemas: WebhookHeaders: type: object description: >- HTTP headers included in webhook POST requests from Braintree. properties: Content-Type: type: string description: Content type of the webhook request body. const: application/x-www-form-urlencoded WebhookFormPayload: type: object description: >- The form-encoded body of all Braintree webhook HTTP POST requests. Merchants use a Braintree server SDK to parse and verify the payload. required: - bt_signature - bt_payload properties: bt_signature: type: string description: >- HMAC-SHA1 signature of the bt_payload value, computed using the merchant's private API key. Must be verified before processing the payload. bt_payload: type: string description: >- Base64-encoded, signed XML document containing the webhook notification kind, timestamp, and associated Braintree object. WebhookNotification: type: object description: >- The parsed webhook notification object returned by the Braintree server SDK after verifying and decoding the bt_payload. required: - kind - timestamp properties: kind: type: string description: >- The event type that triggered this webhook notification. enum: - subscription_billing_skipped - subscription_canceled - subscription_charged_successfully - subscription_charged_unsuccessfully - subscription_expired - subscription_trial_ended - subscription_went_active - subscription_went_past_due - transaction_settled - transaction_settlement_declined - dispute_opened - dispute_won - dispute_lost - dispute_accepted - dispute_auto_accepted - dispute_disputed - dispute_expired - dispute_under_review - disbursement - transaction_disbursed - sub_merchant_account_approved - sub_merchant_account_declined timestamp: type: string format: date-time description: ISO 8601 timestamp of when the webhook event was triggered. SubscriptionNotificationPayload: allOf: - $ref: '#/components/schemas/WebhookFormPayload' description: >- Webhook payload for subscription lifecycle events. The parsed notification contains a subscription object with up to 20 recent associated transactions. TransactionNotificationPayload: allOf: - $ref: '#/components/schemas/WebhookFormPayload' description: >- Webhook payload for transaction settlement events. The parsed notification contains the full transaction object including current status, amounts, and settlement details. DisputeNotificationPayload: allOf: - $ref: '#/components/schemas/WebhookFormPayload' description: >- Webhook payload for dispute lifecycle events. The parsed notification contains the dispute object with the associated transaction, disputed amount, reason code, and current status. DisbursementNotificationPayload: allOf: - $ref: '#/components/schemas/WebhookFormPayload' description: >- Webhook payload for disbursement events. The parsed notification contains a disbursement object with the total amount disbursed and the list of associated transaction identifiers. MerchantAccountNotificationPayload: allOf: - $ref: '#/components/schemas/WebhookFormPayload' description: >- Webhook payload for sub-merchant account status events. The parsed notification contains the merchant account object for the sub-merchant including approval status and any decline reason.