Account Gator WEB SDK¶

The Account Gator WEB SDK enables secure consent collection for accessing user's account transactions via account aggregator framework or bank statements.

Requirements¶

The Web SDK works on Google Chrome, Safari, Firefox, Opera and other popular modern browsers.

Variables¶

The following variables will be referenced throughout this documentation:

Variable	Description	Format	Source
`client_id`	Unique identifier for your organisation	Alphanumeric string	Provided by Credeau during onboarding
`auth_token`	Secret token for API authentication	Alphanumeric string	Provided by Credeau during onboarding
`user_id`	Unique identifier for an end user	Alphanumeric string	Provided by Credeau during onboarding
`redirect_url`	URL to redirect to post process	Like, https://yourdomain.com/redirection/path	Set by client as per requirement
`template_name`	Account Aggregator template name	Either `BANK_STATEMENT_PERIODIC` or `BANK_STATEMENT_ONETIME`	Set by client as per requirement
`consent_templates`	Account Aggregator template names	Array of template names, multiple can be passed	Set by client as per requirement
`customer_mobile_number`	End user's mobile number	Like, 9999999999	Provided by customer during journey

⚠️ Note

Keep these credentials secure and never share them publicly. These credentials are unique to your organization and will be used to authenticate all API requests.

template_name and consent_templates are mutually exclusive. Provide consent_templates for a multi-template flow; provide template_name for a single-template flow. Exactly one of the two must be present.

Adding Dependency¶

Add the SDK to your application using one of the following methods.

1. Install & Configure the AWS CLI¶

Installation Steps

aws configure --profile credeau

The above takes the following as input -

AWS Access Key ID [None]: <provided by credeau>
AWS Secret Access Key [None]: <provided by credeau>
Default region name [None]: ap-south-1
Default output format [None]: json

aws codeartifact login \
    --tool npm \
    --domain "credeau" \
    --domain-owner "068267901648" \
    --repository "account-gator-web" \
    --region ap-south-1 \
    --profile credeau

This command:

fetches auth token
updates ~/.npmrc
enables npm install

⚠️ Note

The authentication token generated by this command expires in 12 Hrs.

3. Install the SDK¶

latest:

npm install @credeau/accountgator

or, Specific version

npm install @credeau/accountgator@1.1.0

Usage¶

ESM / bundler¶

import { openAccountGator } from "@credeau/accountgator";

const result = await openAccountGator({
    client_id: "<client_id>",
    user_id: "<user_id>",
    auth_token: "<auth_token>",
    redirect_url: "<redirect_url>",
    is_redirecting: true / false, // Optional; default=true if not passed
    template_name: "<template_name>", // Pass this if consent_templates is not added
    consent_templates: ["<template_name_1>", "<template_name_2>"], // Pass this if template_name is not added
    mobile_number: "<customer_mobile_number>",
});

console.log(result);

// Values can be access by `result.<field>`, for example:
// result.success
// result.aa_session_id
// result.error
// result.timeout
// result.consent_handles_status  (only present when consent_templates is used)

Script Tag¶

<button id="link">Link bank account</button>

<script src="./dist/accountgator.js"></script>
<script>
    const params = {
        client_id: "<client_id>",
        user_id: "<user_id>",
        auth_token: "<auth_token>",
        redirect_url: "<redirect_url>",
        is_redirecting: true / false, // Optional; default=true if not passed
        template_name: "<template_name>", // Pass this if consent_templates is not added
        consent_templates: ["<template_name_1>", "<template_name_2>"], // Pass this if template_name is not added
        mobile_number: "<customer_mobile_number>",
    };

    document.getElementById("link").onclick = async () => {
        try {
            const result = await accountGatorSDK.openAccountGator(params);
            // Use `result` to drive your app flow (redirect, show success UI, etc.)
            console.log("AccountGator result:", result);
            // Values can be access by `result.<field>`, for example:
            // result.success
            // result.aa_session_id
            // result.error
            // result.timeout
            // result.consent_handles_status  (only present when consent_templates is used)
        } catch (e) {
            console.error("AccountGator error:", e);
        }
    };
</script>

Output¶

The SDK returns the following keys as output -

success (str) - Boolean as string indicating if the consent was successfully provided or not.
aa_session_id (str) - Session ID for the Account Aggregator transaction, further used to fetch insights & reports.
error (str) - Error message indicating if any error occured during the consent session.
timeout (str) - Boolean as string indicating if the process timed out or not.
consent_handles_status (json object) - Only present when consent_templates is used. An object keyed by template name, indicating which templates the user gave consent for.

