Skip to main content

Connect to Stripe

Learn how to connect to Stripe and manage payments, customers, and subscriptions in Retool.

Stripe is a payment processing platform for online businesses. Connect Stripe to Retool to build payment dashboards, subscription management tools, and customer support interfaces.

What you can do with Stripe​

  • Manage payments: View, refund, and track payment transactions across your Stripe account.
  • Handle customers: Create, update, and manage customer records with payment methods and subscription data.
  • Manage subscriptions: Create, update, cancel, and track recurring subscription billing.
  • Process refunds: Issue full or partial refunds for charges with automatic reconciliation.
  • View analytics: Access payment data, revenue metrics, and customer insights from Stripe's API.

Before you begin​

To connect Stripe to Retool, you need the following:

  • Stripe API key: Secret API key from your Stripe account dashboard. Use test mode keys for development and live mode keys for production.
  • Retool permissions: Edit all permissions for resources in your organization.

Create a Stripe resource​

Follow these steps to create a Stripe resource in Retool.

1. Create a new resource​

In your Retool organization, navigate to Resources in the main navigation and click Create new → Resource. Search for Stripe and click the Stripe tile to begin configuration.

2. Configure connection settings​

Configure the following connection settings for your Stripe resource.

Resource name and description​

Specify a name for the resource that indicates which Stripe account it connects to. Include a description that can provide more context to users and Assist about how to use the resource.

Example NameExample Description
StripeStripe account for processing payments and managing subscriptions.
Stripe PaymentsStripe resource for payment processing and customer management.

3. Configure authentication​

Stripe uses API key authentication. Provide your Stripe secret API key to authenticate requests.

API Key​

Provide your Stripe secret API key. Get your API key from the Stripe Dashboard.

Example
{{ retoolContext.environment.stripeSecretKey }}

Store Stripe API keys in configuration variables or rather than hardcoding them in the resource configuration.

Stripe provides separate API keys for test mode and live mode. Test mode keys begin with sk_test_ and live mode keys begin with sk_live_. Always use test mode keys during development.

4. Test the connection​

Click Test connection to verify Retool can connect to your Stripe account. A successful test confirms the API key is valid and has the necessary permissions.

If the connection test fails, verify:

  • API key is correct and hasn't been revoked
  • API key has the necessary permissions for the operations you plan to perform
  • You're using the correct test or live mode key for your environment

5. Save the resource​

Click Create resource to save your Stripe resource. The resource is now available to use in apps, workflows, and agent tools across your Retool organization.

Query Stripe data​

Once you've created a Stripe resource, you can query it in apps, workflows, and agent tools.

Create a query​

You can create a Stripe query in a Retool app using Assist to generate queries with natural language, or manually using code.

Use Assist to generate queries from natural language prompts. Assist can create queries to retrieve and manipulate data from your Stripe resource.

To create a query with Assist:

  1. In the Retool app IDE, click the Assist button at the bottom of the left toolbar to open the Assist panel (if not already visible).
  2. Write a prompt describing the data you want to retrieve, referencing your resource using @.
  3. Press Enter to submit the prompt.
  4. Select your Stripe resource when prompted.
  5. Review the generated query and click Run query to add it to your app.
Example prompt
list all active subscriptions using @Stripe

Stripe operations​

Stripe queries provide access to common Stripe API operations organized by resource type.

Operation categoryAvailable operations
ChargesList charges, retrieve charge, create charge, refund charge
CustomersList customers, retrieve customer, create customer, update customer, delete customer
SubscriptionsList subscriptions, retrieve subscription, create subscription, update subscription, cancel subscription
ProductsList products, retrieve product, create product, update product, delete product
PricesList prices, retrieve price, create price, update price
Payment MethodsList payment methods, retrieve payment method, attach payment method, detach payment method
InvoicesList invoices, retrieve invoice, create invoice, finalize invoice, pay invoice
RefundsList refunds, create refund
BalanceRetrieve balance, retrieve balance transaction

Query configuration​

Each Stripe operation has specific parameters. Common parameters include:

  • Object ID: Identifier for the Stripe object (customer ID, subscription ID, etc.)
  • Filters: Limit results by date, status, or other criteria
  • Pagination: Control result limits and pagination cursors
  • Expand: Include related objects in the response

Common use cases​

The following examples demonstrate typical Stripe operations in Retool apps.

list and display recent payments

First, create a Stripe query to list recent charges.

Configure the query:

  • Operation: List charges
  • Limit: 100
  • Filter: Order by created descending

