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:
  1. Register — backend opens a Juspay /session and persists an INITIATED mandates row. The response includes the verbatim full Juspay response as payload, 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.
  2. 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.
  3. Lifecycle — once the mandate reaches ACTIVE/CREATED, an operator starts it to schedule the Kronos autopay job (LIVE), and can pause / resume / revoke from there. Each transition is validated by a state machine and may schedule or tear down the Kronos job.
Autopay execution itself (the /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

Every route’s {mandate_id} is the internal UUID mandates.id, not the Juspay-issued mandate_id string carried in the response body. The internal id is also the value sent to Juspay as order_id.

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) and frequency come from Superposition (overridable per user via a targeting key).
  • Every amount is an AmountType — { value, currency }, where value is 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).
A mandate in OTHER (an unrecognised Juspay provider status) has no outbound transitions — any lifecycle op returns 400 ME_1211 (MandateInUnknownProviderStatus). An operator must reconcile the mandate at the provider first.

Frontend Flow

Once mandate_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 status-poll route always hits Juspay. There is no server-side short-circuit once mandate_status becomes ACTIVE/LIVE. The frontend is responsible for stopping polling at a terminal status.
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.