When a customer's renewal payment fails, their subscription moves to past due while Stripe retries the payment. Retries recover some of these payments on their own, but your collections team usually wants to contact the others before the retries run out. So every weekday at 9:00 AM, someone on your finance team opens the Stripe Dashboard, filters for past-due subscriptions, and copies each one into a Slack channel so the team knows who to contact. On a quiet day, it's a small chore. On a busy day, it doesn't happen at all.

Nobody notices the skipped day until the retries run out, and a customer who would have updated their card after one friendly message has churned instead. The check itself is predictable: the same list, the same filters, and the same message, every morning. What's unpredictable is whether a person remembers to run it.

This pattern shows up across finance and operations teams. Daily balance checks, weekly payout reports, and month-end reconciliation all depend on the calendar, not on something happening in your account. Stripe Workflows already could react to events and run on demand. Now, it can start a workflow on its own at a time you specify.

The usual fix: a cron job

Teams that want to automate a recurring check usually end up writing a scheduled job. A typical version runs on your own infrastructure, lists past-due subscriptions through the Stripe API, and posts each one to Slack through an incoming webhook:

// past-due-subscriptions.js, run by cron on a UTC server: 0 16 * * 1-5
const stripe = require('stripe')(process.env.STRIPE_SECRET_KEY);

async function main() {
  for await (const subscription of stripe.subscriptions.list({
    status: 'past_due',
    expand: ['data.customer'],
    limit: 100,
  })) {
    await fetch(process.env.SLACK_WEBHOOK_URL, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        text: `Subscription for ${subscription.customer.email} is past due: https://dashboard.stripe.com/subscriptions/${subscription.id}`,
      }),
    });
  }
}

main().catch((err) => {
  console.error(err);
  process.exit(1);
});

The script is short, but the system around it isn't. You need a server or a scheduled function to run it, a place to store a Stripe secret key and a Slack webhook URL, and a deploy process for every change to the message. Time zones are your problem too. A cron expression on a UTC server doesn't follow daylight saving time, so a job set for 9:00 AM in Los Angeles runs at 8:00 AM local time for part of the year. If the job fails, it often fails silently. You find out when someone asks why the channel has been quiet for a week.

The script also lives outside Stripe, and usually outside the finance team's reach. If the collections lead wants to change the channel, add the customer's name to the message, or check twice a day instead of once, they file a ticket with engineering. A 9:00 AM check that should belong to the team that relies on it ends up depending on someone else's sprint.

Introducing recurring schedule triggers in Stripe Workflows

Stripe Workflows now supports recurring schedule triggers. You choose when a workflow runs, such as every weekday at 9:00 AM, every other Monday, or the last day of each month, and Stripe starts a run at each scheduled time. There's no server to run, no cron expression to maintain, and no API key to store.

A recurring schedule is one of three trigger types that Stripe Workflows supports:

• Event triggers run when something happens in your account, such as a payment succeeding or a dispute being created.
• Recurring schedule triggers run at the times you set.
• On-demand triggers run when you start them from the Dashboard or call the API.

Scheduled workflows pair well with list actions and loops. A common pattern is to schedule the workflow, retrieve a list of objects, and loop over that list to act on each item, which is the shape of the past-due subscription check.

Because the workflow lives in the Dashboard, the team that owns the process can read it, change it, and see every run.

Walkthrough: notify your team about past-due subscriptions

The past-due subscription check uses a recurring schedule trigger, a list action, and a loop. Inside the loop, the workflow looks up the customer, skips subscriptions the team already knows about, sends a Slack notification, and records the notification in the subscription's metadata.

1. Set the schedule

In the workflow builder, click Add a trigger, then select Tools, where recurring schedule and on-demand triggers live, and choose Recurring schedule. Set Repeat every to 1, select Week, and select Monday through Friday under Days of the week. Set Starting to the date and time of the first run, and choose a Time zone, such as America - Los Angeles. The workflow runs at the time in Starting on each scheduled day, beginning with the first scheduled time on or after it. After you click Done, the trigger shows a summary so you can confirm the schedule before you publish.

Schedules can run as often as every hour or as rarely as once a year. They follow the local clock, so a 9:00 AM workflow runs at 9:00 AM all year, and the Triggers docs cover the hour when clocks change.

2. List the subscriptions

Add a List subscriptions action and set the status filter to past_due. A subscription stays past due until a payment succeeds or the retries run out, so the same subscription shows up every morning until it's resolved.

3. Look up the customer

List subscriptions returns the customer's ID, not their email, so add a Retrieve a customer action and set its customer ID to the current subscription's customer. Because this action references a field from the list results, the builder adds a For each item in the Subscriptions loop, and every step after it runs once per subscription.

4. Skip subscriptions the team already knows about

Because past-due subscriptions show up every morning, the workflow needs to remember which ones it already reported. It does that with a metadata key, collections_notified_invoice, that the last step in the loop writes after the Slack message goes out. You don't create the key ahead of time, so on the first run, it's empty for every subscription.

Inside the loop, add a condition. For the field, choose Subscription, then Metadata, and enter collections_notified_invoice as the key. Set the operator to isn't equal to, and for the value, insert Subscription | Latest invoice ID. Put the next two steps on the If this condition is met branch.

On the first run, the empty key isn't equal to the latest invoice ID, so the team gets notified. The next morning, the key holds that invoice ID, so the loop skips the subscription. If the subscription later goes past due on a new invoice, the IDs differ again and the team hears about it. A yes-or-no flag wouldn't work, because it stays set after the first notification and hides every later one.

5. Notify the team

On that branch, add another action, click Apps, and under Slack, choose Send Slack Notification. If you haven't installed the Slack app, the builder prompts you to install it from the Stripe App Marketplace and connect your Slack workspace. Choose a channel, such as #collections, write a message template that includes the customer's email and the subscription ID, and add a Dashboard link to the subscription so the team can open it from Slack.

6. Record the notification

Finally, on the same branch, add an Update subscription action that sets collections_notified_invoice to the subscription's latest invoice ID. Anyone who opens the subscription can then see that the collections team has already been notified.

The loop handles pagination for you. If an action fails for one subscription, the loop stops there, and run details show which subscriptions were processed. Any subscription the loop didn’t reach gets picked up on the next run. If the Slack notification succeeds but the metadata update fails, the workflow might notify the team about that subscription again. That’s why the Slack step comes first - a duplicate message is better than a missed one. Each action inside a loop counts once per item. Retrieve a customer runs for every past-due subscription, but the condition limits the Slack and update steps to the ones that are new.

Monitor and manage the schedule

After you publish, the workflow's page shows Next run, and Recent runs lists every run with its status. Click a run to see each step's input and output and, for a failed run, which step failed and why. To get alerted, create a second workflow triggered by the Workflow run failed event. Search for it in the trigger picker, or find it under More > Advanced > Workflow run. Then have it send a Slack notification to a different channel or Email a team member. To stop on a date, set Ending under Advanced. To pause, deactivate the workflow. Times missed while it's inactive are skipped.

A scheduled workflow runs only on its schedule, so you can't start it by hand. To test it, build it in a sandbox, set Starting a few minutes ahead, and check Recent runs. To run the same check on demand, create a separate workflow with an on-demand trigger.

What changes for your team

Recurring schedule triggers move calendar-based work into the same place as the rest of your Stripe automation. The past-due subscription check runs every weekday at 9:00 AM local time whether or not anyone remembers it, each past-due subscription reaches the collections team once, and the subscription itself records that the team was notified.

There's no server, secret key, or daylight saving time logic to maintain. The team that relies on the check can change the channel, the message, or the schedule themselves, and when something goes wrong, the run shows which step failed and why.

Recurring schedule triggers are available in Workflows today. To build your first scheduled workflow, go to Workflows in the Dashboard.

This is the first of two posts on fine-tuning LLMs for risk assessment. Here, we focus on learning from labels; the second post will explore learning from explanations.

High-stakes risk assessment

Stripe powers millions of businesses moving trillions of dollars annually while operating self-serve, globally adopted, financial infrastructure. To achieve this safely, we make thousands of risk decisions every single second. Is this transaction legitimate? Is the business trustworthy? Is this product set allowed by this financial partner? Has this business become suddenly popular, or is it under attack? Should we adjust a business’ credit reserves?

A false negative lets through fraud and abuse, reducing trust and making the internet economy less safe . A false positive can stymie legitimate economic activity and meaningfully affect a business’ livelihood. Balancing these risks, in near real-time at high precision, requires models to connect patterns in our data with an understanding of how the business operates in the wider economy.

Several properties of LLMs make them well suited to these risk decisions. LLMs bring world knowledge from pretraining that helps interpret Stripe’s internal data in the context of real-world business practices. LLMs also provide a flexible way to integrate heterogeneous features, including numerical, categorical, text, and time-series data. Combining these inputs in conventional tabular or sequence models often requires feature engineering, type-specific encodings, or specialized architectures. With LLMs, we can serialize these features into a shared text representation and process them with a single model, enabling it to reason jointly over different feature types.

The problem is that LLMs are word prediction machines, and are not designed for the reliably rigorous statistical analysis Stripe needs as inputs to our risk decisions.

We confirmed this intuition in early testing by asking a model to assess the likelihood that a business was fraudulent. We compared zero-shot prompting, which relied solely on the model’s pretraining, with domain-guided prompting where we made Stripe’s review criteria explicit, including which signals to consider and how to interpret them in context.

For each business, we collected the features used in human reviews, including card payments, money movement, and account activity, and serialized them into a text-based account record (see Figure 1). The model produced a verbalized probability of fraud, which we used as the risk score (Tian et al. 2023). This continuous score allowed us to rank accounts and set thresholds for routing them to human reviewers, balancing fraud detection against disruption to legitimate businesses.

The LLMs performed poorly against human review. While domain-guided prompting outperforms zero-shot, it fails to reach the human reviewer’s precision at the same recall. Both model predictions and initial human-review decisions are evaluated against labels that incorporate subsequent evidence and outcomes. It’s worth noting that for these results, and the others shared below, that fraud prevalence and the mix of cases affect precision, so results on accounts selected for review should not be read as performance across all Stripe businesses.

So how can we get a word predictor to natively conduct and output high quality statistical analysis?

Supervised fine-tuning (SFT)

To fit an LLM into this analytical structure, we explored labels-only supervised fine-tuning (SFT) of an open-weight 4B-parameter LLM. Unlike prompting, SFT updates the model’s weights to predict each account’s review label from its serialized record. Let $$x_i$$ be the state of the business’s account $$i$$, $$s(x_i)$$ its text serialization, and $$y_i \in {0,1}$$ the review label, where $$y_i = 1$$ denotes fraud. The training dataset is $$\mathcal{D} = {(s(x_i), y_i)}_i$$. The target response contains only the label $$y_i$$, so the objective reduces to the negative log-likelihood of that label:

$$ \theta^* = \underset{\theta}{\arg\min}; \mathbb{E}{(s(x_i), y_i) \sim \mathcal{D}} \left[-\log p{\theta}!\left(y_i \mid s(x_i)\right)\right] $$

Although the model is trained to output a discrete label, we can derive a continuous risk score from its next-token distribution. For single-token class labels, we normalize the probabilities of the fraud and non-fraud tokens at the answer position. If $$\ell_1$$ and $$\ell_0$$ are the log probabilities of the fraud and non-fraud label tokens, the fraud score is

$$ r(x) = \frac{e^{\ell_1}}{e^{\ell_1} + e^{\ell_0}} $$

This score lets us rank accounts and choose a decision threshold. Unlike the prompted baseline, which generates a numerical risk estimate as text, this approach derives the score directly from the label-token probabilities.

For example, suppose fraud is encoded as yes and non-fraud as no, each represented by a single token. If the model assigns probability 0.18 to yes, 0.72 to no, and 0.10 to all other tokens, normalizing over the two valid labels yields a fraud score of 0.18 / (0.18 + 0.72) = 0.20 (see Figure 2 for illustration). Rather than retaining only the predicted label, we use the relative probability assigned to each class to obtain a continuous score.

And how does this adapted model perform relative to our human reviewers?

The fine-tuned 4B-parameter model achieved higher precision against historical review labels, achieving approximately 24% higher average precision than domain-guided prompting and 70% higher than zero-shot prompting. These results suggest that Stripe’s risk distribution differs from the broader pretraining distribution. Injecting domain knowledge through context helps bridge that gap, but fine-tuning on our internal data captures nuances that cannot be exhaustively conveyed in written guidelines.

Does SFT learn new knowledge?

The gains in decision accuracy alone do not reveal whether SFT changes how the model represents risk signals, such as suspicious payment patterns or legitimate business activity. To investigate this, we compared the internal representations of this open-weight 4B with and without training on risk review data. We used linear probing (Alain and Bengio, 2016) to measure how risk-relevant concepts could be linearly decoded from each model’s hidden representations. For each model, we extracted the final layer’s hidden state at the answer-prefill position, then trained logistic regression classifiers on these frozen representations.

We probed for 44 concepts using 34 binary and 10 multiclass classification targets, including risk and benign signals, account metadata, business size, case types, and evidence sufficiency. Probe labels came either from the source dataset or from the teacher-model annotations. The benign concepts capture characteristics associated with legitimate businesses, such as a consistent business description, a credible online presence, or an established processing history. Their absence isn't a risk signal; it only means that evidence isn't there. Risk signals are the fraud patterns reviewers flag during business review.

SFT makes benign signals more accessible

Figure 4 shows that linear-probe ROC-AUC improves more for benign signals (0.583 -> 0.642) than for risk signals (0.702 -> 0.729). Before SFT, benign signals are close to chance (0.5) in the base model's representations, so the model carries little information about what a legitimate business looks like. After SFT, eight of the nine benign signals become easier to recover, including a consistent business description (0.614 -> 0.707) and an established processing history (0.644 -> 0.712).

These results suggest that SFT helps the model recognize when suspicious-looking activity makes sense for a legitimate business. A model that better recognizes legitimate businesses is less likely to flag them, which aligns with the higher precision at the same recall in Figure 3 and reduces false positives.

SFT improves risk assessments across tasks

Across multiple risk assessment tasks at Stripe, supervised fine-tuning increased precision by more than 21% at the same recall and consistently outperformed XGBoost. These results make SFT a strong foundation for production risk systems that require both precise risk evaluations and the flexibility to use rich, heterogeneous evidence.

In a past blog post, we explored how to move from hosted onboarding onto a whitelabeled embedded onboarding flow by using the account onboarding embedded component. In this blog post, we’ll go over how to build a whitelabeled dashboard for connected accounts with just a few lines of code by using Connect embedded components.

In this example, we’ll be building out the connected account dashboard for FurEver, a pet grooming SaaS platform.

Rendering payments, allowing refunds and dispute management

To achieve this in the FurEver dashboard, you could build these workflows directly with Stripe’s APIs, but doing so requires substantially more than listing PaymentIntents. You would need to implement pagination, payment-method and status presentation, permissions, payment details, refunds, disputes, capture flows, and ongoing support for new states and capabilities. The Payments embedded component provides these workflows as a Stripe-maintained UI that you can place directly inside your dashboard.

One-time setup

First, we need to make sure we’re initializing embedded components correctly for the connected account. We do this by exposing an endpoint on the FurEver dashboard server-side code that creates an account session for the current account. FurEver is a NextJS application that uses App Router, so we add a new /api/create_account_session POST endpoint:

export async function POST() {
  const session = await getServerSession(authOptions); // Get FurEver session state
  const stripeAccountId = session.user.stripeAccount.id;
  const accountSession = await stripe.accountSessions.create({
    account: stripeAccountId,
    components: {
      payments: {
        enabled: true,
      },
      // Other components go here...
    },
  });

  return new Response(JSON.stringify(accountSession), {
    status: 200,
    headers: {'Content-Type': 'application/json'},
  });
}

We'll use this API to initialize embedded components on the frontend. I’ll need to add a dependency to the @stripe/connect-js and @stripe/react-connect-js packages.

yarn add @stripe/connect-js @stripe/react-connect-js

Now that we have the packages, I’m going to edit the top-level wrapper of my frontend to include the initialization context for embedded components. This makes it so that I can render components in any part of the React tree below this wrapper.

import {loadConnectAndInitialize} from '@stripe/connect-js';
import {
  ConnectComponentsProvider,
} from '@stripe/react-connect-js';

export default function AppWrapper({children}) {
  const [stripeConnectInstance] = React.useState(() => {
    const fetchClientSecret = async () => {
      const response = await fetch('/api/create_account_session', {
        method: 'POST',
      });
      if (!response.ok) {
        throw new Error('Failed to fetch account session');
      } else {
        const {client_secret} = await response.json();
        return client_secret;
      }
    };

    return loadConnectAndInitialize({
      publishableKey:
        'pk_test_123', // Your publishable key goes here!
      fetchClientSecret: fetchClientSecret,
    });
  });

  return (
    <ConnectComponentsProvider connectInstance={stripeConnectInstance}>
      {children}
    </ConnectComponentsProvider>
  );
}

Next, we can render the ConnectPayments embedded component in the payments page:

import {
  ConnectPayments,
} from '@stripe/react-connect-js';

export const PaymentsPage = () => {
  return (
    <div>
       <div>...Header...</div>
       <div>
          <div>Recent payments</div>
          <ConnectPayments />
       </div>
    </div>
  );
}

The payments component is now rendering under the “Recent payments” label. Connected accounts can now refund payments, respond to disputes, and capture payments.

Rendering balance and payouts

Let’s give connected accounts an overview of their balance and payouts by using the payouts component. On the server, we should enable the payouts component:

const accountSession = await stripe.accountSessions.create({
  account: stripeAccountId,
  components: {
    payments: {
      enabled: true,
    },
    payouts: {
      enabled: true,
    },
    // Other components go here...
  },
});

// PayoutsPage.tsx
import {
  ConnectPayouts,
} from '@stripe/react-connect-js';

export const PayoutsPage = () => {
  return (
    <div>
       <div>...Header...</div>
       <div>
          <div>Payouts</div>
          <ConnectPayouts />
       </div>
    </div>
  );
}

Connected accounts can now view balance, payouts, change payout schedule, and change their bank destination.

Keeping connected accounts enabled for payments

Connected accounts may become unable to process payments or obtain payouts for a wide variety of reasons - exceeding processing thresholds, balance overdrafts, or changing regulations, which require additional information from accounts to process payments. To keep accounts enabled, we can automate the information collection flows by enabling the notification_banner component, and render it in our app header.

The notification_banner is conditionally rendered - meaning it will only render when the account is disabled and needs additional information.

const accountSession = await stripe.accountSessions.create({
  account: stripeAccountId,
  components: {
    payments: {
      enabled: true,
    },
    payouts: {
      enabled: true,
    },
    notification_banner: {
      enabled: true,
    },
    // Other components go here...
  },
});

// AppHeader.tsx
import {
  ConnectNotificationBanner,
} from '@stripe/react-connect-js';

export const AppHeader = ({ children } ) => {
  return (
    <div>
       <ConnectNotificationBanner />
       <>{children}</>
    </div>
  );
}

The notification banner (shown within the outline for clarity) now renders when a requirement is present on the connected account, to keep payments and payouts enabled.

Mapping platform user roles to account session features

So far we’ve used components configured with default account session features. In the case of FurEver, we have admin users and regular users, and we want to toggle features depending on the user role. For example, only admin users should be able to perform refunds on the payments component:

export async function POST() {
  const session = await getServerSession(authOptions); // Get FurEver session state
  const isAdmin = session.user.isAdmin;
  const stripeAccountId = session.user.stripeAccount.id;
  const accountSession = await stripe.accountSessions.create({
    account: stripeAccountId,
    components: {
      payments: {
        enabled: true,
        features: {
          refund_management: isAdmin,
          dispute_management: isAdmin,
        },
      },
      payouts: {
        enabled: true,
        features: {
          edit_payout_schedule: isAdmin,
        },
      },
      notification_banner: {
        enabled: true,
      },
      // Other components go here...
    },
  });

  return new Response(JSON.stringify(accountSession), {
    status: 200,
    headers: {'Content-Type': 'application/json'},
  });
}

The account session is now configured correctly to respect admin user roles, and components automatically adjust their behavior depending on this configuration.

The refund flow is only enabled for FurEver admins.

Matching the look and feel of the platform site

By using the appearance API, we can get the components to look exactly like the rest of the UI. We recommend using the “upload” functionality of our theming doc site which can take an image of your site, and output theming values you can fine tune.

FurEver uses the following theme, and toggles it depending on whether the app is in dark or light mode - it also passes in the current locale, to ensure this matches the rest of the dashboard.

export const defaultPrimaryColor = '#27AE60';