Next, add a Table component to the app and set its Data property to {{ listChargesQuery.data }}.

Format the table columns:

  • Amount: Use currency formatter with {{ item.amount / 100 }} (Stripe amounts are in cents)
  • Status: Use status badge formatter to highlight paid, failed, or refunded charges
  • Created: Use timestamp formatter for the created field
create a new customer

First, add a Form component (form1) with input fields for customer data (name, email, description).

Next, create a Stripe query to create a customer.

Configure the query:

  • Operation: Create customer
  • Parameters:
Example parameters
{
  "name": {{ form1.data.name }},
  "email": {{ form1.data.email }},
  "description": {{ form1.data.description }},
  "metadata": {
    "created_via": "retool",
    "created_by": {{ current_user.email }}
  }
}

Then, add an event handler to the form's Submit event that runs the create customer query and displays a success notification.

create a subscription

First, add a Form component with fields for subscription details.

Next, create a Stripe query to create a subscription.

Configure the query:

  • Operation: Create subscription
  • Parameters:
Example parameters
{
  "customer": {{ customerSelect.value }},
  "items": [
    {
      "price": {{ priceSelect.value }}
    }
  ],
  "payment_behavior": "default_incomplete",
  "payment_settings": {
    "save_default_payment_method": "on_subscription"
  },
  "expand": ["latest_invoice.payment_intent"]
}

Then, add an event handler that runs the query and handles the payment flow if payment is required.

issue a refund

First, add a Button component in your charges table to trigger refunds.

Next, create a Stripe query to issue a refund.

Configure the query:

  • Operation: Create refund
  • Parameters:
Example parameters
{
  "charge": {{ table1.selectedRow.data.id }},
  "amount": {{ refundAmountInput.value * 100 }},
  "reason": {{ refundReasonSelect.value }},
  "metadata": {
    "refunded_by": {{ current_user.email }},
    "refunded_at": {{ new Date().toISOString() }}
  }
}

Then, add an event handler to the button's Click event:

  1. Action: Show confirmation modal
  2. If confirmed, trigger the refund query
  3. Then refresh the charges list
cancel a subscription

First, add a Button component in your subscriptions table.

Next, create a Stripe query to cancel a subscription.

Configure the query:

  • Operation: Cancel subscription
  • Subscription ID: {{ table1.selectedRow.data.id }}
  • Parameters:
Example parameters
{
  "cancellation_details": {
    "comment": {{ cancellationReasonInput.value }},
    "feedback": "customer_service"
  },
  "prorate": true
}

Then, add an event handler to the button's Click event:

  1. Action: Show confirmation modal
  2. If confirmed, trigger the cancel subscription query
  3. Then refresh the subscriptions list

Best practices​

Follow these best practices to optimize performance, maintain security, and ensure data integrity when working with Stripe.

Performance​

  • Cache responses: For data that doesn't change frequently, enable query caching to reduce API calls and improve response times.
  • Use pagination: Implement pagination for endpoints that return large datasets to reduce payload size and improve performance.
  • Expand related objects: Use the expand parameter to include related objects in a single request rather than making multiple API calls.
  • Batch operations: When available, use Stripe's batch endpoints to combine multiple operations into fewer requests.
  • Set appropriate timeouts: Configure query timeouts based on expected API response times to prevent hung requests.

Security​

  • Use configuration variables: Store API keys and tokens in configuration variables or rather than hardcoding them.
  • Use HTTPS only: Always connect to APIs over HTTPS to encrypt data in transit and protect authentication credentials.
  • Rotate credentials regularly: Follow your API provider's recommendations for credential rotation and key management.
  • Validate SSL certificates: Keep SSL certificate verification enabled unless absolutely necessary for development environments.
  • Use resource environments: Organizations on an Enterprise plan can configure multiple resource environments to maintain separate configurations for production, staging, and development.
  • Apply least privilege: Use restricted API keys with minimal required permissions. Create separate keys for different environments.

Data integrity​

  • Validate user input: Sanitize and validate all user input before including it in API requests to prevent injection attacks.
  • Handle errors gracefully: Configure error notifications and fallback behavior for failed API calls to improve user experience.
  • Use idempotency keys: For APIs that support idempotency keys (like Stripe), include them in POST/PATCH requests to prevent duplicate operations.
  • Verify responses: Check response status codes and validate response data structure before using it in your app.
  • Implement retry logic: For transient failures, use Retool's automatic retry settings or implement custom retry logic with exponential backoff.
  • Log API interactions: Enable query logging to track API requests and responses for debugging and auditing.