Onboarding

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude

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.

Overview

Getting a customer live requires up to two separate tracks, depending on what you're building:

• Bank & Aritma onboarding — required for every customer, regardless of whether you read account info or send payments. This connects the customer's bank accounts to Aritma.
• User onboarding — required only if you send payments with pre-approval. Nordic regulation requires a user-level authentication flow at the point of payment, so an identity solution needs to be in place before you can send payments through the API.

Prerequisites

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

• A tenant and subscription - see the 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

Step 1: Find your bank

Call GET /banks to find the bank and get its bankId. The response also includes bank order information — a description, of what the customer needs to do at their bank to authorize communication with Aritma. If you want to own this part of the frontend yourselves, use this response as a starting point and build your own version of the ordering flow.

The bank order itself is solely owned by the bank, and typically takes 0–5 business days from when the customer submits it until the bank is ready to communicate with Aritma. Plan for this lead time, and make sure the customer is aware they can check with their bank directly for visibility into the time needed.

curl -i -X GET \
  'https://developer.aritma.com/_mock/apis/banking/v4/openapi/banking-openapi/banks?countryCode=NO&channels=string&includeAdditionalInformation=true' \
  -H 'api-version: string'

Try it out

Step 2: Create a consent

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

curl -i -X POST \
  https://developer.aritma.com/_mock/apis/banking/v4/openapi/banking-openapi/consents \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'api-version: string' \
  -d '{
    "channelType": "openBanking",
    "subscriptionId": "992606c793984bcf81e543d90ecfbb36",
    "resourceGroupName": "999999999",
    "properties": {
      "psuCorporateId": "999999999",
      "combinedServiceIndicator": "true",
      "isHeadless": "true",
      "numberOfApprovers": "1",
      "accountNumbers": "<AccountNumber1>, <AccountNumber2>"
    },
    "bankId": "cba4beaf-9b52-40c5-8929-e0af6c1e8b18"
  }'

The response contains:

• consentId - store this for later use
• status - the initial consent status. awaitingApproval is the normal happy path — expect this by default and continue to Step 3. authorized can happen too (the consent is immediately ready, skip to Step 7), but treat it as a shortcut, not the default case.

Try it out

Step 3: Generate the SCA link

Call the refresh endpoint to generate the strong customer authentication (SCA) link. The response contains a redirectUrl — send the customer here to complete authentication.

curl -i -X PUT \
  'https://developer.aritma.com/_mock/apis/banking/v4/openapi/banking-openapi/consents/{id}/refresh' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'api-version: string' \
  -d '{
    "properties": {}
  }'

Try it out

STEP 4: User verification

The PSU (a person with a valid organizational role) opens the SCA link and logs in with BankID or the local equivalent. This confirms their identity — it does not yet confirm they're allowed to act for the organization; that's the next step.

STEP 5: KYC validation

Aritma automatically checks two things:

1. Role validation — does this person actually have a valid role at the organization?
2. Account ownership — does the organization actually own the requested accounts? If you specified a redirect URL, the result comes back as a scaStatus query parameter:

• finalized — succeeded
• failed — failed, can be retried
• exempted — exempted from validation, treated as succeeded If validation fails and a different person needs to try, generate a new SCA link by repeating step 3.

If verification has failed and you want another user to perform role validation, create a redirect link for the current onboarding using the refresh endpoint.

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 received at the time of SCA (see Step 1 for bank order timing), Aritma will wait for the bank. If the information received is insufficient, or the bank doesn't 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.

Check consent status

curl -i -X GET \
  https://developer.aritma.com/_mock/apis/banking/v4/openapi/banking-openapi/consents/1E5EFC3B-635E-4973-A605-41D7F0D6D7B3 \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'api-version: string'

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

curl -i -X GET \
  'https://developer.aritma.com/_mock/apis/banking/v4/openapi/banking-openapi/accounts?withBalance=true&balanceDate=string&bban=12345612345678&iban=FR7612345987650123456789014&search=string&cursor=string' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Channel-Type: unspecified' \
  -H 'Consent-ID: <consentId>' \
  -H 'PSU-IP-Address: string' \
  -H 'Resource-Group-Name: string' \
  -H 'Scopes: /subscriptions/7fdf00601dfb/resource-groups/my-company' \
  -H 'Subscription-Id: string' \
  -H 'api-version: string'

Option B: Using subscription and resource group headers

curl -i -X GET \
  'https://developer.aritma.com/_mock/apis/banking/v4/openapi/banking-openapi/accounts?withBalance=true&balanceDate=string&bban=12345612345678&iban=FR7612345987650123456789014&search=string&cursor=string' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Channel-Type: openBanking' \
  -H 'Consent-ID: string' \
  -H 'PSU-IP-Address: string' \
  -H 'Resource-Group-Name: 999999999' \
  -H 'Scopes: /subscriptions/7fdf00601dfb/resource-groups/my-company' \
  -H 'Subscription-Id: 992606c793984bcf81e543d90ecfbb36' \
  -H 'api-version: string'

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

Try it out

Next steps

You are now ready to start using the account and payment APIs. To modify the consent later (for example, to request access to an additional account), use the refresh consent endpoint PUT /consents/{id}/{refresh}and specify the properties you want to change.

FAQ

How long does bank & Aritma onboarding take, end to end? Two waiting periods stack: the bank order (0–5 business days) plus however long KYC and provisioning take. If a bank agreement already exists and KYC passes automatically, provisioning can complete within minutes of the customer completing the SCA link.

Can I onboard accounts from multiple banks for one customer? Yes, but each bank needs its own consent — a consent is tied to one bankId. Since only one consent per company per bank is allowed, check for an existing consent before creating a second one at the same bank.

Who should I send the SCA link to? Someone with procura (signing authority) for the company and for the specific accounts being onboarded. If it goes to someone without that authority, validation will fail even if they successfully log in with BankID.

What if the SCA link expires or was already used? It expires after 7 days, and it's single use — opening it a second time invalidates it. Call the refresh endpoint again to generate a new one for the same consent. Note that link-preview crawlers (Slack, Teams, email scanners) can trigger this by fetching the link before the actual user opens it. Excessive and unnecessary use of the SCA URL may be subject to invoicing.

Why did KYC validation fail, and how will I know? There's no automated signal if KYC fails — no separate status or event. If you suspect it, contact Aritma support with the consentId. When it does happen, it's usually because the person who completed the SCA link doesn't have a valid role or procura for the organization, or the organization doesn't own the account(s) listed in the consent.

What does scaStatus=exempted mean — is that a problem? No — it means the bank or flow exempted this request from strong customer authentication, and it's treated as successful, same as finalized.

How do I know if manual review is happening? Consent status will show AwaitingApproval instead of progressing to Authorized. There's no separate API signal for why — if it's stuck, contact Aritma support with the consentId.

Should I fetch account data using Consent-ID, or subscription/resource-group headers? Prefer subscription and resource group headers over scoping to the consent currently being onboarded. This lets you fetch data across a customer's other banks even while a separate onboarding is still in progress.

What's the difference between Authorized and an account being enabled? Authorized is the consent-level status — the connection itself is confirmed. enabled is per-account, returned from GET /accounts — it confirms that specific account is usable for account info or payments. Always check the account-level status even after the consent shows Authorized.