export const LightTheme = {
  fontFamily: 'Sohne, inherit',
  colorPrimary: defaultPrimaryColor,
  colorBackground: '#ffffff',
  colorBorder: '#D8DEE4',
  ...
  // See full light theme [here](https://github.com/stripe/stripe-connect-furever-demo/blob/6c99740f14bf9d76d127aa0495cf38b9ab72ff3b/app/contexts/themes/ThemeConstants.ts#L3)
};

export const DarkTheme = {
  fontFamily: 'Sohne, inherit',
  colorPrimary: defaultPrimaryColor,
  colorBackground: '#1e222a',
  ...
  // See full dark theme [here](https://github.com/stripe/stripe-connect-furever-demo/blob/6c99740f14bf9d76d127aa0495cf38b9ab72ff3b/app/contexts/themes/ThemeConstants.ts#L23)
};
...

const appearanceVariables = theme === 'dark' ? DarkTheme : LightTheme; // Toggle depending on current FurEver theme
const instance = loadConnectAndInitialize({
  ...
  appearance: {
    overlays: 'dialog',
    variables: appearanceVariables || LightTheme,
  },
  locale,
  ...
});

Conclusion

By using embedded components and writing only a few lines of code, we’ve built a full payments dashboard for FurEver connected accounts that:

1. Provides connected accounts with full functionality for payments, payouts and keeping accounts enabled via notification banner
2. Snaps to FurEver user role permissions by using account session features
3. Matches the FurEver look and feel by using appearance and locale
4. Updates automatically, so FurEver won’t miss any new payment methods or compliance updates

You can try this demo live at https://furever.dev. This sample is open source: https://github.com/stripe/stripe-connect-furever-demo.

In this blog post we’ve used only three components. Stripe offers a growing catalog of embedded components, including components for areas such as Instant payouts, Capital, Tax, and Issuing. To see the full component list and read more about how to integrate with them please visit our supported components page.

The first time you build something new, you start from scratch. The second time, you spot the patterns and build a platform. But to truly scale, you build a factory.

We built our payment method factory from over 100 reusable prompts, hardened by agents observing implementation runs, and kept them current by feeding back each run's learnings.

Stepping back, Stripe offers over 125 payment methods across the globe, ranging from credit cards, to PayPal wallets, to Buy Now, Pay Later services like Klarna. At a high level, each payment method does the same thing:

• Makes a payment
• Issues a refund
• Handles a dispute

Under the hood, they have different behaviors and different API shapes. Despite these differences, the process of building each integration follows a familiar pattern. Yet with little reusable tooling, teams were starting from scratch each time, meaning it could take six months to build even a basic integration.

In 2025, this led us to ask two important questions.

• Could we prompt an LLM to build an entire payment method integration?
• And, more importantly, could we reuse those prompts for every future integration?

The factory we built has so far created three new payment method integrations and migrated ten existing integrations to our modern stack, demonstrating its effectiveness for legacy migrations, too. The payment method factory reduced integration timelines from as long as six months to two-to-six weeks.

Along the way, we learned how valuable it was to harden our prompts to make them reusable, keep them up to date as the codebase evolved, orchestrate the agents in a human-guided workflow, and get agents testing their own changes.

Building the foundation: Hardened reusable ‘one-shot’ prompts

An agent skill and a simple prompt are often enough to complete part of an integration. If the agent needs steering, we can refine the original prompt until it completes the task without our help. Saving these prompts for the next integration makes sense, but how do we know whether they’re actually good prompts, or whether the agent just muddled its way through despite them? Even in a successful ‘one-shot’ run, we can still see the agent perform unnecessary investigations or repeatedly attempt to fix failing tests. We hypothesized that evaluating and refining these prompts could get us the same results faster, at a lower cost, and with more confidence in the output.

To see how much difference this approach could make, we did a bake-off, two engineers completed the same integration task: add payment method support for a frontend-facing API. One engineer used vanilla Claude Code, while the other used Claude Code with a reusable set of prompts built from our prior experience. The difference was substantial: the vanilla setup required roughly 20 days of engineering effort, compared to 4 days when using the reusable prompts.

Writing a good one-shot prompt

We began with over 125 past implementations of payment methods as the base of our prompt. We gave the agent these examples and a template for structuring the prompt, then refined the output by hand. We designed the resulting template to be payment-method agnostic so it could be reused across other payment methods. Here’s an example:

Excerpt from a prompt for handling payment confirmations

This gave us a strong starting point for evaluating and hardening the prompt. The process starts with an implementation agent that’s following the prompt to build a payment method integration. A second agent, acting as an observer, runs in parallel to the implementation agent. The observer knows what the agent is trying to implement and what the end state should look like. It reads the implementation agent’s transcript, and notes down which steps took extra time to investigate, where the agent got lost, and what the agent had to re-learn. It checks if any of our internal tooling failed during the process, like a command timing out. If the first pass generated a red CI, it looks at the failures. The engineer takes the observer agent’s report and refines the prompt further.

The first step when starting on a new payment method integration is the scaffolding, which  could take an engineer up to a week to finish. It involves adding an ‘adapter’ so that other Stripe products can interact with the payment method, adding feature gates to restrict access, wiring it in our API specs and SDKs without exposing it, and setting the partner details. This change alone is more than 5000 lines long, touches over 100 files, and is produced in part by 15 commands that generate code and have to run in a set order. When something broke, an engineer had to work out what each command does and where the payment method still needed to be registered. With a prompt that explains what each piece does and where to look if something breaks, we brought this step down to a day of implementation time.

Continuous knowledge loop: Keeping prompts up to date

The issue with reusable prompts, unlike creating a new one each time, is that we have to find a way to effectively maintain them. We now have over 100 saved prompts. If the way we provision databases changes, or an investigation pointer isn’t valid, we need to update any affected prompts.

To take on this maintenance overhead, we developed a system that continuously improves the prompts. While the payment method factory is working on an integration, it collects some artifacts:

• Learning logs from the individual implementation agents about anything they had to learn about our systems that wasn’t covered by the initial prompt.
• Decision logs for all the decisions they had to make unattended to give the reviewers more context on why the agent went down a certain path.
• Full transcripts of the entire session.
• Engineer’s review comments on the created pull request.

When the integration is complete, an agent takes these artifacts and suggests potential improvements to the prompts. Some are straightforward enough and can be implemented with the click of a single button using minions, Stripe’s one-shot coding agents, while others might require further work before we apply them.

Building the factory: Orchestrating our collection of prompts

We now have a collection of prompts that covers every step of building a new payment method integration. Stripe uses a monorepo, so theoretically, we could combine all the prompts into one master prompt and be done in one pull request. In practice, the current limits of an agent’s context window make this impossible and the resulting PR would be too large to review and prone to merge conflicts.

We kept the development lifecycle we already know works: start an agentic session, run a prompt, review the result, and open a PR. The difference is that an engineer no longer has to drive every step themselves. An orchestrator can delegate each step to an isolated implementation agent.

There are two phases to our orchestration. The first is creating a plan, a sequence of discrete steps, each linked to one of the prompts we developed earlier. The goal is for each step to map to one pull request. As we construct the plan, the agent interviews the engineer for context on the payment method being built, asking about requirements like what currencies are supported in which regions. This context is exported to a shared knowledge base that implementation agents can later reference.

The second phase executes the plan, with implementation (sub)agents handling each step. To coordinate their work, we needed an orchestrator that could assign each task to the right implementation agent and track its progress.

Our first approach used a high-level orchestrator agent for this role. It worked, but it was expensive, slow, and sometimes unreliable. In some cases, the orchestrator agent tried to implement the step itself rather than delegating to an implementation agent, which ultimately ate up its context.

We learned that although an LLM can orchestrate a workflow, predictable coordination is better implemented in code.

Building confidence: Letting agents test their own work

As code generation becomes faster, code reviews started becoming a bottleneck. We help reviewers by keeping pull requests small and providing all relevant context, but ultimately, we found that giving agents the tools to test their integrations autonomously gives the reviewer the most confidence.

Let’s take the service that talks with the payment method provider as an example. If a provider has a sandbox environment, the factory creates test payments and runs different end-to-end scenarios against it. The factory checks requests, responses, internal state changes, and emitted events against our expectations. It then snapshots the provider’s API responses and creates immutable contracts that are used throughout our stack, rather than manually creating hand-written mocks. All of this is then presented to the engineer and is used in our system to emulate recorded payment method behavior.

We still have room to improve here. Agents should have the tools to interact with every part of our systems and we’d like to automate remaining manually tested steps, like UI testing.

Beyond payment methods

Payment methods are not the only repeated, customizable integration we have. Teams at Stripe were inspired by the payment method factory to build their own versions. For example, our tax team uses one to build connectors that bring Stripe Tax to businesses selling on other platforms, and our verification team built one for the providers we use to check business details during onboarding.

If making other engineers more productive interests you, we’re hiring.

In order to help Stripe sellers benefit from the rapid growth of AI agents, we enabled WebMCP on all Stripe Checkout UIs resulting in 42% fewer tokens consumed and 38% fewer tool calls invoked against baseline measurements.

While many businesses (Stripe included!) have built MCP servers as a programmatic interface for agents, browser use remains a predominant path for agents to interface with existing services. Websites, traditionally, have been optimized for human usage. To complete a checkout, an agent must interpret both the visual interface and the Document Object Model (DOM), infer both the information presented and which actions are available, and then plan and execute those actions. Even with ongoing model improvement, navigating a webpage is still slow, indirect, and token-intensive.

Just as we optimize human buying experiences to minimize latency and clicks, we need to optimize agent buying experiences to minimize token usage and tool calls. These are the primary measures of agent efficiency: tokens indicate cost, while tool calls indicate effort (and a high number of tool calls can also signal confusion!).

We believed WebMCP, an emerging standard gaining traction, was a strong candidate to improve the agent checkout experience.

This problem is no longer hypothetical. Agents like Muse, Instinct, and Grokbot, are launching and becoming popular – typically equipped with a virtual machine and browser –  and we are seeing and anticipating growth in agentic volume processed on Stripe:

We decided to incorporate agent-friendly WebMCP across Stripe Checkout UIs, which powers over 7.8M businesses processing around 0.45% of global GDP.  We aimed to give millions of merchants access to future agentic shoppers without them needing to change their integration while providing a fast and reliable consumer experience.

As a baseline without WebMCP enabled, we measured an average of 1.8M tokens consumed, 38.83 tool invocations, and >2.5 minutes duration for these agents to complete a transaction with Stripe Checkout. Even in chat-based applications where there is some expectation of latency, this is all simply too high.

This blog post focuses on how we implemented WebMCP to reduce token consumption and tool invocations.  We struck a balance between building a specialized interface that improved agent performance, yet keeping it aligned to the human interface for better maintainability.

What is WebMCP?

WebMCP is a browser technology that lets websites “expose” MCP tools to agents from the client side. Instead of inferring how to complete a task and navigating the DOM, an agent can execute tools, such as get_order_summary or fill_payment_form. The agent doesn’t necessarily have to look at any of the HTML on the page.

Above is a Stripe Checkout page.  We can see that invocations of the available tools result in changes to the UI – select_payment_method dynamically updates the UI and fill_payment_form put in credentials like the card number – we theorized this is a great improvement over ingesting all of the HTML into the LLM context and ascertaining element ids or classes to infer where buttons were (or hardcoding flows that could be brittle).

Building for WebMCP

With a baseline measurement of ~39 tool calls to reach payment, each consuming tokens and time, we focused on tool design that would substantially reduce that number. And for our initial build, we preferred not to “fork” the business logic behind the page depending on whether the user was a human or an agent.

A catalog of tools can eliminate some of the ambiguity that comes with visual browser automation, but with a large catalog, the agent must still decide which actions are valid. An agent presented with too many tools, irrelevant parameters, or invalid actions can still struggle to complete the task.

Consider a checkout that supports multiple payment methods, dynamically rendered address fields, and a payment button that is only activated after the required information has been provided. If an agent receives every possible action at once, its context includes tools and parameters that may be irrelevant or impossible to use.

Instructions in the tool descriptions can help, but they still leave the agent unnecessarily responsible for reasoning about constraints the application already understands. You can think of it like pruning the branches of a tree to  progressively guide the agent towards the target outcome.

Reveal tools as they become actionable

We designed Stripe’s WebMCP implementation around progressive tool disclosure, meaning that the page only exposes only the tools and parameters that are relevant in its current state. This makes agent interactions more reliable while keeping human and agent experiences aligned. Concretely, we want to minimize cases where available tools can result in sequenced invocations that result in errors.

As an example, we do not reveal the submit_payment tool until all the fields have been filled. A simplified checkout might progress like this:

1. The agent inspects the checkout session and available payment methods.
2. After selecting a payment method, the page exposes a form filling tool whose schema reflects the visible fields.
3. The agent provides the required information using that tool.
4. Once the form is complete and valid, the page exposes submit_payment.

If the checkout state changes, the available tools change with it. For example, if the agent changes payment method type to a non-card method, we’ll remove the number from the parameter set of fill_payment_form.

Rather than mapping every possible action upfront, this approach reduces tool calls, improves reliability, and increases successful payment outcomes.

Additionally, we relied on many of the existing accessibility patterns and optimizations in our frontend code to keep a shared infrastructure rather than creating a second checkout implementation exclusively for agentsWebMCP tools delegate to the same foundations used by human-facing checkout interfaces. As we continue to optimize Stripe Checkout for humans, agents will reap all the benefits. And, now that we’re closer to human and agent parity, we’re interested in how agent-first improvements may reflect in the human experience.

Avoid forking our business logic

We used two WebMCP API types to connect tools to the existing interface: imperative and declarative tool implementations. Our existing UI surfaces have both state management and forms designed to handle the end-to-end payment flow. We did not want to introduce an “agent-only” bifurcation that could result in drift or add toil for engineers.

With the Imperative API, we introduced tools like get_order_summary that derive their responses from existing state and select_payment_method for explicit actions like changing payment method that initiate existing state transitions.

For form filling, we used the Declarative API to create tools that derive from rendered HTML. The browser can infer an input schema from the controls that are currently visible rather than requiring us to maintain a second, manually duplicated form schema. This means that if a developer adds a new form field, it will bubble up to the new tools by default.

Agents using browser automation tools like Browserbase can then invoke these tools directly to get checkout information and complete payments.

Evaluating performance

To assess whether WebMCP made agents attempting to checkout more efficient without sacrificing reliability, we measured checkout completion, execution time, tool calls, and token consumption.

We ran 60 tests across six models on a fictional outdoor retailer website using the Stripe Checkout full page UI. 50% of the tests used WebMCP and 50% used a baseline browser interaction. Each test required the agent to complete the same end-to-end task to navigate to the website, add a product to the cart, proceed to checkout and complete payment.

In all of the tests, agents completed the checkout successfully. But when we compared the agents that used WebMCP, we found that agents performed significantly better across three categories.

Agents using WebMCP consumed 42% fewer tokens, completed checkout 39% faster, and made 38% fewer tool calls per run.

We measured total tokens (input + output + cache) consumed by the agent to complete the task. Token usage contributes directly to the cost of an agentic transaction, so reducing tokens can make these transactions less expensive for agents to support at scale.

We also counted the number of actions (clicks, form fills, tool invocations) an agent takes to complete checkout. Fewer tool calls mean the agent took a more direct path through checkout, with less exploratory form interaction.

And finally, we measured wall-clock time from task start to a completed checkout. This looked at the time it took for the agent to navigate to the URL, select a product, complete the checkout form and submit the payment. The reduction in execution time lowered the time a customer spent waiting for an agent to complete a purchase by 60 seconds.

Up next

WebMCP is one step in an evolving standard of browser-agent behavior, where interfaces can serve people and agents without requiring separate experiences for each. As agents become an even more popular way people interact with the web, engineers will need to decide how to communicate desired actions to both human and machine users.

As WebMCP and browser agents evolve, we’ll continue improving Checkout for agent-driven purchases to help businesses serve customers however they choose to buy, whether they interact with Checkout directly or ask an agent to act on their behalf.

Ready to build for agent driven purchases? Get started with Stripe Checkout and WebMCP.

We’re still early in understanding what becomes possible when it comes to building for AI agents. There’s a lot left to build at Stripe, and the work spans infrastructure, developer tools, product systems, and AI all at once. If that’s the kind of problem you want to work on, we’re hiring.

Why SFTP falls short

It is true that SFTP remains common in enterprise environments. However, we consistently hear that SFTP proves to be fragile, hard to scale, and lacks the level of self-service customization that complex, dynamic businesses need.

1. Polling dependency and data delays: Statically scheduled batch jobs can leave data behind operational reality. SFTP reporting pipelines are often coupled with cron jobs and polling processes to detect new files, which is inefficient when Stripe offers real-time payout and report run completion events.
2. Customization limitations: Oftentimes, legacy processors have SFTP reports with a fixed set of available columns and set delivery schedules. With Stripe’s API-based custom reports, when your finance team makes a request for a new report field or cadence, there’s no need to go back and forth with Stripe, you can just implement it.
3. Security overhead: Reporting APIs allow you to use the same API key-based permissioning and audit trail as the rest of your services, not a separate SFTP credential/IP-allowlist to manage.

Stripe’s reporting philosophy

Stripe’s reporting APIs, including the Reports API v2 and Query Run API, are focused on delivering a developer-first approach to financial reconciliation.

1. Data platform consistency: Businesses often have completely separate datasets and schemas being used for financial reconciliation activities versus BI analytics. By offering a consistent schema across data products like Sigma and Data Pipeline, which also closely align with the API conventions, Stripe provides a more consistent experience across your business’ use cases.
2. Self-service: Developer agency is a non-negotiable for Stripe products, and reporting is no different. Whether you need to add custom metadata as a report column, join multiple resource tables, add a new derived field, or update the report run schedule, you can make changes autonomously.

Building financial reconciliation reports

Let’s take a fictional business, Galtee, an outdoor equipment retailer. Galtee has a direct-to-consumer business line as well as a business-to-business line that sells products to campgrounds and adventure tourism companies. The Galtee finance team has shared financial reconciliation reporting requirements that Galtee’s engineering team is working on fulfilling using Sigma. The Query Run API allows Galtee to programmatically execute SQL queries as part of a reporting workflow, making it possible to create fully custom reports that don’t need a post-extraction transformation layer.

Multi-account payout reconciliation

Galtee has created two different Stripe accounts, representing the D2C and B2B business lines, that are grouped under an Organization. Galtee’s finance team needs a report that includes transaction information for all funds paid out to the Galtee bank accounts for a given day.

The balance_transactions Sigma table is the main table for financial reconciliation, because it includes all transactions that contributed to the Stripe account balance. It can be joined with the transfers table to list all transactions that are part of a bank payout on a given date:

SELECT
  date(transfers.date) as payout_date,
  transfers.id as payout_id,
  balance_transactions.id AS balance_transaction_id,
  balance_transactions.source_id,
  balance_transactions.type,
  balance_transactions.net,
  balance_transactions.currency,
  balance_transactions.amount
FROM transfers
JOIN balance_transactions
  ON balance_transactions.automatic_transfer_id = transfers.id
WHERE
  date(transfers.date) = date({{PAYOUT_REPORT_DATE}})

Then, to run this query across both of Galtee’s Stripe accounts, Galtee can set the API key to be the Organization secret key:

curl -X POST https://api.stripe.com/v2/data/reporting/query_runs \
  -H "Authorization: Bearer {{ORGANIZATION_SECRET_KEY}}" \
  -H "Stripe-Version: 2026-07-29.preview" \
  --json '{
    "sql": "{{QUERY_STRING}}"
  }'

Once the query completes, Galtee will receive a v2.data.reporting.query_run.succeeded webhook event that can trigger automated report retrieval.

This returns a clean table listing all balance-affecting activity, including payments, refunds, and fees included in a given payout. The sum of the “net” column amounts, minus the successful payout rows, should equal the total cash paid out to Galtee’s bank accounts that day.

Local presentment and FX in payout reconciliation

Now, let’s say Galtee has started selling cross-border to European buyers and is manually setting prices in EUR. Galtee’s finance team now needs the payout reconciliation report updated to include the presentment amounts and the exchange rate used for the currency conversion of each transaction. This can be easily incorporated by adding the exchange_rate field from the balance_transactions table and adding the presentment data by joining with the charges table:

SELECT
  date(transfers.date) as payout_date,
  transfers.id as payout_id,
  charges.id AS charge_id,
  charges.created AS charge_created_at,
  balance_transactions.id AS balance_transaction_id,
  balance_transactions.source_id,
  balance_transactions.type,
  balance_transactions.net,
  balance_transactions.currency AS settlement_currency,
  balance_transactions.amount AS settlement_amount,
  charges.currency AS presentment_currency,
  charges.amount AS presentment_amount,
  balance_transactions.exchange_rate
FROM transfers
JOIN balance_transactions
  ON balance_transactions.automatic_transfer_id = transfers.id
LEFT JOIN charges
  ON charges.balance_transaction_id = balance_transactions.id
