Braintree

Log into the Braintree Control Panel. For sandbox testing, use sandbox.braintreegateway.com. For production, use www.braintreegateway.com. Navigate to Settings → API. You will find three credentials: - **Merchant ID**: Your account identifier (not secret, but useful to store) - **Public Key**: Used as the username in HTTP Basic Auth - **Private Key**: Used as the password in HTTP Basic Auth — treat this as a secret Write down all three from both sandbox and production environments. Sandbox credentials will ONLY work against the sandbox base URL (`payments.sandbox.braintreegateway.com`), and production credentials will ONLY work against the live base URL (`payments.braintreegateway.com`). Using either set against the wrong environment returns 401 errors. Braintree also has a useful GraphQL API Explorer in the Control Panel under Tools → GraphQL API Explorer. Before you set up Bubble's API Connector, spend a few minutes in this explorer running sample queries — it validates your query syntax and shows you exactly what the response structure looks like. This saves significant debugging time in Bubble.

1{
2  "sandbox": {
3    "base_url": "https://payments.sandbox.braintreegateway.com",
4    "graphql_endpoint": "/graphql",
5    "merchant_id": "your_sandbox_merchant_id",
6    "public_key": "your_sandbox_public_key",
7    "private_key": "your_sandbox_private_key"
8  },
9  "live": {
10    "base_url": "https://payments.braintreegateway.com",
11    "graphql_endpoint": "/graphql",
12    "merchant_id": "your_live_merchant_id",
13    "public_key": "your_live_public_key",
14    "private_key": "your_live_private_key"
15  }
16}

Go to Plugins tab → Add plugins → search 'API Connector' (by Bubble) → Install. Open API Connector settings. Click 'Add another API' and name it 'Braintree Sandbox'. Set the base URL to `https://payments.sandbox.braintreegateway.com`. In the Authentication section of the API group, select 'Basic auth'. Enter your Public Key in the Username field and your Private Key in the Password field. Check the 'Private' checkbox for both fields — this marks them as server-side only, ensuring they never appear in browser network requests. In Shared Headers, add three headers: 1. `Braintree-Version: 2019-01-01` — this is MANDATORY; missing it causes 400 or unexpected schema responses 2. `Content-Type: application/json` 3. `Accept: application/json` The `Braintree-Version` header pins you to a stable, well-documented API version. Pin to `2019-01-01` and update it intentionally when Braintree releases a new stable version — do not use `latest` or leave it out.

1{
2  "api_name": "Braintree Sandbox",
3  "base_url": "https://payments.sandbox.braintreegateway.com",
4  "authentication": {
5    "type": "basic_auth",
6    "username": "<private: your_public_key>",
7    "password": "<private: your_private_key>"
8  },
9  "shared_headers": {
10    "Braintree-Version": "2019-01-01",
11    "Content-Type": "application/json",
12    "Accept": "application/json"
13  }
14}

Inside the 'Braintree Sandbox' API group, click 'Add a call'. Name it 'Search Transactions'. Set the method to POST and the endpoint path to `/graphql`. In the body section, select JSON and enter the GraphQL query structure. All Braintree operations use this same format — only the `query` string and `variables` object change: ```json { "query": "query SearchTransactions($input: TransactionSearchInput!, $first: Int) { search { transactions(input: $input, first: $first) { edges { node { id legacyId amount { value currencyCode } status createdAt paymentMethodSnapshot { ... on CreditCardDetails { brandCode last4 } } } } pageInfo { hasNextPage endCursor } } } }", "variables": { "input": { "createdAt": { "greaterThanOrEqualTo": "2026-01-01T00:00:00Z", "lessThanOrEqualTo": "2026-12-31T23:59:59Z" } }, "first": 20 } } ``` Mark `input.createdAt.greaterThanOrEqualTo` and `input.createdAt.lessThanOrEqualTo` as dynamic so the Bubble workflow can filter by date range. Mark `first` as dynamic for pagination control. Click 'Initialize call'. Bubble will run the GraphQL query against your sandbox account. The successful response nests data under `data.search.transactions.edges[].node`. Bubble's type detector will infer the nested structure — verify it correctly identifies the `edges` array and the `node` fields (id, amount, status). Set 'Use as' to 'Data'.

