Consent Start

About the Signzy Account Aggregator (AAA) product. The Account Aggregator (AA) framework is an RBI-regulated, consent-driven system that lets a customer securely share their financial data from banks and other institutions (FIPs — Financial Information Providers) with a business that needs it (an FIU — Financial Information User), through a licensed Account Aggregator. No data moves without the customer's explicit, purpose-bound, time-bound digital consent.

Signzy's TSP solution is the FIU-side integration that hides all of this complexity behind a small set of REST APIs. It manages Sahamati onboarding, consent creation and signing, the AA webview/redirect handshake, encrypted FI data pulls from each bank, decryption, and normalization.

The intended integration is one API call plus a webhook. You call start once to open a journey, redirect the customer, and then receive every outcome — consent approved, consent dead, journey finished, data ready, data failed — as callback events on your own endpoint. The status and data APIs exist for polling and reconciliation; a callback-driven integration does not need to call them on the happy path.

Where start fits. start is the entry point of a consent journey. You call it with the customer's identifier (mobile) and one or more of your configured consent templates; it creates the consent(s) and returns a redirectUrl to which you send the customer. The typical journey is:

Send a POST request. Every request must carry your Signzy API key in the Authorization header and Content-Type: application/json.

Authorization: Content-Type: application/json

You need to pass the following information:

Once the customer leaves your app for the AA, everything that follows is asynchronous: the customer may approve, decline, walk away, or come back three weeks later and revoke. Callback events report each of those facts to your endpoint as it happens, so a single start call is the only API you need to integrate.

Events answer three independent questions, and all three can be true at once for the same journey:

A multi-consent journey can finish successfully on the journey axis while one consent dies on the consent axis and another consent's data fails on the data axis.

Two guarantees worth building on:

Two independent settings:

The callbackUrl passed to start always wins for that journey. The account default applies only when start omits it. The destination is resolved once, when the journey is created, so changing the default never redirects a journey already in flight. If neither is set, nothing is pushed at all.

Event selection works like this:

Every event except dataReady is delivered in this envelope:

Fires once per consent for automatic fetches, and once per session for fetches you request yourself. The status object and the data array are identical to what the data API returns — the full field-by-field breakdown of data[] is on the Consent Data page.

Fires when the consent was ACTIVE but the fetch produced nothing at all. Exactly once per consent. A consent that was rejected, revoked or expired reports on the consent axis instead, so one death never produces two contradictory events.

Fires once per consent, when the AA reports it ACTIVE.

This is not redundant with dataReady. For an autoFetch: false consent no data is fetched until you ask for it, so this is the only event you will receive — without it, an integration with no polling loop would wait forever for data it has to request. Even with autoFetch: true it arrives well before the data does.

Fires when a consent can no longer be used. Each reason is a different business fact with different remediation — they are not synonyms.

Fires once, when the journey reaches SUCCESS — the customer got through the AA flow.

Fires once, when the journey reaches any non-SUCCESS terminal state. There is no separate expiry event: expiry is one more terminal state, reported here with reason EXPIRED.

Two deadlines produce reason EXPIRED, and stage tells them apart:

Expiry is terminal: once expired, a late return from the AA can no longer complete the journey.

What you actually receive, end to end. Events within a journey are not guaranteed to arrive in the order listed — key on eventId, not on arrival order.

The happy path for autoFetch: true.

Five pushes total: consentApproved ×2, journeyCompleted ×1, dataReady ×2 — one data event per consent, each with its own consentHandle.

This is the scenario that strands integrations built on dataReady alone: without consentApproved, nothing ever tells you it is your turn to act.

The AA reports nothing at all about a consent the customer ignored. After a short grace window (about two minutes, to let a late approval land) the untouched consent is declared NOT_ACTED_UPON.

This is what makes the consent axis complete: every consentHandle reaches a terminal consent event, so you never interpret silence.

No data event is sent. The consent never became ACTIVE, so there was never a fetch to fail.

You get dataReady, not dataFailed.

Read failedAccounts before treating the payload as complete.

On the SESSION_* reasons, check partialDataAvailable: true means some accounts were already stored before the session died and are readable via the data API.

Both carry dataDelivered, which tells you whether the consent ever produced data before it died. For a PERIODIC consent, either event means the recurring fetch series has stopped — stop requesting fetches for that consentHandle.

A PERIODIC consent keeps serving fetches until it expires. Each fetch you request opens a new session and produces its own dataReady with a distinct sessionId. The consent stays ACTIVE throughout; you receive no further consent events until it is revoked or expires.