Account Information - Hellgate Cloud Platform

AIS is available on request. Ask your account representative to activate it for your tenant — see 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 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

Start the check

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).

Return to your checkout

The shopper is redirected back to your success or failure page. The browser never receives the account data.

You receive the record

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.

Ask your account representative to activate AIS on your existing platform tenant.
Obtain AIS-scoped service credentials through the platform’s credential issuance. These are the bearer token the session API authenticates.
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.
Register a notification endpoint — a public HTTPS URL that receives the outcome. You register it once and store the signing secret (see Notifications).
Embed the Web SDK (@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.

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.

POST /api/services/account-information
Authorization: Bearer <access token>
Content-Type: application/json

{
  "market": "DE",
  "redirect_urls": {
    "success": "https://shop.example/verify/success",
    "failure": "https://shop.example/verify/failure"
  }
}

{ "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 for the full request and response.

2. Initialize the Web SDK

Initialize the Web SDK with the session ID and nothing else. The SDK redirects the shopper to their bank automatically — there is no separate start or process call.

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:

{
  "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:

{
  "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:

GET /api/services/account-information/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d
Authorization: Bearer <access token>

An account check returns exactly one financial institution and one account:

{
  "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 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

API Reference

Create sessions, read records, and register webhooks.

Authentication

Obtain the AIS-scoped access token the session API requires.

Web SDK

Embed the SDK and initialize it with the session ID.

Composable Payment Architecture

How AIS composes with other Hellgate services.

​What is an account check?

​From the shopper’s perspective

​Get access

​How it works

​1. Create a session

​2. Initialize the Web SDK

​3. Handle the return

​Notifications

​The record

​Outcomes

​Data handling

​Testing

​Next steps

API Reference

Authentication

Web SDK

Composable Payment Architecture

What is an account check?

From the shopper’s perspective

Get access

How it works

1. Create a session

2. Initialize the Web SDK

3. Handle the return

Notifications

The record

Outcomes

Data handling

Testing

Next steps