Question 1

How does capture-then-release differ from "I get paid right away"?

Accepted Answer

Capture-then-release matches the operational reality of healthcare: a consult takes time, a session takes time, and the actual cost is known at the end rather than the start. Pay-right-away forces you to decide the price before the work has happened and forces the patient to trust that decision. Hold-and-capture is the same primitive a card network uses for a fuel pump or a hotel deposit — the patient authorises a maximum, you capture the actual, and the difference releases. It is also the only correct primitive when a service can be cancelled mid-flight.

Question 2

How do I know a hold is real?

Accepted Answer

Two ways. The patient's balance card shows the held subline ({N} on hold) the moment the hold is placed; the credits have visibly moved from balance to held_total. The transactions API returns the hold row with type=hold, reference set to your originating reference, and balance_after / held_after snapshotted on the row. The partial index on WHERE status = 'active' is fast even when most holds are terminal, so listing your active holds is a cheap query.

Question 3

What if the patient cancels?

Accepted Answer

If the cancel happens before capture, you call ReleaseHold and the credits return to the patient's balance immediately. The release row carries reference release:{originalRef} and related_tx_id pointing at the original hold. If the cancel happens after capture — for example because the consult was completed but the patient disputes the quality — you issue a refund. The refund row carries reference refund:{originalTxID}, related_tx_id pointing at the debit, and the credits return to the patient's balance.

Question 4

When do payouts arrive?

Accepted Answer

After the Provider Payouts service ships. That service is on the 2026 roadmap and will roll up your captured-debit transactions into a daily statement, settle to your bank account on a configurable cadence, and reconcile any refunds against the same period. Today the data is in the ledger as transaction rows your service token can read; the rolled-up settlement layer is what 2026 unlocks. Until then, your captures and refunds are queryable through GET /v1/accounts/:id/transactions.

Question 5

Can I refund a capture?

Accepted Answer

Yes. Only debits can be refunded; a captured hold writes a debit row, so a captured hold can be refunded. Call POST /v1/transactions/:id/refund against the debit's transaction ID. The refund row writes with reference refund:{originalTxID}, related_tx_id set to the original debit, and the credits return to the patient's balance. The refund is itself idempotent on its own reference, so a duplicate refund attempt resolves to the existing refund rather than a second credit.

Question 6

What if I capture twice by accident?

Accepted Answer

The second capture is a no-op. The reference grammar — capture:{originalRef} — is deterministic, so a retry produces the same reference, the unique index on (account_id, reference) deduplicates the insert, and the repository re-reads the existing row. The 409-is-success invariant applies when your service is the sole writer of the hold reference: a 409 response is a confirmation that your prior call succeeded and the response was lost, not an error to surface to the patient.

Question 7

How is fraud handled?

Accepted Answer

Card-side fraud sits with Paystack; Paystack runs the rail-level controls and handles disputes. Ledger-side fraud is constrained by the ledger architecture: every transaction is immutable, every account is balance-non-negative by CHECK, every write runs at SERIALIZABLE isolation, and the audit trail is append-only. Multiple captures on a single hold are deduplicated by reference; multiple refunds on a single debit are deduplicated by reference. Service-token scope is the access-control boundary; admin actions go through the FastLogin admin surface, not through a backdoor. The FastLogin admin actor proxy stamps every administrative override with a correlation_id on the audit row, so any override path is provably attributed to a named admin identity rather than buried in service-token noise.

Question 8

Can I see the history of a single transaction?

Accepted Answer

Yes. GET /v1/transactions/:id returns the row, including type, amount, reference, related_tx_id, balance_after, held_after, source_service, and the timestamps. The related_tx_id chains a refund back to its original debit and chains a captured debit back to the originating hold (via the hold's captured_tx_id). The chain lets you reconstruct any single consult's full transaction history from any one of its rows.

Question 9

Are there hold limits I should know about?

Accepted Answer

Two. The default hold lifetime is ten minutes — DefaultHoldTTL — used when the caller does not specify one. The maximum hold lifetime is twenty-four hours, or eighty-six thousand four hundred seconds, enforced by the handler before the database is touched. Pre-OH-09 the FastCredits service silently ignored the duration_seconds parameter and always used the ten-minute default; that bug is fixed and the duration is now honoured up to the cap. If your service routinely runs operations longer than ten minutes you must pass duration_seconds explicitly; if you rely on the default, your hold may expire mid-operation and the expirer worker will release the credits back to the patient before you get a chance to capture.

Question 10

What does the source_service column do for me?

Accepted Answer

Every transaction carries a source_service that names the originating product (doorcta, onehealth, future product slugs). The dashboard transaction feed surfaces a via {source_service} subline next to each row. For your service-token integration, source_service is also a query filter — GET /v1/accounts/:id/transactions?source_service=doorcta returns only the transactions your service drove. The same column is the basis on which the 2026 Provider Payouts service will roll up settlements.

Patient	Consult	Held	Reference	Status
usr_42a8…	GP follow-up · 25 min	250 CREDITS	consult_42a8…	Awaiting capture
usr_eef0…	Initial assessment · 40 min	1,800 CREDITS	consult_eef0…	Awaiting capture
usr_7c11…	Repeat prescription · 10 min	120 CREDITS	consult_7c11…	Awaiting capture

Date	Gross	Fees	Net to bank	Status
Apr 25	₦7,100	−₦107	₦6,993	Paid
Apr 24	₦6,300	−₦95	₦6,205	Paid
Apr 23	₦4,900	−₦74	₦4,826	Paid
Apr 22	₦5,100	−₦77	₦5,023	In transit
Apr 21	₦4,250	−₦64	₦4,186	Pending

Hold, capture, refund. Every consult.

1 · Booking → hold

2 · Consult ends → capture

3 · Patient cancels → refund

4 · Earnings summary — coming 2026

5 · Daily payout statement — coming 2026

6 · Capture-rate analytics — coming 2026

Predictable hold/capture lifecycle

Idempotent capture and refund

Refund grammar built into the ledger

Ledger-quality audit trail

No chargeback exposure

Capabilities

Integrations

Compliance & safety

Plain answers