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.

​
Sessions

A session represents one patient paying one invoice. Sessions are the primary object in the Veridian API — most integrations only ever touch this endpoint family.

​
Create a session

curl -X POST https://api.veridianhp.com/api/practice/sessions \
  -H "Authorization: Bearer $VERIDIAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "invoiceId": "INV-2026-001",
    "amountCents": 14500,
    "patient": {
      "firstName": "Jane",
      "lastName": "Patient"
    },
    "metadata": {
      "providerId": "prov_42"
    }
  }'

​
Request body

FieldTypeRequiredDescription
invoiceIdstringyesYour invoice identifier, surfaced in webhooks.
amountCentsintyesAmount in cents. Positive integer.
patientobjectyesMinimal patient identifiers. See below.
metadataobjectnoUp to 16 keys, string values, surfaced in webhooks.
patient object:
FieldTypeRequiredDescription
firstNamestringyesFirst name only.
lastNamestringyesLast name only.
Veridian intentionally requires only the minimum identifiers needed to render a friendly Bridge page. Do not pass diagnosis codes, account numbers, or any other PHI in the patient or metadata fields.

​
Response — 201 Created

{
  "sessionId": "ses_01HZX9ABCDEF",
  "hostedUrl": "https://pay.veridianhp.com/s/abc123xyz",
  "status": "pending",
  "amountCents": 14500,
  "expiresAt": "2026-05-28T16:32:00Z",
  "createdAt": "2026-05-28T15:32:00Z"
}
The hostedUrl is what you send to the patient. The session expires 30 minutes after the patient first opens the page (configurable per practice).

​
Get session status

curl https://api.veridianhp.com/api/practice/sessions/ses_01HZX9ABCDEF/status \
  -H "Authorization: Bearer $VERIDIAN_API_KEY"

​
Response — 200 OK

{
  "sessionId": "ses_01HZX9ABCDEF",
  "invoiceId": "INV-2026-001",
  "status": "succeeded",
  "amountCents": 14500,
  "createdAt": "2026-05-28T15:32:00Z",
  "settledAt": "2026-05-30T08:15:00Z"
}
You can poll /status if you must, but webhooks are the source of truth. Use status checks for human-driven reconciliation, not for primary payment state tracking.

​
List sessions

curl "https://api.veridianhp.com/api/practice/sessions?status=succeeded&limit=50" \
  -H "Authorization: Bearer $VERIDIAN_API_KEY"

​
Query parameters

ParamTypeDescription
statusstringFilter by status. Repeatable.
limitintPage size, 1-100, default 25.
cursorstringPagination cursor from previous response.

​
Response — 200 OK

{
  "data": [
    { "sessionId": "ses_...", "status": "succeeded", "amountCents": 14500, ... }
  ],
  "nextCursor": "cur_..."
}

​
Cancel a session

Cancels a pending session. Once cancelled, the hosted page shows the patient the payment is no longer required. 
curl -X POST https://api.veridianhp.com/api/practice/sessions/ses_01HZX9ABCDEF/cancel \
  -H "Authorization: Bearer $VERIDIAN_API_KEY"

​
Response — 200 OK

{
  "sessionId": "ses_01HZX9ABCDEF",
  "status": "cancelled",
  "cancelledAt": "2026-05-28T15:45:00Z"
}
You can only cancel sessions in pending or processing state. Cancelling a succeeded session is not refunding — issue a refund through your normal banking flow.

​
What’s next

Webhooks

Verifying and processing session events.

Errors

Session error codes and how to handle them.