Payment Methods

EaseLab processes SaaS subscription payments through configured payment gateways. This guide covers how lab owners pay for plans, what data EaseLab stores, and how platform administrators wire the payment account.

Payment architecture

flowchart TB
    subgraph Lab Portal
        CO[Checkout]
    end
    subgraph EaseLab API
        BILL[BillingService]
        WH[Webhook handler]
    end
    subgraph Provider
        GW[Payment gateway]
    end
    CO --> BILL --> GW
    GW --> WH --> BILL
    WH --> SUB[Subscription activation]

Patient invoice payments (cash, card at desk) are recorded in tenant ledgers — separate from SaaS gateway flows documented here.

Supported payment flows

Flow	Route	Environment
Standard checkout	/billing/checkout/:planId	Production
Payment return	/billing/return	After redirect
Dev simulation	/billing/dev-pay	Development only
Billing history	/billing/history	Receipts

Gateway brand depends on platform configuration (Stripe, regional PSP, etc.).

Checkout payment capture

During checkout:

1. User selects plan and billing cycle.
2. EaseLab creates a payment session with the provider.
3. User enters card or wallet details on provider-hosted or embedded fields.
4. Provider tokenizes sensitive data — PAN never touches EaseLab databases.
5. Webhook confirms success → subscription activated.

3-D Secure

Cards requiring SCA may show an extra bank challenge — complete it or payment stays pending.

Stored payment data

Data	Stored in EaseLab?
Full card number	No
Provider customer ID	Yes
Last four digits	Optional display
Expiry	Optional display
Billing address	Yes for invoices

PCI scope is minimized via provider tokenization.

Platform payment account

Platform operators configure merchant credentials in Payment Account Setup:

Setting	Purpose
API keys	Server-side charge creation
Webhook secret	Validate callback authenticity
Currency	Default checkout currency
Test mode	Sandbox transactions

Labs cannot edit platform gateway keys — only consume checkout.

Webhooks

sequenceDiagram
    participant Gateway
    participant EaseLab
    Gateway->>EaseLab: payment.succeeded
    EaseLab->>EaseLab: Verify signature
    EaseLab->>EaseLab: Extend subscription ExpiresAt
    EaseLab->>EaseLab: Clear IsLocked

Failed webhooks may leave paid customers in read-only mode until manual reconciliation.

Failed payments

Event	Tenant state
Card declined	Checkout error — no change
Renewal failed	May transition to Overdue
Chargeback	Platform admin review

Users should update payment method and retry from /billing/plans or billing history.

Receipts and invoicing

/billing/history provides:

• Transaction reference
• Amount and tax
• PDF receipt download (when enabled)
• Email copy to billing contact

Export for accounting alongside financial reports of your lab business.

Security

Control	Detail
HTTPS	Required for checkout
Webhook signatures	Prevents forged activations
Idempotency	Duplicate webhooks ignored
Audit	Platform admin billing log

Phishing

EaseLab never asks for card details via email. Checkout only on official portal URLs — verify custom domain TLS certificate.

Troubleshooting

Issue	Action
Payment succeeded, still locked	Wait 2 min; contact support with txn ID
Currency mismatch	Platform currency config
Webhook 401	Secret rotation — platform admin
Dev-pay only works locally	Expected — use real checkout in staging

Related documentation

• Plans & Checkout
• Billing Overview
• Platform: Payment Account
• Troubleshooting: Billing