WHERE
  date(transfers.date) = date({{PAYOUT_REPORT_DATE}})

Now the reconciliation report supports local currency presentment scenarios and Galtee’s engineering team can immediately deploy this change by updating their Query Run API sql parameter.

Itemized IC+ transaction fees in payout reconciliation

Next, Galtee’s finance team wants to know the total IC+ fees associated with each card charge on the payout report. The original query can be modified to also join with the icplus_fees table and sum all of the IC+ fee rows for each charge:

SELECT
  date(transfers.date) as payout_date,
  transfers.id as payout_id,
  balance_transactions.id AS balance_transaction_id,
  balance_transactions.source_id,
  balance_transactions.type,
  balance_transactions.net,
  balance_transactions.currency AS settlement_currency,
  balance_transactions.amount AS settlement_amount,
  charges.currency AS presentment_currency,
  charges.amount AS presentment_amount,
  balance_transactions.exchange_rate,
  CASE
    WHEN balance_transactions.type = 'charge' THEN (
      SELECT SUM(icplus_fees.billing_amount)
      FROM icplus_fees
      WHERE icplus_fees.charge_id = balance_transactions.source_id
    )
    ELSE NULL
  END AS icplus_fee_total
FROM transfers
JOIN balance_transactions
  ON balance_transactions.automatic_transfer_id = transfers.id
LEFT JOIN charges
  ON charges.balance_transaction_id = balance_transactions.id
WHERE
  date(transfers.date) = date({{PAYOUT_REPORT_DATE}})

Galtee can also take it a step further and create an itemized row of all IC+ fees to add to each card charge row:

WITH

-- Create a table with a single row of all IC+ fees for each charge
icplus_by_charge AS (
  SELECT
    charge_id,
    SUM(CASE WHEN fee_name = 'interchange' THEN total_amount END) AS interchange,
    SUM(CASE WHEN fee_name = 'card_scheme' THEN total_amount END) AS card_scheme,
    SUM(CASE WHEN fee_name = 'volume_fee' THEN total_amount END) AS volume_fee,
    SUM(CASE WHEN fee_name = 'per_auth_fee' THEN total_amount END) AS per_auth_fee,
    SUM(total_amount) AS total_icplus_fee
  FROM icplus_fees
  GROUP BY charge_id
)

-- Final query using the IC+ fees by charge table
SELECT
  date(transfers.date) as payout_date,
  transfers.id as payout_id,
  charges.id AS charge_id,
  charges.created AS charge_created_at,
  balance_transactions.id AS balance_transaction_id,
  balance_transactions.source_id,
  balance_transactions.type,
  balance_transactions.net,
  balance_transactions.currency AS settlement_currency,
  balance_transactions.amount AS settlement_amount,
  charges.currency AS presentment_currency,
  charges.amount AS presentment_amount,
  balance_transactions.exchange_rate,
  
  --icplus_fees columns
  icplus_by_charge.total_icplus_fee,
  COALESCE(icplus_by_charge.interchange, 0) AS interchange_fee,
  COALESCE(icplus_by_charge.card_scheme, 0) AS card_scheme_fee,
  COALESCE(icplus_by_charge.volume_fee, 0) AS stripe_volume_fee,
  COALESCE(icplus_by_charge.per_auth_fee, 0) AS stripe_per_auth_fee,
  COALESCE(icplus_by_charge.interchange, 0)
    + COALESCE(icplus_by_charge.card_scheme, 0) AS total_network_fees,
  COALESCE(icplus_by_charge.volume_fee, 0)
    + COALESCE(icplus_by_charge.per_auth_fee, 0) AS total_stripe_fee
FROM transfers
JOIN balance_transactions
  ON balance_transactions.automatic_transfer_id = transfers.id
LEFT JOIN charges
  ON charges.balance_transaction_id = balance_transactions.id
LEFT JOIN icplus_by_charge
  ON icplus_by_charge.charge_id = charges.id
WHERE
  date(transfers.date) = date({{PAYOUT_REPORT_DATE}})

The final Galtee report output looks like this:

And the itemized IC+ fee columns for those same rows:

Note: the example above is for illustration of the report format only. Some columns have been hidden for brevity and actual data and amounts have been redacted/modified.

Conclusion

Financial reporting has historically been a siloed process that relies on push-based files with fixed templates and static schedules. Whether the reports are delivered directly to finance team members or fed into ERP integrations, Stripe’s Query Run API makes it possible to build an on-demand, flexible reporting pipeline that can evolve alongside your business.

At Stripe, we’ve integrated AI into many of our workflows. We created Minions that write code and built our Knowledge AI Platform to help Stripes with a wide range of knowledge work. Many tasks are now faster and easier to complete thanks to these AI assistants.

An area where we haven’t seen as many improvements from AI has been prototyping. When making changes to stripe.com, our team often wants more information to evaluate the feasibility of a new design idea, but can’t always invest in developing a full engineering prototype.

One engineer built the first version of Harbor in about 40 days to solve that problem. We wanted to see whether AI could help designers turn a static design into something dynamic, without needing to understand code.

The result is an interactive, browser-based platform where designers can use AI to rapidly develop shareable prototypes using Stripe’s design systems and realistic mock data.

Harbor immediately improved the design phase of stripe.com projects, increasing engagement and driving clarity around the final vision. In one of the first projects to use Harbor, a designer built a new product page experience, including its animated hero. Engineers, product managers, and leaders interacted with it in real time, leading to quick iteration and consensus. When the page shipped, the animation carried over nearly one-for-one from the prototype.

Stripes across the company adapted Harbor for their own needs. Finance teams started presenting monthly actuals and business reviews as clickable prototypes instead of slide decks, a risk operations analyst turned a handle time analysis into a dashboard the rest of the team could inspect, and account executives built pricing proposals, battlecards, and ROI calculators for specific prospects.

A monthly actuals review built in Harbor: the running prototype on the left, the agent and its tool calls on the right.

Since May 2026, 3,000+ Stripes have created 12,000 prototypes, and 25% of Stripes have created at least one prototype in Harbor. This adoption came with more requests for increased collaboration within a Harbor prototype and interoperability with other AI tooling. Read on to learn how we built this functionality.

Building Harbor for collaboration with people and agents

Harbor’s interface is a browser tab with the running prototype and a chat panel. The author selects a design system for the prototype, setting its packages and starting files, then describes what they want. From there, Harbor works like this:

• The agent writes a multi-file source tree, and the page compiles and renders in the browser rather than on a server.
• The agent can read the rendered page, list and inspect elements, click, type, scroll, switch the viewport between mobile, tablet, and desktop widths, and take screenshots.
• When the prototype is ready, the author publishes it to a shareable URL. There’s one published version at a time, and every view compiles that copy fresh in the viewer’s own browser.

The agent writes files; Drydock compiles them in the browser; the agent inspects and iterates; viewers compile the copy.

Authors can give permission for others to comment on an element of the page or remix the published prototype into a copy of their own.

As prototypes became inputs to reviews, analyses, and production work, Stripes needed better ways to discuss changing designs and move them between AI tools. In the next sections, we’ll cover how we added commenting in Harbor, and how we integrated Harbor into other AI tooling at Stripe.

Anchoring comments to changing prototypes

As more Stripes began using Harbor, they wanted to leave comments. Because Harbor prototypes can change, people and agents need to easily understand comments in their right context. We built comments so they could stay connected to what prompted them, and let people and the agent know when that connection has changed.

Anchoring a comment to a page that the agent keeps rewriting is challenging. Harbor solves this by capturing several signals, including semantic labels, stable identifiers, text evidence, structural paths, list keys, and the surrounding context, such as a dialog or accordion, that needs to be opened to reveal the element. It also records whether a signal was unique at the time. When the agent updates the prototype, the resolution flow uses the stored information to report if the comment’s anchor element is attached, needs review, or is orphaned, rather than silently moving the comment to a plausible replacement.

A comment is pinned; the agent rewrites the page; it re-resolves: attached, needs review, or orphaned.

Published comments are tied to the version of the prototype where they were posted. When the author publishes a new snapshot, Harbor marks existing comments as stale so reviewers can tell which version the feedback is for.

Integrating Harbor with other AI tools

Harbor’s in-browser experience worked well for designers, but Stripes working in our other AI tools wanted to access it from there, so they could bring interactive visual prototypes into existing workflows. Two architectural choices made this possible: exposing Harbor’s toolset over our internal Model Context Protocol (MCP) server, and exposing Drydock, Harbor’s rendering engine, as its own service.

Harbor exposes a toolset through Stripe’s MCP infrastructure that allows other agents to create, read, update, and publish a prototype without needing a person to manually copy context into a new conversation. The same toolset is available to coding agents working on Stripe devboxes. They can pull a Harbor prototype’s file tree into a real repository, or push an idea from another workflow into Harbor for visual exploration. The handoff preserves the decisions around ownership and implementation while eliminating manual transcription between tools.

Drydock, Harbor’s rendering engine, has a small contract: it takes a multi-file React and TypeScript file tree and returns a running page inside the browser, alongside a report that includes compile and runtime failures, so that the agent can inspect and interact with the running result. Because that contract doesn’t depend on anything else in Harbor, other tools across Stripe can use it. This was particularly useful in Kai, our AI platform for knowledge work. Harbor gave Kai users the means to take the next step with a prototype. One of our producers, who run stripe.com programs across design, engineering, and editorial, ran a viewport analysis of stripe.com in Kai, then used Harbor to turn the results into a clickable prototype.

What we learned

Harbor began as an experiment in building with AI. Now it gives all Stripes a way to rapidly experiment and iterate on visual prototypes. We started with solving a small, team-focused problem and expanded beyond its original boundary thanks to our culture of friction logging, AI-forward culture, and colleagues who were willing to try out the early version of a tool, share what they made, and help develop useful pieces into shared infrastructure.

In Stripe’s internal AI tools, we’ve found that it’s effective to keep agents specialized (on research, coding, or browser-native tools) while exposing them to capabilities in other systems. In our viewport analysis example, we started with research in Kai, and built an interactive prototype in Harbor. In other examples, engineers mocked up internal admin tools in Harbor, then handed the generated prototype to a coding agent to rebuild for production. And Harbor’s own rendering engine became infrastructure for Kai.

What’s next

Our goal is to continue to make Stripe’s AI tools work together rather than have each tool solve every part of the workflow. For Harbor, we want prototypes to hold small amounts of state and connect to live data. That includes prototype-scoped databases and embeddable widgets that refresh internal data queries on their own, instead of requiring an agent to copy numbers into the source and rewrite them whenever the data changes.

We’re still early in understanding what becomes possible when research, code, and interactive artifacts can move between AI tools without losing their context. There’s a lot left to build, and the work spans infrastructure, developer tools, product systems, and AI all at once. If that’s the kind of problem you want to work on, we’re hiring.

Stripe provides the financial infrastructure businesses need to accept payments, manage subscriptions, send invoices, and move money. For many businesses, Stripe’s default behavior is exactly what they need - it works without any additional customization.

Sooner or later, you need something specific: a custom proration rule, a multi-step fraud response, data that doesn’t fit an existing Stripe object, or a purpose-built Dashboard view for your operations team.

Traditionally, that meant building around Stripe. A webhook sends an event to your server, your application runs some logic, and then calls the Stripe API. It’s a flexible pattern, but every customization adds more infrastructure, and more responsibility for availability, retries, state, secrets, security, and error handling.

Stripe extensibility lets you move more of that customization into Stripe. In this post, you’ll learn how to extend Stripe across three dimensions: logic, data, and user interface, using scripts, Workflows, Custom Objects, and UI extensions, and see how they work together in a complete example.

Prefer to watch? See how these capabilities work together in our Stripe Sessions talk, Extensibility with Scripts and Workflows.

Three dimensions of extensibility

Most Stripe customizations fall into three dimensions:

• Logic defines what should happen when something occurs in your business.
• Data represents the concepts and relationships that are unique to your business.
• User interface gives your team the tools it needs to view that data and take action.

You can use each independently, but they become much more powerful when they work together. Your interface can display your custom data, your data can contain business-specific actions, and those actions can invoke your logic.

Logic: From default behavior to custom rules

The best place to begin is usually Stripe’s default behavior. If the default meets your needs, there is nothing else to build or maintain. When you need something different, configuration gives you additional options supplied by Stripe or a partner. You can change how something behaves without writing the logic yourself.

Some rules, however, belong only to your business, and that is where custom logic fits. For example, when a customer changes plans midway through a billing period, Stripe can calculate the credit for the old plan and the charge for the new one down to the second - this is called proration. That works for most businesses. Yours might round to the nearest day, waive adjustments below $5, or use an entirely different calculation.

With a script, you can write that rule in TypeScript and deploy it to Stripe. When Stripe reaches the proration decision in its billing flow, it invokes your code, receives an answer, and continues processing. The code runs in a secure environment on Stripe, without requiring a server for you to manage. Scripts are for singular decisions: Stripe asks a question and your code returns an answer.

More complex requirements need a different process. For example, when an early fraud warning arrives, you might need to check the charge amount, issue a refund when it falls below a threshold, and notify your risk team in Slack.

Stripe Workflows coordinates these steps in the correct order. Workflows can be triggered by a Stripe event, started by someone in the Dashboard, or called from your backend. It can combine Stripe API calls, third-party integrations, and custom actions without requiring you to build the surrounding orchestration infrastructure.

Scripts run code. Workflows coordinate work.

Data: Teach Stripe the language of your business

Everything in Stripe is an object. Customers, Products, Payments, Invoices, and Subscriptions are all objects that represent the core concepts Stripe understands. But your business likely has other concepts that do not fit neatly into those objects. Imagine a vehicle rental company called Rocket Rides. A Driver maps naturally to a Stripe Customer, but the company also needs to represent Vehicles and Rentals.

A Vehicle has a make, model, year, and vehicle identification number. A Rental has a start date, status, assigned vehicle, and driver. These are structured entities with validation rules and relationships, not simply additional labels.

You could store some of this information in metadata, but metadata is not a complete data model. It does not provide typed fields, enforce a schema, or express relationships between objects.

Custom objects let you define these business-specific models inside Stripe. Rocket Rides can require every Vehicle to have a 17-character VIN and define a Rental that references both a Vehicle custom object and Stripe’s native Customer object.

In simplified TypeScript, that relationship looks like this:

interface RentalFields {
  startsAt: Date
  status: 'upcoming' | 'in_progress' | 'completed'
  vehicle: Ref<Vehicle>
  driver: Ref<Customer>
}

@CustomObject
class Rental extends BaseObject<RentalFields> {}

Once deployed, Stripe provides APIs for creating, reading, updating, and deleting these objects. Your business-specific data now has structure, relationships, and the same platform foundation as native Stripe data.

User interface: Build where your team already works

APIs give developers access to your custom data, but operations and finance teams should not need to query an endpoint to understand what is happening.

With UI extensions, you can create pages and side panels inside the Stripe Dashboard using Stripe’s design system. You choose where the experience appears and which information it presents.

For Rocket Rides, that could be a rental operations page containing the vehicle details, driver, payment history, rental status, and inspection information. Instead of switching between Stripe and a separate internal tool, the operations team gets a single view designed around the way it works. Viewing the data is only part of the job. When a vehicle is returned, the team also needs to end the rental.

Bringing logic, data, and UI together

Rocket Rides can add an End Rental button to its custom Dashboard page. That button invokes an action defined on the Rental custom object.

When an operator selects it, the action updates the rental status, triggers the inspection workflow, and marks the vehicle as available again. The team remains in the Dashboard while custom logic runs against custom data and coordinates the next stage of the process.

This is where the three dimensions of extensibility become one connected system:

• Custom objects model Rentals and Vehicles.
• A custom Dashboard page gives the operations team the right view.
• An action provides a business-specific operation.
• A workflow coordinates everything that must happen next.

The team clicks one button, but behind it Stripe is operating in the language of the business.

Start with what you need

Extensibility does not mean every Stripe integration needs custom code. Start with the default. Use configuration when an existing option meets your requirements. Build custom logic, data, or interfaces when the requirement is genuinely unique to your business.

Scripts let you define individual decisions. Workflows coordinate processes over time. Custom objects represent the concepts that Stripe does not model natively. UI extensions give your team tailored pages, side panels, and actions inside the Dashboard.

Together, they let you extend Stripe without turning every customization into another standalone system your team must operate.

Stripe provides the foundation. Extensibility lets you build the business only you can build.

Start building with Stripe extensibility.

The interesting part is what AI did to the stages that usually slow platform work down: the gap between an idea and a working prototype, between a prototype and a reviewable spec, between a spec and aligned implementation, and between implementation and polished deliverable.

AI compressed all of those gaps - not by replacing human judgment, but by making human judgment more effective by giving it better artifacts to operate on, earlier in the process. That changed the quality of our decisions, not just the speed of our output.

Platform work has an abstraction problem

When you're building an SDK, you're not building a feature a user clicks on. You're building primitives other developers will compose. The hard questions aren't "can we build this?" but "should we build it this way?"

What should the developer experience feel like? Where should boundaries live? What belongs in the model and what's intentionally outside it? How do you keep six product surfaces coherent when each team could reasonably optimize in a different direction?

In a traditional cycle, you discuss the idea, write a design doc, debate feasibility in the abstract, eventually build a prototype, discover rough edges weeks later, and course-correct. Each stage is expensive, so you do fewer of them, sequentially.

That sequential cost is the real bottleneck in platform work, not the typing speed. The bottleneck is how long it takes to get from idea to an artifact the whole team can evaluate.

A working prototype in two days

Early on, we were shaping how developers would define custom objects and attach behavior to them - part product design, part architecture, part platform strategy. We weren't asking "can we add methods to custom objects?" We were asking what the authoring experience should feel like, how much of the existing platform we could reuse, and whether the approach was sustainable as part of Stripe's broader extensibility architecture.

Without AI, this would have been a two-to-three-week effort of stubbing out the type system, building the transform pipeline, wiring up the demo, and writing the docs. The kind of work that's well-understood but time-consuming enough that you'd normally skip the prototype entirely and go straight to a design doc.

With an AI coding assistant, one engineer on the team built a working prototype in roughly two days - complete with a demo and documentation site.

That prototype wasn't the production code we shipped. But it was conceptually close to the production direction: author-defined custom objects, methods attached to those objects, generated runtime machinery, and a model that reused existing platform pieces rather than creating a bespoke system.

The value wasn't that one person built something fast. It was that the team's conversation shifted from speculation to evaluation. Without the prototype, we'd have been debating a design document, and design documents require the suspension of disbelief. People have to imagine the developer experience, imagine the runtime behavior, imagine whether the pieces fit together. A working prototype removed that gap. The discussion moved from "Could this work?" to "Is this the right shape?" and "Where should the boundaries live?"

That prototype ultimately convinced us to reprioritize the feature into scope for our next major launch. The decision happened weeks earlier than it would have otherwise, because we had a concrete artifact to evaluate rather than a speculative proposal to debate.

AI as architecture collaborator

The next challenge was turning prototype intuition into coherent architecture.

Prototypes create momentum, but platform work needs clean boundaries and durable abstractions. AI became useful differently here: not writing implementation, but helping us explore and articulate the implications of design choices across multiple surfaces.

Much of the architectural work was sharpening important distinctions:

• Product code shouldn't know or care how an extension is implemented
• Low-latency enforcement belongs in deterministic declarative artifacts, not user-authored functions on every write path
• A state machine is a lifecycle artifact; expressions are predicates inside that lifecycle
• Dashboard-authored and code-authored experiences should wrap the same primitive, not fork into incompatible languages

AI didn't invent those distinctions (the team's judgment was the source of truth) but AI helped us write down implications quickly enough to test whether our abstractions held across scripts, workflows, custom objects, SDK generation, runtime enforcement, and developer tooling.

Platform work is especially vulnerable to local optimization. Any individual surface can be made to work alone. The system only becomes coherent if the same abstractions hold everywhere. AI helped us keep more of the system in view at once.

Spec-first agent delegation

As the architecture solidified, we identified work naturally suited for delegation: bounded scope, clear correctness criteria, well-known patterns, strong connection to developer-facing behavior.

ESLint rules were a good example: they encode what's allowed in the authoring experience, what's unsafe, and what should fail early. But we didn't hand an agent a vague goal and hope for the best. That's the common failure mode with AI coding, and it produces work that looks plausible while quietly violating deeper constraints.

Instead, the workflow became disciplined:

1. Identify work bounded enough for agent delegation
2. Ask the agent to draft a detailed spec
3. Review those specs as GitHub issues before implementation begins
4. Implement using agent skills grounded in domain-specific guidance
5. Review output against architectural intent

Here's what one of those specs looked like in practice. A GitHub issue for a rule that prevents developers from using bare numbers in Custom Object fields (they should use Integer or Decimal instead):

## Rule Contract

