StripePlugin

Setup

1. Add the plugin to your VendureConfig plugins array:
   Ts

   import { StripePlugin } from '@vendure-community/stripe-plugin';// ...plugins: [  StripePlugin.init({    // This prevents different customers from using the same PaymentIntent    storeCustomersInStripe: true,  }),]
   For all the plugin options, see the StripePluginOptions type.
2. Create a new PaymentMethod in the Admin UI, and select "Stripe payments" as the handler.
3. Set the webhook secret and API key in the PaymentMethod form.

Storefront Usage

The plugin is designed to work with the Custom payment flow. In this flow, Stripe provides libraries which handle the payment UI and confirmation for you. You can install it in your storefront project with:

If you are using React, you should also consider installing @stripe/react-stripe-js, which is a wrapper around Stripe Elements.

The high-level workflow is:

1. Create a "payment intent" on the server by executing the createStripePaymentIntent mutation which is exposed by this plugin.
2. Use the returned client secret to instantiate the Stripe Payment Element:
   Tsx

   import { Elements } from '@stripe/react-stripe-js';import { loadStripe, Stripe } from '@stripe/stripe-js';import { CheckoutForm } from './CheckoutForm';const stripePromise = getStripe('pk_test_....wr83u');type StripePaymentsProps = {  clientSecret: string;  orderCode: string;}export function StripePayments({ clientSecret, orderCode }: StripePaymentsProps) {  const options = {    // passing the client secret obtained from the server    clientSecret,  }  return (    <Elements stripe={stripePromise} options={options}>      <CheckoutForm orderCode={orderCode} />    </Elements>  );}
   Tsx

   // CheckoutForm.tsximport { useStripe, useElements, PaymentElement } from '@stripe/react-stripe-js';import { FormEvent } from 'react';export const CheckoutForm = ({ orderCode }: { orderCode: string }) => {  const stripe = useStripe();  const elements = useElements();  const handleSubmit = async (event: FormEvent) => {    // We don't want to let default form submission happen here,    // which would refresh the page.    event.preventDefault();    if (!stripe || !elements) {      // Stripe.js has not yet loaded.      // Make sure to disable form submission until Stripe.js has loaded.      return;    }    const result = await stripe.confirmPayment({      //`Elements` instance that was used to create the Payment Element      elements,      confirmParams: {        return_url: location.origin + `/checkout/confirmation/${orderCode}`,      },    });    if (result.error) {      // Show error to your customer (for example, payment details incomplete)      console.log(result.error.message);    } else {      // Your customer will be redirected to your `return_url`. For some payment      // methods like iDEAL, your customer will be redirected to an intermediate      // site first to authorize the payment, then redirected to the `return_url`.    }  };  return (    <form onSubmit={handleSubmit}>      <PaymentElement />      <button disabled={!stripe}>Submit</button>    </form>  );};

   Show 32 more lines
3. Once the form is submitted and Stripe processes the payment, the webhook takes care of updating the order without additional action in the storefront. As in the code above, the customer will be redirected to /checkout/confirmation/${orderCode}.

Note: A full working storefront example of the Stripe integration can be found in the Remix Starter repo

Manual capture (authorize then capture)

By default the plugin captures funds as soon as the customer confirms payment (captureMethod: 'automatic'). On high demand stock this can create a race: between the customer paying and the webhook completing, the item can sell out, leaving the customer charged for an order that cannot be fulfilled and requiring a manual refund.

Setting captureMethod: 'manual' uses Stripe's separate authorization and capture flow to close that gap. It is opt-in: the default 'automatic' mode keeps its existing payment flow, and only gains the duplicate-event check and per-order lock described under Reliability below.

With manual capture:

1. Confirming the payment only places a hold on the funds (the PaymentIntent moves to requires_capture).
2. When the plugin receives the payment_intent.amount_capturable_updated webhook it transitions the order to ArrangingPayment. The default order process re-checks stock at this transition, respecting your backorder settings (arrangingPaymentRequiresStock and each variant's saleable stock), so an item that sold out during checkout blocks the transition.
3. If the transition succeeds, the plugin adds an Authorized payment. Once the payment covers the order total, Vendure moves the order to PaymentAuthorized and allocates stock, and the plugin commits it. Only then does it capture the held funds from Stripe, and it settles the payment in a second, short transaction. Stripe is never called while a database transaction is open, so a capture can't succeed while Vendure rolls the payment back.
4. If the order cannot be arranged, or the authorization does not cover the order total (for example the cart changed after the PaymentIntent was created and the customer confirmed the old client secret), the plugin does not record the payment and voids the authorization instead. The customer is never charged, so no refund is required.

Webhook events: manual capture also requires the payment_intent.amount_capturable_updated and payment_intent.canceled events. Add them to your Stripe webhook endpoint alongside payment_intent.succeeded and payment_intent.payment_failed.

Expired authorizations: Stripe cancels an authorization that is not captured in time (7 days for most card payments). The plugin then cancels the Authorized payment on the payment_intent.canceled event. Cancelling the payment does not release the order's stock, so the order stays in PaymentAuthorized and is logged: cancel it from the Admin UI to release the stock, or collect a new payment.

Payment method support: authorize-then-capture is supported by cards and several other methods, but not all (for example bank debits). Setting captureMethod: 'manual' restricts the PaymentIntent to eligible methods. See the Stripe documentation linked above for the current list.

Reliability: the webhook handler is idempotent (a redelivered event for an already recorded payment is skipped) and returns a 5xx on an unexpected/transient error so Stripe redelivers the event, rather than silently dropping it. Events for the same order are processed one at a time under a row lock on the order. The duplicate check and the lock apply in both capture modes. A deterministic outcome, such as the item having sold out, is handled once (the hold is voided) and acknowledged with a 2xx. Outgoing calls to Stripe (authorize, capture, void) use the SDK's idempotent network retries. The capture request carries no idempotency key of its own, because Stripe would return a stored error to every retry for 24 hours. A repeated capture is refused by Stripe as already captured instead, and the plugin then reads the PaymentIntent's live state.

The payment stays Authorized if the capture fails or the process stops after the funds were captured but before the payment was settled. A temporary Stripe error makes the webhook return a 5xx, and the redelivered payment_intent.amount_capturable_updated event resumes the capture. The payment_intent.succeeded event settles any payment that is still Authorized once its PaymentIntent has been captured, so the two events can arrive in any order or more than once and the payment is settled exactly once. A capture that Stripe refuses for good is logged and the payment is left Authorized, so it can be captured or cancelled from the Admin UI.

Limits of the duplicate-hold protection: the PaymentIntent for an order is created under an idempotency key made of the order code and amount, and a replacement for a cancelled intent under a key derived from the cancelled intent. This relies on Stripe keeping idempotency keys for 24 hours. After 24 hours, or after the order total changes, a new PaymentIntent is created, so a customer who still holds an older client secret can place a second hold. The plugin only captures a hold that covers the current order total and voids the others, so the customer is not charged twice, but the second hold stays on their card until it is voided or expires.

Local Development

1. Download & install the Stripe CLI: https://stripe.com/docs/stripe-cli
2. From your Stripe dashboard, go to Developers -> Webhooks and click "Add an endpoint" and follow the instructions under "Test in a local environment".
3. The Stripe CLI command will look like
   Shell

   stripe listen --forward-to localhost:3000/payments/stripe
4. The Stripe CLI will create a webhook signing secret you can then use in your config of the StripePlugin.