Full-stack · Python · FastAPI · PostgreSQL · Stripe · Render

Jobs API with Stripe payments (Python, FastAPI and PostgreSQL)

A jobs-board API with a production-grade payment flow, built and verified end to end. Employers create, list and filter listings, then feature a job for £5 through Stripe-hosted Checkout. Webhooks are signature-verified, payments are recorded idempotently in PostgreSQL, and a nightly job reconciles anything Stripe has confirmed that the database does not yet have.

BackendPython · FastAPI, hosted on Render
DatabasePostgreSQL (Neon) · psycopg
PaymentsStripe Checkout · test mode, live-ready
AutomationGitHub Actions nightly reconcile at 02:00 UTC
FastAPI Swagger documentation page (/docs) for the live Jobs API, showing the interactive OpenAPI interface
Interactive API documentation (FastAPI /docs) for the live Jobs API, captured on 18 November 2026.

The payment integrity problem

A featured listing should appear only after Stripe has confirmed payment, and only once. Checkout can succeed while the webhook never arrives — the process was asleep, the request timed out, or the listener was not running yet — and the same event can be delivered twice. Handle either case badly and a paid listing stays unfeatured, or featured is applied twice.

The system treats Stripe as the source of truth. The webhook records a payment when it arrives; a protected reconcile route later inserts any completed session the database is missing. Both paths share the same idempotent write, so they can overlap.

Architecture

Client
  ↓
FastAPI API on Render
  ↓
Stripe-hosted Checkout
  ↓
Stripe → signature-verified webhook → Neon Postgres

Nightly GitHub Action
  ↓
Wake GET /jobs
  ↓
POST /admin/reconcile (X-Admin-Token)
  ↓
Stripe API → Postgres
Main API routes
RouteRole
/jobsCreate and list jobs, with case-insensitive city and visa-sponsorship filters
/jobs/{id}/featureStart Stripe Checkout for a £5 featured listing
/webhooks/stripeVerify the Stripe signature and record a completed payment
/admin/reconcilePull completed sessions from Stripe and insert any that are missing

Key technical decisions

  • Hosted Checkout, not a card form on the server. Taking card details would pull the API into PCI scope. It creates a Checkout session and redirects to Stripe, so card data never touches the server. The trade-off is Stripe’s payment UI.
  • Verify the webhook on the raw body, first. An unverified endpoint could accept a forged “paid” event. The handler checks Stripe’s signature against the raw request body before any write, and returns HTTP 400 on failure, so the body must not be pre-parsed.
  • Make the write idempotent in the database. Stripe retries webhooks, and reconcile can see a session already handled. A UNIQUE constraint on stripe_session_id plus INSERT ... ON CONFLICT DO NOTHING (with RETURNING) lets exactly one insert win; featured is set only when a row is inserted.
  • Reconcile from Stripe, not from the webhook alone. A missed webhook is a silent failure. POST /admin/reconcile pulls completed sessions and inserts any payment the database does not yet have. During development this recovered a real missed payment from before the listener was running.
  • Protect reconcile with a constant-time token. An open route would let anyone probe Stripe and write payments. The X-Admin-Token header is compared with secrets.compare_digest — a tight lock on one privileged route, not a full authentication system.
  • Run reconcile unattended, after waking the server. Render’s free tier sleeps when idle, so a scheduled call can time out. At 02:00 UTC, GitHub Actions wakes the service with /jobs, then posts to reconcile, using an encrypted Actions secret.
  • Keep secrets and SQL conservative. Parameterised SQL, transactions that roll back on error, secrets only in environment variables, and a stateless Render deploy with data in Neon Postgres.

Challenges and fixes

  • A missing space in a dynamically built query produced invalid SQL until the query builder was corrected.
  • City filtering is case-insensitive, so “hull” and “Hull” return the same listings.
  • Local webhook testing used a tight Stripe CLI allow-list, forwarding only the events the handler uses.
  • Free-tier sleep delayed webhooks and the scheduled job, so the nightly workflow wakes the API with /jobs before reconcile.

Going live

The payment code is already the live path. Switching the public deployment from test to live is a configuration change, not a rewrite: live Stripe keys in the Render environment variables, a live webhook at /webhooks/stripe with the matching signing secret, and Stripe account activation. Checkout, signature verification, the idempotent insert, reconcile and the nightly job do not change. The API uses Stripe test keys, so the flow can be exercised end to end without taking real card payments.

Scope and next steps

  • The public deployment uses Stripe test keys today; going live is the configuration step above.
  • The free-tier Render service sleeps when idle, so the first request after a quiet period can be slow.
  • Refunds, an admin dashboard, rate limiting and alerting are planned next.

What this project demonstrates

  • API design: a FastAPI jobs board with create, list, filter, get, delete and a paid feature path, deployed on Render.
  • Payment integration: hosted Checkout, signature-verified webhooks and idempotent PostgreSQL writes, safe to retry and safe to run twice.
  • Reconciliation and operations: a protected admin route that recovers missed webhooks from Stripe, a nightly GitHub Actions job, and secrets held in environment variables and encrypted Actions secrets.

I offer the same pattern under the Payment Integration & Business Automation service.

Written by Emmanuel Abolade, Data Analyst, Business Intelligence Developer and Full-Stack Software Developer based in Hull, UK. Every figure on this page comes from the linked public repository or live demo.