AbsoluteJS

@absolutejs/commerce-stripe

@absolutejs/commerce-stripev0.25.1-beta.11betaCommerce & Growth

Stripe payment + checkout adapter for @absolutejs/commerce

#Installation

BASH
bun add @absolutejs/commerce-stripe

#Capabilities

Overview

Stripe payment + checkout adapter for @absolutejs/commerce. Implements the PaymentProvider contract: create embedded or hosted checkout sessions (with shipping, discounts, and automatic tax + graceful fallback), mint one-off coupons, idempotent refunds, and verify webhooks into normalized checkout and payment-dispute events. Disputes retain only provider-neutral identity, amount, reason, status, and evidence deadline for the commerce aftercare case substrate.

During signing-secret rotation, pass webhookSecrets in newest-first order and use onWebhookSecretVerified to record which retained version matched. Managed platforms can use createStripeWebhookEndpointManager to stage an endpoint as disabled, persist its one-time signing secret, verify local retrieval, and only then enable delivery.

submitDisputeEvidence() uploads every clean attachment with Stripe purpose dispute_evidence, maps provider-neutral text and file purposes onto the Dispute evidence fields, and updates the exact dispute. File and dispute calls receive stable host-owned idempotency keys. submit: false stages evidence for review; submit: true sends it to the payment network. The host application keeps the latter behind a separate default-off gate.

Show 1 more

reconcileDisputeEvidence() retrieves the exact Stripe Dispute and compares the intended normalized text and file-purpose fields with Stripe's retained evidence. It reports whether the effect applied, maps provider file IDs back to host attachment IDs, and derives staged/submitted state from has_evidence and submission_count. It also reports only the mismatched field/purpose names and missing/different reason, never the expected or observed customer values. Hosts can therefore explain and reconcile an ambiguous update before deciding whether the stable-idempotency submission may be retried.

Outcomes

What you can build

Build on the supported package contract

Use @absolutejs/commerce-stripe through its supported public entry points.

Hardening checklist

Production guidance

Make every external boundary explicitPin the deployed @absolutejs/commerce-stripe version, replace example or memory-backed dependencies with durable implementations, bound external calls, protect credentials, and emit enough evidence to retry or recover safely.

Follow in order

Troubleshooting path

1
Trace from the first failed boundary
Reproduce the smallest canonical @absolutejs/commerce-stripe example, confirm the supported entry point and version in the API explorer, then inspect the first boundary that did not produce its documented result.

#@absolutejs/commerce-stripe quick start

Partial snippet

# @absolutejs/commerce-stripe

TS
import { createStripePayment } from "@absolutejs/commerce-stripe";

const payments = createStripePayment({
  secretKey: process.env.STRIPE_SECRET_KEY!,
  webhookSecret: process.env.STRIPE_WEBHOOK_SECRET!,
});

const { clientSecret } = await payments.createCheckout({
  idempotencyKey: "checkout-attempt-123",
  uiMode: "embedded",
  returnUrl: `${origin}/return?session_id={CHECKOUT_SESSION_ID}`,
  lineItems: [{ name: "Classic Tee", amountCents: 4000, quantity: 1 }],
  shipping: { mode: "collect", countries: ["US", "CA"], flatAmountCents: 600 },
  automaticTax: true,
});

// In your webhook route (pass the raw body):
const event = await payments.verifyWebhook(rawBody, signature);
if (event.isComplete) fulfil(event.session); // normalized, gateway-agnostic

#Public entry points

Supported entry points declared by this package manifest.

Package entry point declared in package.json.

@absolutejs/commerce-stripe@absolutejs/commerce-stripe/manifest@absolutejs/commerce-stripe/manifest.json

#Package commands

Scripts declared by this package manifest.

bun run buildrm -rf dist && bun build ./src/index.ts ./src/manifest.ts --root ./src --outdir dist --target bun --external @absolutejs/commerce --external '@absolutejs/commerce/*' --external @absolutejs/manifest --external @sinclair/typebox --external stripe --external 'stripe/*' && tsc --emitDeclarationOnly --project tsconfig.json && absolute-manifest emit
bun run check:packagebun run format && bun run typecheck && bun run test && bun run verify-package && bun run build
bun run formatprettier --write "./**/*.{js,ts,json,md}"
bun run testbun test
bun run typechecktsc --noEmit