1{
2  "query": "query SearchTransactions($input: TransactionSearchInput!, $first: Int) { search { transactions(input: $input, first: $first) { edges { node { id legacyId amount { value currencyCode } status createdAt paymentMethodSnapshot { ... on CreditCardDetails { brandCode last4 } } } } pageInfo { hasNextPage endCursor } } } }",
3  "variables": {
4    "input": {
5      "createdAt": {
6        "greaterThanOrEqualTo": "<dynamic: date_from>",
7        "lessThanOrEqualTo": "<dynamic: date_to>"
8      }
9    },
10    "first": "<dynamic: page_size>"
11  }
12}

Add a second call to the 'Braintree Sandbox' API group. Name it 'Refund Transaction'. Method: POST. Endpoint: `/graphql` (same as search — all operations share this path). The refund operation is a GraphQL mutation: ```json { "query": "mutation RefundTransaction($input: RefundTransactionInput!) { refundTransaction(input: $input) { refund { id legacyId amount { value currencyCode } status createdAt } } }", "variables": { "input": { "transactionId": "dHJhbnNhY3Rpb25fYWJjMTIz", "refund": { "amount": "19.99" } } } } ``` Mark `input.transactionId` and `input.refund.amount` as dynamic parameters. Enter test values (a real sandbox transaction ID and an amount) for initialization. In your Bubble page workflow, add the refund action with an 'Only when' condition: `Current cell's Transaction's status is 'SETTLED' or 'SETTLING'`. Braintree only allows refunds on SETTLED or SETTLING transactions — attempting a refund on AUTHORIZED or SUBMITTED_FOR_SETTLEMENT transactions returns a GraphQL error. Build a confirmation dialog before the refund step: use a Bubble Alert or a conditional popup that shows the transaction amount and asks 'Confirm refund of $X?' with a Confirm button triggering the actual refund workflow. This prevents accidental refunds. Set 'Use as' to 'Action'. For RapidDev's clients managing high-volume refund workflows in Bubble with Braintree, we've found that capturing the Braintree transaction `id` (the GraphQL global ID, not `legacyId`) in the Bubble database at transaction time makes mutation calls significantly simpler. Book a free scoping call at rapidevelopers.com/contact if you need help designing your Bubble payment database schema.

1{
2  "query": "mutation RefundTransaction($input: RefundTransactionInput!) { refundTransaction(input: $input) { refund { id legacyId amount { value currencyCode } status createdAt } } }",
3  "variables": {
4    "input": {
5      "transactionId": "<dynamic: transaction_global_id>",
6      "refund": {
7        "amount": "<dynamic: refund_amount_string>"
8      }
9    }
10  }
11}

Braintree's Drop-in UI is a pre-built payment form (rendered by Braintree's JavaScript SDK) that supports cards, PayPal, and Venmo in a single embedded interface. In Bubble, you embed it via an HTML element. Add an HTML element to your Bubble checkout page. In the HTML element editor, paste: ```html <div id="dropin-container"></div> <script src="https://js.braintreegateway.com/web/dropin/1.43.0/js/dropin.min.js"></script> <script> braintree.dropin.create({ authorization: 'YOUR_CLIENT_AUTHORIZATION_TOKEN', container: '#dropin-container', paypal: { flow: 'checkout', amount: '19.99', currency: 'USD' }, venmo: {} }, function(createErr, instance) { if (createErr) { console.log('Drop-in error:', createErr); return; } window.braintreeInstance = instance; }); function submitPayment() { braintreeInstance.requestPaymentMethod(function(err, payload) { if (err) { console.log('Payment method error:', err); return; } bubble_fn_nonce(payload.nonce); }); } </script> ``` The `authorization` value is a Braintree Client Authorization Token — generate one via a separate API Connector call to Braintree's `createClientToken` GraphQL mutation, store it in a page custom state, and pass it to the HTML element via a Bubble dynamic data binding or the Toolbox plugin's 'Set state from JS' mechanism. The `bubble_fn_nonce` function (from the Toolbox plugin) sends the payment method nonce back to Bubble, where a workflow step can receive it and use it in a `chargePaymentMethod` GraphQL mutation to complete the payment. Note: The Drop-in UI only works in the published version of your Bubble app — it may behave differently or not load in Bubble's preview/test mode due to domain restrictions.