- Rule name: co/no-bare-number
- Purpose: Disallow bare `number` in Custom Object fields, requiring Integer or Decimal instead.
- Spec reference: S-002 Custom Object DDL §4, §3.7, §12.1
- Severity: error
- Auto-fix: yes
- Requires type-checker: yes

## Required Behavior

Applies only to *.object.ts files. Targets type positions within the fields type — the type argument F passed to BaseObject<F>. The type-checker is required to resolve aliases and nested references.

## Invalid Examples

interface OrderFields {
  total: number;     // error
  discount?: number; // error
}

type MyNum = number;

interface OrderFields {
  count: MyNum;      // error (resolved through alias)
}

## Valid Examples

interface OrderFields {
  total: Integer;
  rate: Decimal;
}

## Auto-fix behavior

* Offer two auto-fix options: update the field to use the `Integer` or `Decimal` types from the extensibility-sdk

The spec defines exactly what "correct" means: which files it applies to, what it catches, what it doesn't, whether it auto-fixes. The agent drafts this, the team reviews and refines it, and only then does implementation begin. The review catches design issues such as "should this also fire inside action parameter types?" that would have been discovered much later in a code review-only workflow.

As this pattern scaled, we used it to produce roughly twenty ESLint rules that enforce the SDK's authoring constraints - sandbox boundaries, import restrictions, type safety requirements. The spec-review-implement cycle actually caught design issues earlier than a conventional "just write it" approach would have, because the spec review forced us to articulate what "correct" meant before anyone touched implementation.

Persistent guidance, not one-off prompts

Complex platform work can't rely on one-off prompting. Agents need context that persists: product principles, implementation constraints, architectural invariants, pitfalls specific to your system.

We invested in repository-local documentation written for AI consumption - architectural principles, boundary definitions, known anti-patterns. When agents made changes, the output was more likely to be globally consistent with platform intent, not just locally correct in isolation.

If the architecture says build-time validation is authoritative, the agent shouldn't defer a check until deploy. If the product model says expressions are deterministic, the implementation must reject loopholes that let side-effecting code into the evaluator path. Making those invariants available at the point of work raised the floor of what arrived for human review.

This also solved a collaboration problem. When multiple teams contribute to a shared codebase, onboarding cost is usually high. Persistent AI guidance reduced it. Engineers from adjacent teams could make architecturally consistent changes without weeks of context-building. The documentation that helped agents helped humans too.

Compressing the feedback loop

Near the end of the project, AI shifted to high-throughput refinement. As feedback came in from demos, design reviews, and hands-on use, we could turn around changes same-day that would normally take two to three days each. AI helped explore edge cases, reproduce subtle bugs, update documentation, adjust examples, generate targeted tests, and keep multiple artifacts consistent while details were still changing.

The final mile of platform work is where quality is won or lost. The architecture might be sound, but the deliverable only lands if examples are clear, demos are believable, docs match implementation, and rough edges are caught before users find them.

This is usually the phase where quality gets triaged away. Every piece of feedback competes with remaining implementation work, and most of it loses. AI changed that calculus. The marginal cost of responding to feedback dropped enough that we could incorporate most of it before the deadline rather than deferring to the next quarter. The deliverable shipped tighter than it would have otherwise.

What AI didn't do

AI did not replace architectural judgment. It didn't decide which abstractions were load-bearing. It didn't know which tradeoffs mattered most for Stripe's platform. It didn't automatically understand that two things similar in code represent fundamentally different product concepts.

In several places, raw output needed correction. AI could blur boundaries that needed to stay sharp. It could generate implementations that looked locally reasonable while quietly violating a deeper invariant. It could make plausible architectural claims that were subtly wrong. The more AI amplified output volume, the more important review discipline became — which is why the spec-first delegation model mattered so much.

The lesson is not that AI can independently drive complex platform work. It's that AI dramatically increases the surface area over which a strong team can apply judgment. The judgment still has to be there. AI makes it go further.

What this means for how we work

AI changes the economics of making ideas concrete.

Before, a working prototype, a detailed architecture brief, a full set of implementation specs, agent-readable guidance, and a tight test-and-refine loop would each have competed for scarce engineering time. Because they were expensive, you'd choose fewer of them - which meant more abstract discussion, later feedback, and less confidence early on.

With AI, the cost dropped enough that we could use more of them, earlier, across more surfaces. Instead of asking stakeholders to trust a document, we showed a prototype. Instead of asking engineers to infer intent, we wrote detailed specs. Instead of asking agents to guess constraints, we gave them reviewed issues and persistent guidance. Instead of accepting late feedback as too expensive, we folded it in.

That's the shift. Not "AI writes code faster" but "AI makes more of the development loop concrete earlier." When ideas become artifacts sooner, teams make better decisions, catch problems earlier, and build with more confidence.

For platform work - where the hardest part is getting a cross-functional team to agree to a shared conviction about the right abstractions - that's exactly the kind of leverage that compounds.

We're still early in understanding what this means for how engineering teams should be organized and how projects should be structured. But the direction is clear: the teams that benefit most from AI won't be the ones that use it to type faster. They'll be the ones that redesign their workflows around the new economics of making ideas real.

A failed payment request means a Stripe user did all the work to get a customer to pay, but lost the sale because of us. We never want this to happen. To minimize failed payments for our users, we target 99.9995% reliability. Maintaining that level of reliability while processing around 1.6% of global GDP is an exceptionally difficult technical challenge, but most of us who join Stripe’s infrastructure teams are here because we love technical challenges.

For almost 10 years, we used Envoy as our proxy for Stripe’s service mesh. It worked well for us for years, but as Stripe’s traffic grew and we increased our reliability targets, we started running into critical issues that made us wonder if we needed our own proxy.

We decided to try building a replacement for Envoy. We wanted better reliability and scalability, but we weren’t sure if we’d be able to match Envoy’s latency or CPU footprint. This was a technical risk: if our solution ended up slower or less efficient than Envoy, it would prevent us from deploying it.

Why did we build it ourselves?

Internal services at Stripe use our service mesh to communicate with each other. The data plane of the service mesh is responsible for request routing, load balancing, authorization, encryption, and other similar features.

Stripe’s service mesh handles millions of requests per second between thousands of services. One public API request relies on many internal service requests, so small improvements in data-plane latency or reliability make a huge difference in maintaining 99.9995% public API uptime.

Over time, a few reliability and latency issues we had with Envoy became large problems we could no longer ignore. For example, under consistent traffic, Envoy’s worker-based threading model means that each worker will usually hold a connection to every upstream endpoint it can route traffic to. The default deployment strategy is to run Envoy with one worker per CPU core, which means each server machine ends up with one outbound connection per client core.

Here is an example of what this would look like with two 8-core client machines load balancing sustained traffic between two server machines:

Every worker on both client machines maintains a connection to both server machines, which means each server machine needs to handle 16 connections for just these two clients. This becomes especially problematic if you run an infrastructure service that handles requests from the entire fleet (e.g., a service that processes application tracing data). That infrastructure service is forced to maintain connections for roughly every CPU core fleetwide, which is many hundreds of thousands of connections. Scaling up a machine enough to handle this many connections is expensive, and often the problem went unnoticed until too many open connections overloaded the service and caused an incident.

Over time, our Envoy rollouts also started to get increasingly risky, which forced us to roll out upgrades more slowly. Hyrum's Law is especially applicable at Stripe because our fleet contains many unique services. This means small behavior changes in Envoy updates would occasionally cause problems for us.

For example, in 2024, we ran into an especially scary issue when trying to roll out an Envoy upgrade. This upgrade pulled in a new version of nghttp2, which introduced a rapid-reset HTTP/2 DDoS defense to protect against a vulnerability. Unfortunately, when using the default settings, this mitigation accidentally rejected some legitimate traffic to one of our services. Luckily, we caught this in a QA load test and fixed the configuration before rolling out to production, but this was a close call. If our load test didn’t replicate the specific traffic pattern the service receives in production, we might not have noticed this regression until it started rejecting real requests. A single production incident like this could jeopardize our 99.9995% reliability goal for the whole year.

Running Envoy also limited our ability to provide custom features for Stripe. For example, Stripe’s Ruby services require big, expensive machines to run. We had designed a new routing approach we could use to distribute traffic more efficiently across backend machines to reduce our Ruby machine sizes and make our Ruby backends more reliable. But this would have required too much customization of Envoy, so we never pursued it.

What we built

Mesh-proxy is our Go proxy and Envoy replacement. To efficiently implement all the features of a proxy, mesh-proxy has its own implementation of HTTP/1.1 and HTTP/2. Mesh-proxy connects to our service registry directly for service discovery and supports retries, hedging, rate limiting, and dynamic priority-based request routing.

Go has a few features that helped make mesh-proxy successful. Goroutines are cheap to spin up, which allows us to spin up new ones for every connection. Go’s official HTTP/2 framing library was very useful, and Go is well-supported at Stripe, so we benefit from great developer tooling.

Our biggest risk in building mesh-proxy was that we weren’t sure if we’d be able to match Envoy’s latency or CPU footprint, but our early load tests looked good compared to our Envoy deployment. After rolling out mesh-proxy, we saw around half the CPU under high load, and roughly a 50% latency reduction compared to our Envoy deployment. At our scale, this saves around 3,000 days of cumulative inter-service latency each day.

To address the connection cardinality problem, we built mesh-proxy with a different concurrency model. Instead of a worker-based model with one worker per core, mesh-proxy uses one read goroutine and one write goroutine per connection. Because mesh-proxy multiplexes requests across a shared connection rather than partitioning requests across many workers, we only need one connection per host, compared to one connection per worker with Envoy.

Here is what the 8-core client machines from above look like after migrating to mesh-proxy:

Each client machine only needs one connection to each server machine, which means the server machines only need to maintain two connections for these two clients. This connection reduction means fleetwide services don’t need to maintain nearly as many connections, which allows them to run reliably on smaller machines. The downside is that this approach required more work to coordinate shared request state across goroutines, but we felt this tradeoff was worth it.

We also found that connecting to our service registry directly from mesh-proxy was more efficient than xDS in many cases. Our Envoy deployment tended to cause more xDS updates than were necessary, which used extra CPU and memory on every machine. Here are a couple of graphs of the most significant example of a service that previously received an enormous number of xDS updates. You can tell when mesh-proxy was rolled out by the massive drop in CPU and memory.

In addition to the performance improvements, rolling out mesh-proxy enabled us to make improvements that were not previously feasible for us with Envoy. We rolled out a feature that uses custom Ruby infrastructure code to balance traffic more evenly between Ruby backend replicas, which gives us 15–20% more headroom before traffic bursts overwhelm the machines. We were also able to roll out an overhaul of our priority-based routing system that has enabled improvements to our deployment infrastructure, rate limiting system, and traffic shifting logic. These features and others on our roadmap were far too custom for us to realistically build into our old Envoy deployment.

What’s next

It’s a little counterintuitive that building something in-house would be more reliable than operating a battle-tested open-source project. But our internal service mesh has become complex and custom enough that we’ve had great success building our own proxy. All mesh-proxy code is reviewed by our team and rigorously tested with unit tests, end-to-end tests, and synthetic tests before deployment.

Because our team operates components that handle communication between almost every service at Stripe, we have a unique advantage for identifying inefficiencies and finding solutions. We’re currently working on capabilities like anomaly detection and smart routing so we can find and fix issues before users feel any impact.

If you’re interested in improving infrastructure at Stripe, we’re hiring.

That speed is what developers tell me constantly now: building on Stripe has never been this quick. And they are right. The next step is helping the integration understand what the money is supposed to do, not just how to move it.

I am the Technical Advisor to the Head of Professional Services EMEA, and reviewing integrations for large users is most of my job, so I see where the gaps are. Someone builds an integration, it looks correct, and most of it is. Then they come to us saying it’s not working as expected, even though on paper it should be. The code ran, but the result did not match the business intent behind it.

When the business intent is missing, nothing throws and nothing is logged. The integration simply starts sending signals, money rests in states it should not rest in, and a week later a support ticket lands: "I was charged and got nothing." The code was correct. The business intent behind it had not been made explicit yet. The good news is that these signals are readable, and once you can read them, you can get ahead of them.

Why payments are different

Payments are different from most software a team builds. The developers usually have strong development skills, but not always payment skills. They work from the API reference and build against it the same way they would build anything else.

Two things are usually missing at once: the payment knowledge, and the business intent behind the money. Put those gaps together and you get code with correct syntax that passes tests, but then behaves in ways nobody decided on in production. It does not crash. It moves money along paths the business never chose. The model was never the constraint. Knowing what the money is supposed to do is the part worthy of your attention, and the part you can add.

That knowledge rarely announces itself as an error. Instead the integration emits signals, small clues in the data that something is off. Each looks minor and unrelated on its own. Read together, against what the money was supposed to do, they point at a single source, the part a developer cannot see without payment knowledge. That is where a review begins, and it is exactly what you can teach the integration to check for itself.

This post walks you through how to read those signals, encode the business intent, and validate every build against it, whether the build came from a person or an agent.

The PaymentIntent and the business intent

When I start an integration review, I ask for the first fifteen minutes with no code, just the business: what should happen to the money, and what must never happen to it. If I read the code first, I get biased and start reasoning from code to code. I would rather build the end-to-end business version in my head, find the payment pattern that fits it, and only then look at how it becomes a PaymentIntent.

That order matters, so enforce it within your team: define the business intent before the payment intent. The two share a word for a reason. The PaymentIntent is the Stripe object that tracks the payment through its lifecycle. The business intent is the set of decisions behind it, the rules the money has to obey. An agent is very good at producing the first. It cannot know the second unless someone tells it.

Here is what that gap looks like in code. A return_url is required for any redirect-based payment method, so on its own it tells you nothing. The signal is a flow that redirects every customer away, even card payments that never needed a redirect:

// Client. redirect: "always" bounces every customer to the return page,
// even card payments that never needed a redirect.
// redirect: "if_required" would keep those on the page. Why always? And what runs there?
const { error } = await stripe.confirmPayment({
  elements,
  confirmParams: {
    return_url: "https://example.com/order/complete",
  },
  redirect: "always",
});

The syntax is correct. But the object cannot tell you why every payment leaves the page. Is fulfillment meant to happen on that return page? Was redirecting everyone a deliberate business decision, or just the default nobody questioned? The business intent behind it is nowhere in the code, and neither the object nor the model can enforce a rule it was never given.

Signals that the business intent is missing

You have probably seen at least one of these. On their own they look like small, unrelated bugs in different parts of the stack. Put them next to the business intent and they turn out to be the same failure wearing five faces.

An authorization rate of 43% that was really above 90%. A retry loop was resubmitting hard declines, authentication_required, incorrect_number, or expired_card, none of which passes on a second attempt. It looks like a processor problem. The cause is retry logic that treats every decline the same instead of branching on the decline_code.

PaymentIntents resting in requires_action. A server-side confirm with no client-side handleNextAction, so the 3DS step is never triggered and the intent waits for an authentication nobody sent. Money that could have been collected is instead stuck, and nothing errors.

A requires_capture with money held and no order behind it. The order is created by a client call that runs after the authorization lands. Kill the tab in that window and the money is held with nothing behind it. The customer was charged and got nothing, and the exception tracker is empty.

Connected accounts that quietly went restricted. No subscription to account.updated, so an account hits requirements.currently_due, flips to restricted, and keeps taking payments into testmode_charges_only. Live volume is lost while the code that moves money keeps working.

Async payment methods refunded like cards. The integration fulfills off the return URL, ignores payment_intent.processing, and never handles the succeeded that lands a day or two later. Revenue you already earned, refunded.

Independent signals like these tend to arrive late, after the money has already moved. Five subsystems, five different bugs. None threw an error. None is a syntax problem. Each one is a decision about how the money should behave that nobody actually made. On their own they look unrelated, but read against the business intent they share one source: the payment knowledge that was never written into the code. Once you can read them, you can encode them.

Encoding the business intent

This part is harder, because the right answer depends on the team, and there is no single best practice. Think about how you already treat code style: a formatter and a linter keep the syntax consistent so anyone can read it. Business intent needs the same discipline, and most teams do not have it yet. Whether you use a well-named function, a comment that states the rule, a pull request linked to a documented requirement, metadata on the object, or a Stripe custom object does not matter. The point is that the decision is written down where the next person, or the next agent, cannot miss it.

Here is the test I use. I ask a developer why a parameter is set the way it is, and I want more than the technical meaning. I want the business needs behind it. Why does every payment redirect? Why do we retry, and which declines? What happens when a connected account becomes restricted? If the answer is "that is just how it was generated," the intent was never encoded.

Metadata is a good habit here, because it makes the intent legible from the outside. Open a PaymentIntent in the Dashboard, and if the metadata says which order and decision it belongs to, you understand the business behind it without reading the code:

// Server. Put the business context on the object itself.
const order = await orders.createPending(); // your order id, status "pending"

const paymentIntent = await stripe.paymentIntents.create({
  amount,
  currency,
  // Business decision: authorize now, capture only once the order is confirmed.
  // Never hold funds we cannot fulfill.
  capture_method: "manual",
  // Business decision: every authorization must trace back to an order.
  metadata: { order_id: order.id },
});

Validating every build against the intent

We have an agent to build the code. We need an agent to validate it.

The best teams I work with have stopped treating the build agent as the whole story. They run a small system of agents. An orchestrator coordinates the work for the development team. A builder agent writes the code. And a verifier agent runs after the build, with one job: check that what was built actually does what the money is supposed to do.

The verifier is where it comes together. To build one, someone has to encode the business knowledge into it. You cannot check that a terminal decline is never retried, or that no order exists without an authorization behind it, unless someone states those rules. So the verifier forces the business intent to be written down. In most reviews the business owner never stated it up front, which is exactly why nothing encoded it. Building a verifier forces the conversation that should have happened at the start.

The important part is that those rules are code, not a checklist. Here are three of the five signals from earlier, each written down as something a verifier can run on every build. The other two follow the same shape:

// Verifier rules, each one a signal that cost a live integration money.
const paymentRules = [
  {
    rule: "Never retry a terminal decline",
    check: (retry) =>
      !["authentication_required", "incorrect_number", "expired_card"]
        .includes(retry.declineCode),
  },
  {
    rule: "A held authorization must have an order behind it",
    check: (pi) =>
      pi.capture_method !== "manual" || Boolean(pi.metadata?.order_id),
  },
  {
    rule: "Async payment methods handle their asynchronous result",
    check: (integration) =>
      integration.subscribesTo("payment_intent.processing") &&
      integration.subscribesTo("payment_intent.succeeded"),
  },
];

How these rules run is up to the team, and both common paths work. You can encode them in a skill the verifier agent loads before it reviews a build, so the check happens conversationally as part of the agent workflow. Or you can wire the same rules into automated testing, a CI step that inspects the integration and fails the build when a rule is violated, the same way a linter fails on a style break. The teams getting the most value do both: the skill catches intent gaps while the code is being written, and the test suite enforces the same rules on every merge so nothing regresses later. What matters is not the mechanism but that the rules run on every build automatically, not when someone remembers to look.

None of these came from a specification. Each one came from an integration that looked correct and lost money until someone read the signal and wrote the rule down. That is the point: the rules live where the code can be checked against them, and writing them forces the conversation with the business owner that should have happened first.

And that is the shift: judgment stops being personal and becomes shared. A business team encodes what correct means into the verifier, and every build, whoever or whatever wrote it, is checked against the same rules. None of this removes the human. Encoding the knowledge into an agent does not hand over the decision, it makes it explicit and repeatable. The person still owns what correct means; the agents only enforce it.

Conclusion

The value is moving. The low-level code that makes a payment go through is getting cheap, fast. What is becoming valuable is the judgment above it: knowing what the money is supposed to do and making sure the code obeys it.

So read the signals your integration is already sending. State the business intent out loud, encode it where the code can be checked against it, and keep a human owning what correct means. Implementing the PaymentIntent is getting cheap. Being right about the business intent behind it is now the whole job.

SaaS platforms don't fit a single mold when it comes to payments pricing. An early-stage vertical software company needs simple, flexible tools to experiment and iterate. A platform moving upmarket needs granular cost control and the ability to offer sophisticated pricing to enterprise customers. And as AI features reshape how platforms monetize, that diversity is only going to increase.

Connect has made significant strides on both ends of that spectrum. For platforms that want flexibility without complexity, segmented pricing lets you set and manage rates directly from the Dashboard with the ability to differentiate by payment method, geography, and other attributes. For platforms moving upmarket, Interchange Plus Plus (IC++) takes things further: it gives you the ability to offer cost-plus pricing to your users, passing network costs transparently while protecting your margins, without the operational burden of managing rate tables, navigating messy reconciliation, or tracking constant interchange updates from the networks.

