Step 1 — Schedule the run
...Step 2 — Collect intents
...Step 3 — Approve & sign
...Step 4 — Post with idempotency
...Step 5 — Reconcile
After the batch, verify every posted set of ledger rows is balanced per currency. Anything non-zero is an exception, not a rounding issue.
-- Assert double-entry balance for a batch
select currency, sum(debit_minor) - sum(credit_minor) as delta
from ledger_entries
where batch_id = $1
group by currency
having sum(debit_minor) <> sum(credit_minor);Wiring it together
The full routine calls each step in sequence and short-circuits on any failure — the batch either commits end-to-end or leaves the intents untouched for the next run.
export async function runPaymentRoutine(runDate: string) {
const intents = await collectIntents();
const batch = await createBatch(intents, runDate);
await approveBatch(batch.id, await promptPin());
for (const intent of intents) {
await postTransfer(intent, runDate);
}
const exceptions = await reconcile(batch.id);
if (exceptions.length > 0) {
throw new Error(`Reconciliation failed: ${exceptions.length} imbalance(s)`);
}
return batch.id;
}Frequently asked questions
What is a payment routine flow?
A payment routine flow is a scheduled, repeatable process that collects pending payment intents, approves them with step-up authentication, posts transfers with idempotency keys, and reconciles the ledger so every run is auditable and safe to retry.
Why use idempotency keys when posting payments?
Idempotency keys let the ledger safely dedupe retried requests. A stable key derived from the intent id and run date ensures network retries, worker crashes, or double-clicks never create duplicate ledger entries.
How often should a payment routine run?
Most teams run payment routines on a fixed daily or weekly cadence anchored to a single timezone and cut-off. Higher-volume operators run intraday batches, but every run should share one clock so due-date windows are unambiguous.
What happens if reconciliation fails?
If a posted ledger set is not balanced per currency, treat the delta as an exception and pause the routine. The idempotent design means the batch can be re-posted safely once the underlying intent or FX quote is corrected.
Do I need step-up authentication for every batch?
Require PIN or 2FA for batches above your approval threshold and for any manually initiated run. Low-value automated batches can rely on the routine's signed context, as long as the signing event is captured and replayable.
Related guides
Complementary reading to go deeper on the concepts behind the payment routine flow.
Higher-level walkthrough of the five stages: Schedule, Collect, Approve, Post, Reconcile.
How Smart Pay Engine picks the best rail per intent using cost, speed, and success-rate signals.
Run the flow interactively — parsed intents, confirmation card, PIN, and ledger post.
What the sandbox environment covers and how seeded demo data behaves.
Next steps
Try the flow interactively in the Hive assistant, or read the higher-level concepts guide.