Auth: orders are keyed by their own id, with no
{user_id} path label —
ownership is resolved from the row. GET /orders/{id} and
POST /orders/{id}/sync admit the owning app user, or an admin. Sync also admits
a DIRECT contributor token, for its own platform’s payment-rail tips to its
beneficiary only — any other order answers 403. GET /orders
injects an app token’s own user_id into the filter (so a user only ever sees
their own orders) and requires a trusted-backend identity — admin,
readonly-admin, benefit-provider or platform — for the unfiltered cross-user
list.Orders are created by the goal rail — POST /goals/{goal_id}/contribution/self/manual,
.../self/auto and .../contribution/sponsor — not by this module.Overview
An order is a single funding event crediting a user’s PBA-backed (HSA) account. Theorders table is universal across funding flavours;
a source URN column on every row identifies the funding leg.
Both the self contribution and sponsor legs are exposed through the public API —
the self legs via POST /goals/{goal_id}/contribution/self/{manual,auto} and the sponsor
match via POST /goals/{goal_id}/contribution/sponsor.
They share this table shape; they differ in how the money moves (a two-phase deposit from
the user’s bank vs. a one-shot PBA-to-PBA transfer from the sponsor’s account) and therefore
in how they settle.
Funding source (source)
Every order carries a source field on the response, URN-encoded:
The payload always names a party, never a kind — direct vs indirect tipping is the
settlement rail and lives on
medium.
The payload decides which bank the PBA deposit quotes as its origin, and PBA books a
remittance to the goal’s self or others pool by whether that bank matches the pool’s
own origin. So a self contribution quotes the user’s SAVINGS and lands in self; a tip
quotes its platform’s and lands in others.
Validation runs at every entry point — JSON deserialization and DB row reads. A malformed
URN is a 400 with the parse error.
Order lifecycle (self contribution)
- Create —
POST /goals/{goal_id}/contribution/self/manualtakes{ amount, currency }(amountin minor units — an exact integer, so there is no major→minor float conversion at the boundary), opens a Juspay session, and inserts anordersrow against the goal’s own HSA pool withsource = "self_contribution",medium = PAYMENT, internalstatus = INITIATED, and a nullexternal_status. The Juspay/sessionresponse is returned verbatim aspayload(the frontend usespayload.sdk_payloadto render the payment page). - Sync —
POST /orders/{id}/synccalls Juspay/orders/{id}, merges the latestexternal_status(CHARGED/PENDING_VBV/FAILED/ verbatimOther(...)for unknown values) and payment-method fields into the row, and returns the refreshed snapshot. Both the frontend and the Kronos settlement-poll ring it; there is no server-side short-circuit. UseGET /orders/{id}for a read-only snapshot that makes no provider call. - Settle on CHARGED — status only. The first poll observing
CHARGEDadvances the internalstatustoSUCCESS. It does not credit the pool:wallet_txn_datais left as-is, because confirming the deposit has to be atomic with moving the goal’s counters, and that is step 4’s job. The one exception is failure — aFAILED(or reversed) order has its parked hold released here, since step 4 only ever runs on a settled order and nothing else would free it. - Credit —
POST /goals/{goal_id}/contributeconfirms the PBA deposit, flipswallet_txn_data.statustoSUCCESS, and credits the goal, gated once-only so a re-delivery is a no-op. PBA’sidempotency_key = order.idguards against double-deposits even if that gate is bypassed. - Match — for a self contribution,
POST /goals/{goal_id}/contribution/sponsormints the sponsor order and transfers the sponsor’s share in; step 4 is then rung again with that order to credit the sponsor leg.
SUCCESS by the transfer
that creates them. POST /orders/{id}/sync on one is a no-op: it returns the row
unchanged rather than erroring, so a caller polling every order it knows about does not have
to special-case the rail.
GET /orders is a paginated list of funding orders, backing both a user’s own history
and the dashboard Orders tab. It returns lean rows straight off the orders table (no
Juspay poll) and filters by user_id, order_id (exact match), initial_order_id (every
attempt of one retry chain), is_retry, sources, mediums, statuses (comma-separated
OrderStatus), and a created_at time range.
is_retry is three-way: omit it for every attempt, false keeps first attempts only
(retry_count = 0), true keeps retries only. A first-attempt view shows that attempt’s own
status, not the chain’s outcome — a chain that failed and then succeeded on retry still
lists its first attempt as FAILED.
sources and mediums are two independent axes — whose money, and which rail moved it.
Both are comma-separated and OR-ed internally; the two are AND-ed with each other.
So
sources=tip is every tip, and sources=tip&mediums=MANDATE is only those recovered
through the driver’s mandate. Some pairings are simply empty rather than invalid — sponsor
legs settle over PBA exclusively, so sources=sponsor&mediums=PAYMENT returns nothing.
Response shape
Every order route returns the same
OrderResponse. The only field that varies is
payload (the verbatim Juspay SDK blob): the create
(POST /goals/{goal_id}/contribution/self/manual) populates it so the frontend can
render the payment page; reads, syncs and list rows leave it null rather than echo a
large provider blob per item.