Account Aggregator: How to Build It

from datetime import datetime, timedelta, timezone
IST = timezone(timedelta(hours=5, minutes=30))

# Everything you are allowed to do with this data is decided HERE, before the
# customer sees anything. Over-ask and they decline. Under-ask and you go back
# for a second consent, which they will also decline.

def build_consent_request(customer, use_case):
    now = datetime.now(IST)
    return {
        # WHY. Must be a permitted purpose code, and it binds you at step 7.
        "Purpose": {
            "code": use_case["purpose_code"],       # e.g. "101" wealth, "103" lending
            "text": use_case["purpose_text"],       # shown to the customer, in plain words
            "refUri": use_case["policy_url"],
        },
        # WHAT. Narrow it. "All accounts, all history" reads as a fishing trip.
        "fiTypes": use_case["fi_types"],            # ["DEPOSIT"] not everything
        "consentTypes": ["TRANSACTIONS", "PROFILE", "SUMMARY"],

        # HOW FAR BACK. Ask for what your model uses, not what it might use.
        "FIDataRange": {
            "from": (now - timedelta(days=use_case["lookback_days"])).isoformat(),
            "to":   now.isoformat(),
        },
        # HOW LONG, and HOW OFTEN. A one-off underwriting pull is ONE fetch.
        # A monitoring use case is recurring -- and needs saying out loud.
        "consentStart": now.isoformat(),
        "consentExpiry": (now + timedelta(days=use_case["consent_days"])).isoformat(),
        "fetchType": use_case["fetch_type"],        # "ONETIME" | "PERIODIC"
        "Frequency": use_case.get("frequency"),     # only if PERIODIC
        "DataLife":  {"unit": "MONTH", "value": use_case["retain_months"]},
        "DataFilter": use_case.get("filters", []),

        "customerId": customer["aa_handle"],        # name@aa, not your user id
    }

# WHAT TO CHECK
# [ ] ONETIME vs PERIODIC is a product decision, not a default. A periodic
#     consent for a one-off underwriting decision is over-collection and it is
#     the first thing a reviewer will ask about
# [ ] DataLife is how long you may KEEP it, separate from how long the consent
#     runs. Two different clocks, two different obligations
# [ ] lookback_days matches what your model actually consumes. Asking 24 months
#     to use 6 is over-collection you cannot justify
# [ ] purpose_text is written for a human, not copied from the code table. The
#     customer reads this in the AA app and decides there
# [ ] store the SIGNED ARTEFACT you received, not your request. The artefact is
#     the permission; your request was a proposal
# [ ] one consent per purpose. Bundling lending and marketing into one request
#     is how a whole ecosystem loses consent success rate

# STEP 5. The customer leaves your app, consents inside the AA's app, and comes
# back. That redirect is where most drop-off happens, and it is the part you can
# actually influence.

def start_consent_journey(consent_request, aa_client, session):
    art = aa_client.create_consent(consent_request)     # returns consentHandle
    return {
        "redirect_url": art["redirectUrl"],
        "consent_handle": art["consentHandle"],
        # Save EVERYTHING you will need when they come back. They may return on
        # a different device, an hour later, or not at all.
        "resume_token": persist_session(session, art["consentHandle"]),
        # Tell them what is about to happen. An unexplained redirect to an
        # unfamiliar brand is the single biggest cause of abandonment here.
        "explain": "You'll approve this with your Account Aggregator, then come "
                   "straight back. We never see your banking password.",
    }

# STEP 6. Poll for the artefact, then fetch, then decrypt.
def fetch_when_ready(consent_handle, aa_client, keys):
    status = aa_client.consent_status(consent_handle)
    if status["status"] == "PENDING":
        return {"state": "waiting"}                     # customer still deciding
    if status["status"] in ("REJECTED", "EXPIRED"):
        return {"state": "no_consent", "reason": status["status"]}

    artefact = aa_client.get_consent(status["consentId"])
    verify_signature(artefact)                          # NOT optional
    store_artefact(artefact)                            # the permission itself

    sess = aa_client.create_fi_request(artefact, keys["public"])
    data = aa_client.fetch_fi(sess["sessionId"])        # encrypted payload
    return {"state": "ready",
            "records": [decrypt(d, keys["private"]) for d in data["FI"]]}

# WHAT TO CHECK
# [ ] VERIFY THE ARTEFACT SIGNATURE. It is the only thing proving the customer
#     actually consented. Skipping it because "it came from the AA" removes the
#     entire security property of the framework
# [ ] the redirect explains itself BEFORE it happens, and names the AA. An
#     unexplained jump to an unknown brand is the main drop-off cause
# [ ] resume works on a different device and after a delay. Consent journeys are
#     abandoned and resumed hours later far more often than teams assume
# [ ] PENDING is normal and can last minutes. Poll with backoff; never block a
#     user-facing request on it
# [ ] private keys live in a KMS or HSM, never in application config. You are
#     holding the only thing standing between an encrypted payload and a breach
# [ ] a failed fetch is reported to the customer in plain words, with a retry.
#     "Something went wrong" after they just approved data sharing reads as a
#     betrayal of the trust they extended thirty seconds ago
# [ ] log every step with the consent handle. Disputes are reconstructed from it