Skip to content

Payments with Stripe

Overview

Status: Planned feature - not yet implemented in current deployment.

Quill Medical will use Stripe as its payment processing platform to handle secure financial transactions between patients and healthcare providers. Stripe will enable patients to pay for clinical communication services and other healthcare-related charges safely and reliably.

Why Stripe?

Security and Compliance

  • PCI DSS Compliant: Stripe handles all payment card data, so Quill Medical never stores sensitive card information
  • Healthcare-Ready: Supports compliance with healthcare regulations and data protection requirements
  • Fraud Prevention: Built-in tools to detect and prevent fraudulent transactions
  • Secure by Default: All payment data is encrypted in transit and at rest

Developer Experience

  • Well-Documented API: Comprehensive documentation and libraries for integration
  • Test Mode: Separate test environment for development and testing
  • Webhooks: Real-time notifications for payment events
  • Dashboard: Web-based interface for viewing transactions and managing settings

Payment Features

  • Multiple Payment Methods: Credit cards, debit cards, and digital wallets
  • International Support: Accept payments in multiple currencies
  • Subscription Billing: Recurring charges for ongoing services
  • Refunds: Easy processing of full or partial refunds

How Payments Work

Payment Flow

  1. Service Request: Patient requests a paid communication service (e.g., video consultation, letter review)
  2. Payment Intent: Backend creates a Stripe payment intent with the amount and description
  3. Payment Form: Frontend displays secure payment form (hosted by Stripe)
  4. Card Processing: Patient enters payment details, which go directly to Stripe
  5. Confirmation: Stripe processes payment and notifies our backend via webhook
  6. Service Delivery: Once payment confirmed, the requested service is activated

Payment Intents

Payment Intents represent a payment transaction from start to finish:

  • Track the payment lifecycle from creation to completion
  • Support authentication for secure transactions (3D Secure)
  • Handle declined payments and retry logic
  • Confirm successful payments

Webhooks

Stripe sends webhook notifications to our backend when payment events occur:

  • Payment Succeeded: Funds captured successfully
  • Payment Failed: Transaction declined or failed
  • Refund Processed: Refund completed
  • Dispute Created: Customer initiated a chargeback

Our backend listens for these events and updates service status accordingly.

Payment Types

One-Time Payments

Used for individual services such as:

  • Single consultation sessions
  • Document review requests
  • Clinical letter generation
  • Ad-hoc medical advice

Recurring Payments (Future)

Planned support for subscription-based services:

  • Monthly care packages
  • Ongoing monitoring services
  • Regular check-ins

Security Measures

Payment Data Isolation

  • Patient payment information never passes through our servers
  • All card details handled exclusively by Stripe
  • Reduces our PCI compliance scope
  • Minimises security risks

Verification and Authentication

  • 3D Secure: Additional cardholder authentication for supported cards
  • Address Verification: Check billing address matches card details
  • CVC Verification: Confirm card security code
  • Email Confirmation: Send receipts and confirmations to patients

Webhook Security

  • Webhook signatures verify requests actually come from Stripe
  • Prevents malicious actors from faking payment notifications
  • All webhook endpoints protected and validated

Patient Experience

Transparent Pricing

  • Clear display of costs before payment
  • Breakdown of fees and charges
  • No hidden costs

Payment Receipts

  • Automatic email receipts for all transactions
  • Accessible payment history in patient portal
  • Downloadable invoices for record-keeping

Refund Process

  • Refunds processed back to original payment method
  • Typically appear within 5-10 business days
  • Automatic notification when refund is initiated

Integration Points

Backend API

The FastAPI backend integrates with Stripe via:

  • Stripe Python SDK: Official library for server-side integration
  • API Keys: Secure authentication with Stripe services
  • Webhook Handlers: Endpoints to receive Stripe event notifications

Frontend Application

The React frontend uses:

  • Stripe.js: JavaScript library for secure payment forms
  • Stripe Elements: Pre-built UI components for payment collection
  • Payment Confirmation: Display success/failure messages to users

Testing

Test Mode

Stripe provides test credentials for development:

  • Test API keys that never process real payments
  • Test card numbers for simulating different scenarios
  • Ability to trigger webhooks manually

Test Scenarios

Developers can test:

  • Successful payments
  • Declined cards
  • Expired cards
  • Insufficient funds
  • 3D Secure authentication
  • Refund processing

Monitoring

Transaction Dashboard

Administrators can view:

  • All payment transactions
  • Success and failure rates
  • Revenue reports
  • Disputed payments

Financial Reconciliation

  • Automatic matching of Stripe payouts to transactions
  • Export transaction data for accounting
  • Track fees and net revenue

Resources