@antelopejs/stripe

The AntelopeJS Stripe provider implements portable payments and Stripe-native subscriptions with the official stripe SDK. It also implements the Stripe-specific API of @antelopejs/interface-stripe, with payment watchers and optional Redis fan-out.

Part of AntelopeJS, the TypeScript framework where modules depend on contracts and the application chooses the provider. Built by the team behind AntelopeJS DMS.

Choose an interface

| Consumer dependency | Use it for | | ------------------------------------- | --------------------------------------------------------------------------------------------------------- | | @antelopejs/interface-payment | Hosted checkout, direct payments, capture, refunds, customers, saved methods and normalized webhooks. | | @antelopejs/interface-subscriptions | Recurring billing scheduled by Stripe. This is the recommended subscription implementation for Stripe. | | @antelopejs/interface-stripe | Stripe SDK integrations and payment watchers. See the Stripe-specific guide. |

The generic payment-subscriptions scheduler is an alternative to Stripe-native subscriptions. Run one of the two, never both. The subscriptions guide shows how to switch.

Install and configure

Add the provider to the project and the payment interface to the consumer module:

ajs project modules add @antelopejs/stripe
ajs project modules install
pnpm add @antelopejs/interface-payment

The configuration guide has a complete package-source example with environment overrides, several accounts, and the optional API and Redis modules.

Portable checkout

Call this function from a consumer module that runs in AntelopeJS with this provider configured. The amount is an integer in minor units, so 2500 EUR means €25.00. Persist one idempotency key per logical checkout attempt, and reuse it only to retry that attempt.

import { CreateCheckoutSession } from "@antelopejs/interface-payment";

export async function checkoutOrder42() {
  const session = await CreateCheckoutSession(
    {
      reference: "order-42",
      amount: { value: 2500, currency: "EUR" },
      description: "Order 42",
      successUrl: "https://shop.example/orders/42/return",
      cancelUrl: "https://shop.example/orders/42/cancel",
    },
    "order-42:checkout:attempt-1",
  );
  return { sessionId: session.id, redirectUrl: session.redirectUrl };
}

Store the session ID and redirect the payer to redirectUrl. A browser return does not prove the payment. Read GetCheckoutSession when the payer returns, and fulfill the order from verified, deduplicated webhook events.

Documentation

• Configuration and multiple accounts
• Payments and retry safety
• Webhook routes, signatures and event types
• Stripe-native subscriptions and generic fallback
• Stripe-specific SDK access and watchers
• Agent skill: integrating Stripe checkout

Compatibility

| Package | Supported | Tested with | | ------------------------------------- | ----------------- | ----------- | | @antelopejs/interface-api | >=0.0.15 <1.0.0 | 0.0.15 | | @antelopejs/interface-core | >=0.4.0 <1.0.0 | 0.4.0 | | @antelopejs/interface-payment | >=0.2.0 <0.3.0 | 0.2.0 | | @antelopejs/interface-redis | >=0.0.9 <1.0.0 | 0.0.9 | | @antelopejs/interface-stripe | >=0.0.6 <0.1.0 | 0.0.6 | | @antelopejs/interface-subscriptions | >=0.1.0 <0.2.0 | 0.1.0 |

The table lists the interface ranges from package.json. .nvmrc sets the Node.js version for development, and dependencies in package.json sets the stripe SDK range.

Contributing and verification

Read CONTRIBUTING.md before opening a pull request. Run the local checks with pnpm:

pnpm install --frozen-lockfile
pnpm test
pnpm typecheck
pnpm lint
pnpm format:check
pnpm knip

pnpm test builds, then runs ajs module test . on four offline files: dist/test/provider-regressions.test.js, dist/test/webhook-events.test.js, dist/test/interface-stripe.test.js, and dist/test/redis-relay.test.js. They use a mocked Stripe transport, signed fixtures, and a mock Redis, not a real Stripe account.

pnpm test:stripe builds, then runs ANTELOPE_STRIPE_TEST_MODE=live ajs module test .. It needs a local STRIPE_KEY that starts with sk_test_. It refuses to run when CI is set, and it can create test-mode resources in your Stripe account. Run it before a release. A green offline run does not prove that the live Stripe API accepts the calls.

License

Apache-2.0