Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.veridianhp.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Core concepts

The Veridian API is built around four objects. If you understand these, everything else is just endpoints.

​
Practice

Your organization. A practice has API keys, webhook endpoints, branding settings, and a deposit destination. Most integrations only ever interact with one practice — their own.

​
Session

A single patient payment in progress. A session represents one invoice that one patient is paying. Sessions have a short lifetime — typically 30 minutes of patient activity — and move through these states:
  • pending — created, awaiting patient
  • processing — patient connected their bank, payment is in flight
  • succeeded — funds confirmed, you can mark the invoice paid
  • failed — bank declined, insufficient funds, or processor error
  • cancelled — practice or patient cancelled before completion
Once a session reaches a terminal state (succeeded, failed, cancelled), it doesn’t change. Failed sessions can be retried by creating a new session for the same invoice.

​
Hosted page

The patient-facing payment URL Veridian generates for each session. The hosted page handles the entire patient experience: showing what’s owed, collecting bank connection, confirming payment, displaying a receipt. You never embed or proxy the hosted page. You just send the patient the link (SMS, email, QR code at the front desk). Veridian handles the rest.

​
Webhook

A signed HTTP POST Veridian sends to your server when a session changes state. Webhooks are your source of truth for payment outcomes — never trust the hosted page or the patient’s browser. Always wait for the webhook. Webhooks are:
  • Signed with HMAC-SHA256 using a secret you control
  • Idempotent — Veridian retries on 5xx, you de-duplicate by event ID
  • Ordered best-effort — process them by created_at, not arrival order

​
How they fit together

┌──────────┐                                          ┌──────────┐
│ Practice │  ──── POST /sessions ──────────────────► │ Veridian │
│ backend  │  ◄──── { sessionId, hostedUrl } ──────── │   API    │
└──────────┘                                          └──────────┘
     │                                                     │
     │ send hostedUrl                                      │
     ▼                                                     │
┌──────────┐                                          ┌──────────┐
│ Patient  │  ─── opens hosted page ────────────────► │ Veridian │
│ phone    │                                          │ Bridge   │
└──────────┘  ◄── confirms payment ─────────────────  └──────────┘
                                                           │
                                                           │ payment settles
                                                           ▼
┌──────────┐                                          ┌──────────┐
│ Practice │  ◄── webhook: session.payment.* ──────── │ Veridian │
│ backend  │  ──── 200 OK ──────────────────────────► │ Webhooks │
└──────────┘                                          └──────────┘

​
What’s next

Bridge overview

Deeper look at the patient payment flow.

Authentication

API keys, scopes, rotation, and revocation.