That last capability is proving to be a meaningful unlock. In the article below, we dig into how network cost passthrough actually works: what it means for your pricing model, how to set it up and how it shows up in your users' fee reporting.

Why blended pricing hurts platform margins

On a blended rate, the platform absorbs all interchange variance. When your card mix is predictable, this isn’t a problem. But premium rewards cards, corporate purchasing cards, and high-interchange consumer cards can cost materially more in network fees than your blended rate assumes. The difference comes straight out of your spread, and as platforms scale and attract larger, more sophisticated merchants, that card mix tends to shift in the higher cost direction.

Network cost passthrough solves this by moving the platform to IC++: interchange and card scheme fees flow directly to connected accounts at cost, and the platform earns a clean, protected margin on top. Regardless of card mix, the economics become predictable. The operational headache of tracking interchange schedules, managing rate table updates, or reconciling cost variances disappears. And for connected accounts, the model is actually more transparent: they receive reporting on the network costs attributed to their payment, not a blended approximation of it.

That combination: margin protection for the platform and cost transparency for users, is why IC++ is increasingly the default choice for platforms moving upmarket.

Setting the stage: IC+ vs IC++

IC+ and IC++ are related but distinct offerings for Connect platforms:

• IC+ (Interchange Plus): A pricing model where the platform is charged the underlying network costs (interchange + scheme fees) plus a Stripe markup, instead of a single blended rate.
• IC++ (also referred to as network cost passthrough for platforms): A Connect capability built on top of IC+ that lets a platform pass its network costs through to its connected accounts. In this case, the platform can offer IC+pricing to its own connected accounts rather than charging them a blended rate.

How network cost passthrough (IC++) works

Eligibility requirements

For your platform to be eligible for network cost passthrough, the following must be true:

• Your platform must be on IC+ pricing
• Your platform must control pricing (IC++ is only relevant if the platform is on a buy-rate, not on revenue share)
• The connected account must have the transfers capability enabled
• The connected account should be the Merchant of Record of the transaction: in practice, this means you’re either using Direct Charges or Destination Charges with the on_behalf_of parameter fund flows
• The platform and connected account pair must be in eligible geographies (you can work with your account team to ensure geographical availability)

Enable network cost passthrough for your connected accounts

You can enable Network Cost Passthrough for a connected account either on the Dashboard or through the Stripe API.

In the Dashboard, navigate to the connected account's detail page. In the monetization section, toggle on "Pass through network costs" in the Network costs tab.

Through the API, create a Pricing Config Scheme of type network_costs for the connected account using the Stripe-Account header:

curl POST https://api.stripe.com/v1/pricing_configs/network_costs/schemes \
  -u "sk_live_xxxx:" \
  -H "Stripe-Version: 2026-06-24.preview" \
  -H "Stripe-Account: CONNECTED_ACCOUNT_ID" \
  -d enabled=true

To check the current status for a connected account:

curl https://api.stripe.com/v1/pricing_configs/network_costs/schemes/current_at \
  -u "sk_live_xxxx:" \
  -H "Stripe-Version: 2026-06-24.preview" \
  -H "Stripe-Account: CONNECTED_ACCOUNT_ID"

Once enabled, IC++ passes eligible card-network costs, including interchange, scheme fees, and applicable adjustments, through to the connected account at cost. It does not pass through separate Stripe product fees.

In practice, Stripe first charges network costs to your platform account on your IC+ billing schedule (typically within two days of the payment occuring). Within a few hours, we recover these costs from the connected account’s balance and add them to the platform’s balance via a Balance Transaction of type platform_fee_transfer. Note that if the connected account has paid out its funds, issued refunds, or otherwise reduced its balance before the recovery occurs, the network cost recovery can take the account negative. In this case, payouts are paused until the connected account’s balance goes positive again.

Adjust the pricing for your connected accounts

To accommodate this change, your platform’s existing blended application fee, which was priced to absorb network costs, needs to come down.

If you use Stripe's Platform Pricing Tool (no-code pricing management), the recommended approach is to create a dedicated pricing group for IC++ accounts rather than modifying your existing rules. Add a condition of "Network cost passthrough = Enabled" to scope the rule correctly, then set a lower volume fee that reflects your Stripe fees and your markup, without the network costs.

Alternatively, if you manage pricing programmatically, you can update your own internal pricing engine to accommodate for this change.

Reporting and reconciliation for your merchants

As you change your pricing strategy for your connected accounts, you must accompany this change by providing them with new reporting capabilities. You can help your connected accounts understand their network costs by sharing the following reports with them:

• IC+ plan-level report: This report shows data aggregated at the calendar month level. This helps connected accounts understand the monthly network costs computed across all their charges. It provides interchange plan names and an aggregated scheme fee total
• IC+ transaction-level report: This report helps connected accounts understand transaction costs at an individual-transaction level. It provides information about which charges led to higher network costs and how refunds and disputes impact network costs. This report shows data aggregated by calendar month.

Both reports provide complementary information. You can access the reports for a connected account in several ways:

• Stripe Dashboard (for connected accounts with Dashboard access): this route requires no technical lift at all from you as a platform.
• Network cost passthrough embedded component: you can use Connect embedded components to add connected account dashboard functionality to your website. These libraries allow you to grant your users access to Stripe products directly in your dashboard. This route requires very little technical lift from you as a platform.
• Reporting API: our Reporting API lets you programmatically access the same financial data that's in your Dashboard’s financial reports. This route requires some technical lift from you as a platform.
• Sigma or Stripe Data Pipeline (for platforms with access to these two products):  to run custom analyses and integrate network cost data into your existing workflows, you can access this report data in Sigma and Stripe Data Pipeline. Similarly, this route requires some technical lift from you as a platform.

Regardless of how you access the report, the network cost schema is the same and is described here in our documentation.

How to deploy this new pricing strategy

Start with a pilot cohort

Enabling IC++ is a pricing change with real financial implications for your connected accounts. We recommend starting with a pilot cohort of a few connected accounts that are good candidates:

• High-volume, payment-aware accounts: merchants who already think carefully about their processing costs and will understand the change quickly
• Commercially engaged: accounts you have a close relationship with and can get feedback from

Communicate before you enable

Connected accounts need context before they see new line items on their statements. Before enabling this change for a cohort, send a short explanation covering: what is changing, why (transparency and cost accuracy), what their new fee structure will look like, and where the connected accounts can find the IC++ reports.

Embed IC++ into your go-to-market motion

Once the pilot validates your rollout approach, IC++ becomes a commercial differentiator in addition to being an operational change. For prospecting, IC++ is a key value proposition with enterprise and payment-aware buyers who have outgrown blended pricing elsewhere. Position IC++ as a premium tier with greater transparency for sophisticated operators.

Get started

Network cost passthrough is available for eligible Connect platforms today. If you're ready to move your connected accounts to IC++, the full documentation covers everything from enabling passthrough per account to reading the network cost reports.

If you're not yet enabled for IC++ at the platform level, or you want to talk through whether this pricing model is the right fit for your business, reach out to your Stripe account team. They can confirm your eligibility and help you build a rollout plan.

How does the fridge turn a sensor signal into a trusted grocery order? How does it find an available product, choose a delivery window, and pay on the household’s behalf, without receiving unrestricted access to the household’s card or wallet?

For the fictional grocery marketplace GreenMart, the first architecture choice is not about payment. It is about how GreenMart becomes discoverable to agents. GreenMart could build and operate its own ACP product feed, discovery document, and checkout implementation. Instead, it uses the Stripe Agentic Commerce Suite to upload or connect its catalog and expose a dedicated, hosted ACP endpoint.

That choice lets GreenMart share current product, price, and availability data with AI agents without building and maintaining a protocol-specific public surface itself.

The solution includes:

• Stripe Agentic Commerce Suite to turn GreenMart’s existing catalog and commerce data into a hosted ACP storefront. Stripe can also expose UDP storefront and eventually manage any changes to protocols.
• Agentic Commerce Protocol (ACP) for the fridge buying agent and the companion mobile app to interact with that storefront.
• Household authorization policies to define what the shopping agent may buy.
• A household payment authorization experience—for example, a fridge companion app—that decides when the agent may use household payment authority.
• Link for AI wallet  for agents as an optional way to give the shopping agent bounded payment capability without exposing a card to the fridge or marketplace.
• Shared Payment Tokens (SPTs) as the underlying Stripe payment primitive for direct Stripe integrations; Link can handle those mechanics for the agent.

We follow this core principle: an agent should be able to make approved decisions autonomously, but it should not receive more authority than the buyer intended.

We assume the fridge’s sensors and inventory-detection model already exist. This post focuses on the commerce flow after the fridge detects that something needs to be bought.

Why GreenMart uses the Suite instead of building ACP itself

A marketplace’s product information is usually scattered across catalog, inventory, pricing, delivery, and order-management systems. Implementing ACP directly means turning those systems into a protocol-facing product feed and checkout API, keeping that interface available, and maintaining compatibility as the protocol evolves.

GreenMart already needs to own the source data and business decisions: what is in stock, what substitutions are acceptable, which delivery windows are possible, and whether an order can be fulfilled. It does not need to own the agent-facing protocol surface as well.

With the Stripe Agentic Commerce Suite, GreenMart provides its catalog and relevant commerce information to Stripe. The Suite exposes the hosted ACP endpoint that agents call. GreenMart retains its role as the merchant and source of truth for inventory, pricing, fulfillment, and order operations.

The benefit is practical:

• GreenMart can make its catalog available to agentic surfaces without separately implementing discovery, feed hosting, and protocol routing.
• The fridge agent can use a standard ACP interaction rather than a GreenMart-specific integration.
• The companion mobile app can display the same authoritative checkout state that the agent received.
• GreenMart can concentrate engineering effort on catalog quality, inventory freshness, and fulfillment—not protocol infrastructure.

The hosted endpoint is an abstraction boundary, not a replacement for GreenMart’s commerce system. GreenMart must still keep the underlying information accurate and re-check price and availability before an order is accepted.

The GreenMart shopping agent

Every Friday, the fridge checks the household’s inventory and prepares a grocery order for Saturday-morning delivery. The household has configured preferred brands, dietary requirements, acceptable substitutions, delivery windows, and a weekly spending limit.

The fridge also supports an urgent mode. If milk or eggs run out, the agent can request same-day delivery—but only for approved items, within a lower budget, and without automatically accepting substitutions.

The roles stay deliberately separate:

• The fridge identifies what is missing.
• The shopping agent builds a basket and communicates with GreenMart through ACP.
• Stripe Agentic Commerce Suite hosts GreenMart’s ACP-facing catalog and checkout surface.
• GreenMart provides the source information and performs its normal inventory, fulfillment, and order operations.
• Household policy decides whether the agent may request payment.
• The household payment authorization experience decides whether payment authority is issued.

One hosted marketplace surface, two ACP clients

GreenMart sends catalog, price, inventory, and delivery information from its commerce systems to Stripe Agentic Commerce Suite. The Suite exposes that information through a hosted ACP endpoint.

The fridge buying agent is one ACP client. It uses the endpoint to discover products and create a checkout. The companion mobile app is the household-facing ACP client: it uses the final checkout state to show what the agent wants to buy, apply household policy, and initiate the supported payment-authorization flow.

This is why the hosted endpoint is useful: GreenMart avoids a bespoke protocol implementation, while the agent and app still have a consistent way to exchange discovery and checkout information.

The end-to-end flow

Here is how the scheduled or urgent grocery order moves through the system.

The agent never needs to understand GreenMart’s internal catalog schema. It sees the information through ACP. GreenMart never needs to build a custom API for this agent. It supplies information to the Suite and receives the resulting order in its normal fulfillment flow.

The household policy is core to the companion app

Household policy is a concrete configuration owned by the people who control the bridge between the household’s agent and payment authority. The companion app should give them a way to define who may buy, what they may buy, and when the agent must stop and ask.

A policy setup flow can combine:

• Guided controls: approved agents, merchants or categories, item exclusions, per-order and weekly limits, delivery locations and time windows, substitution rules, and approval thresholds.
• Policy templates: starting points for common arrangements, such as routine household replenishment, emergency purchases, or a child’s limited spending allowance.
• Natural-language authoring: as an optional convenience, an LLM can turn a request such as “restock essentials up to €80 per week, but always ask before changing brands” into proposed structured rules. The household should review and confirm the resulting rules before they are enabled.
• Lifecycle controls: named policy owners, policy versions, an audit trail, expiration dates, and a quick way to pause or revoke the agent’s authority.

Evaluate the final checkout, not an estimate

The household policy is not a payment credential. It determines whether the agent may request payment for this specific final checkout. If the amount, item, seller, or delivery terms violate policy, the agent can choose another option or ask the household to approve an exception.

That evaluation uses a deterministic policy engine against the merchant, items, quantities, total, currency, selected fulfillment option, delivery address or window, substitutions, and any applicable budget already spent.

The result should be explicit: approved, requires household approval, or denied.

An approved result allows the app to request bounded payment authority through Link or another supported payment path. A checkout that exceeds a limit or introduces an unapproved substitution can be revised by the agent, escalated to a household member, or canceled. This keeps the policy understandable and auditable: an LLM may help people write it, but it should not be the component that decides whether a particular payment is allowed.

Below is an example of authoritative results after the shopping agent creates or updates the checkout through GreenMart’s Stripe-hosted ACP endpoint.

{
  "id": "chk_greenmart_123",
  "status": "ready_for_payment",
  "currency": "usd",
  "line_items": [
    {
      "id": "li_milk_organic_2l",
      "item": {
        "id": "gm_milk_organic_2l",
        "name": "Organic 2% milk",
        "unit_amount": 449
      },
      "name": "Organic 2% milk",
      "unit_amount": 449,
      "quantity": 2,
      "availability_status": "in_stock",
      "totals": [
        {
          "type": "subtotal",
          "display_text": "Organic 2% milk",
          "amount": 898
        }
      ]
    },
    {
      "id": "li_eggs_free_range_12",
      "item": {
        "id": "gm_eggs_free_range_12",
        "name": "Free-range eggs, 12 pack",
        "unit_amount": 487
      },
      "name": "Free-range eggs, 12 pack",
      "unit_amount": 487,
      "quantity": 2,
      "availability_status": "in_stock",
      "totals": [
        {
          "type": "subtotal",
          "display_text": "Free-range eggs, 12 pack",
          "amount": 974
        }
      ]
    }
  ],
  "fulfillment_options": [
    {
      "id": "delivery_sat_0900_1100",
      "type": "shipping",
      "title": "Saturday delivery, 09:00–11:00",
      "selected": true,
      "totals": [
        {
          "type": "shipping",
          "display_text": "Delivery fee",
          "amount": 499
        }
      ]
    },
    {
      "id": "delivery_sat_1100_1300",
      "type": "shipping",
      "title": "Saturday delivery, 11:00–13:00",
      "selected": false,
      "totals": [
        {
          "type": "shipping",
          "display_text": "Delivery fee",
          "amount": 299
        }
      ]
    }
  ],
  "totals": [
    {
      "type": "subtotal",
      "display_text": "Subtotal",
      "amount": 1872
    },
    {
      "type": "shipping",
      "display_text": "Delivery fee",
      "amount": 499
    },
    {
      "type": "tax",
      "display_text": "Tax",
      "amount": 13
    },
    {
      "type": "total",
      "display_text": "Total",
      "amount": 2384
    }
  ],
  "messages": []
}

Which becomes the following policy-evaluation view derived by the fridge:

{
  "checkout_id": "chk_greenmart_123",
  "seller": "GreenMart",
  "total": 2384,
  "currency": "usd",
  "selected_delivery": "Saturday delivery, 09:00–11:00",
  "items": [
    {
      "product_id": "gm_milk_organic_2l",
      "quantity": 2,
      "amount": 898
    },
    {
      "product_id": "gm_eggs_free_range_12",
      "quantity": 2,
      "amount": 974
    }
  ]
}

id, status, line_items, fulfillment_options, and totals are ACP checkout concepts. The actual names and optional fields should follow the current ACP checkout schema.

Where payment authority lives

The app does not store card details. It uses the final ACP checkout as the purchase context, applies the household’s policy, and can either ask for an explicit approval or let the household grant the shopping agent bounded access to its Link wallet for agents.

That gives the full system two controls:

1. Household policy decides whether the agent may request payment for this particular checkout.
2. The household chooses how payment authority is issued: explicit approval for a purchase, or a pre-authorized Link capability with guardrails.

Link is an optional payment-authority layer, not a prerequisite for ACP or the Agentic Commerce Suite. An implementation can still use a different supported wallet or a direct SPT integration when that is the right product choice.

Optional: let Link handle the payment credential

If the household gives the shopping agent access to its Link wallet for agents, the agent does not need to handle card data—or, for a Stripe-processing marketplace, the details of an SPT—at all. It still needs the final checkout and household policy decision before it asks Link to pay.

GreenMart processes payments on Stripe

For a marketplace like GreenMart that processes payments on Stripe, Link can provide the agent’s payment capability and handle the Stripe-specific credential handoff. Under the hood, the Stripe payment flow uses a Shared Payment Token and a PaymentIntent to process the transaction. GreenMart receives the payment result, not the household’s card details.

That means the buyer-facing flow can stay simple:

1. The agent creates an ACP checkout through GreenMart’s Stripe-hosted endpoint.
2. The companion app evaluates the final checkout against household policy.
3. Link authorizes the agent to pay GreenMart within the household’s limits.
4. The hosted checkout completes and GreenMart receives the confirmed order.

The agent and companion app do not need to create, transport, or interpret an spt_… identifier in this path. SPTs remain the Stripe plumbing behind the authorization. For the lower-level model, a merchant creates a PaymentIntent using the granted SPT; see Shared Payment Tokens.

GreenMart does not process payments on Stripe

Link can also support an agent purchasing from a merchant that is not processing payments on Stripe by issuing a virtual card for the transaction. The virtual card can carry the same kind of bounded authority the household intended—for example, a capped amount and a short expiry window of a few hours—rather than exposing the household’s reusable card credentials.

This gives the agent a payment credential that a non-Stripe merchant can accept through its existing card-processing stack. Availability and the exact guardrails depend on the Link and Issuing-for-agents capabilities enabled for the household and merchant, so production teams should validate the current product and integration requirements before relying on this path.

Use direct SPTs only when you need the lower-level integration

A direct SPT flow remains useful when the agent, wallet, or marketplace needs to control the token exchange explicitly. In that model, after policy approval a supported wallet returns a GreenMart-specific SPT; the marketplace then uses it to create a PaymentIntent on Stripe.

Whether Link abstracts the token or the integration passes an SPT directly, the security boundary is the same:

• The agent receives bounded payment authority, not a card number.
• GreenMart receives a confirmed order through its commerce integration.
• Retries must be idempotent, and payment/order events must be reconciled through verified webhooks.
• Revoked or expired payment authority must prevent order completion.

Design for the moments when the agent should stop

Suppose GreenMart’s preferred milk is unavailable. The marketplace offers a larger replacement, but the replacement raises an urgent order from $23.84 to $26.10.

The agent should not silently accept the change if it exceeds the household’s policy. It can find another eligible product, remove the unavailable item, select a lower-cost delivery window, or ask the household to approve the higher total.

That is what bounded autonomy looks like: the agent can take routine action quickly, and it can recognize when the decision belongs to a person.

Where the Model Context Protocol fits

This architecture does not require the Model Context Protocol (MCP)  on the purchase path. Stripe Agentic Commerce Suite gives GreenMart a hosted ACP endpoint, and the fridge agent and companion app use ACP to work with the marketplace.

MCP can still be useful for optional capabilities in MCP-enabled hosts: meal planning, loyalty lookup, recipe-based baskets, delivery recommendations, customer support, or fridge-side tools that interpret sensor data. Those extensions remain separate from GreenMart’s hosted commerce surface.

Reference implementation

The companion sample implements mocked fridge inventory signals, household policy evaluation, both an ACP- and ACS- based checkout, a household payment-authorization step, SPT-based payment, and webhook-safe order confirmation. Its developer console shows the full flow, including the distinction between a policy decision and payment authorization.

Explore the Smart Fridge Agentic Commerce reference implementation on GitHub.

Coding agents transformed engineering at Stripe, but non-engineers like sales reps, finance analysts, technical account managers, and others felt left behind by the AI wave of Claude Code and Codex. No existing tool could handle the data security requirements and specific workflows Stripe needed: querying data warehouses, researching accounts before sales calls, triaging incidents, modeling revenue scenarios, or preparing compliance reviews. That all changed when we shipped Stripe’s knowledge AI platform.

Within two weeks of our April launch, most of Stripe was using Stripe's Knowledge AI Platform, also known as Kai. Today, 83% are weekly active users, including nearly all of GTM (marketing, sales, customer success managers, and technical account managers). Most Kai sessions require many turns, with users doing deep research, creating specific artifacts, or refining assets before sharing internally or externally.  With Kai, everyone at Stripe has an agent built specifically to help them with their day-to-day work.

