Auth guards are per-route. User-facing routes (register, status, active,
pause, resume, revoke) use
require_self_or_trusted_backend — the user
themselves (jwt.sub == user_id) or a trusted backend / admin. update
requires an admin actor. start requires a callback service or an admin:
autopay is started automatically once the mandate is registered and the benefit
it funds is active, so the mandate’s own holder is still refused.
GET /mandates serves both audiences: an app token has its own user_id
injected into the filter server-side and can only ever see its own rows;
everyone else is admin-gated and may filter freely.One live mandate per goal. A goal may hold at most one live mandate
at a time —
PENDING, CREATED, ACTIVE, LIVE, PAUSED, or
EXTERNALLY_PAUSED. This is enforced by an application-level check before
insert (no DB constraint), scoped to the goal’s own HSA pool since goal↔HSA is
1:1 — so a user with several goals holds one live mandate per goal.
INITIATED rows (a registration started but never completed on the payment
page) and terminal FAILED / CANCELLED / COMPLETED rows do not count
and can stack freely. Registering again while the goal already has a live
mandate returns that mandate as-is (200), not a conflict.Overview
The mandate module lets an authenticated user set up a recurring debit (autopay) on a card or bank account via Juspay’s payment page, then drives that mandate through its lifecycle. The flow:- Register — backend opens a Juspay
/sessionand persists anINITIATEDmandatesrow. The response includes the verbatim full Juspay response aspayload, which the frontend hands to Juspay’s SDK (native) or uses for a redirect (payment_links.web). Amounts are server-derived (config + Superposition) — the request body is empty. - Poll status — after the user finishes the payment flow, the frontend
polls. Status routes hit Juspay’s
/orders/{id}and sync the row with the latest state. - Lifecycle — once the mandate reaches
ACTIVE/CREATED, an operatorstarts it to schedule the Kronos autopay job (LIVE), and canpause/resume/revokefrom there. Each transition is validated by a state machine and may schedule or tear down the Kronos job.
/txns debit + reconciliation) lives in the
Mandate Execution Module.
Endpoints
POST /mandates/{mandate_id}/sync
Re-poll Juspay and write the refreshed row back. The mandate UUID resolves the row.
GET /mandates
Paginated, currency-aware mandate list. App tokens are scoped to self; admins may filter by
user_id, mandate_id (the internal id, not the Juspay reference in the response’s mandate_id), statuses, frequency and a created_at window.POST /mandates/{mandate_id}
Admin: set
mandate_status directly (validated against the state machine).POST /mandates/{mandate_id}/start
Admin: activate autopay —
→ LIVE, schedules the Kronos job, stamps job_id.POST /mandates/{mandate_id}/pause
Pause a live mandate — cancels the Kronos job,
→ PAUSED.POST /mandates/{mandate_id}/resume
Resume a paused mandate — schedules a fresh Kronos job,
→ LIVE.POST /mandates/{mandate_id}/revoke
Revoke at Juspay then re-sync —
→ CANCELLED, tears down the Kronos job.Every mandate route is keyed on the mandate UUID alone — no
{user_id} in the path.
Ownership is asserted server-side against the mandate row, so a caller cannot reach
another user’s mandate by guessing an id. Mandate registration and
active-mandate discovery are the exception: they are goal-scoped, see POST /goals/{goal_id}/mandate/register and
GET /goals/{goal_id}/mandate/active in the Goal Module. A mandate
binds to the goal’s own HSA pool, so a user with several goals holds one live
mandate per goal.Identifiers
Amount Convention
- Amounts are server-derived, not supplied in the request body. The initial
order amount comes from config (
mandate.order_amount, in paise) and the per-debit ceiling (mandate_max_amount) andfrequencycome from Superposition (overridable per user via a targeting key). - Every amount is an
AmountType—{ value, currency }, wherevalueis an exact integer in minor units (paise).{ "value": 9999 }is ₹99.99. - Juspay’s wire format is a decimal rupee string — the backend converts at the Juspay client boundary.
Mandate Status
mandate_status is the coarse internal lifecycle (common_enums::MandateStatus,
wire values SCREAMING_SNAKE_CASE), derived from the raw Juspay status. The full set:
Alongside
mandate_status, the row carries external_mandate_status — the raw
Juspay vocabulary (ACTIVE, PAUSED, REVOKED, EXPIRED, …) stored verbatim
so new Juspay statuses don’t require schema changes.
State machine
update / start / pause / resume / revoke all flow through one
transition validator. Allowed transitions:
Side effects:
ACTIVE/CREATED → LIVE (and PAUSED → LIVE on resume)
schedules the Kronos autopay job and stamps job_id; LIVE → PAUSED/CANCELLED
cancels the job and clears job_id. An invalid transition returns
400 ME_1210 (InvalidMandateStatusTransition).
Frontend Flow
Oncemandate_status reaches CREATED, start activates autopay. It is normally
called for you: the Auto Mandate Starter fires it as soon as both preconditions hold —
the mandate is CREATED, and the benefit entity its goal funds is ACTIVE. Whichever
of the two happens second triggers the call. An operator can also call it directly.
start refuses a → LIVE transition while that benefit entity is not ACTIVE
(400, BenefitEntityNotActive). The guard applies to resume and update too, since
all three target LIVE.
Request validation
Also: the user must have a non-null
email (the Juspay session needs it; else
400 ME_1205).
Error responses
These
ME_* numbers are internal identifiers, not the code on the wire.
Routes return AarokyaAppError, so the response code is the generic AE_*
class code and the ME_* number reaches you only inside the message. Match on
status and message, never on code.Gotchas
The
payload field on the register response is a verbatim pass-through of
Juspay’s /session body. Backend does not interpret its shape, so frontend
can freely consume sdk_payload, payment_links.web, or any new fields
Juspay adds later without a backend change.