Project

stripe-development

A lightweight local dashboard, playground, and webhook receiver for exercising the Stripe API in test mode — built directly against the Stripe REST API, no SDK dependency, on BoxLang and BoxExpress.

View on GitHub

Dashboard

Read-only overview of a Stripe test account — balances, charges, customers, subscriptions, invoices, payouts, disputes, checkout sessions, payment methods, and both the raw Stripe event log and the app's own received webhook events.

Playground

Forms that fire real create/update/cancel calls against Stripe test mode and show the raw JSON response.

Webhook receiver

Verifies Stripe webhook signatures, guards against replay, and persists recent deliveries at POST /webhooks/stripe.

Live-mode lockout

If the configured Stripe key is in live mode, every Playground write is refused automatically. The dashboard still works, since it only reads.

Requirements

  • The BoxLang runtime (boxlang on your PATH)
  • A Stripe account with a test-mode secret key
  • (Optional) the Stripe CLI for local webhook testing

Setup

Create a .env file at the project root:

envENV=development
STRIPE_SECRET_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...

STRIPE_WEBHOOK_SECRET is only needed for webhook testing — see below for where that value comes from.

Running it

bashboxlang app.bxs

Then open http://localhost:3000.

Testing webhooks

With the app running, forward Stripe events to it with the Stripe CLI:

bashstripe listen --forward-to localhost:3000/webhooks/stripe

Copy the signing secret it prints (whsec_...) into .env as STRIPE_WEBHOOK_SECRET — it generates a new one each time it starts, so restart boxlang app.bxs after updating it. Then fire a test event:

bashstripe trigger charge.succeeded

Accepted deliveries show up in the dashboard's "Recent webhook events" section.

Running tests

tests.bxs is a small, dependency-free regression suite for StripeWebhookHandler.bx (signature verification, replay protection, secret rotation, persistence) — no network calls involved.

bashboxlang tests.bxs

Exits non-zero on any failure.

Project layout

app.bxs                     Bootstrap: creates the app, wires up helpers and routes, listens on :3000
bootstrap/stripe.bxs        Builds the StripeClient + webhook handler, checks live-mode
helpers/
  Formatting.bx              Pure display formatting (money, dates, status badge classes)
  Annotators.bx              Attaches formatted fields onto raw Stripe list responses
  Playground.bx              Shared playground render/guard logic (CSRF data, live-mode block)
routes/
  *Routes.bx                 One class per Stripe resource (charges, customers, invoices, ...)
  WebhookRoutes.bx           POST /webhooks/stripe
  DashboardRoutes.bx         GET /
  PlaygroundRoutes.bx        GET /playground
views/
  *.bxm                      One template per page
  partials/nav.bxm           Shared navbar + Quick nav dropdown
  partials/breadcrumb.bxm    Shared breadcrumb trail
StripeClient.bx              Thin wrapper over the Stripe REST API — no SDK dependency
StripeWebhookHandler.bx      Signature verification + event persistence
public/                      Static assets, including the developer guide

Developer guide

A fuller developer guide — dashboard walkthrough, the full Playground action list, Stripe CLI webhook testing steps, and how to add a new resource route — lives as static pages under public/docs/ in the repo, and is one click away from any page in the running app via the Quick nav → Developer guide link.