Why we built a Knowledge AI Platform

For coding tasks, the specific change varies, but the workflow and tools needed to perform the task stay about the same. You edit files, run tests, commit. The programming languages vary, but the shape of the work is rather uniform, which is why a single agent architecture works well. Knowledge work is the opposite side of that spectrum. Tasks like researching an account or preparing a compliance review require different tools, different data, different outputs, and different definitions of "done".

Before Kai, we had two AI options for knowledge work:

• NoCode Agent Builder: Anyone could build and deploy workflow-specific agents that could use tools. Over 4,000 agents were built using this system. However, we quickly noticed that teams were writing conceptually similar prompts but with varying levels of quality, and found the proliferation of these micro-agents increasingly hard to monitor and maintain.
• Coding agents: Coding agents were powerful, but they introduced a different set of risks. Since our goal is to enable improved productivity for all of Stripe, some users altered their workflows and chose coding agents.  However, security concerns quickly emerged, along with a new support burden for code quality teams that had never supported non-engineers before.

From these experiences, we realized that building a knowledge AI platform required getting three things right: scaling expertise without centralizing it, meeting users wherever they work, and enforcing guardrails that don't exist in code.

Scaling expertise without centralizing it

The range of expertise required to serve Stripe’s users is staggering. The people who know how to triage a billing escalation or model a revenue scenario are not centralized and certainly aren't on the team building the agent infrastructure. They're distributed across dozens of specialized domains – GTM, Finance, Marketing, Legal, Data Science, and more – each with its own tools, data sources, workflows, and judgment about what "good" looks like. Multiply this across all the products and countries Stripe operates in, and the result is astonishingly complex. Kai has to model that complexity in a way that makes it invisible, so that the task just works.

The agent has to roam

Where the agent surfaces matters as much as what it knows. Not everyone works in a browser tab, and fewer still in a terminal. So a knowledge agent can't just be a single product; it has to be a platform, flexible enough to embed itself wherever work happens.

For example, consider an internal application our Finance team uses to model complex changes in Stripe's operating budget: the agent needs to read the context, research related documents, propose valid changes, and summarize the differences, all without pulling them out of the app.

Building a standalone agent product wouldn't work.  Instead, it would force users out of their natural workflows and into a new app. Building a separate agent product for each surface wouldn’t work either; it’d be hard to maintain, and users who span multiple tools would have a fractured experience. The platform has to meet the user where they are.

Building guardrails from scratch

Coding agents operate in an environment with decades of fast, verifiable guardrails: compilers reject invalid syntax, tests catch regressions, and git makes every mistake reversible. Knowledge work has very little support for these constructs.

Consider a core invariant at Stripe: “you shouldn't combine data from two unrelated customer contexts in a single analysis.” A user may have legitimate access to both contexts independently, but they can never appear in the same session. The isolation boundary isn't "what can this person access based on their authorization token?", but instead "what should this task be allowed to view given this context?"  The platform has to enforce these implicit guardrails that users rely upon.

How we built Kai

A single monolithic agent simply cannot encode all of these constraints effectively. And, asking every domain team to independently build secure, hosted, performant agent infrastructure doesn't scale either. To manage this challenge, we built Kai in three layers:

• Surface-agnostic APIs that give multiple interfaces into the same agent
• Agent Studio where domain owners build and govern their own Kai agents, and
• Execution environments to deliver security in seconds without anyone thinking about infrastructure.

Surface-agnostic APIs

Kai ships with an opinionated web application and a Slack integration, but the main primitive is the underlying API that powers them both. The agent is a service, not an application, and surfaces are simply customized views into it.

Most Stripes interact with Kai through the internally hosted web application. There's no infrastructure to set up – it's available to every employee on Day 0.

Any internal tool can also embed Kai, and many have chosen to do so. For example an employee working in our business intelligence platform can ask Kai a question from within their existing application because our Chrome extensions surface Kai capabilities inside web-based third-party tools.

Custom applications embed Kai via APIs to bring agentic experiences to all workflows

Agent Studio

Agent Studio is the control plane for domain owners. Teams use it to build, test, and monitor their skills, custom Kai agents, and tool selections. A GTM team, for example, owns a Kai agent tuned to their workflows. It loads their skills by default, connects to their data sources, and presents outputs in the format their users expect. Agent Studio surfaces usage data and quality signals alongside each asset, so domain owners can see what's working without asking the platform team.

Assets are organized into areas across Stripe that are managed by domain experts

The execution environment

This is the layer that makes the platform's promises real. The core primitives, including the agent harness, sandbox, workflow orchestration, and access control framework, are deliberately shared with Stripe's product-facing agents. Internal knowledge work operates on the same sensitive data and serves the same users as our external products, so it requires the same security and compliance bar. Sharing the substrate forces discipline and creates a flywheel: improvements to the execution environment benefit both internal and product agents simultaneously.

The agent harness, built using LangChain’s deepagents, runs on Kubernetes with a secure per-session sandbox and a multi-tenant virtual filesystem. Within a session, the agent works with a virtual filesystem where it creates and iterates on artifacts, while a secure code execution sandbox is used for analytics and data processing.

It's built to hold state across long, complex sessions — one recently reached 932 turns. With Kai’s deep task management capabilities, a single conversation can consist of hundreds of turns, and hundreds of tool and LLM calls without timing out or overloading the context window. This matters because knowledge work is rarely a single question. It's iterative reasoning that builds on itself, and the session has to hold that state without degrading.

User behaviors are changing, and sessions are increasingly used for deep multi-turn collaboration

One of the most interesting parts of the harness is how it chooses the correct skill to use. Kai is connected to 1,000+ skills and tools spanning various internal systems – from business intelligence dashboards that track key metrics, to project management tools that organize internal execution, and third-party services like Zoom and Google Workspace. Anyone can ask it a question and trust it will load the right context and use the right tools to get the job done. Coding agents have a natural advantage here: the folders they work provide a natural organization for skills and context. In a follow-up post, we’ll go into how we solved this without that pre-existing structure by utilizing a hybrid RAG/LLM approach, among other techniques.

Impact

The results have been striking. New hires on GTM are Kai-native: they use it 2.7x more, and power users close 80% more value than low users within the same cohort. When Account Executives use Kai, they produce 2x the sales activity, create 17% more opportunities, generate 26% more revenue opportunities, and close 39% more deals when compared to the same sellers in weeks they don't use it. In aggregate, Kai has helped shift 25,000 hours per year from administrative work, to revenue generating work.

In finance and operations, Kai is helping Stripes analyze messy data, generate recurring digests, and turn fragmented context into usable artifacts.

In engineering, Kai is now a natural place to ask system questions, research for run requests, analyze logs, draft plans, and invoke more specialized agents and skills.

And across Stripe, more than 5,000 sessions everyday center on data analysis. This makes Kai a unique leverage point: by plugging in the right context about data quality and our analytics layer, we can ensure correct responses by default for most questions.

Stripes’ direct feedback backs up these aggregates: they report feeling “empowered to embrace AI” and “astounded at what Kai just does precisely correct”. But our favorite anecdote is a non-engineer who left a Kai intro session and immediately collaborated on a digest that pulls together Asana, Slack, and Jira into a single automated process.

We haven’t won yet

At Stripe, one of our favorite catchphrases is “we haven’t won yet”, and that’s apt for Kai. We’re in the earliest stages of this journey, and have a lot more we want to do:

• Better state management: General-purpose agents like Kai generate a lot of state as they iteratively make tool calls, pull down large documents, and more. We are continuously tuning both the “active” context being sent to the LLM and the “extended” context sitting in state stores like S3 or the virtual file system.
• Reflection and self-improvement: We are working on a quality improvement loop that lets Kai reflect on traces involving a skill, propose improvements, test them, and submit changes for the skill owner to review.
• Better collaboration primitives: Users generate a lot of context in their Kai sessions that is currently “locked in”, but that’s not how work gets done. We want to let people share what Kai surfaces across sessions, and let multiple people (and agents!) collaborate on the same artifacts.

Coding agents made AI feel concrete for software engineers first. Kai has helped bring that same sense of leverage to knowledge workers across Stripe. It’s interesting because while we have improved productivity considerably, we don't know the ceiling yet - and we’re excited to keep pushing the envelope here. If building agentic systems that power internal productivity and external agents sounds like your kind of challenge, we’re hiring.

At 2 a.m. on a Tuesday, an on-call engineer's pager fires. A MongoDB shard—one of 2,000 that collectively processed $1.9 trillion in payments in 2025—has entered a degraded state. Two nodes are down, and a third is blocking an index build due to a misconfigured vote. To nurse the shard back to health, the engineer will need to spend 15 minutes carefully sequencing manual operations, then up to 3 hours triggering and monitoring each operation.

This scenario played out hundreds of times a year across Stripe's Document Database fleet—our global MongoDB infrastructure spanning over 40 distinct shard layouts, from cost-optimized configurations to high-availability setups designed for disaster recovery. The combinatorial explosion of failure modes made it impossible to anticipate every scenario with static, hand-coded automation. We needed a fundamentally different approach.

Our solution treats infrastructure state as a traversable graph and lets a pathfinding algorithm discover recovery sequences at runtime. By applying breadth-first search, and later, Dijkstra's algorithm, over a simulated state machine, we built a system that dynamically computes and executes multi-step recovery plans. As a result, we’ve seen a 30% reduction in pager volume (~200 fewer pages per year), 12 fewer days of shards stuck in unhealthy states annually, and zero additional work required to support new shard layouts.

Why static automation breaks at scale

Our original auto-remediation system (V1) operated as a single-step, hard-coded state machine. A set of plugins—each responsible for one issue, like "fix votes," "fix priority," or "rebuild downed node"—ran in a carefully ordered sequence based on hard-coded ranking and assumptions within a reconciliation loop.

This worked well for simple cases, like if a single node went down, or one or two misconfigured votes, but it had fundamental limitations:

• Implicit dependencies between plugins meant that ordering was fragile. The "fix votes" and "fix priorities" plugins required no nodes to be down, but they had higher priority than the "node down" plugin. We could only resolve these circular dependencies with manual intervention.

• Multi-failure scenarios exposed blind spots. When multiple impaired nodes combined with voting and priority misconfigurations, the sequential, single-issue-at-a-time approach couldn't find a valid ordering. The system would exhaust its options and page an operator.

• Layout coupling was everywhere. Each plugin contained layout-specific safety checks, so onboarding a new layout to the V1 remediation platform required auditing the logic of every plugin and workflow, a process that took about 1 week for each new layout.

• Workflow cancellations left shards stranded. A canceled workflow could leave the shard in an intermediate state that V1 never anticipated. These orphaned states fell outside any plugin's preconditions and required manual cleanup.

In one six-month window, the control plane paged operators 124 times for misconfigured shards, and 32 times for single-node-down scenarios complicated by additional health issues. Critical operations like index builds and planned maintenance were blocked for an average of one hour per incident.

Infrastructure as a traversable graph

Reframing the question

The breakthrough came when we stopped asking, "What's the most important issue to fix right now?", which is a local, greedy question. Instead, we asked, "What sequence of operations transforms the current shard state into a healthy state without ever violating safety invariants?" Once we framed it that way, we realized we were looking at a graph search problem.

Modeling a shard’s health as a state machine

In MongoDB, cluster topology is controlled by assigning nodes specific roles: voting rights determine participation in leader elections and quorum writes, priority levels control a node's eligibility to become the primary, and hidden status keeps a node out of the client read path. We capture these per-node attributes, along with shard-level properties like oplog sizes, regional distribution, and quorum status, to model a shard’s state as a node in a directed graph.

Edges in the graph represent atomic infrastructure operations: adding or removing a vote or priority, hiding or unhiding a node, rebuilding a node, or resizing an oplog. These are steps we need to take on the path to getting the shard healthy again.

Finding the path with breadth-first search over simulated states

The initial state is the shard's current ground reality. The goal state, the desired, healthy configuration, is the shard's Source of Truth (SOT). Invalid states violate safety invariants. These could be an even number of votes, a minority of healthy voting nodes, which puts write availability at risk, or a node in an invalid state, like priority=1 and vote=0.

With the state space defined, we use breadth-first search (BFS) to find the shortest sequence of operations from the current state to the goal state. The algorithm generates successor states at each step, prunes any that are invalid, and returns the first path that reaches the goal. Since BFS traverses level-by-level, it guarantees that the first solution uses the minimum number of operations.

Consider a healthy shard where three things go wrong simultaneously: a data node goes down, the backup node goes down, and another data node loses its vote and priority. V1 is completely stuck—the vote-fix plugin requires no nodes to be down, and the node-rebuild plugin requires votes to be correct. Our state machine, however, explores all valid orderings:

Current State → [Rebuild backup] → [Fix vote+priority] → [Rebuild data node] → Healthy
Current State → [Fix vote+priority] → [Rebuild backup] → [Rebuild data node] → Healthy
Current State → [Fix vote+priority] → [Rebuild data node] → [Rebuild backup] → Healthy

Each path is validated against invariants at every intermediate step. Fixing the vote/priority issue first is safe since it maintains quorum, which then unlocks subsequent operations.

In-memory simulation and durable execution with Temporal

We orchestrate our remediation workflows with Temporal, a durable execution framework that guarantees a workflow interrupted by a deploy, crash, or timeout can resume exactly where it left off—essential for node rebuilds that can take hours.

But Temporal's durability model creates a challenge for pathfinding. Our remediation building blocks are implemented as Temporal workflows and activities that are tightly coupled to Temporal's workflow.Context. They make network calls, wait for infrastructure changes, and checkpoint progress. We can't call these functions in a loop to simulate thousands of state transitions. A single simulated path through a five-step recovery would take minutes of real I/O; exploring hundreds of candidate paths would be intractable.

We solved this by introducing an abstraction layer: a CommonContext interface that can be backed by either Temporal's real workflow context, or a lightweight in-memory implementation.

// CommonContext abstracts Temporal's workflow.Context, enabling both
// production execution and local simulation.
type CommonContext interface {
        ExecuteActivity(opts workflow.ActivityOptions, resultPtr any, activity any, args ...any) error

        ExecuteLocalActivity(opts workflow.LocalActivityOptions, resultPtr any, activity any, args ...any) error

        ExecuteWorkflow(opts workflow.ChildWorkflowOptions, resultPtr any, workflow any, args ...any) error

        WithExternalDeps(sotProvider, grProvider SerializedShardProviderData, simState *SMShardState) (CommonContext, error)
}

The interface wraps Temporal's core primitives so that remediation logic can call them without knowing whether it's running inside a real workflow or a local simulation. The key method is WithExternalDeps, which swaps in simulated SOT and Ground Reality providers along with an in-memory shard state, allowing the system to explore thousands of state transitions without touching real infrastructure. In production, CommonContext delegates to Temporal and makes real API calls. In simulation, it delegates to an in-memory state provider that applies operations as pure state transformations. Both modes run the same business logic.

This gives us a critical property: what you simulate is what you execute. There’s no separate planning codebase that could diverge from the execution codebase. When the simulator determines that a sequence of operations will heal a shard, we have very high confidence that executing those same operations in production will produce the same result.

The simulation approach transforms minutes of I/O-bound execution into just milliseconds of CPU-bound computation. The BFS pathfinder can explore hundreds of state transitions per second, evaluating complete multi-step recovery paths in the time it would take to make a single network call.

Evolving the algorithm: From BFS to Dijkstra

BFS finds the optimal path to a fully healthy state, but it fails entirely if no complete path exists. Consider a shard with an extra node that automation can’t reach, alongside another node that has a missing vote. BFS returns no path at all, because the full goal state is unreachable—even though it’s trivial to fix the missing vote, and leaving it unfixed puts the shard at elevated risk of losing write quorum.

When our algorithm couldn’t reach a perfectly healthy state, could it find the least degraded state instead?

Weighted graph search

We evolved the algorithm to use Dijkstra's shortest-path algorithm over a weighted graph. The edge weight for each operation accounts for misconfiguration and estimated time:

edgeWeight(state, operation) = misconfiguration(state) × estimatedTime(operation)

misconfiguration(state) quantifies how far the current state deviates from healthy, using a rules-based scoring system that accounts for missing votes, incorrect priorities, downed nodes, and other issues. estimatedTime(operation) estimates wall-clock duration–a vote change takes seconds, while a node rebuild takes an hour. Using the product of these two for edge weight means the algorithm minimizes time spent in misconfigured states, prioritizing quick fixes that reduce exposure before committing to longer operations.

Partial remediation

Because Dijkstra's algorithm explores paths to all reachable states rather than only the goal state, we can also get partial remediation. When no complete path exists, the algorithm returns the path to the least misconfigured state. The ephemeral-node example resolves itself: Dijkstra fixes the vote, reduces the shard's risk, and leaves the ephemeral node for operator attention.

Extensibility through composable rules

The misconfiguration scoring is designed as a set of composable rules. The core function curries the SOT and returns a closure that can rapidly score any candidate state during graph traversal:

type MisconfigRule func(*ar.SMShardState, *ar.SMShardState) int

func GetMisconfigFunc(misconfigRules map[string]MisconfigRule, sot *ar.SMShardState) func(current *ar.SMShardState) int {
    return func(current *ar.SMShardState) int {
        misconfig := 0

        for _, rule := range misconfigRules {
            misconfig += rule(current, sot)
        }
  
        return misconfig
    }
}

Each rule targets a specific class of misconfiguration—downed nodes, voting mismatches, priority mismatches, oplog sizing, hidden status, and availability zone imbalance—and we can add new rules independently as our understanding of severity evolves:

func ListAllMisconfigRules() map[string]MisconfigRule {
      return map[string]MisconfigRule{
          "DownNodeMisconfigRule":     DownNodeMisconfigRule,
          "VotingMisconfigRule":       VotingMisconfigRule,
          "PriorityMisconfigRule":     PriorityMisconfigRule,
          "OplogResizeMisconfigRule":  OplogResizeMisconfigRule,
          "HiddenStatusMisconfigRule": HiddenStatusMisconfigRule,
          "AZMisconfigRule":           AZMisconfigRule,
      }
  }

Operation costs are expressed as relative weights that reflect how dramatically operations differ in duration—a node rebuild takes roughly 33 times longer than a config change:

const (

      OPTIME_NODE_UPDATE_MONGO_CONFIG = 3
      OPTIME_SHARD_UPDATE_OPLOG       = 19
      OPTIME_NODE_REBUILD             = 101

  )

The named rule map also makes debugging straightforward. The logs for a generated path show exactly how each rule contributed to the misconfiguration score at every intermediate state.

Impact

The state machine auto-remediation system has fundamentally changed our operational baseline. We’ve seen a 30% reduction in pager volume, or ~200 fewer pages a year, along with 12 days of fleet health reclaimed annually from shards that used to sit in degraded states until someone noticed them. Critical operations like index builds and planned maintenance now proceed without getting bottlenecked by manual stabilization.

The system is also layout-independent: when we onboarded a new layout for a planned failover, auto-remediation worked with zero code changes. And because workflows can be canceled mid-execution, the system can compute a fresh recovery path from whatever intermediate state was left behind.

Beyond metrics, the system has changed how we think about failure. Instead of writing runbooks for anticipated scenarios, we define invariants and available operations, and let the algorithm compose them into recovery plans.

Future directions

Right now, the state machine answers one question: "How do I get this shard back to its declared healthy state?" But the framework is extensible.

The most immediate extension is layout transformation. Our database fleet has over 40 shard layouts, and migrating a shard from one topology to another currently means writing a bespoke workflow that encodes every intermediate step. Instead, we can set the goal state and let the algorithm discover a safe migration sequence the same way it discovers a recovery sequence. We can use simple config updates for fleet-wide topology changes rather than needing to write bespoke migration workflows.

We can also adapt the state model to handle blue-green migrations, where a shard temporarily runs two "colors" of nodes during a version rollout. The pathfinder must be topology-aware, understanding which color is active and what "healthy" means at each phase of the migration. We want to be able to overlay migration context onto the shard's SOT, allowing the same Dijkstra-based planner to rebalance votes, rebuild failed nodes with the correct version binary, and resize oplogs. Then we can safely automate rollbacks when health signals degrade after a traffic shift.

Further out, we want the system to orchestrate planned maintenance alongside reactive healing. Right now, we execute one operation at a time on a single node across the entire shard, but when a node is already offline for a version upgrade, we could batch an oplog resize or index build into the same window. The system could discover these batching opportunities by modeling "node offline for maintenance" as a state where multiple operations become safe to execute together.

Conclusion

If you can model your infrastructure's state space and define valid transitions, recovery becomes a search problem. The engineering challenge is making that search practical—building a simulation layer that’s fast enough for exhaustive exploration, ensuring simulation fidelity matches production execution, and maintaining safety invariants that prevent the algorithm from proposing dangerous intermediate states.

