Collecting PSD2 Banking Data

This guide explains how to collect PSD2 Account Information Service (AIS) data — checking accounts, savings accounts, credit cards, balances, and transactions — using the Insurely API.

You will learn:

1. How users, sessions, consents, and collections work together for PSD2 data collection
2. Two collection modes: one-time and consent-based (reusable)
3. Step-by-step API call sequences with request/response examples

Overview

PSD2 data collection involves four core concepts: Users, Sessions, Consents, and Collections.

• User — Created once per individual. Maps your externalId to a userUuid in Insurely.
• Session — Created per interaction window. Provides a JWT that scopes operations to a user.
• Consent (consent-based only) — Created once per bank. Stores PSD2 authorization, reusable for multiple collections until expired or revoked. User authenticates with BankID once during consent creation.
• Collection — A single data fetch returning accounts, balances, and transactions. In the one-time flow, the user authenticates with BankID during the collection itself.

Authentication model

User management

The User API lets you create and manage users that map to individuals in your system. Each user is identified by an externalId (your own identifier) and receives a userUuid within Insurely.

curl -X POST https://api.insurely.com/users \
  -H "authorization-token: <API_KEY>" \
  -H "Insurely-Version: 2026-04-01" \
  -H "Content-Type: application/json" \
  -d '{ "externalId": "your-internal-user-id" }'

{
  "userUuid": "abc-123",
  "externalId": "your-internal-user-id",
  "anonymized": false,
  "createdAt": "2026-03-05T10:00:00Z",
  "updatedAt": "2026-03-05T10:00:00Z"
}

curl -X POST https://api.insurely.com/users/abc-123/sessions \
  -H "authorization-token: <API_KEY>" \
  -H "Insurely-Version: 2026-04-01"

{
  "token": "eyJhbG...",
  "userUuid": "abc-123",
  "expiresAt": "2026-03-05T12:00:00Z"
}

You can look up an existing user by their externalId using GET /users?externalId=..., or retrieve a user directly by userUuid using GET /users/{userUuid}. To delete a user, call DELETE /users/{userUuid} — this anonymizes the user by setting externalId to null.

Consent lifecycle

A consent represents explicit PSD2 user authorization. It is created via POST /consents and its status is polled via GET /consents/{consentId}/status.

INITIATED → AWAITING_AUTHORIZATION → AUTHORIZED
                                   → FAILED
                                   → EXPIRED (after expiresAt)
                                   → REVOKED (via revoke endpoint)

The CreateConsentRequest specifies the company, loginMethod, and parameters including a Psd2AisConsentParameter defining the scope (accountIds, balances, transactions) plus PSD2-required fields (psuIpAddress, optional psuLocale, optional validUntil).

During AWAITING_AUTHORIZATION, the ConsentStatusResponse includes authInstructions — either a SwedishBankIdQr with qrCodeData (for QR code flow) or a SwedishBankIdAutostartToken with autoStartToken (for same-device flow). The pollingInterval field (milliseconds) indicates how often to poll.

Once AUTHORIZED, the consent can be used to start one or more collections until it expires or is revoked via DELETE /consents/{consentId}.

Two Ways to Collect PSD2 Data

curl https://api.insurely.com/companies/availability \
  -H "authorization-token: <API_KEY>" \
  -H "Insurely-Version: 2026-04-01"

curl -X POST https://api.insurely.com/collections \
  -H "authorization-token: <API_KEY>" \
  -H "Insurely-Version: 2026-04-01" \
  -H "Content-Type: application/json" \
  -d '{
    "company": "se-demo-psd2",
    "loginMethod": "SWEDISH_MOBILE_BANKID_OTHER_DEVICE",
    "parameters": [
      {
        "type": "SWEDISH_BANKID",
        "personalNumber": "200001012384"
      },
      {
        "type": "PSD2_AIS_CONSENT",
        "accountIds": [],
        "balances": true,
        "transactions": true,
      }
    ]
  }'

{
  "id": "coll-456",
  "status": "RUNNING",
  "company": "se-demo-psd2",
  "pollingTimeout": "2026-03-05T10:05:00Z",
  "extraInformation": null
}

curl https://api.insurely.com/wealth/collection/coll-456/status \
  -H "authorization-token: <API_KEY>" \
  -H "Insurely-Version: 2026-04-01"

{
  "id": "coll-456",
  "status":"WAITING_FOR_USER_ACTION",
  "company":"se-demo-psd2",
  "extraInformation": {
    "SWEDISH_BANKID_QRCODE": "BASE_64_ENCODED_QR_CODE",
    "SWEDISH_MOBILE_BANKID_ANIMATED_QR_DATA": "BANK_ID_TOKEN CODE"
  }
}

curl https://api.insurely.com/collections/coll-456/wealth/data \
  -H "authorization-token: <API_KEY>" \
  -H "Insurely-Version: 2026-04-01"

curl https://api.insurely.com/companies/availability \
  -H "authorization-token: <API_KEY>" \
  -H "Insurely-Version: 2026-04-01"

