How to Integrate Retool with Braintree

Braintree uses a three-part credential system: Merchant ID (identifies your account), Public Key (username for API authentication), and Private Key (password for API authentication). Navigate to the Braintree Control Panel (sandbox.braintreegateway.com for sandbox, www.braintreegateway.com for production). Go to Settings → API → API Keys. You'll see your Merchant ID displayed at the top. Click Generate New API Key if you haven't already, or use an existing key. The table shows your Public Keys — click 'View' next to a public key to see the corresponding Private Key. Copy both the Public Key (visible) and Private Key (the associated secret). Also note your Merchant ID for use in API request headers. Open Retool → Resources tab → Add Resource → REST API: - Name: 'Braintree API' - Base URL: https://payments.sandbox.braintreegateway.com (for sandbox) or https://payments.braintreegateway.com (for production) - Authentication: Basic Auth - Username: your Braintree Public Key - Password: your Braintree Private Key Add default headers: - Braintree-Version: 2019-01-01 (for GraphQL API version pinning) - Content-Type: application/json - Accept: application/json Store your Merchant ID as a Retool configuration variable (Settings → Configuration Variables → BRAINTREE_MERCHANT_ID) since it's needed in request paths and query variables. Store Public Key and Private Key as additional configuration variables referenced in the resource's Basic Auth fields. Click Save Changes and Test Connection.

Braintree's GraphQL API endpoint is at /graphql — all GraphQL queries are POST requests to this single endpoint with the query in the request body. This is Braintree's preferred modern API. Create a transaction search query in your Retool app: - Method: POST - Path: /graphql - Body type: JSON - Body: ```json { "query": "query SearchTransactions($input: TransactionSearchInput!) { search { transactions(input: $input) { edges { node { id amount { value currencyIsoCode } status createdAt merchantAccountId customer { email } paymentMethodSnapshot { ... on CreditCardDetails { brandCode last4 expirationMonth expirationYear } ... on PayPalTransactionDetails { payerEmail } } } } } } }", "variables": { "input": { "status": { "in": ["SETTLED", "SUBMITTED_FOR_SETTLEMENT", "AUTHORIZED"] }, "createdAt": { "greaterThanOrEqualTo": "{{ dateRange.start || new Date(Date.now() - 30*24*60*60*1000).toISOString() }}", "lessThanOrEqualTo": "{{ dateRange.end || new Date().toISOString() }}" } } } } ``` The GraphQL response wraps results in data.search.transactions.edges where each item has a node property containing the transaction fields. Add a JavaScript transformer to flatten the edges into clean table rows. For customer email filtering, add a customerDetails search condition to the variables input when the email filter has a value.

1// Transformer for Braintree GraphQL transaction search response
2// data.search.transactions.edges is the array of { node: transaction } objects
3const edges = data?.search?.transactions?.edges || [];
4return edges.map(edge => {
5  const tx = edge.node;
6  const paymentSnapshot = tx.paymentMethodSnapshot || {};
7  let paymentMethod = 'Unknown';
8  let paymentDetail = '';
9  if (paymentSnapshot.brandCode) {
10    paymentMethod = paymentSnapshot.brandCode;
11    paymentDetail = `...${paymentSnapshot.last4 || ''}`;
12  } else if (paymentSnapshot.payerEmail) {
13    paymentMethod = 'PayPal';
14    paymentDetail = paymentSnapshot.payerEmail;
15  }
16  return {
17    id: tx.id,
18    amount: tx.amount ? `${tx.amount.value} ${tx.amount.currencyIsoCode}` : '',
19    amount_numeric: parseFloat(tx.amount?.value || 0),
20    status: tx.status || '',
21    customer_email: tx.customer?.email || '',
22    payment_method: paymentMethod,
23    payment_detail: paymentDetail,
24    merchant_account: tx.merchantAccountId || '',
25    created_at: tx.createdAt
26      ? new Date(tx.createdAt).toLocaleString()
27      : ''
28  };
29});

When an agent selects a transaction row, load a full detail panel with additional transaction metadata. Create a transaction detail query: - Method: POST - Path: /graphql - Body with a transaction(id: "...") query that fetches extended fields: - billing address, shipping address - risk data (fraudFiltered, decisionReasonCodes) - status history (for tracking authorization → settlement flow) - processor response code and text - refundedTransactionId (if this was a refund) For refund processing, create a refund mutation query: - Method: POST - Path: /graphql - Body: ```json { "query": "mutation RefundTransaction($input: RefundTransactionInput!) { refundTransaction(input: $input) { refund { id amount { value } status } } }", "variables": { "input": { "transactionId": "{{ transactionsTable.selectedRow.id }}", "amount": "{{ refundAmountInput.value || transactionsTable.selectedRow.amount_numeric }}" } } } ``` Set the refund query to Manual trigger. Add event handlers: On Success → refresh the transactions query, show a notification 'Refund issued: {{ refundQuery.data.refundTransaction.refund.id }}', and log the refund to an internal audit_log table with the agent email, transaction ID, refund amount, and timestamp. Drag a Number Input component for refund amount (default value: {{ transactionsTable.selectedRow.amount_numeric }}) and a Button with Confirm before running enabled. Display refund details in a success notification.