For teams managing complex distributed infrastructure, this pattern of state machine modeling, simulation-based planning, and runtime pathfinding offers a compelling alternative to accumulating ever-more-specific runbooks. Runbooks encode known recovery procedures; a state machine discovers novel ones.

Special thanks to Aarush Gupta, Jessica Glustien, Neeraj Joshi, Puneet Oberai, Runchen Yan, Shalin Shekhar Mangar and Srivatsan Sridharan for their contributions to this project.

If building systems like this interests you, we're hiring.

Many marketplaces or platforms operate on Stripe Connect, using the separate charges and transfers charge type. This allows marketplaces to offer different purchase combinations for their customers, such as items from different marketplace sellers, in a single transaction, and then perform separate transfers.

If you operate in this model, when your platform collects a payment, those funds land into the Stripe balance on your platform account, pooled together with your own revenue. Stripe handles the accounting and reporting, but the funds themselves aren’t ring-fenced until you explicitly transfer them to a seller's connected account.

PSD2 is the 2nd revision of the Payment Services Directive, a European Union law that regulates electronic payments. The latest version of this, PSD3, is due to take effect from late 2027. Under PSD2, most marketplaces and platforms operate in this way using the Commercial Agent Exemption (CAE), allowing you to process payments without a formal payment institution license. Due to upcoming changes to PSD3 and the likely tightening of Commercial Agent Exemptions, Stripe has created a new charge type for Stripe Connect called "Segregated Separate Charges and Transfers".

The problem with pooled balances

If we take a marketplace that is processing payments for thousands of different sellers, without fund segregation, a single platform balance on Stripe holds funds for many different connected accounts (sellers), meaning that:

• Automatic payouts scheduled on your platform account could inadvertently consume funds meant for a seller.
• Unrelated chargebacks or disputes on one transaction can draw from the shared pool, affecting funds earmarked for a completely different seller.
• Stripe fees are debited from your platform balance - the same pool that holds seller money.
• Operational errors such as an accidental refund, or misconfigured payout schedule, can leave sellers short with no clear audit trail.

In isolation, each scenario may seem unlikely, but at scale they can compound into systemic risk.

Why this matters now

Under PSD2 and EMD2 regulations in the EU, regulators are increasingly requiring platforms and marketplaces to demonstrate that customers’ funds are safeguarded, that they are held separately from operational funds and protected from the platform’s own creditors. Within the UK, the FCA enforces similar client money rules.

Even in geographies outside of this regulation, fund segregation is often treated as a trust signal. Sellers want to know their money is protected, investors or auditors want to see clear separation, and engineering teams want deterministic fund flows, rather than a shared pool of funds where edge cases can compound.

How fund segregation works

Fund segregation in Stripe Connect introduces a new holding state for funds. Funds from payments are allocated; they exist on your platform account, but don’t appear in your available balance, can’t be used for payouts, and can only be transferred to a connected account. The diagram below shows a high level overview of the fund flow:

The full end-to-end flow can be described as follows:

Create a payment with allocated funds

When creating a PaymentIntent, set allocated_funds to enabled: true. At capture time, Stripe automatically places the funds into the allocated balance within your Stripe Platform account.

You should also specify the transfer_group with your value; this value lets you track the flow of funds from payment through to transfer, and helps with reconciliation and audit flows.

{
  "amount": 10000,
  "currency": "eur",
  "allocated_funds": {
    "enabled": true
  },
  "transfer_group": "ORDER-1234"
}

After successful capture of funds, the full amount becomes available in your allocated balance, subject to normal payment method settlement timing.

Check the allocated balance

You can inspect the allocated funds balance for a specific payment intent by expanding the latest_charge property within the PaymentIntent object. This gives you per-payment visibility, so you know exactly how much is in your allocated balance, and how much has been transferred into a connected account.

In this example, we can see that allocated_funds is enabled, so we know the charge amount is using your allocated balance, and €98.00 is available to be transferred (€100 minus €2 example Stripe fees).

{
  "id": "pi_xxx",
  "latest_charge": {
    "id": "ch_xxx",
    "allocated_funds": {
      "enabled": true,
      "balance": {
        "available": 9800,
        "pending": 0,
        "currency": "eur"
      }
    }
  }
}

Transfer to connected accounts and collect your platform fee

When creating the transfer object to transfer allocated funds to a connected account, set the source_transaction parameter to the charge ID from the original payment intent. This tells Stripe to draw from that specific payment’s allocated balance. You can also collect your platform fee in the same call by specifying the application_fee_amount parameter. This debits the fee from the allocated funds and credits it to your platform’s payment balance.

It’s important to note that the application_fee_amount is additive to the transfer amount. For example, if you want to collect a €5.00 application fee for a €100.00 charge, and then transfer the remaining €93.00 to a connected account, you’d need to specify this as follows:

{
  "amount": 9300,
  "currency": "eur",
  "destination": "acct_seller_123",
  "source_transaction": "ch_xxx",
  "transfer_group": "ORDER-1234",
  "application_fee_amount": 500
}

You don’t need to transfer everything at once, you can split allocated funds across multiple transfers to connected accounts; this is useful if you have mixed first-party and third-party purchases, or purchases from multiple sellers in a single transaction. One rule to remember is that the total transferred cannot exceed the original charge amount.

As the application_fee_amount is taken directly from the allocated funds on your platform account, it avoids unnecessary FX conversions when the platform and connected account operate in different currencies.

Handling the hard parts

In the real world, we know our users don’t just process happy path payments. Refunds, disputes, and reversals are also common, so it’s key to understand how these work using allocated balances.

Refunds

When you process a refund, Stripe will first draw from the remaining allocated balance before touching the balance of your platform account. As an example, if you had a €100.00 charge in your allocated balance, you transferred €60.00 to a connected account (leaving €40.00 in the allocated balance), and then did a €100.00 refund:

1. €40.00 would come from the remaining allocated funds
2. €60.00 would come from your platform’s account balance

This predictable ordering means allocated funds are always used first, reducing the frequency of debits from your platform’s account balance.

Transfer reversals

If you need to claw back funds from a connected account balance, for example before processing a refund or while awaiting a dispute outcome, you can use a transfer reversal. Reversed funds will return to the allocated balance, not your platform’s account balance.
When creating a reversal, if you set the refund_application_fee to true, the application fee is also returned to the allocated balance. This is an important decision for your business; some marketplaces choose to refund the application fee, while others choose to retain it.

Disputes

When a dispute is raised on an allocated payment, you can reverse the transfer to pull funds back from the connected account into your allocated balance whilst awaiting the outcome.

If the dispute is won, you can then transfer the allocated funds back to the connected account. If the dispute is lost, you can use a Balance Transfer to move these funds into your platform balance, providing the currency matches the original charge settlement currency.

Dispute fees are always debited from your platform balance, they never affect the allocated funds balance.

Hanging balances

You may find that you end up with allocated funds that no longer need to be in your allocated balance, for example after a dispute is refunded from your platform balance and you later reverse the transfer from the connected account.

In this scenario, you can use a Balance Transfer to move these funds from the allocated balance to your platform balance, providing the currency matches the original charge settlement currency.

Getting ready

Before starting, there are some pre-requisite steps worth being aware of:

1. Your platform account must be responsible for negative balances on connected accounts
2. Include the allocated_funds_preview=v1 parameter as part of the header on all API requests. For example, with Node you include this as a parameter when defining the Stripe const variable:

const stripe = require('stripe')(
  'sk_test_',
    {
      'allocated_funds_preview=v1',
    }
  );

3. Allocated funds currently only work with card payment methods, so you should avoid using automatic_payment_methods and specify payment methods explicitly
4. Allocated balances cannot be combined with overcapture, multi capture, or incremental authorisations
5. For testing, allocated balances can only be used with sandbox accounts, they do not work in legacy test mode
6. The Stripe dashboard doesn’t distinguish between allocated balances and other account balances, you must use the API for visibility

Benefits

With segregated separate charges and transfers and allocated balances, your platform can achieve:

• Deterministic fund flows — every payment's funds are traceable from capture to transfer, with no possibility of leakage into unrelated operations.
• Regulatory alignment — demonstrable safeguarding of customer funds, separated from platform operational balances.
• Operational safety — auto-payouts, unrelated chargebacks, and fee debits can't touch allocated funds.
• Clear audit trail — per-payment balance visibility via the API at every stage of the lifecycle.

For platforms or marketplaces that operate in regulated markets, or those handling significant seller volumes, this allows you to move to a world in which fund safety becomes enforced by the infrastructure, rather than being purely on a trust basis.

Next steps

• Review the full fund segregation documentation
• Set up a Sandbox environment to test your integration
• If you're evaluating whether fund segregation fits your regulatory requirements, reach out to your Stripe account team for guidance on your specific jurisdiction

Once your event destination is set up, upgrades can be tricky. Because the shape of events are tied to a specific API version, upgrading either your event destination or SDK (especially in strongly typed languages) can lead to unexpected runtime errors.

Stripe's solution to the maintenance problem is thin events, which are unversioned JSON payloads. Because they're identical across API versions, you can use them with any SDK version, making upgrades much safer. But the authoring problem remains: how can the SDKs present as much information about the shape of events as early as possible?

Enter event notification handlers. They encapsulate everything your event handler needs to run and let you focus on your business logic. They surface errors when you're writing code instead of later, in production.

If you'd like early access to thin events for v1 resources, please fill out this form.

How it works today

When handling thin events today, you need to write a lot of code to validate and route the event correctly. You're also responsible for managing the Stripe-Context header when handling events for connected accounts.

Here's what a TypeScript handler might look like today:

const app = express();
const stripe = new Stripe("sk_test_YOUR_KEY_HERE");

app.post(
  '/webhook',
  express.raw({type: 'application/json'}),
  async (req, res) => {
    const sig = req.headers['stripe-signature']?.[0] ?? '';

    try {
      const eventNotification = stripe.parseEventNotification(
        req.body,
        sig,
        webhookSecret
      );

      if (eventNotification.type == 'v1.billing.meter.error_report_triggered') {
        console.log(
          `Meter w/ id ${eventNotification.related_object.id} had a problem`
        );

        const event = await eventNotification.fetchEvent();
        console.log(`More info: ${event.data.developer_message_summary}`);
      } else if (eventNotification.type === 'v1.billing.meter.no_meter_found') {
        const meters = await stripe.billing.meters.list(undefined, {
          // important!
          stripeContext: eventNotification.context,
        });

        console.log(
          `Meter not found. Available meters for this account are: ${meters.data
            .map((m) => m.id)
            .join(', ')}`
        );
        // ...
      } else {
        console.log(`Received unhandled event type: ${eventNotification.type}`);
      }

      res.sendStatus(200);
    } catch (err) {
      console.log(`Webhook Error: ${(err as any).stack}`);
      res.status(400).send(`Webhook Error: ${(err as any).message}`);
    }
  }
);

Notice how all of your business logic is interwoven in webhook-related hardware? Even if you split your logic into small functions, it's still up to you to wire everything up correctly. Plus you have to hope (and verify) that you haven't made any typos in those webhook type strings.

A better way

Event notification handlers abstract away as much of this grunt work as possible, keeping you focused on the unique parts of your implementation. The Stripe SDK takes care of all the casting, routing, validating, and conversions behind the scenes. Let's walk through some examples.

Create a handler

The first step is initializing the handler itself. If you're not using StripeClient yet, you can use it for just this bit of your integration without changing anything else. There's more info in our docs.

Once you have an authenticated client, create your handler. Make sure to provide a "fallback callback", the function that gets called when the event isn't otherwise handled:

const stripe = new Stripe("sk_test_YOUR_KEY_HERE");

const handler = stripe.notificationHandler(
  webhookSecret,
  async (unhandledEvent, client, details) => {
    console.log(
      `Received unhandled event type: ${unhandledEvent.type}; the SDK does${
        details.isKnownEventType ? '' : ' not'
      } have types for it`
    );
  }
);

Handle a thin event

You can declare callback functions anywhere in your codebase:

// webhookCallbacks.ts
const handleNoMeterFound = async (
  notification: Stripe.V2.Core.Events.V1BillingMeterNoMeterFoundEventNotification,
  client: Stripe
) => {
  // don't need to specify stripeContext! it just works
  const meters = await client.billing.meters.list();

  console.log(
    `Meter not found. Available meters are: ${meters.data
      .map((m) => m.id)
      .join(', ')}`
  );
};

// eventDestination.ts
import {handleNoMeterFound} from './webhookCallbacks.ts'

const handler = stripe.notificationHandler(...) // same as above

handler.on('v1.billing.meter.no_meter_found', handleNoMeterFound);

That handler.on(...) call validates (at compile time) that the argument types for your callback match those expected for the v1.billing.meter.no_meter_found event, so you don't have any surprises at runtime.

The SDK will supply the parsed event notification and a special instance of StripeClient that's pre-bound to the context of the event. It also retains all the settings from the client instance that created the handler, so no need to re-configure anything. You can make any additional API calls you want.

Best of all, because handleNoMeterFound is just a function, you can test it as part of your normal development flow.

In some languages (like TypeScript), you can even declare callbacks inline, meaning they have the exact correct types without having to specify anything:

handler.on(
  'v1.billing.meter.error_report_triggered',
  async (eventNotification, client) => { // these are automatically typed correctly
    console.log(
      `Meter w/ id ${eventNotification.related_object.id} had a problem`
    );

    const event = await eventNotification.fetchEvent();
    console.log(`More info: ${event.data.developer_message_summary}`);
  }
);

The final result

Put it all together and you've got a much more maintainable event destination:

const app = express();
const stripe = new Stripe("sk_test_YOUR_KEY_HERE");

const apiKey = process.env.STRIPE_API_KEY ?? '';
const webhookSecret = process.env.WEBHOOK_SECRET ?? '';

const handler = stripe.notificationHandler(
  webhookSecret,
  async (unhandledEvent, client, details) => {
    console.log(
      `Received unhandled event type: ${unhandledEvent.type}; the SDK does${
        details.isKnownEventType ? '' : ' not'
      } have types for it`
    );
  }
);

handler.on("v1.billing.meter.no_meter_found", handleNoMeterFound);
handler.on(
  "v1.billing.meter.error_report_triggered",
  handleErrorReportTriggered
);

app.post(
  "/webhook",
  express.raw({ type: "application/json" }),
  async (req, res) => {
    try {
      const sig = req.headers["stripe-signature"]?.[0] ?? "";
      handler.handle(req.body, sig);
      res.sendStatus(200);
    } catch (err) {
      console.log(`Webhook Error: ${(err as any).stack}`);
      res.status(400).send(`Webhook Error: ${(err as any).message}`);
    }
  }
);

This pattern is supported in all seven of our server-side SDKs, though the exact implementation details will differ between them. In each case, we designed a clean and idiomatic experience for the language.

What comes next

While event notification handlers represent an exciting leap forward, we're not done yet. This more structured approach to event handling sets the stage for even better experiences going forward. While we don't have concrete plans yet, we're working on better validations (like ensuring your handler is listening for all the events your webhook endpoint is sending) and better integrations with popular web frameworks so we can make the integration experience even more seamless.

How you can help

Ahead of their GA launch later this summer, we're looking for developer feedback on the handlers to ensure they're ready for prime time. Though we're confident in their overall design, there's no replacing adoption in a real production codebase. If you have a chance to try them, please report any feedback (good or bad) in your SDK's corresponding GitHub issue:

• Node
• Python
• Java
• Go
• Ruby
• PHP
• .NET

Stablecoins offered something new: a stablecoin transfer settles on-chain in seconds, 24/7, with global reach and no per-country rail integration. When we decided to add stablecoin support to Stripe, the challenge went beyond "support a new currency." We had to stitch blockchain-based settlement into the GPTN's existing graph of bank accounts, payment rails, and entity structures, while respecting safeguarding requirements and regional regulations, and making it work in both directions.

How stablecoins move through Stripe

Here's a concrete example: a platform holds a USD balance on Stripe and wants to pay out a user in stablecoins.

When the platform calls our Payouts API, we decrement their USD balance and record a pending stablecoin obligation. Then, crucially, we don't wait for fiat rails to catch up. We maintain a stablecoin liquidity pool at Bridge, our crypto infrastructure partner. Bridge can draw from this pool and credit the recipient's wallet directly, delivering the payout in seconds to minutes.

Meanwhile, the dollars catch up asynchronously. Our cash management layer creates a request to move funds from the originating bank account to replenish the Bridge liquidity pool — but that movement happens over traditional fiat rails, and takes hours to days depending on the corridor. Opposing flows on the same route get batched and netted, so the number of actual bank transfers is a small fraction of the number of payouts.

The reverse direction — stablecoins back to fiat — works the same way. Bridge liquidates the stablecoins, dollars flow back through intercompany channels, and liquidity at the fiat entity provides immediate availability while cash settles.

Decoupling settlement and movement was our key insight. User-facing settlement runs at crypto speed, while the underlying cash movement runs at fiat speed. Liquidity pools on each side bridge the gap.

The role of Bridge

Bridge, which Stripe acquired in 2025, is the orchestration layer between Stripe's fiat infrastructure and the blockchain. It manages wallet custody, executes on-chain transfers, and handles the minting and burning of stablecoins against reserve accounts. When we need to fund a recipient's wallet, Bridge handles the last mile: converting from the liquidity pool to stablecoins and executing the on-chain transfer to the destination address and replenishing the pool with stablecoins when incoming fiat settles.

Because Stripe relies on Bridge for stablecoin custody and transactional services, every fiat-to-stablecoin conversion, in either direction, is a cross-entity cash movement. Payout and onramp transactions require cash to move from Stripe's fiat entities to Bridge; offramps and stablecoin-to-fiat conversions bring it back. Each flow needs to be tracked as an intercompany liability, settled through intercompany channels, and reconciled across both sets of books.

The settlement graph had to integrate a new type of node — the wallet — with properties unlike any bank account it had handled before: near-instant finality, per-recipient (not pooled) balances, and no cutoff times.

Extending the existing graph

When we integrated stablecoins, we had two choices: build a parallel system, or extend the existing GPTN. We chose to extend.

The existing infrastructure already solves hard problems — orchestration, netting, cross-entity settlement, FX, reconciliation, and liquidity management — with years of investment behind them. Building stablecoins on top gave us those capabilities for free on day one, and improvements to shared infrastructure benefit both fiat and stablecoin flows.

To understand what we extended, it helps to see how the fiat side works. Stripe operates entities in dozens of countries, each with its own bank accounts. We model cash movement as a directed graph: nodes are accounts, edges are the available rails between them (ACH, SEPA, wire, book transfer), each with properties for currency, speed, cost, and availability. When the cash management layer needs to move money from account A to account B, it finds the optimal path through this graph.

At Stripe's scale, this graph handles millions of cash movement requests per day. Many of them never result in an actual bank transfer — we apply net settlement, which cancels them out. If account A owes account B 10M USD, and account B owes account A 8M USD, we send one 2M USD wire from account A to account B instead of two. With multilateral netting across entity pairs, we can net out a significant portion of overall daily volume across our entities—but getting it right means carefully tracking when cash needs to be available at the destination.

Adding stablecoins meant adding new node types and edge types to this graph. The new nodes are wallets: Bridge's liquidity pool, and individual user wallets for recipients. The new edges connect fiat accounts to these wallets, in both directions. The same netting logic applies across fiat and stablecoin flows — if we're sending 5M USD to Bridge to fund payouts while 3M USD is flowing back from offramps, the engine nets this to a single 2M USD fiat transfer. Bilateral netting between fiat and stablecoin flows is one of our most important efficiency gains, because it directly reduces the number of cross-entity transfers needed to keep the whole system running.

The composability of this approach also makes expansion practical. Adding a new currency pair or product is a matter of extending a path through the graph, rather than building a new pipeline. A EUR → stablecoin flow, for example, naturally composes from capabilities that already exist: the FX leg converts EUR to USD through our treasury hub, and the stablecoin leg mints at Bridge. Stablecoin support for new products can reuse the same architecture rather than requiring bespoke infrastructure each time.

A USD → stablecoin payout starts with a standard fiat hop that already existed in the graph. The routing layer understands both fiat and wallet nodes, so it can construct end-to-end paths that cross the fiat-to-stablecoin boundary and complete the payout. Wallet edges will also eventually add routing redundancy: for example, a USD → MXN payout will be able to go via a traditional fiat partner or via Bridge (liquidating a stablecoin to MXN), giving the system multiple paths for the same funds and the ability to choose based on cost, speed, or availability.

Making it instant

The net settlement engine was designed for a world where everything is measured in hours. It runs on a planning cycle of a few minutes, a negligible delay when your fastest rail settles in hours.

