> ## Documentation Index > Fetch the complete documentation index at: https://developer.hellgate.io/llms.txt > Use this file to discover all available pages before exploring further. # Account Information > Verify a shopper's bank account — ownership, holder name, and IBAN — directly from your checkout, using the Hellgate Web SDK. AIS is available on request. Ask your account representative to activate it for your tenant — see [Get access](#get-access). The **Account Information Service (AIS)** lets you verify a shopper's bank account — ownership, holder name, and account identifiers such as IBAN — directly from your checkout. The shopper logs into their bank once; you receive a verified record on your backend. There is no bank integration, PSD2 licence, or third-party contract on your side: Hellgate holds the regulated provider relationship, and your only integration surface is the Hellgate Cloud Platform. AIS is a [Composable Payment Architecture](/platform/cpa) service: use it on its own today, and compose it with fraud and decisioning later without re-integrating. ## What is an account check? An **account check** confirms that a shopper owns a given bank account by fetching data directly from their bank in real time. The shopper authenticates with their bank inside the flow and consents; in return you receive a verified record containing the account holder's name, the account identifiers (IBAN and related details), and — in some markets — identity data. The whole process typically takes under a minute and produces a point-in-time snapshot, not an ongoing data feed. Account checks are built on PSD2 account-information rails. Common uses are setting up direct debit without micro-deposit verification and confirming a payout account before disbursing funds. ### From the shopper's perspective On your checkout, the shopper begins account verification. The Web SDK redirects them to their bank. The shopper selects their bank, logs in, and consents to share their account details. They complete Strong Customer Authentication (SCA) — in Germany this is typically app-to-app via their banking app (for example pushTAN or photoTAN). The shopper is redirected back to your `success` or `failure` page. The browser never receives the account data. Your backend receives a notification with the outcome and can retrieve the verified record. ## Get access AIS is activated per tenant on request — there is no separate account to create. 1. **Ask your account representative to activate AIS** on your existing platform tenant. 2. **Obtain AIS-scoped service credentials** through the platform's [credential issuance](/platform/authentication). These are the bearer token the session API authenticates. 3. **Prepare two redirect URLs** — `success` and `failure` — where the shopper lands after the bank step. They must be HTTPS and are validated against your allowed origins. 4. **Register a notification endpoint** — a public HTTPS URL that receives the outcome. You register it once and store the signing secret (see [Notifications](#notifications)). 5. **Embed the [Web SDK](/platform/resources/sdks/web-sdk/overview)** (`@starfish-codes/hellgate`) in your shopper-facing page. You do **not** need a third-party provider account, your own PSD2 licence, or any certificates — all of that sits on Hellgate's side. ## How it works Three actors share the flow: your **frontend** embeds the Web SDK, your **backend** creates the session and receives the record, and **Hellgate** drives the bank interaction behind the scenes. ```mermaid theme={null} sequenceDiagram participant FE as Your frontend participant BE as Your backend participant HG as Hellgate (AIS) participant BANK as Bank participant SH as Shopper BE->>HG: POST /api/services/account-information HG-->>BE: 201 { id } BE-->>FE: session id FE->>HG: Hellgate.init(id, { base_url }) HG-->>FE: redirect shopper to bank SH->>BANK: log in + SCA (app-to-app) BANK->>HG: return with verification result HG-->>BE: notification (success | error) HG->>FE: redirect shopper to success / failure URL Note over BE,HG: Backend reads the record: GET /api/services/account-information/{id} ``` ### 1. Create a session Your backend creates a session by calling the API with your AIS-scoped bearer token. The service is selected by the **request path** — there is no `type` field. ```http theme={null} POST /api/services/account-information Authorization: Bearer Content-Type: application/json { "market": "DE", "redirect_urls": { "success": "https://shop.example/verify/success", "failure": "https://shop.example/verify/failure" } } ``` ```json theme={null} { "id": "3f7c1e9a-2b4d-4c6e-8a1f-9d0b2c3e4f56" } ``` The response `id` is a short-lived, shareable secret that also pins the market and the redirect destinations. Hand it to your frontend. `account_identifier` is **optional**: if you already know the shopper's account (for example their IBAN), pass it to pre-bind the bank so the shopper can skip ahead. Omit it and the shopper picks their bank in the normal flow. See [Create session](/platform/api-reference/account-information/create-session) for the full request and response. ### 2. Initialize the Web SDK Initialize the [Web SDK](/platform/resources/sdks/web-sdk/overview) with the session ID and nothing else. The SDK redirects the shopper to their bank automatically — there is no separate start or process call. ```ts theme={null} import { Hellgate } from '@starfish-codes/hellgate' // sessionId came from your backend const client = await Hellgate.init(sessionId, { base_url: 'https://api.eu1.hellgate.cloud', }) // → the SDK automatically redirects the shopper to their bank ``` That is the whole frontend contract. After the bank step, the shopper lands on your `success` or `failure` URL — the page load is your frontend signal. The verified record arrives on your **backend**, never in the browser. Bank login is the bank's own SCA, not a form Hellgate controls. In many markets it is app-to-app (for example German pushTAN or Nordic BankID): the shopper leaves the browser for their banking app, which cannot happen inside an iframe. The SDK therefore performs a full-window redirect. ### 3. Handle the return After the shopper completes (or abandons) the bank step, Hellgate redirects the browser to the `success` or `failure` URL you supplied when creating the session. Both are validated against your allowed origins, so AIS cannot be used as an open redirect. The redirect is a frontend signal only. The authoritative outcome and the record come through the notification and the read API on your backend. ## Notifications Hellgate delivers **events** to your registered webhook endpoint. Webhook delivery is a platform-wide mechanism with a shared event envelope — `id`, `created_at`, `type`, `reason`, and a `related_object` you can fetch for the detail; the events on this page are the Account Information Service's `ais.*` events. When a session reaches a terminal state, the matching `ais.*` event is pushed to your endpoint. This is the primary signal; the read API is the backstop. Branch on `type`, then fetch the referenced resource through `related_object` when you need the detail. On success, the event references the account information record: ```json theme={null} { "id": "f1e2d3c4-b5a6-4978-8a1b-2c3d4e5f6a7b", "created_at": "2026-06-22T09:59:56Z", "type": "ais.completed", "reason": "The account check completed successfully.", "related_object": { "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d", "url": "https://api.eu1.hellgate.cloud/api/services/account-information/a1b2c3d4-…" } } ``` On a failure, `type` carries the outcome and `related_object` references the session: ```json theme={null} { "id": "c4d5e6f7-a8b9-4c0d-9e1f-2a3b4c5d6e7f", "created_at": "2026-06-22T09:59:56Z", "type": "ais.user_cancelled", "reason": "The shopper cancelled the bank login.", "related_object": { "id": "3f7c1e9a-2b4d-4c6e-8a1f-9d0b2c3e4f56", "url": "https://api.eu1.hellgate.cloud/api/services/account-information/3f7c1e9a-…" } } ``` Every delivery is signed with `x-hmac-signature` (HMAC-SHA256 over the raw body, keyed by your `signing_secret`). **Verify the signature before trusting the payload.** Deliveries are retried with backoff and dead-lettered on exhaustion; dead-lettered events hold references only, never the record. ## The record On `ais.completed`, read the verified record from your backend using the `related_object.id`: ```http theme={null} GET /api/services/account-information/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d Authorization: Bearer ``` An account check returns exactly one financial institution and one account: ```json theme={null} { "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d", "created_at": "2026-06-22T09:59:56Z", "data": [ { "financial_institution": "Demo Bank", "user_identity": { "full_name": "John Doe" }, "accounts": [ { "id": "ee7ddbd1…", "name": "Personal account", "account_number": "DE69…", "account_type": "checking", "currency_code": "EUR", "identifiers": { "iban": { "iban": "DE69…", "bban": "…", "bic": "…" } }, "parties": [ { "identity": { "name": "John Doe" }, "role": "holder" } ] } ] } ] } ``` Some fields are market-dependent: parts of `user_identity` (date of birth, social security number) and the identifier shape (IBAN for SEPA markets) vary by country. See [Get account information](/platform/api-reference/account-information/get-account-information) for the full schema. ## Outcomes Every session resolves to one of four event types. | Event type | What it means | What to do | | -------------------------- | ------------------------------------------------------- | --------------------------------- | | `ais.completed` | The account was verified. | Read the record. | | `ais.user_cancelled` | The shopper abandoned or declined consent. | Offer a retry — not a hard error. | | `ais.authentication_error` | Bank authentication or SCA failed. | Offer a retry. | | `ais.technical_error` | A provider, bank, timeout, expiry, or internal failure. | Offer a retry or fall back. | The bank token and report windows are short (roughly 30–60 minutes), so an account check is a "complete in one sitting" flow. A stale return resolves to `technical_error`; start a fresh session. ## Data handling * The record is personal data (not card data) and **never reaches the browser** — the data path is backend-only. * The record is available for your tenant's configured **retention window — 15 days by default** — via the notification and the read API, then redacted to attempt metadata. AIS is not a long-term store of record. * If you need the data beyond the retention window, **pull the record and persist it on your side.** * Under the data processing agreement, you are the controller and Hellgate the processor. ## Testing On the **Test** tier, the bank step is simulated by a **Demo Bank** — no real credentials. The full happy path is: create a session, let the SDK redirect to Demo Bank (Open Banking → password → 4-digit OTP), pick a test account, return to your `success` URL, and receive the record at your endpoint. Test users map to scenarios such as the happy path, cancellation, and error. ## Next steps Create sessions, read records, and register webhooks. Obtain the AIS-scoped access token the session API requires. Embed the SDK and initialize it with the session ID. How AIS composes with other Hellgate services.