`consent_handles_status` Structure¶

Each entry in consent_handles_status is keyed by the template name and contains:

Field	Description
`consent_handle`	Unique handle for the consent request
`consent_status`	Status of the consent (see values below)
`consent_id`	Present when consent is accepted; otherwise `null`

`consent_status` values¶

Value	Meaning
`"ACCEPTED"`	User gave consent for that template; `consent_id` will be present
`"REJECTED"`	A failure occurred for that template (e.g. an error during the consent flow)
`"REQUESTED"`	User did not give consent for that template; `consent_id` is `null`

Response Examples (when using `consent_templates`)¶

Single template:

Passing one template to consent_templates:

consent_templates: ["BANK_STATEMENT_ONETIME"];

Response:

{
    "success": "true",
    "aa_session_id": "3617c94822b94d998f9bdcaefcb01e51",
    "error": "null",
    "timeout": "false",
    "consent_handles_status": {
        "BANK_STATEMENT_ONETIME": {
            "consent_handle": "e0312e30-66f0-4793-8b3a-a64f109b036e",
            "consent_status": "ACCEPTED",
            "consent_id": "9f59c234-9050-89db-b944-bbfb549c9514"
        }
    }
}

Multiple templates:

Passing multiple templates to consent_templates:

consent_templates: ["BANK_STATEMENT_PERIODIC", "BANK_STATEMENT_ONETIME"];

Response:

{
    "success": "true",
    "aa_session_id": "783a8122359e4ea5a3b7eba7f8ba8d55",
    "error": "null",
    "timeout": "false",
    "consent_handles_status": {
        "BANK_STATEMENT_PERIODIC": {
            "consent_handle": "dbc880e3-799e-44d8-a305-9bad846ed1be",
            "consent_status": "REQUESTED",
            "consent_id": null
        },
        "BANK_STATEMENT_ONETIME": {
            "consent_handle": "ec2b3993-890a-4b51-932d-f806351f2b57",
            "consent_status": "ACCEPTED",
            "consent_id": "3124912f-6624-2349-8379-246745fadf7b"
        }
    }
}

Note: In the example above, BANK_STATEMENT_PERIODIC has "consent_status": "REQUESTED" — this means the user did not give consent for that template. Only BANK_STATEMENT_ONETIME was accepted.

When is_redirecting is set to true, the SDK will redirect to the passed URL in redirect_url with SDK output keys appended as query parameters.

💡 Example:

If, redirect_url is set to 'https://yourdomain.com/user/journey' and is_redirecting to true, then the SDK will redirect the browser window to the following URL -

'https://yourdomain.com/user/journey?success=true&aa_session_id=f310805cedd0485ba18b6f10bb8b1843&error=null&timeout=false'

When consent_templates is used, consent_handles_status is also appended as a URL-encoded JSON string:

'https://yourdomain.com/user/journey?success=true&aa_session_id=b167e674e1734e1e8db2d7893bcc827c&error=null&timeout=false&consent_handles_status=%7B%22BANK_STATEMENT_PERIODIC%22%3A%7B%22consent_handle%22%3A%22aadf72dc-76de-4012-8f7a-a3e10a6354be%22%2C%22consent_status%22%3A%22REQUESTED%22%2C%22consent_id%22%3Anull%7D%2C%22BANK_STATEMENT_ONETIME%22%3A%7B%22consent_handle%22%3A%22ae73dce9-5168-4b9d-bcc1-c53368cbb739%22%2C%22consent_status%22%3A%22ACCEPTED%22%2C%22consent_id%22%3A%2242d71264-2944-46d6-b724-c9c8cbd4d046%22%7D%7D'

And, the values can be used within the page from here.

Using the values from query parameters -

const params = new URLSearchParams(window.location.search);

const success = params.get("success"); // "true" | "false" | null
const aa_session_id = params.get("aa_session_id"); // string | null
const error = params.get("error"); // string | null
const timeout = params.get("timeout"); // "true" | "false" | null

// Only present when consent_templates is used:
const consent_handles_status_raw = params.get("consent_handles_status"); // JSON string | null
const consent_handles_status = consent_handles_status_raw ? JSON.parse(consent_handles_status_raw) : null;
// => { [templateName]: { consent_handle, consent_status, consent_id } }