TransactKit-Lite quickstart

Prerequisites

The Maven wrapper is included, so a system Maven installation is not required.

Java 25.
Git.
A current browser.
A Stripe account and Stripe CLI only when testing real Stripe Checkout and webhook delivery.
MySQL only when replacing the default in-memory H2 database.

Clone and run

Do not create a .env file for the first run. The application starts on port 8080, applies Flyway migration V1 to in-memory H2, and validates the schema with Hibernate.

macOS / Linux

git clone https://github.com/buildbasekit/TransactKit-Lite.git
cd TransactKit-Lite
./mvnw spring-boot:run

Windows PowerShell

git clone https://github.com/buildbasekit/TransactKit-Lite.git
Set-Location .\TransactKit-Lite
.\mvnw.cmd spring-boot:run

Verify the local application

Open http://localhost:8080/api-test/index.html to load the same-origin browser API tester. It can inspect configuration and submit Customer, Checkout, Payment, and Refund requests. Webhook delivery is intentionally excluded because a browser must not receive the signing secret.

Windows PowerShell

Invoke-RestMethod http://localhost:8080/api/configuration

macOS / Linux

curl http://localhost:8080/api/configuration

Expected response without Stripe configuration

{
  "stripeApiConfigured": false,
  "webhookConfigured": false
}

✓ TransactKit-Lite is running with H2 and its local testing interface is available.

Choose the right test path

TransactKit-Lite test paths
Path	Credentials	What it verifies
Default automated suite	None	Application validation, persistence, idempotency, webhook fixtures, transaction behavior, and error handling
stripe-mock profile	Dummy local test key	Selected Stripe request contracts and SDK serialization/deserialization
Stripe Test Mode	Stripe test secret plus webhook secret	Hosted Checkout, card outcomes, real Stripe lifecycle behavior, webhook delivery, retries/order, and Dashboard state

Connect Stripe Test Mode

Copy .env.example to .env only when you are ready to call Stripe. Set a Stripe test-mode secret key, then use the Stripe CLI to forward the seven handled event types. Put the CLI-provided whsec_ value in STRIPE_WEBHOOK_SECRET and restart the application.

.env

STRIPE_SECRET_KEY=sk_test_replace_me
STRIPE_WEBHOOK_SECRET=whsec_replace_me
STRIPE_SUCCESS_URL=http://localhost:8080/api-test/success.html
STRIPE_CANCEL_URL=http://localhost:8080/api-test/cancel.html

Stripe CLI

stripe listen --events checkout.session.completed,checkout.session.async_payment_succeeded,checkout.session.async_payment_failed,checkout.session.expired,refund.created,refund.updated,refund.failed --forward-to localhost:8080/api/stripe/webhook

Run the safest first payment flow

Confirm /api/configuration reports stripeApiConfigured and webhookConfigured as true.
Create a Checkout Session with a stable businessReference and a unique attemptReference.
Open only the checkoutUrl returned by the API and use Stripe test payment data on Stripe's hosted page.
Let the Stripe CLI forward the resulting Checkout event.
Retrieve /api/payments/{paymentId} and compare the local projection with Stripe Test Mode.
Create a refund only after the local payment status is PAID or PARTIALLY_REFUNDED.

Checkout and payment API reference Webhook setup and retries Complete testing guide

Run the offline test suite

The standard suite requires no Stripe key, Stripe CLI, MySQL, browser, or internet service. Import TransactKit-Lite-API.postman_collection.json when you want the repository's guided Postman workflow.

macOS / Linux

./mvnw clean verify

Windows PowerShell

.\mvnw.cmd clean verify