Stripe Backend: Production-Ready Payments on Hostinger with Node.js

Integrating Stripe into a Node.js backend sounds straightforward until you hit the details: webhook signature verification, idempotent event handling, correct raw body capture, and deploying to shared hosting without native compilation. This project solves all of it in a minimal, well-documented package targeting Hostinger shared hosting with Node ≥ 22.

The backend uses Node's built-in node:sqlite module — no npm database driver, no native build step. Every Stripe event is recorded in an append-only audit log. The full test suite runs with Node's built-in test runner. Nothing exotic.

What the backend covers

The project handles the complete Stripe Checkout lifecycle: creating sessions, processing webhook events, persisting orders, and providing read endpoints for inspecting what happened. It's structured for real deployment, not just tutorial code.

POST /checkout/create-session — creates a Stripe Checkout Session and pre-inserts a pending order in SQLite. Returns the hosted Stripe checkout URL.

POST /webhook — receives signed Stripe events. Raw body is captured before any JSON parsing so the HMAC signature check passes. 9 event types handled.

GET /checkout/success — Stripe redirects here after payment. Verifies the session with Stripe and returns the stored order.

GET /orders, /orders/:id — read-only inspection endpoints for the SQLite database during development and debugging.

GET /orders/events/log — the full Stripe event audit trail, paginated. Every webhook received is stored here with its complete JSON payload.

GET /health — returns { "status": "ok" }. Used to verify the Hostinger deployment is alive.

Webhook event handling

One of the trickier parts of a Stripe integration is handling all the events correctly, including retries. The backend processes 9 event types and uses the Stripe event ID as a UNIQUE constraint in SQLite — duplicate deliveries are detected and silently acknowledged without processing twice.

Event	DB action
checkout.session.completed	Creates order if needed, marks `paid`
checkout.session.expired	Updates order status to `expired`
payment_intent.succeeded	Logged — order already set by session event
payment_intent.payment_failed	Logged + console alert
payment_intent.canceled	Logged
charge.succeeded	Logged
charge.failed	Logged + console alert
charge.refunded	Updates order status to `refunded`
charge.dispute.created	Logged + console warn

Database design

Two tables, each with a clear purpose. orders tracks the lifecycle of each Checkout Session — one row per session, status transitions from pending through paid, expired, or refunded. payment_events is an append-only audit log of every webhook received, including the full JSON payload.

-- orders: one row per Stripe Checkout Session
id              TEXT PK   -- cs_... session id
payment_intent  TEXT      -- pi_... (set after webhook)
customer_email  TEXT
amount_total    INTEGER   -- in cents
currency        TEXT
status          TEXT      -- pending → paid / expired / refunded
stripe_metadata TEXT      -- JSON blob
created_at      TEXT
updated_at      TEXT

-- payment_events: append-only audit log
id               INTEGER PK AUTOINCREMENT
stripe_event_id  TEXT UNIQUE  -- idempotency key
event_type       TEXT
related_object_id TEXT
payload          TEXT         -- full Stripe JSON
processed_at     TEXT

The stripe_event_id UNIQUE constraint is doing real work here. When Stripe retries a webhook delivery (which it will), the insert fails with a constraint violation, the handler catches it and returns { received: true, duplicate: true }, and no order state is corrupted.

Project structure

stripe-backend/
├── config/
│   └── stripe.js           # Stripe client + env validation
├── db/
│   └── database.js         # Schema, connection, query helpers
├── middleware/
│   └── rawBody.js          # Raw body capture for webhook HMAC
├── routes/
│   ├── checkout.js         # Create session, /success, /cancel
│   ├── orders.js           # Read-only order/event endpoints
│   └── webhook.js          # All Stripe event handlers
├── tests/
│   ├── database.test.js    # 27 DB layer unit tests
│   └── webhook.test.js     # Webhook handler integration tests
├── public/
│   └── index.html          # Quick browser test page
├── server.js
└── .env.example

Configuring Stripe keys

Stripe gives you two environments — Sandbox (formerly Test mode) and Live — with completely separate keys and webhook endpoints. The project includes a dedicated STRIPE_KEYS_GUIDE.md that covers every step: finding your API keys in the new Stripe Workbench UI, registering a webhook endpoint and selecting the 9 events, capturing the signing secret, configuring your .env, and setting environment variables in Hostinger's hPanel. It also covers key rotation and the security rules you can't skip.

Three environment variables is all you need to start:

# .env
STRIPE_SECRET_KEY=sk_test_51...
STRIPE_WEBHOOK_SECRET=whsec_...
APP_BASE_URL=https://yourdomain.com
CORS_ORIGINS=https://yourdomain.com
PORT=3000

Never commit .env to Git. The .gitignore already excludes it — verify with git check-ignore -v .env before your first push.

Testing the API

The project ships with two testing tracks: an automated test suite and a curl-based manual guide. The API_TESTING_GUIDE.md walks through every endpoint with exact curl commands, expected responses for both success and error cases, and a full end-to-end payment flow from session creation to webhook confirmation.

Automated tests

The test suite uses Node's built-in node:test runner — no Jest, no Vitest, no extra dependencies. Each test suite gets an isolated :memory: SQLite database, so nothing touches disk and tests are fully repeatable.

npm test

▶ orders table (9 tests)
▶ payment_events table (7 tests)
▶ schema integrity (5 tests)
▶ webhook: checkout.session.completed (2 tests)
▶ webhook: checkout.session.expired (2 tests)
▶ webhook: idempotency (2 tests)
▶ webhook: charge.refunded (1 test)
▶ webhook: event log audit trail (1 test)

tests 34  pass 34  fail 0

Webhook testing with Stripe CLI

The webhook endpoint requires a valid Stripe signature — you can't just curl it directly. Use the Stripe CLI to forward real sandbox events to your local server:

# Terminal 1 — start the server
npm run dev

# Terminal 2 — forward Stripe events to localhost
stripe listen --forward-to localhost:3000/webhook

# Terminal 3 — trigger test events
stripe trigger checkout.session.completed
stripe trigger charge.refunded
stripe trigger charge.dispute.created

Test cards

Card number	Scenario
4242 4242 4242 4242	Payment succeeds
4000 0000 0000 0002	Card declined
4000 0025 0000 3155	3D Secure required
4000 0000 0000 9995	Insufficient funds

Deploying to Hostinger

The README includes a specific Hostinger deployment section because shared hosting has some non-obvious constraints. The key decisions:

Set DB_PATH to an absolute path outside the web root — never inside public_html. The directory is created automatically on first run, but the path must be writable by your Node process. On Hostinger, something like /home/username/stripe-data/stripe.db works reliably.

Use hPanel's Environment Variables section instead of uploading a .env file via SFTP. Add each variable individually, save, and restart the Node.js app. This is safer than managing a secrets file on disk and easier to update without SSH access.

The production checklist in the README covers the full go-live sequence: switching from sandbox to live Stripe keys, registering a live webhook endpoint, locking down the /orders endpoints (no auth in the current implementation), enabling HTTPS, and setting up a SQLite backup schedule.