1<!-- Bubble HTML element for Braintree Drop-in UI -->
2<div id="dropin-container"></div>
3<script src="https://js.braintreegateway.com/web/dropin/1.43.0/js/dropin.min.js"></script>
4<script>
5  // 'authorization' is a Client Authorization Token from a Bubble custom state
6  // Replace YOUR_CLIENT_TOKEN with a Bubble dynamic expression or use Toolbox to inject it
7  braintree.dropin.create({
8    authorization: 'YOUR_CLIENT_TOKEN',
9    container: '#dropin-container',
10    paypal: {
11      flow: 'checkout',
12      amount: '19.99',
13      currency: 'USD'
14    },
15    venmo: {}
16  }, function(createErr, instance) {
17    if (createErr) { console.error('Drop-in error:', createErr); return; }
18    window.braintreeInstance = instance;
19  });
20
21  // Call this from a Bubble workflow via Toolbox plugin's Run JavaScript action
22  function submitPayment() {
23    if (!window.braintreeInstance) { return; }
24    braintreeInstance.requestPaymentMethod(function(err, payload) {
25      if (err) { console.error('Payment error:', err); return; }
26      // Send nonce back to Bubble via Toolbox plugin
27      bubble_fn_nonce(payload.nonce);
28    });
29  }
30</script>

Braintree sends webhook notifications for subscription events (subscription charged, subscription expired), dispute events (opened, won, lost), and payment lifecycle events. Setting up a Backend Workflow to receive them requires a paid Bubble plan. Braintree webhooks use a non-standard format: the payload is Base64-encoded XML, not JSON. This makes parsing in a Bubble Backend Workflow more complex than typical JSON webhooks. For simpler setups at early stage, consider polling instead of webhooks: use a 'Recurring event' Backend Workflow (paid plan) that runs every hour, calls Braintree's GraphQL to fetch recent transactions with status SUBMITTED_FOR_SETTLEMENT, and updates Bubble DB records accordingly. If you do need webhook support: 1. Settings → API → check 'This app exposes a Workflow API'. 2. Backend Workflows → new workflow named `braintree_webhook`. 3. Register the URL in Braintree Control Panel → Settings → Webhooks: `https://yourapp.bubbleapps.io/api/1.1/wf/braintree_webhook`. 4. The webhook body contains a Base64-encoded XML string in the `bt_payload` parameter. Decoding and parsing XML in Bubble requires a Custom Action using `atob()` and an XML parser in JavaScript — use the Toolbox plugin for this. 5. After decoding, extract the `kind` field (event type) and `subject` fields to determine what action to take. To go live: - Add a second API Connector group named 'Braintree Live' with base URL `https://payments.braintreegateway.com`, your live Public Key and Private Key in Basic Auth. Never mix sandbox and live keys in the same API Connector group.

1// Braintree webhook payload structure
2// Content-Type: application/x-www-form-urlencoded
3// Fields:
4//   bt_signature: webhook signature for verification
5//   bt_payload: Base64-encoded XML string
6
7// After decoding bt_payload with atob():
8// <notification>
9//   <kind>subscription_charged_successfully</kind>
10//   <timestamp>2026-01-15T12:00:00Z</timestamp>
11//   <subject>
12//     <subscription>
13//       <id>sub_abc123</id>
14//       <plan-id>monthly_pro</plan-id>
15//       <status>Active</status>
16//       <next-billing-date>2026-02-15</next-billing-date>
17//       <transactions>
18//         <transaction>
19//           <id>txn_xyz789</id>
20//           <amount>29.99</amount>
21//           <status>settled</status>
22//         </transaction>
23//       </transactions>
24//     </subscription>
25//   </subject>
26// </notification>
27
28// Webhook kinds (common):
29// subscription_charged_successfully
30// subscription_charged_unsuccessfully
31// subscription_expired
32// dispute_opened
33// dispute_won
34// dispute_lost
35// check (sent as verification when webhook is first registered)