Stablecoins changed that calculus. When a user is waiting for a stablecoin to land in their wallet, a few minutes of batching is the difference between "instant" and "not instant." Some wallet funding requests are urgent — maybe a high-priority payout is pending — and holding them for the next batch isn't acceptable.

We introduced a direct mode that bypasses the planning cycle for time-sensitive requests, explicitly skipping batching and netting opportunities in exchange for speed. A request that could have netted against an opposing flow now goes out as its own transfer. The system now runs both modes simultaneously, with most flows going through the standard cycle and benefiting from netting, and urgent wallet funding going direct. The decision of which mode to use is made upstream based on urgency, and in the future could factor in real-time pool state and demand forecasts to make smarter tradeoffs between speed and netting efficiency.

The liquidity pool is the tightest operational constraint in the system. Payouts and onramps reduce it; offramps and stablecoin-to-fiat conversions replenish it. On a day where payout volume and offramp volume are roughly balanced, the pool stays relatively stable with minimal fiat transfers needed. The netting engine makes this work: by netting opposing fiat-stablecoin flows before they hit the banking system, it directly reduces how much replenishment pressure ends up on fiat rails in the first place. Demand-driven forecasting — the ability to right-size the pool based on predicted flows in each direction—is one of our biggest near-term opportunities.

Running 24/7

Fiat settlement follows banking hours. Blockchains don't, which has real operational consequences. With fiat, a problem detected in a batch process might give us hours to respond before users are affected. With stablecoins settling in minutes, our alerting SLAs tightened from hours to minutes. We designed routine operations like pool replenishment and reconciliation, to run without needing manual intervention outside business hours. We had to extend our operational tooling, too: the same dashboards that show bank account balances and sweep status now display wallet balances, pool utilization, and on-chain transaction status, with reconciliation that spans both bank statements and blockchain records.

Agent-accessible operations

As SLAs tighten further, autonomous agents that can run routine diagnostics start to make a lot of sense. We're investing in making stablecoin operations more agent-accessible: giving agents visibility into the full transaction lifecycle, training them on patterns from past incidents, and enabling them to diagnose and respond to common issues without needing to wait for a human to come online.

What's next

The infrastructure described in this post is live and handling real traffic, but we're early in what stablecoins at Stripe will become. Here's where we're headed.

Demand-driven liquidity forecasting

Static pool buffers work, but they're not capital-efficient. The next step is moving to dynamic, forecast-driven sizing: right-sizing liquidity per corridor per time window based on historical usage patterns, time-of-day demand curves, redemption rates, and real-time inflow/outflow rates. Better forecasting also makes smarter batch-vs-direct decisions by pre-positioning liquidity ahead of predicted demand spikes rather than reacting after the pool dips.

Faster replenishment

We're working on using real-time fiat rails like RTP and SEPA Instant to replenish the liquidity pool where available. Closing the gap between pool drain speed (minutes) and replenishment speed (currently hours to days) is one of the highest-leverage improvements we can make to give us smaller buffers, less idle capital, and more resilience to demand spikes.

Expanding to new products and corridors

The composability of a settlement graph makes expansion practical. We can add stablecoins to a new product by connecting a new fiat leg to existing wallet edges, or add a new currency pair through the treasury hub's FX capabilities. This same architecture now powers stablecoin payouts to Link, enabling companies like Meta to pay content creators in dollars around the globe. Each of these are new edges in the graph—they all plug into the same netting, routing, reconciliation, and settlement infrastructure that already exists.

We want to make stablecoins a first-class rail at Stripe, alongside ACH, SEPA, and wires, as another edge type in the graph with its own speed and cost characteristics, available to every Stripe product that moves money. The architecture is designed to get us there. If these are the kinds of opportunities you want to work on, we're hiring.

Previously, I wrote about building a transcription app using Stripe Projects. While that tool certainly has a real use case and is still being used by my team, it's much closer to a hobby project than a real production app. That much was obvious both from how quickly I was able to spin it up (just a few days, with only a few hours of development time) to how frictionless the process was.

So what does building a more complex production app using agents look like? Even with the best-laid plans, sometimes it will still be mostly friction. Navigating that friction is where the takeaways come in.

The use case

So many people are building with Stripe Projects, it's getting hard to keep track of them all! I wanted a fun way to catalog and showcase open-source projects, and maybe add a competitive element to it for future hackathons, so I decided to build a leaderboard app. The concept was fairly simple: I wanted to build an app where users could add their project to a table, share it via social media links, and vote on other projects.

Despite the simplicity of the app, it would require some more complex infrastructure, namely:

• Auth, for tracking user submissions and enforcing a one-project-per-user limit
• A database with multiple tables, for tracking project details, user details, and votes
• Hosting for the app itself
• A mechanism to prevent voting abuse, i.e. ensuring non-logged-in users can only vote once per project

The initial plan

When it comes to agents, a well-crafted plan pays dividends in the long run. I had my requirements but wanted to ensure nothing was missing, so I meticulously laid out every piece of functionality the leaderboard would need.

First, I made sure I had the Projects skill available, so my agent would know to use Projects for provisioning infrastructure:

npx skills add https://docs.stripe.com

Then, I crafted a detailed markdown document covering requirements and styling, such as the theme's primary and secondary colors, fonts, light/dark mode, etc. Anything left out of the requirements is left to the agent's discretion, which tends to trend towards the generic, and I had a very specific vision in mind as well as Stripe UX guidelines to follow.

The requirements included how I was thinking about the data structure, and contained instructions such as:

- The leaderboard data will be stored in a database in an object with the following types:
    leaderboard: [
        {
            "projectId": "project_<ID>", <taken from state.local.json>
            "projectName": "demo-project", <taken from state.local.json>
            "projectURL": "", <link to live deployed app, from form>
            "projectRepoURL": "", <link to public repo, from form>
            "projectStackURL": "", <from `stripe projects share` output, from form>
            "userName": "", <handle of user when registering>
            "userEmail": "", <given when registering, must match Stripe Projects email>
            "ranking": {
                "position": <number>,
                "upvotes": <number>,
                "timeAtPosition": <function>
            }
        }
    ]

While in the past I've used apps such as Figma for wireframing, this time I figured the agent needed just a general concept for layout, and I was in a bit of a hurry - so I went old school and sketched out a rough idea of what I had in mind on a scrap of paper, took a photo, and added it to my requirements directory:

Then came the actual prompt, using Claude's planning mode:

I want to build a single-page NextJS app that shows a leaderboard of applications created using Stripe Projects and allows users to upvote on existing applications without registering, though limited to one vote per user per project. In order to add an application to the leaderboard for voting, a user will need to register and fill out a form, which will be in a modal activated by a "Submit your project" button.

See <inserted requirements> for details, styling, and data requirements, and <wireframe> for a rough wireframe, which should be re-created as a table.

Use the best database and auth for the use case, though simpler to use would be better for both, and any other infrastructure needed. Use Vercel for hosting as I already have an account.

The initial pivot

As expected, the agent's initial plan included provisioning the following resources:

• Database + auth: Supabase (single service)
• Hosting: Vercel

The agent followed my request for infrastructure simplicity and chose Supabase as both my database and auth provider, and Vercel for hosting as specified. It created CSS variables based on my requested color scheme, laid out the data structure for a projects table and a votes table, and presented the following architecture:

Everything looked good, and I hit build. The agent started by adding services via the CLI:

stripe projects add supabase/project
stripe projects add vercel/project
stripe projects env --pull   # writes .env.local

This also added the relevant skills for each service, which let the agent know to install @supabase/supabase-js and other libraries we would need.

As the agent was building, we ran into the first issue: enforcing the one vote per user rule for voting on the leaderboard. Using the Vercel skill, the agent determined that the built-in rate limiter for voting integrity it had initially planned would not work on the serverless architecture we were using, and a server-side enforcement mechanism was necessary. It would replace the existing vote flow with a single atomic database function, but that required a new service: Upstash Redis for rate limiting.

I gave my consent, it ran stripe projects add upstash/redis, and it was able to complete the rest of the build plan.

Pivoting providers

The real problems started once the integrations were configured, the app was working locally, and I started running into limits from the providers themselves. This was most obvious when I started testing the sign-up auth flow using Supabase auth - specifically, the email rate limits. It turns out that everybody has a plan until they get hit by rate limits.

Supabase's auth plan includes a rate limitation of two emails that can be sent per hour from my project - that was not enough for testing, much less a production app. Digging into the docs, I found out I would have to set up a custom SMTP provider or use my own email service via a custom hook to update the email rate limit. That meant another service, specifically an SMTP or email provider, something not yet offered by Stripe Projects - as well as potential new costs. I wanted to avoid having to run a custom email service when all I needed was a way to authenticate my users, so I decided to swap out my auth provider instead.

This is the point where human intervention was absolutely necessary, because when asked for potential solutions to this issue, the agent suggested implementing a Twilio integration instead, which aside from lacking the functionality I needed would have been absolute overkill for my use case.

Pivoting plans

It was time to go back into plan mode, both for myself and the agent. I would need to research the available auth providers, see if any of them would work for my use case, or potentially use a provider not offered by Projects. Luckily, Clerk ended up having the functionality I needed with much more generous rate limits aimed at preventing abuse.

Once I knew what service I wanted to use, I asked the agent to come up with a migration plan, which resulted in this simplified auth flow:

Once built, I was able to get auth working locally and in a deployed version, and after a few more back and forth iterations was ready to share the MVP.

Takeaways

Think through your data and UX when planning

The requirements doc I made had data models as well as CSS values laid out for the agent. Because I already had specific ideas of how I wanted those to look, writing them out for the initial plan saved a lot of the back and forth I had experienced in previous builds.

Trust but verify (and research)

The initial plan had a major flaw: an in-memory rate limiter doesn't work on Vercel's serverless architecture. Next time I'll have an adversarial agent go over the plan to find issues like this before they come up in the build, as well as going through the provider's docs if I have any doubts a proposed solution won't work.

Be deliberate in your prompt wording

I specifically asked the agent "Use the best database and auth for the use case, though simpler to use would be better for both". When it saw that Supabase offered both, it naturally picked that as the simplest solution, though it ended up being the wrong one for auth. Initially biasing the agent towards simplicity ended up causing a significant refactor after the first build was complete.

Go with your gut

When I initially hit the email rate limit issue, I did ask the agent to give me possible solutions; it came up with implementing Twilio on top of everything. My gut said this was an auth problem and changing the auth provider should solve it, and that ended up being the case.

Results

By the time I was finished, I had built a far more complex app with Projects than any previous endeavors, and ended up with five resources between four providers. But most importantly, I ended up with a working app:

Before submitting my code for review, I switched to a different model and ran a security audit with one agent and a performance audit with another and patched some fairly trivial but important issues those agents found. All together, the leaderboard app took over a full day of building compared to just a few hours for my previous projects - which is worth putting into perspective considering a year ago it would have taken a whole team at least a week to put together.

If you want to get started with Stripe Projects yourself, head to projects.dev!

When a Stripe engineer makes changes to an API, merging the PR is just the beginning. Stripe maintains a vast developer product suite that needs to stay in sync with the API changes we frequently ship:

• The official SDKs need to have new versions published across seven different languages and three release channels.
• The CLI, Shell and API Explorer need to be updated to include the new functionality.
• The API Reference needs to reflect the new API shape, and have meaningful descriptions to assist developers in integrating with it.
• The public changelog needs to list the new change, why it matters, and how it affects users.
• Internal tools need to reflect these changes to help Stripe engineers (and AI agents) manage and maintain their APIs.
• … and more.

Keeping all of this in sync is a significant challenge, and building the infrastructure to do it reliably is a long-term investment that started a few years back.

Enter OpenAPI

The OpenAPI Specification defines a standard format for describing HTTP APIs. It’s widely used across the industry to generate documentation, client libraries, and to build out a company’s Developer Experience Infrastructure (DXI). Stainless (founded by a former Stripe engineer and recently acquired by Anthropic) and many other companies are built around solving the challenge of DXI.

OpenAPI has been part of Stripe’s toolbox since 2016, initially powering internal tooling like validations and test suites. In 2017, we published a public OpenAPI description of our API and kept it up-to-date as our APIs evolved. In 2019, we used OpenAPI to auto-generate a Stripe SDK for the first time, releasing stripe-java@8.0.

But OpenAPI wasn’t universally adopted across Stripe. Some tools relied on the OpenAPI descriptions we generated. Others, like the API Reference, bypassed OpenAPI entirely and parsed APIs straight from our internal Ruby-based DSL.

A breaking point

In 2024, Stripe introduced the v2 namespace to bring improved domain modeling and updated API semantics to our users. Internally, this meant an architectural shift in how we define and implement APIs, leveraging Protocol Buffers. Unlike v1, v2 APIs are defined by a separate internal DSL and serialized into snapshots using a Stripe-built internal API spec. Both are protobuf-based, which lets us share primitives and represent the DSL, API shape, and version differences (patch files) in the same format.

class AccountRetrieveMethod < APICore::AbstractAPIMethod
  description "Retrieves the details of an account."

  resource AccountAPIResource
  permission Permission.fetch(:account_retrieve)
  # ...

  client_metadata(
    in_class: "AccountAPIResource",
    method_type: :retrieve,
    endpoint_url: "/v1/accounts/:id"
  )

  def execute
    # ...
  end
end

service AccountsApi {
  // Retrieves the details of an Account.
  rpc RetrieveAccount(RetrieveAccountRequest) returns (RetrieveAccountResponse) {
    option (v2.method) = {
      get: "/v2/core/accounts/:id"
      documented: PUBLIC
      permission: "v2_account_read"
      error_code: "not_found"
      error_code: "account_rate_limit_exceeded"
      // ...
    };
  }
}

Now there were two formats: OpenAPI (or parsing the Ruby-based DSL) for v1, and our internal API spec for v2.

The consequences of the new internal API spec were immediate. Teams responsible for a developer product now had to support two formats instead of one. SDK and API Reference generators had to be duplicated. Preview support for v2 APIs in the CLI was shut down entirely because the maintenance burden was too high. Stripe Shell didn’t support v2 APIs at all.

The situation was already unsustainable, and we hadn't even launched v2 publicly yet. With new developer products like Stripe Workflows and an improved changelog on the way, things were only going to get worse. It was clear we needed to converge on a single way of representing Stripe’s APIs.

Between the different DSLs, the internal API spec, and OpenAPI, the choice was clear: converge on OpenAPI. OpenAPI was, and still is, the industry standard for representing HTTP APIs and a path already proven within Stripe. Most importantly, OpenAPI is extensible. Anything we needed to represent that wasn’t natively supported could be added as an extension.

This decision to use OpenAPI enabled us to further expand a pipeline that ships developer products at scale, keeping them in sync with every API change we make.

How the pipeline works

The pipeline starts with generating OpenAPI descriptions for each API namespace. But not every consumer of those descriptions needs the same thing. The Stripe CLI doesn't need the same information as the public API Reference. Internal tools can operate on APIs that are internal or still in development, which have no place in public-facing SDKs. To handle this, the generator’s output is controlled by three main parameters: variant, phase, and version. Together, they determine which API definitions (methods, event types, resource types, etc.) and what metadata is included in each artifact.

The OpenAPI Generator takes inputs from both v1 and v2 DSLs and produces tailored artifacts per consumer.

The variant controls which APIs and metadata are included for a given consumer. Think of variants as "surfaces." Each developer product gets its own tailored artifact.

• Public artifacts, like our stripe/openapi repository, exclude metadata that describe private or sensitive information.
• Some APIs are omitted entirely from certain artifacts. For example, methods that power internal integrations like the Stripe Dashboard don't appear in the descriptions powering public SDKs.

The phase parameter filters APIs based on their release phase:

For example, our public API Reference is powered by two different artifacts chosen based on whether the Preview toggle is enabled–one for GA APIs and one for preview. That distinction is controlled at the DSL level, so that a method marked undocumented won't appear in any public spec and one marked private_preview won't appear in GA artifacts.

The version parameter dictates what version of Stripe's API is being described. Products like API Reference or Stripe Database can support different views of the API depending on the API version chosen by the customer, and this parameter allows these teams to fetch the appropriate OpenAPI description.

In the v2 namespace, all API changes are stored on disk and easily reproducible from the beginning of history. This allows us to generate snapshots of the API surface, and their OpenAPI representation, for any point in time. With that capability, we can provide a canonical OpenAPI description for any past or current API version, and propagate improvements to the spec (e.g. richer metadata about an API) at will.

Things are a little trickier for v1. Due to the historical architecture of the v1 platform, it’s not trivial to regenerate descriptions for non-current API versions. Today, when a new API version is released, we store the current OpenAPI spec as the canonical description of v1 APIs for that version. It’s not perfect: new variants or metadata we add to the spec can't be backfilled into older versions. This is a problem we still have to solve in v1: how to support older API versions and leverage new OpenAPI features we add.

Making OpenAPI our own

Stripe uses vendor extensions to include extra information about the APIs and communicate to consumers how the spec should be interpreted. The extensions cover gaps in what the OpenAPI spec natively supports, helping us bridge the two API namespaces and their DSLs when possible, and signal to consumer products about special behavior that applies to some APIs but not others.

For example, we define Stripe's resources as reusable JSON schemas (under #/components/schemas) and include an extension called x-stripeOperations. This extension lists which API methods operate on a given resource and, with some additional metadata, directly powers the methods available on an SDK object and the subcommands available in the Stripe CLI.

components:
  schemas:
    v2.core.account:
      type: object
      properties: [...]
      x-stripeOperations:
      - method_name: list
        method_type: list
        operation: get
        path: /v2/core/accounts
      # ...
      - method_name: close
        method_type: custom
        operation: post
        path: "/v2/core/accounts/{id}/close"

Extensions helped us turn a standard spec into something purpose-built for Stripe's needs. Here are a few others we have added over the years:

Drawing the rest of the owl

The above is just a small piece of the work we do to be able to deliver consistently world-class developer experiences. Over Stripe's lifetime, we’ve invested significant care into understanding how API changes impact our entire product suite. Along the way, we’ve codified a set of design patterns that all APIs must follow.

Before a PR can merge, a set of automated tests validate API changes against those patterns: API naming, field types, versioning considerations such as backwards compatibility, or constraints specific to products (e.g. reserved words in SDKs). Documentation and code samples follow the same model, they're authored and validated alongside the API definition itself and threaded through to the API Reference generator via OpenAPI artifacts.

warn[empty_doc_string]: Every public API method, event, error, field, & enum value should have a doc string. See https://go/v2-api-ref for more details.
  --> /path/to/accounts_api_service.proto:71
70 |   
71 |   rpc CreateAccount (CreateAccountRequest) returns (CreateAccountResponse) {
72 |     option (v2.method) = {
73 |       stable_id: "v2_method_create_account"
74 |       post: "/v2/core/accounts"
   | ...
  help: see https://go/api-v2-lint/empty_doc_string for more information

In the PR view, we display an OpenAPI-based diff of the changes for visual (or much more common now: agent-assisted) spot-checking. In the v2 namespace, we also detect and display changes to past API versions (if applicable), a feature that has been especially helpful for catching inadvertent changes to older API versions.

Once the changes get merged, a pre-release flow is kicked off: the changes make their way into our internal API versioning tool, where the OpenAPI description of the previous and upcoming API versions are compared. Each change is listed and enriched with extra information such as previews of how SDKs will be affected, the affected product, suggested changelog descriptions, and more, providing one more place for product architects to review and refine upcoming changes.

At release time, the canonical OpenAPI description for the new version is snapshotted and propagated to downstream consumers for their subsequent releases. The new artifact is made available to internal services via direct dependencies or build artifacts. It’s published to our CDN and fetched by workflows in our open-source repos such as stripe/openapi and stripe/stripe-cli. The API Reference is updated with the new API version, up-to-date code snippets are generated, new versions of our SDKs and the CLI are released, and so on.

All of those improvements–and many others not mentioned here–have helped Stripe maintain a high bar for developer products while reducing manual work for engineers and the chance of mistakes being made.

What comes next

The pipeline’s foundation is solid, but there’s a lot more we want to build on top of it.

Smoothing the differences between defining v1 and v2 APIs is an area of active work as we incorporate the learnings of both stacks to provide a more unified experience to Stripe engineers building on either namespace (or most likely, both!). We are also extending our DSLs so that product teams can more easily define custom integration points targeting any developer product: some functionality may not really fit Stripe's API, but make a lot of sense in the Stripe CLI or as an action in a Stripe Workflow.

As Stripe launches new developer products, such as Stripe Database, we constantly find new use-cases that fit into this pipeline and managing that growth becomes its own challenge. It takes a coordinated effort maintaining parity between the DSLs, the OpenAPI generators of both v1 and v2 stacks, and keeping consumer teams in the loop when further extending the spec.

—

There's no shortage of interesting problems left to solve. If that sounds like your kind of challenge, and you want your work to reach every developer who builds on Stripe, we're hiring.