8 min read

Payment Gateway Integration

Patients pay by card in the patient portal, and staff can take a card on a patient account, through Stripe Connect: each practice connects its own Stripe account and the charge is made on it, with card details going straight to Stripe. It ships switched off - nothing is charged until the platform's Stripe keys are set and the practice has connected its account.

Card payments, saved cards and AutoPayNeeds an external connection

Built on Stripe, with each practice paid into its own Stripe account. Not switched on for the hosted service today: payments run in a non-charging mode and no Stripe keys are set, so no card can be charged. Payments received another way can still be recorded. No ACH.

Requires: Stripe enabled for the deployment by ArkCloud, then your administrator connects your practice's Stripe account.

What It Does

Patient card payments in the portal

Patients pay a balance by credit or debit card in the patient portal. The charge is made on the practice's own connected Stripe account - never on ArkCloud's.

Card data stays with Stripe

Card details are entered in Stripe's own form (Stripe Elements) and tokenised by Stripe; card numbers never reach ArkCloud's servers.

Payments recorded on the ledger

A successful payment is posted to the patient account through the payment ledger; Stripe's signed webhook confirms success, failure, refunds and disputes.

Staff card payments

Staff with the process_payments permission (Agent, Supervisor, Admin) use Take card payment on a patient account. The card is entered in Stripe's card form on the practice's connected account, and the ledger moves only when Stripe's signed webhook confirms the charge.

Saved cards and AutoPay

With the patient's explicit, versioned consent, a card can be saved through a Stripe SetupIntent (by staff or by the patient in the portal). AutoPay on a payment plan charges it only after the AutoPay terms are accepted; installments are charged by the background worker, so the worker service must be running.

Refunds

Refunds of card payments are issued through Stripe and need the refund_payments permission (ADMIN).

Turning It On

Platform: set the Stripe keys

Set STRIPE_SECRET_KEY, NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY and STRIPE_WEBHOOK_SECRET in the server environment (plus STRIPE_CONNECT_WEBHOOK_SECRET for events from practices' accounts)

These are environment-managed: the back office Credentials page shows their status but will not store them, because the publishable key is built into the browser bundle

PAYMENT_MODE must not be "stub"

Point the Stripe webhook at /api/webhooks/stripe - the Connect webhook (events from practices' accounts) uses the same URL with its own signing secret

Practice: connect Stripe

An ADMIN opens Settings -> Payments (/dashboard/settings/payments, or /rehab/settings/payments in Rehab)

Starts Stripe Connect and completes Stripe's onboarding for the practice's own account

Returns to ArkCloud, which asks Stripe whether the account can take charges

Test

Use Stripe test-mode keys on a non-production deployment first

Pay a test balance in the patient portal and confirm it posts to the account

Issue a test refund and confirm the webhook records it

Separately, staff with the process_payments permission (AGENT, SUPERVISOR, ADMIN) can record payments the practice took by other means, such as cash, cheque or its own card terminal. ArkCloud's own subscription billing of the practice also uses Stripe, but on ArkCloud's account - it is not part of patient payments.

Not Built

ACH / eCheck / bank transfer payments

Staff typing card or bank numbers into an ArkCloud screen - staff payment actions refuse card and bank methods (lib/payment-liveness.ts:79-92); cards go through Stripe's form only

Card-present terminals, tap-to-pay or swipe readers

Square, Authorize.Net, PayPal or any processor other than Stripe - Square and Authorize.Net are not integrated; selecting them takes no payment

Turning on AutoPay while enrolling in a portal payment plan - the plan is created first, then AutoPay is turned on with a card saved through Stripe's form

Digital-wallet buttons as an ArkCloud feature (whatever Stripe's form offers is Stripe's)

Security

Processor-held PCI DSS Level 1 attestation

Card details route to the processor, which holds the attestation. ArkCloud holds none and stores no card numbers.

Tokenisation by Stripe

Stripe Elements collects the card; ArkCloud handles Stripe's tokens and payment IDs, and for a saved card only the brand, last four digits and expiry Stripe reports.

Signed webhooks

Stripe events are accepted only with a valid Stripe signature; without the webhook secret the endpoint refuses every event.

Practice-owned funds

Charges go to the practice's connected account. If a practice has not connected one, the portal does not take the payment - it never falls back to ArkCloud's account.

PCI Compliance

Card data is handled by Stripe, which holds its own PCI DSS attestation. ArkCloud holds no PCI certification or attestation of its own. Because card details are entered in Stripe's form and never reach ArkCloud, your own PCI scope for portal payments is reduced - confirm your obligations with Stripe and your assessor.

No Card Storage

Stripe tokens and payment IDs (plus brand, last four and expiry of a saved card), never full card numbers or CVCs

Reduced Scope

Card entry happens in Stripe's form

Payment Processing Payment Methods PCI Compliance Payment Plans