1// GraphQL mutation body for Braintree refund — use as JSON body
2// Configured as a JavaScript expression in the query body field
3{
4  "query": "mutation RefundTransaction($input: RefundTransactionInput!) { refundTransaction(input: $input) { refund { id amount { value currencyIsoCode } status createdAt } } }",
5  "variables": {
6    "input": {
7      "transactionId": "{{ transactionsTable.selectedRow.id }}",
8      "amount": "{{ refundAmountInput.value ? String(refundAmountInput.value) : undefined }}"
9    }
10  }
11}

Create a dispute search query using Braintree's GraphQL API: - Method: POST - Path: /graphql - Body with disputes search query filtering by status (OPEN, WON, LOST, EXPIRED) and sorting by receivedDate The disputes response includes: id, amount, reason, status, receivedDate, replyByDate, transaction.id, and merchantAccountId. Create a transformer that calculates days remaining until reply deadline. For customer search, use Braintree's legacy REST API (the GraphQL customers API is limited): - Method: POST - Path: /merchants/{{ retoolContext.configVars.BRAINTREE_MERCHANT_ID }}/customers/advanced_search_ids - Body: XML-formatted search criteria (Braintree's search uses XML even for JSON REST endpoints) Alternatively, use the GraphQL customer search: ```json { "query": "{ search { customers(input: { email: { is: \"{{ customerEmailInput.value }}\" } }) { edges { node { id firstName lastName email createdAt defaultPaymentMethod { id usage } } } } } }" } ``` Create two additional tabs: 1. Disputes tab — dispute table sorted by reply-by date with urgency color coding 2. Customers tab — customer search by email with vaulted payment methods and transaction history For complex Braintree integrations involving custom merchant accounts, subscription management, and multi-currency dispute workflows, RapidDev's team can help architect and build your Retool solution.

1// Transformer for Braintree GraphQL disputes response
2// Calculates days remaining and formats dispute data for the table
3const edges = data?.search?.disputes?.edges || [];
4return edges.map(edge => {
5  const dispute = edge.node;
6  const replyBy = dispute.replyByDate ? new Date(dispute.replyByDate) : null;
7  const today = new Date();
8  const daysRemaining = replyBy
9    ? Math.ceil((replyBy - today) / (1000 * 60 * 60 * 24))
10    : null;
11  let urgency = 'normal';
12  if (daysRemaining !== null) {
13    if (daysRemaining <= 3) urgency = 'critical';
14    else if (daysRemaining <= 7) urgency = 'warning';
15    else urgency = 'ok';
16  }
17  return {
18    id: dispute.id,
19    amount: dispute.amountDisputed
20      ? `${parseFloat(dispute.amountDisputed).toFixed(2)} ${dispute.currencyIsoCode || 'USD'}`
21      : '',
22    reason: dispute.reason || '',
23    status: dispute.status || '',
24    received_date: dispute.receivedDate
25      ? new Date(dispute.receivedDate).toLocaleDateString()
26      : '',
27    reply_by_date: replyBy ? replyBy.toLocaleDateString() : '',
28    days_remaining: daysRemaining !== null ? daysRemaining : 'N/A',
29    urgency,
30    transaction_id: dispute.transaction?.id || '',
31    merchant_account: dispute.merchantAccountId || ''
32  };
33});

Braintree's subscription management allows viewing and modifying recurring billing plans. Create a subscription search query: - Method: POST - Path: /graphql - Body with subscription GraphQL query filtering by status (ACTIVE, PAST_DUE, CANCELED) and customer ID from the customer search panel The subscription response includes: id, planId, status, price, currentBillingCycle, numberOfBillingCycles, nextBillingDate, and paymentMethodToken. Create a daily summary view at the top of the dashboard using Statistics components: - Total settled amount today: sum of amount_numeric from transactions query filtered to today's date and SETTLED status - Transaction count today: count of today's transactions - Open disputes: count from disputes query filtered to OPEN status - Refunds issued today: count of REFUNDED transactions created today For cancelling a subscription (operations teams sometimes need this for churned customers): - Method: POST - Path: /graphql - Body: cancelSubscription mutation with the subscription ID from the selected row Add retry functionality for past-due subscriptions: - Method: POST - Path: /graphql - Body: retrySubscriptionCharging mutation targeting the past-due subscription Arrange the complete dashboard with a header metrics row and four tabs: Transactions, Disputes, Customers, and Subscriptions.

1// Daily summary transformer — computes today's metrics from transactions data
2// Input: transactionsQuery.data (array of formatted transaction rows)
3const allTx = transactionsQuery.data || [];
4const today = new Date().toLocaleDateString();
5const todayTx = allTx.filter(tx => tx.created_at && tx.created_at.includes(today));
6const settledToday = todayTx.filter(tx => tx.status === 'SETTLED');
7const refundedToday = todayTx.filter(tx => tx.status === 'REFUNDED');
8const totalSettledAmount = settledToday.reduce((sum, tx) => sum + (tx.amount_numeric || 0), 0);
9return {
10  transaction_count: todayTx.length,
11  settled_count: settledToday.length,
12  settled_amount: '$' + totalSettledAmount.toFixed(2),
13  refunds_today: refundedToday.length,
14  refund_amount: '$' + refundedToday.reduce((sum, tx) => sum + (tx.amount_numeric || 0), 0).toFixed(2)
15};