How to Integrate Retool with Stripe

Creating a restricted API key before connecting Retool is the most important security step. Navigate to the Stripe Dashboard (dashboard.stripe.com) and go to Developers → API keys. Click Create restricted key and name it 'Retool Admin Panel' or similar. Configure permissions based on what your dashboard will do: For a read-only revenue dashboard: - Customers: Read - Charges: Read - Subscriptions: Read - Invoices: Read For a billing support tool with refund capability: - All of the above, plus: - Refunds: Write For subscription management: - All of the above, plus: - Subscriptions: Write Avoid giving Write access to anything you don't actively need — a refund dashboard doesn't need the ability to create charges or modify products. Copy the generated key (it's only shown once). Open Retool and go to the Resources tab. Click Add Resource, search for Stripe, and click it. In the configuration form: - Name: 'Stripe Production' or 'Stripe Test' to make the environment clear - API Key: paste your restricted key - Environment: the UI label is cosmetic only — the actual environment (test vs. live) is determined by whether your key starts with sk_test or sk_live Click Save Changes. Create a second resource for the other environment (test key if you set up live first, or vice versa) so you can test safely.

Create a new query in your Retool app and select the Stripe resource. Set Action Type to List Customers. Configure the query parameters: - Limit: 25 (start small; increase with pagination) - Email: {{ customerSearchInput.value }} — wire to a Text Input component on the canvas so agents can search by email address Set the query to Run this query automatically when inputs change so the table updates as the agent types. Add a delay (150ms debounce) in the query's Advanced settings to avoid firing on every keystroke. Add a Transformer to the query to reshape the Stripe response into a clean table format. Create a second query: set Action Type to List Charges and add a Customer parameter set to {{ customersQuery.selectedRow?.id }} — this scopes charges to the currently selected customer. Set the charges query to Run this query automatically when inputs change, so it fires when a customer row is selected. Add a condition in the query's Advanced settings: Only run when {{ customersQuery.selectedRow?.id !== undefined }}. Drag two Table components onto the canvas: the top table shows customers (bound to {{ customersQuery.data }}), and the bottom table shows charges for the selected customer (bound to {{ chargesQuery.data }}). Set the top table to Row select mode: single, so clicking a row selects a customer and triggers the charges query.

1// JavaScript transformer for Stripe charges query
2// Reshapes raw Stripe charge objects into display-ready rows
3const charges = data; // raw array of Stripe charge objects
4return charges.map(charge => ({
5  id: charge.id,
6  amount: '$' + (charge.amount / 100).toFixed(2),
7  currency: charge.currency.toUpperCase(),
8  status: charge.status,
9  description: charge.description || 'No description',
10  receipt_email: charge.receipt_email || '',
11  payment_method: charge.payment_method_details?.type || '',
12  card_last4: charge.payment_method_details?.card?.last4 || '',
13  created: new Date(charge.created * 1000).toLocaleString(),
14  refunded: charge.refunded ? 'Yes' : 'No',
15  refund_amount: charge.amount_refunded > 0
16    ? '$' + (charge.amount_refunded / 100).toFixed(2)
17    : ''
18}));

Refund functionality is the most common write operation in Stripe admin panels. The key is to make it easy but not accidental — a refund button with a confirmation dialog and post-refund audit logging strikes the right balance. Create a new query with Action Type: Create Refund. Configure: - Charge: {{ chargesTable.selectedRow.id }} — the Stripe charge ID from the selected charges table row - Amount: {{ refundAmountInput.value * 100 }} — convert dollars to cents; leave blank for full refund - Reason: {{ refundReasonSelect.value }} — map to a Select component with options: 'duplicate', 'fraudulent', 'requested_by_customer' Set this query to Manual trigger. Add event handlers: On Success → trigger an audit log query (insert a row into your database's refunds_log table), then trigger chargesQuery to refresh the charges table, then show a notification 'Refund issued successfully'. Drag the needed components onto the canvas: a Number Input for refund amount (label: 'Refund amount ($ — leave blank for full refund)'), a Select component for refund reason, and a Button labeled 'Issue Refund'. Wire the button to trigger the refund query with Confirm before running enabled. For the audit log query, configure an INSERT statement targeting your database with the agent's name, the charge ID, the refund amount, the reason, and a timestamp. The On Success chain ensures this runs every time a refund is issued.

1-- Audit log INSERT query — runs after every successful refund
2-- Configure this as a separate database query triggered on refund success
3INSERT INTO refunds_log (
4  agent_name,
5  charge_id,
6  refund_amount_cents,
7  refund_reason,
8  customer_email,
9  created_at
10) VALUES (
11  {{ retoolContext.currentUser.email }},
12  {{ chargesTable.selectedRow.id }},
13  {{ refundAmountInput.value
14     ? Math.round(refundAmountInput.value * 100)
15     : chargesTable.selectedRow.amount_cents }},
16  {{ refundReasonSelect.value }},
17  {{ customersQuery.selectedRow.email }},
18  NOW()
19);

Customer subscriptions are a critical part of Stripe for SaaS businesses. Build a subscriptions panel that lets your team view, modify, and cancel subscriptions for any customer. Create a query with Action Type: List Subscriptions and Customer parameter: {{ customersQuery.selectedRow?.id }}. Set to auto-run when the selected customer changes with an 'only run when a customer is selected' condition. Add a transformer to extract the most operationally relevant fields from each subscription object: plan name, status, billing period, next invoice date, and current amount. For subscription cancellation, create a Cancel Subscription query with Action Type: Cancel Subscription and Subscription ID: {{ subscriptionsTable.selectedRow.id }}. Add a parameter for cancel_at_period_end: true (cancels at the end of the billing period rather than immediately — usually the right choice for customer experience). For plan changes (upgrades/downgrades), create an Update Subscription query. The key parameter is items — an array of objects with the price ID to change to. Create a Select component with your Stripe price IDs loaded from a List Prices query, and reference the selected value in the Update Subscription query's items parameter. Add a subscriptions Table component bound to {{ subscriptionsQuery.data }}. Below it, add a subscription actions panel with: a plan change Select, an Update Plan button wired to the update query, and a Cancel Subscription button wired to the cancel query. Both buttons should have confirmation dialogs with clear descriptions of what will happen.

1// JavaScript transformer for Stripe subscriptions response
2const subs = data;
3return subs.map(sub => ({
4  id: sub.id,
5  status: sub.status,
6  plan_name: sub.items?.data?.[0]?.price?.nickname
7    || sub.items?.data?.[0]?.price?.id
8    || 'Unknown Plan',
9  amount: '$' + ((sub.items?.data?.[0]?.price?.unit_amount || 0) / 100).toFixed(2)
10    + '/' + (sub.items?.data?.[0]?.price?.recurring?.interval || ''),
11  current_period_end: sub.current_period_end
12    ? new Date(sub.current_period_end * 1000).toLocaleDateString()
13    : '',
14  cancel_at_period_end: sub.cancel_at_period_end ? 'Cancels at period end' : 'Active',
15  trial_end: sub.trial_end
16    ? new Date(sub.trial_end * 1000).toLocaleDateString()
17    : 'No trial',
18  created: new Date(sub.created * 1000).toLocaleDateString()
19}));

Retool includes a dedicated Stripe Card Form component that renders Stripe's official payment element UI inside your Retool app — allowing you to securely collect payment information without handling raw card numbers. This component uses Stripe.js under the hood, ensuring PCI DSS compliance. In the Component panel, search for 'Stripe Card Form' or find it under the Payments section. Drag it onto the canvas. In the component's Inspector: - Stripe publishable key: enter your Stripe publishable key (pk_test_... or pk_live_...). Note: this is the publishable key, not the secret key — it is safe to embed in the frontend. - Payment Intent client secret: this must come from a server-side query that creates a PaymentIntent first Create a query using Action Type: Create Payment Intent. Configure: - Amount: {{ amountInput.value * 100 }} — the charge amount in cents - Currency: 'usd' (or appropriate currency code) - Automatic payment methods: enabled: true Set this query to run when the user enters an amount and clicks 'Prepare Payment'. Wire the Card Form's Payment Intent client secret to {{ createPaymentIntentQuery.data.client_secret }}. Create a 'Confirm Payment' button that calls the Card Form component's built-in confirmPayment() method via a JavaScript query: retoolStoreCardForm.confirmPayment(). Handle the result with On Success and On Failure event handlers to show appropriate feedback. This pattern — creating the PaymentIntent server-side through Retool's proxy, then confirming it client-side via the Card Form — matches Stripe's recommended integration approach and maintains security throughout.

1// JavaScript query to confirm payment via the Stripe Card Form component
2// Wire this to a 'Confirm Payment' button's event handler
3try {
4  const result = await stripeCardForm.confirmPayment({
5    return_url: window.location.href // redirect URL after 3DS authentication
6  });
7  
8  if (result.error) {
9    // Show error notification to user
10    showNotification({
11      title: 'Payment failed',
12      description: result.error.message,
13      notificationType: 'error'
14    });
15  } else if (result.paymentIntent.status === 'succeeded') {
16    // Trigger success flow
17    refreshChargesQuery.trigger();
18    showNotification({
19      title: 'Payment successful',
20      description: 'Charge ID: ' + result.paymentIntent.id,
21      notificationType: 'success'
22    });
23  }
24} catch (err) {
25  console.error('Payment confirmation error:', err);
26}