antelopejs/stripe

Official

Stripe payment processing module with webhook support

ajs project modules add @antelopejs/stripe

Implementsstripe

@antelopejs/stripe

The AntelopeJS payment module: it serves the Stripe interface with the official stripe SDK, receives Stripe webhooks, and shares payment intent updates between instances through Redis.

Interfaces

Interface	Documentation
`@antelopejs/interface-stripe`	Stripe

The module also needs a module for each of these interfaces:

@antelopejs/interface-api, for the webhook route, served by @antelopejs/api.
@antelopejs/interface-redis, to broadcast payment intent changes, served by @antelopejs/redis. The module waits for a Redis client before it starts.

Install

ajs project modules add @antelopejs/stripe
ajs project modules install

ajs project modules install adds the API and Redis modules when the project has none yet.

Configuration

import { defineConfig } from "@antelopejs/interface-core/config";

export default defineConfig({
  name: "my-project",
  modules: {
    stripe: {
      source: {
        type: "package",
        package: "@antelopejs/stripe",
        version: "^1.0.2",
      },
      config: {
        apiKey: "sk_test_...",
        webhookSecret: "whsec_...",
        endpoint: "stripe",
        maxNetworkRetries: 2,
      },
    },
  },
  envOverrides: {
    STRIPE_SECRET_KEY: "modules.stripe.config.apiKey",
    STRIPE_WEBHOOK_SECRET: "modules.stripe.config.webhookSecret",
  },
});

Key	Description
`apiKey`	Stripe secret key.
`webhookSecret`	Signing secret of the webhook endpoint, used to verify each event.
`endpoint`	Path of the webhook route. Defaults to `stripe`, which serves `POST /stripe`.
any other key	Passed to the SDK as `StripeConfig` (`apiVersion`, `maxNetworkRetries`, `timeout`…).

ajs project modules add writes placeholder values for apiKey and webhookSecret: replace them before starting the project.

Point a Stripe webhook endpoint at <public API origin>/<endpoint> and subscribe it to the payment_intent.* events your modules watch. Requests whose stripe-signature header does not verify get a 403.

Quick start

In the module that takes payments, add the interface:

pnpm add @antelopejs/interface-stripe

import { InitializePayment, WatchPayment } from "@antelopejs/interface-stripe";

const intent = await InitializePayment("order-42", {
  amount: 2500,
  currency: "eur",
  payment_method_types: ["card"],
});

WatchPayment(intent.id, (id, paymentIntent, context) => {
  console.log(id, paymentIntent.status, context.local);
});

Send intent.client_secret to the browser to confirm the payment with Stripe.js. The watcher runs on every instance when the webhook reports a change; context.local is true on the instance that received the webhook.

Documentation

Stripe: the @antelopejs/interface-stripe contract this module implements
Configuration: module sources, config blocks and config variables in antelope.config.ts

Compatibility

Package	Supported range
`@antelopejs/interface-stripe`	`>=0.0.4 <1.0.0`
`@antelopejs/interface-api`	`>=0.0.5 <1.0.0`
`@antelopejs/interface-redis`	`>=0.0.6 <1.0.0`
`@antelopejs/interface-core`	`>=0.0.5 <1.0.0`

The module is developed against @antelopejs/core ^1.13.4 on Node.js 24, with stripe ^18.5.0.

Contributing

pnpm install
pnpm lint
pnpm format:check
pnpm typecheck
pnpm knip

The module has no automated tests yet: pnpm test only prints a message. Read the contribution guidelines before opening a pull request.

License

Apache-2.0