Stripe

Experimental. Use test credentials. Keep its event endpoint private until provider verification, retries, and duplicate events pass your tests. See maturity levels.

The Stripe Module implements the current PaymentProvider interface from the Payments Module using the Stripe REST API. When you configure a signing secret, it verifies Stripe’s timestamped HMAC-SHA256 Webhook signatures. Source: modules/stripe · npm: @86d-store/stripe

Installation

npm install @86d-store/stripe @86d-store/payments

{
  "modules": ["@86d-store/payments", "@86d-store/stripe"],
  "advanced": {
    "version": 1,
    "allowExperimentalModules": true
  }
}

Set STRIPE_SECRET_KEY and STRIPE_WEBHOOK_SECRET in the server environment. The generator passes those values to the current provider factory. Do not put secret keys in source, config.json, browser variables, or Store Admin fields.

Configuration

string

required

Your Stripe test secret. Keep it in the server environment.

string

Stripe test-event signing secret. When provided, incoming requests use Stripe’s HMAC-SHA256 verification and timestamp tolerance.

PaymentProvider API

StripePaymentProvider implements the PaymentProvider interface. Use it directly when you need to create or manage payment intents in server-side code.

`createIntent`

Creates a Stripe PaymentIntent and returns a clientSecret in providerMetadata. Pass amount in the smallest currency unit (cents for USD).

const apiKey = process.env.STRIPE_SECRET_KEY;
if (!apiKey) throw new Error("STRIPE_SECRET_KEY is required");
const provider = new StripePaymentProvider(apiKey);

const intent = await provider.createIntent({
  amount: 2500,      // $25.00
  currency: "usd",
});
// {
//   providerIntentId: "pi_1234567890123",
//   status: "pending",
//   providerMetadata: { clientSecret: "pi_1234567890123_secret_1234567890123" }
// }

`confirmIntent`

Confirms a PaymentIntent after the Shopper completes payment on the client side.

await provider.confirmIntent("pi_1234567890123");

`cancelIntent`

Cancels an uncaptured PaymentIntent.

await provider.cancelIntent("pi_1234567890123");

`createRefund`

Issues a full or partial refund. Omit amount for a full refund.

await provider.createRefund({
  providerIntentId: "pi_1234567890123",
  amount: 1000,                       // $10.00 partial refund
  reason: "requested_by_customer",
});

Status mapping

Stripe status	Mapped status
`succeeded`	`succeeded`
`canceled`	`cancelled`
`processing`, `requires_capture`	`processing`
`requires_payment_method`, `requires_confirmation`, `requires_action`	`pending`

Store endpoints

Method	Path	Description
`POST`	`/stripe/webhook`	Receive and verify Stripe webhook events

Webhook setup

Set the environment variable

Add your webhook signing secret to your environment:

STRIPE_WEBHOOK_SECRET=stripe_webhook_secret_here

In the Stripe dashboard, add a new endpoint:

https://yourdomain.com/api/stripe/webhook

Select events to listen to

Enable at minimum:

payment_intent.succeeded
payment_intent.payment_failed
charge.refunded

How signature verification works

The webhook endpoint reads the raw request body before JSON parsing (required for HMAC integrity), then verifies the Stripe-Signature header:

signed_payload = event_timestamp + "." + raw_request_body
expected_sig   = HMAC-SHA256(webhookSecret, signed_payload)

The endpoint compares the v1 signature from the header in constant time to prevent timing attacks. Requests with invalid or expired signatures (older than 5 minutes) return 401. Verification uses the Web Crypto API and needs no external dependencies.

Types

interface StripeOptions {
  apiKey: string;
  webhookSecret?: string;
}

interface ProviderIntentResult {
  providerIntentId: string;
  status: "pending" | "processing" | "succeeded" | "cancelled" | "failed";
  providerMetadata?: Record<string, unknown>;
}

interface ProviderRefundResult {
  providerRefundId: string;
  status: "pending" | "succeeded" | "failed";
  providerMetadata?: Record<string, unknown>;
}

The full PaymentProvider interface from @86d-store/payments:

interface PaymentProvider {
  createIntent(params: {
    amount: number;
    currency: string;
    metadata?: Record<string, unknown>;
  }): Promise<ProviderIntentResult>;

  confirmIntent(providerIntentId: string): Promise<ProviderIntentResult>;

  cancelIntent(providerIntentId: string): Promise<ProviderIntentResult>;

  createRefund(params: {
    providerIntentId: string;
    amount?: number;
    reason?: string;
  }): Promise<ProviderRefundResult>;
}

Overview

Catalog

Shopping

Customers

Fulfillment

Marketing

Content

Finance

Sales channels

Operations

Installation

Configuration

PaymentProvider API

`createIntent`

`confirmIntent`

`cancelIntent`

`createRefund`

Status mapping

Store endpoints

Webhook setup

How signature verification works

Types

​Installation

​Configuration

​PaymentProvider API

​createIntent

​confirmIntent

​cancelIntent

​createRefund

​Status mapping

​Store endpoints

​Webhook setup

​How signature verification works

​Types

​Related pages

Installation

Configuration

PaymentProvider API

`createIntent`

`confirmIntent`

`cancelIntent`

`createRefund`

Status mapping

Store endpoints

Webhook setup

How signature verification works

Types

Related pages