Braintree Integration

Braintree by PayPal provides a full-stack payment platform popular with marketplace and subscription businesses. LostChurn connects to Braintree using API credentials and processes failed payment webhooks to automate recovery.

Prerequisites

• An active Braintree account (sandbox or production)
• Access to the Braintree Control Panel with admin permissions
• Your Braintree Merchant ID, Public Key, and Private Key for the environment you want to connect
• A LostChurn account with at least one workspace created

Connection Steps

Braintree uses separate credentials for sandbox and production environments. Follow the steps below for whichever environment you want to connect first. You can connect both environments simultaneously.

Sandbox Credentials

1. Log in to the Braintree Sandbox Control Panel.
2. Navigate to Settings > API (under the gear icon in the top-right corner).
3. Under API Keys, you will see your Merchant ID at the top. Below it, find or generate a key pair. Click View on an existing key pair to reveal the Public Key and Private Key.
4. In your LostChurn dashboard, go to Settings > Integrations and click Connect Braintree.
5. Select Sandbox as the environment.
6. Enter your Merchant ID, Public Key, and Private Key.
7. Click Save and Verify. LostChurn makes a test API call to confirm the credentials are valid.

Production Credentials

1. Log in to the Braintree Production Control Panel.
2. Navigate to Settings > API.
3. Copy your Merchant ID, Public Key, and Private Key as described above.
4. In your LostChurn dashboard, go to Settings > Integrations > Braintree and click Add Production Credentials.
5. Select Production as the environment.
6. Enter your credentials and click Save and Verify.

Multiple Merchant Accounts

If you operate multiple Braintree merchant accounts (for example, one per currency or region), you can connect each one separately. In your LostChurn dashboard, click Add Another Braintree Account and repeat the steps above for each merchant account. All accounts appear under a unified view in the Events feed.

Webhook Configuration

Braintree webhooks require configuration in the Braintree Control Panel.

1. In the Braintree Control Panel, go to Settings > Webhooks.
2. Click Create New Webhook.
3. Set the Destination URL to:

   https://webhooks.lostchurn.com/v1/braintree

4. Under Notifications, select the following webhook types:
   • Subscription Charged Unsuccessfully
   • Subscription Charged Successfully
   • Subscription Canceled
   • Subscription Expired
   • Subscription Went Active
   • Subscription Went Past Due
   • Transaction Settled
   • Transaction Settlement Declined
   • Disbursement Exception
   • Dispute Opened
   • Dispute Won
   • Dispute Lost
   • Payment Method Revoked
5. Click Create Webhook.
6. Braintree displays the webhook details page.

Webhook Signature Verification

Braintree signs webhook payloads using HMAC-SHA1. Each webhook is delivered as a form-encoded POST with two parameters:

• bt_signature: A string in the format public_key|signature, where public_key is your Braintree public key and signature is the HMAC-SHA1 hex digest.
• bt_payload: A base64-encoded XML notification body.

LostChurn verifies every incoming webhook by:

1. Confirming the public_key portion of bt_signature matches your configured Braintree Public Key.
2. Validating that bt_payload decodes to valid XML.
3. Computing HMAC-SHA1 of bt_payload using your Braintree Private Key and comparing the result against the provided signature (timing-safe comparison).

To configure verification, ensure your Braintree Public Key and Private Key are entered in the LostChurn Braintree integration settings. Without these keys, webhook delivery will be rejected.

Verify Connection

1. In the Braintree Control Panel, go to Settings > Webhooks and click Check next to the LostChurn webhook URL. Braintree sends a verification request and reports whether the endpoint responded correctly.
2. To send a live test event, create a test transaction in your Braintree sandbox using one of Braintree's test card numbers:
   • Use card number 4000111111111115 to simulate a declined transaction.
   • Use card number 4111111111111111 with amount 2000.00 to simulate a processor decline.
3. In your LostChurn dashboard, navigate to Events and confirm that the declined transaction event appears within a few seconds.

A successful connection shows a green Connected badge on the Braintree card in Settings > Integrations.

Supported Events

Provider-Specific Notes

Sandbox vs. Production

Braintree maintains completely separate sandbox and production environments with different URLs and credentials:

• Sandbox (sandbox.braintreegateway.com): Test transactions use simulated processor responses. No real charges occur. LostChurn labels all sandbox events with a sandbox badge.
• Production (www.braintreegateway.com): Real transactions with real payment methods.

Always test your recovery configuration in sandbox before enabling it in production.

Processor Response Codes

Braintree provides detailed processor response codes that LostChurn maps to its internal decline taxonomy. Common codes include:

• 2000 — Do Not Honor
• 2001 — Insufficient Funds
• 2003 — Card holder's Activity Limit Exceeded
• 2010 — Card Not Activated
• 2046 — Declined
• 2057 — Issuer or Cardholder has restricted the card
• 3000 — Processor Network Unavailable

LostChurn uses these codes to determine the optimal retry strategy. For example, a 2001 (Insufficient Funds) triggers a delayed retry, while a 2057 (Restricted Card) triggers a dunning email asking the customer to update their payment method.

Braintree Vault

If you use the Braintree Vault to store customer payment methods, LostChurn can access vaulted payment method metadata (type, last four digits, expiration) to personalize dunning emails. No sensitive card data is ever transmitted or stored by LostChurn.

Rate Limits

Braintree does not publish fixed rate limits but recommends keeping API requests under 50 per second for most merchant accounts. LostChurn throttles retry attempts to stay well within this threshold. If you have a high-volume Braintree account with custom rate limits, contact LostChurn support to adjust your throughput settings.

PayPal Transactions via Braintree

If you process PayPal transactions through Braintree, LostChurn processes the associated webhook events. PayPal-specific decline reasons (such as insufficient PayPal balance or pending bank transfers) are mapped to LostChurn's decline taxonomy and handled with PayPal-appropriate retry and dunning strategies.

Subscription Add-Ons and Discounts

LostChurn captures add-on and discount amounts attached to Braintree subscriptions so that recovery metrics accurately reflect the full subscription value, not just the base price.