# Onboarding

This guide walks you through onboarding corporate bank accounts via the Open Banking channel. The onboarding process connects your organization's bank accounts to the Aritma Banking API, enabling account information retrieval and payment initiation.

## Prerequisites

Before you begin, make sure you have the following in place:

* A **tenant** and **subscription** - see the [Getting Started](/getting-started) guide
* A **client** with the `banking.consents.create` IAM action granted on the subscription. In most cases, granting `banking.manage` is sufficient as it includes `banking.consents.create` and other required actions.
* The **scope** `banking.ais.read` to verify onboarded accounts


Example values used in this guide
The examples below use the following values - replace them with your own:

| Placeholder | Example value | Description |
|  --- | --- | --- |
| `subscriptionId` | `992606c793984bcf81e543d90ecfbb36` | Your subscription ID |
| `organisationNumber` | `999999999` | The organization number |
| `bankId` | `cba4beaf-9b52-40c5-8929-e0af6c1e8b18` | The bank identifier |


## Step 1: Find your bank

Use the `GET /banks` endpoint to find available banks for open banking. You'll need the `bankId` from the response when creating a consent.

Note:
Some banks include an `onboarding` field with links to external onboarding documents or pages. Check these for any bank-specific requirements before proceeding.

### Try it out

## Step 2: Create a consent

Create a consent by calling `POST /consents` with the organization and bank account details.

| Field | Description |
|  --- | --- |
| `channelType` | Must be `"openBanking"` for open banking |
| `subscriptionId` | Your subscription ID (e.g. `992606c793984bcf81e543d90ecfbb36`) |
| `resourceGroupName` | The organization number (e.g. `"999999999"`). A new resource group is created automatically if one does not already exist. |
| `bankId` | The bank identifier from Step 1 |
| `properties.psuCorporateId` | The organization number |
| `properties.accountNumbers` | Comma-separated list of account numbers to onboard |
| `properties.combinedServiceIndicator` | Set to `"true"` to enable combined AIS and PIS services |
| `properties.numberOfApprovers` | Number of required approvers (e.g. `"1"`) |


Note:
The required consent properties may vary between banks. Use `GET /banks/{bankId}` with `includeAdditionalInformation=true` to discover bank-specific property requirements.

The response contains:

* `consentId` - store this for later use
* `redirectUrl` - the URL to redirect the PSU (Payment Service User) to
* `status` - the initial consent status


Note:
The `redirectUrl` is only usable once.

### Try it out

## Step 3: Redirect the PSU

A user with a valid role in the organization must open the `redirectUrl` from the previous step. They will be presented with information about the onboarding and asked to confirm it.

You can preselect the language by appending a `ui-culture` query parameter to the redirect URL:

* `?ui-culture=nb` - Norwegian Bokmål
* `?ui-culture=en` - English (default)


## Step 4: User Verification

The PSU must authenticate with BankID (in Norway) or the country-equivalent identification method. This verifies the user's identity with Aritma.

## Step 5: KYC validation

After user verification, our system automatically performs KYC (Know Your Customer) validation:

1. **Role validation** - verifies the PSU has a valid role in the organization
2. **Account ownership** - verifies the organization is the account owner of the bank accounts requested in the consent


## Step 6: Completion and provisioning

What happens next depends on the state of the bank agreement and KYC results:

* **Bank agreement exists** - If an agreement with the bank has already been established (external process), the onboarding service will typically complete the onboarding automatically and provision the accounts.
* **No bank agreement or insufficient information** - If no bank agreement has been created, or the bank does not supply enough onboarding information, the Aritma support team will manually review the onboarding.
* **KYC insufficient** - If KYC validation is not sufficient, or KYC is not supported for the country, Aritma support can execute manual KYC validation.


Note:
You can track the consent status by polling `GET /consents/{consentId}` or by subscribing to consent events through the [Events API](/apis/platform/events). The consent status will transition from `Created` → `Started` → `Authorized` when complete, or to `AwaitingApproval` if manual review is required.

### Check consent status

## Step 7: Verify onboarded accounts

Once the consent status is `Authorized`, verify the onboarding by retrieving the accounts. You can scope the request in two ways:

### Option A: Using Consent-ID

### Option B: Using subscription and resource group headers

If accounts are returned with status `enabled`, they are ready for use - including payment initiation.

### Try it out