> For the complete documentation index, see [llms.txt](https://docs.younium.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.younium.com/payments-integrations/aiia.md). # Aiia ## Overview The Aiia integration connects Younium to **Aiia** (open banking) so bank account transactions can be imported and converted into **payment batches** for payment matching. The integration uses OAuth to obtain access and refresh tokens, synchronises the list of bank accounts available in Aiia, and periodically fetches booked transactions per configured account. Unlike card or Direct Debit integrations, Aiia does not charge customers or post invoice settlements directly from bank debits. It ingests **incoming bank transactions** (non-negative amounts) and delegates batch creation to the payment matching subsystem. *** ## Authentication An administrator connects Younium to Aiia from the integration settings of a legal entity, choosing whether to connect to Aiia's sandbox or to production. Younium sends them to Aiia, where they sign in to the bank connection and approve the access; Aiia returns them to Younium and the connection is live. Younium keeps the connection alive on its own, renewing its access before each account sync and transaction import, so an administrator never has to reauthorise it on a schedule. The integration settings show whether the connection is currently working, alongside when accounts were last synchronised. > **Note on reconnection:** Aiia can ask for the connection to be authorised again. When it does, transaction import stops and reports that reconnection is required, and it stays stopped until someone reconnects from the integration settings. Nothing is lost in the meantime — the next successful import picks up the transactions that were missed. ### Settings | Setting | Description | Default | | ------------------------------------------ | ----------------------------------------------------------------------------- | ---------------------- | | `LastAccountSync` / `LastAccountSyncCount` | When the account catalogue was last refreshed, and how many accounts it found | Empty until first sync | | `AccountSync` | Whether the account catalogue is kept in step automatically | Per configuration | *** ## Sandbox vs. Production You choose sandbox or production when you connect, and the choice is fixed for that connection. The two are separate Aiia environments reached with separate credentials, so moving from testing to live means connecting again rather than switching a setting. *** ## Activation Connecting prepares the authorisation and records which Aiia environment you chose; the connection itself completes when you approve it at Aiia and are returned to Younium. Each authorisation attempt is single-use: Younium checks the callback against the connection attempt that started it, so completing the same authorisation link a second time, or returning to Aiia on a stale or bookmarked link, fails and the connection must be started again from Younium. Connecting does not by itself import anything. Once connected, you synchronise the list of bank accounts and assign a Younium payment method to each account you want transactions imported for — until an account has one, its transactions are not imported. *** ## Deactivation Disconnecting removes the connection and the list of bank accounts Younium had synchronised, together with the payment methods assigned to them. Transaction imports stop. The two are removed together, so reconnecting later starts from an empty account list and the payment method assignments have to be made again. Payments already imported and matched in Younium are unaffected. *** ## Save and Setup There is no separate save/setup handler that creates custom fields or event subscriptions. Operators map each `AiiaAccount` to a `YouniumPaymentMethodId` via `AddPaymentMethod`. *** ## Custom fields created by the integration Aiia does not create Younium custom fields. *** ## Eligibility and scope ### Transaction import * Only transactions with `amount >= 0` are converted to payments (credits to the account). * Transaction query uses pattern `state = Booked` only. * Default interval: from three days before `AiiaAccount.AiiaLastSynchronized` until now; skipped entirely if account `lastSynchronized` unchanged since last fetch (unless custom date fetch). * Page size 250 with paging token until exhausted. * Duplicate transaction ids: deduplicated by keeping the entry with the latest effective date (`detail.valueDate` or `date`, then `creationDate`). ### Scheduled job (`Aiia import payments job`) 1. Calls `ManualDataSynch` — if Aiia returns an `authUrl`, the job fails with “reconnection required”. 2. Requires at least one `AiiaAccount`. 3. Processes only accounts with `YouniumPaymentMethodId` set. ### Manual data sync `POST {baseUrl}/v1/update` with body `{ "redirectUrl": "{frontend}/settings/aiia" }` returns an `authUrl` when user re-authentication is required at Aiia. *** ## Field mapping ### Bank account catalogue (`GET /v1/accounts` → `AiiaAccount`) | Aiia field | Younium `AiiaAccount` field | | ---------------------- | ---------------------------------------------------- | | `id` | `AiiaAccountId` | | `name` | `Name` | | `currency` | `Currency` | | `accountProvider.name` | `AccountProviderName` | | `syncStatus` | `SyncStatus` | | `isOrphaned` | `IsOrphaned` | | `type` | `Type` | | `lastSynchronized` | `AiiaLastSynchronized` (on create only for new rows) | Accounts removed in Aiia are deleted from Younium on sync. ### Default incoming payment (before provider rules) | Aiia transaction field | Younium `IncomingPayment` field | | ---------------------- | -------------------------------------------------- | | `id` | `ExternalBankId` | | `text` | `PaymentDescription`, `PaymentReference` (initial) | | `originalText` | `PayerInformation` | | `amount` | `Amount.Amount` | | `currency` | `Amount.CurrencyCode` | | `date` (`yyyy-MM-dd`) | `PaymentDate`, `Amount.CurrencyConversionDate` | | `detail.source.name` | `PayerName` (when present) | ### Payment batch generation | Younium field | Value | | ------------------------------------------------ | -------------------------------------- | | `PaymentSection.BatchDescription` | `Transactions from {AiiaAccount.Name}` | | `PaymentSection.SourceDescription` | `Aiia import` | | `MatchingAccountSettings.YouniumPaymentMethodId` | `AiiaAccount.YouniumPaymentMethodId` | | `MatchingAccountSettings.FinancialAccountId` | From linked payment method | ### Provider-specific payment reference overrides When `AccountProviderName` matches, `PaymentReference` (and sometimes `PayerName`) are derived from transaction text or `detail` fields: | Provider | Rule (summary) | | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **ING** | Text after `Omschrijving:` up to `<` in `originalText` | | **Danske Bank Business Online** | Skips `InternalCounterEntry`; EUR parses `Payment details:` and `Originator Reference Party:` from `detail.message`; DKK uses `originalText`; tenant-specific rules for configured legal entities (message suffix / last 8 digits) | | **ABN AMRO** | Default: digits after `Omschrijving` in `originalText`; variants for specific legal entity (after `V`) or tenant BCS (regex `Fxxx-########`) | | **Sparekassen Kronjylland** | `originalText` or regex / last 4 characters when line ends with `IK71` | | **HSBCnet** | Digits after `INV` in `originalText` | | **Nordea Yrityspankki** | `detail.identifiers.reference` when present | ### Batch log (`AiiaBatchLog`) | Younium field | Source | | ------------------------ | ---------------------------------- | | `BatchNumber` | Generated payment batch | | `BankAccount` | `AiiaAccount.Name` | | `NumberOfTransactions` | Payment count in batch | | `Description` | Batch description | | `TotalBatchLogAmount` | Batch total amount | | `Currency` | Account currency | | `AiiaSynchronized` | `AiiaAccount.AiiaLastSynchronized` | | `YouniumTransactionSync` | `UtcNow` at import | | `AiiaEnvironment` | Current settings environment | *** ## Transaction fetch workflow 1. Refresh OAuth token. 2. `GET /v1/accounts/{AiiaAccountId}` — compare `lastSynchronized`; exit early if unchanged (unless custom date). 3. `POST /v1/accounts/{id}/transactions/query` with `pageSize`, `interval`, and `patterns` (Booked only). 4. Paginate with `pagingToken` until complete. 5. Deduplicate, update `YouniumLastTransactionSync`, `YouniumLastTransactionSyncCount`, `AiiaLastSynchronized`. 6. Build the payment sections and generate payment batches for matching. 7. Write `AiiaBatchLog` when batch contains payments. *** ## Events and jobs | Trigger | Name | Behaviour | | ------------------ | ---------------------------------- | --------------------------------------------------------- | | Scheduled job | Aiia import payments job | Reconnection check; fetch transactions per mapped account | | Application events | None | — | | Manual action | Account sync (`FetchAiiaAccounts`) | Refresh account list from Aiia | | Manual action | `AddPaymentMethod` | Set `YouniumPaymentMethodId` on `AiiaAccount` | --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.younium.com/payments-integrations/aiia.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.