curl -X POST https://api.insurely.com/consents \
  -H "Authorization: Bearer <JWT>" \
  -H "Insurely-Version: 2026-04-01" \
  -H "Content-Type: application/json" \
  -d '{
    "company": "se-demo-psd2",
    "loginMethod": "SWEDISH_MOBILE_BANKID_OTHER_DEVICE",
    "parameters": [
      {
        "type": "PSD2_AIS_CONSENT",
        "accountIds": [],
        "balances": true,
        "transactions": true,
        "psuIpAddress": "192.168.1.1",
        "psuLocale": "sv-SE",
        "validUntil": "2026-05-31"
      },
      {
        "type": "SWEDISH_BANKID",
        "personalNumber": "200001012384"
      }
    ]
  }'

{
  "consentId": "consent-789",
  "company": "se-demo-psd2",
  "status": "INITIATED",
  "scope": {
    "type": "PSD2_AIS",
    "accountIds": [],
    "balances": true,
    "transactions": true
  },
  "expiresAt": "2026-05-31T23:59:59Z"
}

curl https://api.insurely.com/consents/consent-789/status \
  -H "Authorization: Bearer <JWT>" \
  -H "Insurely-Version: 2026-04-01"

curl -X POST https://api.insurely.com/collections \
  -H "Authorization: Bearer <JWT>" \
  -H "Insurely-Version: 2026-04-01" \
  -H "Content-Type: application/json" \
  -d '{
    "company": "se-demo-psd2",
    "parameters": [
      {
        "type": "STORED_CONSENT",
        "consentId": "consent-789",
        "psuIpAddress": "192.168.1.1",
        "psuUserAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)"
      }
    ]
  }'

{
  "id": "coll-456",
  "status": "RUNNING",
  "company": "se-demo-psd2",
  "pollingTimeout": "2026-03-05T10:05:00Z",
  "extraInformation": null
}

curl https://api.insurely.com/wealth/collection/coll-456/status \
  -H "Authorization: Bearer <JWT>" \
  -H "Insurely-Version: 2026-04-01"

curl https://api.insurely.com/collections/coll-456/wealth/data \
  -H "Authorization: Bearer <JWT>" \
  -H "Insurely-Version: 2026-04-01"

Consent Management

Listing Consents

• As the user (Authorization: Bearer): GET /consents — returns all consents for the authenticated user
• As the backend (authorization-token): GET /users/{id}/consents — returns all consents for a specific user

Revoking a Consent

Revoke a previously authorized consent via DELETE /consents/{consentId}:

curl -X DELETE https://api.insurely.com/consents/consent-789 \
  -H "Authorization: Bearer <JWT>" \
  -H "Insurely-Version: 2026-04-01"

• The revocation is forwarded to the bank (ASPSP)
• Once revoked, the consent cannot be used for new collections

Consent Expiration

• The validUntil field in the create request is a requested expiration date; the bank may enforce a shorter period
• The actual expiration is in the expiresAt field of the ConsentStatusResponse
• Expired consents cannot be used — create a new consent when the previous one expires
• Check consent status before starting a collection to avoid using an expired consent

Listing Collections

• As the user (Authorization: Bearer): GET /collections — returns all CollectionSummary objects for the authenticated user
  • Optional query params: latest=true (latest per company), statusIn=COMPLETED,FAILED (filter by status)
• As the backend (authorization-token): GET /users/{id}/collections — returns all collections for a specific user

Choosing Between One-Time and Consent-Based

Important Notes

PSU Presence (PSD2 Compliance)

PSD2 requires signaling whether the end user (PSU — Payment Service User) is present when interacting with the bank. This affects how the bank processes the request — without PSU presence fields, the request may be treated as a background refresh, which some banks handle differently or reject.

When creating a consent — include PSU fields in the Psd2AisConsentParameter:

When starting a collection with a stored consent — include PSU fields in the StoredConsentParameter to signal that the user is present:

If the collection is a background refresh (no user present), omit both fields.

When starting a One-Time Collection collection without a stored consent — you can omit the PSU fields, they are optional.

Account Scoping

The accountIds field in the Psd2AisConsentParameter controls which accounts the consent/collection covers:

• Empty array or omitted: Consent applies to all accounts the user has at the bank
• Specific IDs: Consent applies only to those accounts

Swedish BankID Authentication Variants

For Swedish companies, two BankID flows are available:

Error Handling

Consent errors (when status is FAILED):

• The ConsentStatusError object contains code (e.g., AUTHENTICATION_TIMEOUT) and a human-readable message

Collection errors:

• Terminal failure statuses include: FAILED, AUTHENTICATION_TIMEOUT, INCORRECT_CREDENTIALS, AUTHENTICATION_CANCELLED, AUTHENTICATION_CONFLICT, THIRD_PARTY_ERROR, ACCOUNT_TEMPORARILY_LOCKED
• For THIRD_PARTY_ERROR, the issue is on the bank's side — retry later
• See Collection statuses for the full list with recommended actions

Polling Best Practices

• Consent polling: Use the pollingInterval field from the ConsentStatusResponse (in milliseconds). Typically 1–2 seconds.
• Collection polling: Respect the pollingTimeout timestamp in the CollectionStatus — poll before this time or the collection may be terminated. Recommended interval: 1–2 seconds.
• Do not poll more aggressively than indicated — excessive polling may trigger rate limiting (HTTP 429).