Dev API Access – Setup Guide

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

About this document

This document describes how to get started with the Aritma Open Banking V4 API in the development environment. It walks you through authentication, consent creation, account verification, and submitting your first payment.

This assumes you have already requested a demo and received a demo email containing your credentials, which are used throughout this guide. The environment variables from the accompanying email replace all placeholders ({...}) in this guide.

Documentation and references

API versioning

The API is versioned via the api-version header. Use api-version: 1.0 on all requests. Supported versions are returned in the api-supported-versions response header.

Idempotency

The API supports idempotency for safely retrying POST requests. Include the header Idempotency-Key: {UUID} to avoid duplicate operations. If a replayed response is returned, the header Idempotent-Replayed: true will be present.

1. Your credentials

Tenant

The Identity URL is used for token generation (OAuth 2.0).

Client

Authentication uses the OAuth 2.0 Client Credentials flow.

The ClientSecret must be treated as confidential. Do not store it in plain text or share it outside your development team.

Environment

These two values are used as headers (Subscription-Id and Resource-Group-Name) on all API calls after onboarding. Store them in your application configuration.

Test account

Your dev environment includes two accounts, see the demo email.

This account is configured with non pre-approved payments (RGB off), which means payments go directly to the mock bank without a signing step. This is the default configuration for dev and allows you to test the full payment flow end-to-end with minimal steps.

2. Authentication: Generate access token

All API calls require a valid access token.

Endpoint:

POST https://id.dev.aritma.io/{TenantId}/connect/token
Content-Type: application/x-www-form-urlencoded

Parameters:

cURL example:

curl -X POST "https://id.dev.aritma.io/{TenantId}/connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id={ClientId}&client_secret={Secret}"

Response:

{
  "access_token": "eyJhbGciOi...",
  "expires_in": 3600,
  "token_type": "Bearer",
  "scope": "api"
}

Use the access_token in the Authorization header on all subsequent calls:

Authorization: Bearer {access_token}

The token is valid for 1 hour. Generate a new one when it expires.

3. Create consent (onboard a test company)

Before you can make payments or retrieve account data, you need to establish a consent. The consent links a company's bank accounts to your subscription.

In the dev environment, you use the MockBank, which bypasses the BankID redirect flow.

Endpoint:

POST https://banking.dev.aritma.io/api/consents

Headers:

Request body:

{
  "channelType": "openbanking",
  "bankId": "3a85a03b-2f39-4c65-868b-6f8389e46a04",
  "subscriptionId": "{SubscriptionId}",
  "resourceGroupName": "{ResourceGroupName}",
  "properties": {
    "accountNumbers": "{BBAN}",
    "isHeadless": "true",
    "combinedServiceIndicator": "true",
    "numberOfApprovers": "1"
  }
}

Important:

• bankId must be lowercase. The value above is the MockBank ID. For real banks, always fetch IDs from GET /banks — never hardcode.
• isHeadless must be "true" when using MockBank. This bypasses the BankID redirect.
• combinedServiceIndicator: "true" enables both account information (AIS) and payment initiation (PIS).

Response (key fields):

{
  "consentId": "a1b2c3d4-e5f6-...",
  "status": "Created"
}

Store the consentId. Since MockBank with isHeadless: true is used, the consent completes automatically.

Check consent status

GET https://banking.dev.aritma.io/api/consents/{consentId}

Status progression: Created → Started → Authorized

Once the status is Authorized, the consent is active and accounts are ready for use.

4. Verify onboarded accounts

After the consent is authorised, verify that accounts are available.

Endpoint:

GET https://banking.dev.aritma.io/api/accounts

Headers:

Accounts with status enabled are ready for payments and data retrieval.

The response includes accountId values — store these for transaction retrieval and balance checks.

5. Create a payment

Endpoint:

POST https://banking.dev.aritma.io/api/bulk-payments/credit-transfer

Headers:

Request body:

{
  "debtorAccount": {
    "iban": "{IBAN}"
  },
  "debtorName": "{CompanyName}",
  "requestedExecutionDate": "2026-06-01",
  "batchBookingPreferred": false,
  "paymentLines": [
    {
      "endToEndIdentification": "TEST-PAYMENT-001",
      "instructedAmount": {
        "currency": "NOK",
        "amount": "1500.00"
      },
      "creditorAccount": {
        "iban": "NO6036407513651"
      },
      "creditorName": "Test Supplier AS",
      "remittanceInformationUnstructured": "Invoice #1234",
      "instructionPriority": "normal"
    }
  ]
}

Important:

• debtorAccount must match one of your onboarded test accounts.
  • creditorAccount should be the other account we provided — this will simulate incoming payments by generating transactions.
• requestedExecutionDate must be a future date.
• One or more payment lines can be included in a single request.
• The Postman collection includes a pre-built body with randomly generated payment lines — you only need to update debtorAccount, debtorName, and requestedExecutionDate.

Response (key fields):

{
  "paymentId": "9425e6f7-4300-...",
  "transactionStatus": "RCVD"
}

With your default dev account (non pre-approved), the payment progresses automatically:

RCVD → ACSP → ACSC

No further action is required. The mock bank accepts the payment and produces return files. You can verify the final status by polling:

GET https://banking.dev.aritma.io/api/bulk-payments/credit-transfer/{paymentId}

6. Retrieve data

After onboarding and payment creation, you can retrieve account data.

Get account balances

GET https://banking.dev.aritma.io/api/accounts/{accountId}/balances

Get transactions

GET https://banking.dev.aritma.io/api/accounts/{accountId}/transactions

Standard headers for all data retrieval

Important: For all data retrieval after onboarding, use Subscription-Id and Resource-Group-Name — not Consent-ID. The consent ID is only used during the consent creation flow and for payment initiation.

Quick reference

Troubleshooting

Next steps

Once you have completed your first payment in dev:

• Webhooks: Subscribe to real-time events (payment status, transactions, balance updates) via the Events API instead of polling.
• Real bank testing: Test with non-mock banks using isHeadless: false and BankID verification.
• Pre-approved payments: If you need to test the signing basket flow, contact us and we will configure an additional account (see Appendix A).
• Production: Contact Aritma to set up production credentials when you are ready to go live.

Appendix A: Pre-approved payments and the signing basket flow (optional)

Your default dev account is configured with non pre-approved payments, meaning payments are sent directly to the bank without a signing step. In production, many customers will use pre-approved payments instead, where an authorised user signs payments in your system before they are forwarded to the bank.

If you want to test this flow in dev, contact Aritma support and we will configure an additional account with pre-approved payments enabled.

How pre-approved payments work

When an account has pre-approved payments enabled (RGB on), the payment stays at status RCVD after creation. To move it forward, you need to complete the signing basket flow:

Step 1 — Create signing basket

POST https://banking.dev.aritma.io/api/signing-baskets

{
  "paymentIds": [
    "{paymentId}"
  ]
}

Multiple payment IDs can be included to approve several payments at once. The response returns a basketId.

Step 2 — Start authorisation

POST https://banking.dev.aritma.io/api/signing-baskets/{basketId}/authorizations

The response includes scaRedirect.href — a URL where the user completes BankID verification.

Step 3 — Complete authorisation in browser

1. Open scaRedirect.href in a browser
2. Create a user account (if first time) or log in
3. Complete BankID verification using the BankID demo (see below)
4. Approve the signing basket
5. You are redirected back to the configured TPP-Redirect-URI

After successful authorisation, payments progress: RCVD → ACSP → ACSC.

BankID demo credentials

The dev environment uses the Norwegian BankID demo. Generate a test user:

1. Go to https://ra-preprod.bankidnorge.no/#!/generate
2. Click Generate number
3. Fill in the fields — you can use randomly generated values
4. Click Order
5. Copy the generated End User Identification number

Use this number in the BankID verification step.

These are default values from BankID Norway's own documentation.

Payment status comparison

Appendix B: The consent flow in production

In the dev environment, the MockBank with isHeadless: true completes the consent automatically. In production, the consent flow is the process by which your end customers connect their bank accounts to your application through Aritma.

The real flow works as follows:

1. Your application creates a consent via the API for a specific bank, company, and set of accounts.
2. The API returns a redirectUrl that you send the end user to.
3. The user lands on the Aritma onboarding portal, where they verify their identity with BankID and confirm the connection.
4. Aritma performs KYC validation (role verification and account ownership).
5. The user is redirected back to your application.
6. At the end of the consent flow, the customer receives instructions for contacting their bank to order bank integration (file exchange). This step is handled by the customer directly with their bank.
7. When the bank has activated the integration and Aritma receives the first files, the setup is completed on our side and the account status becomes enabled.

Each of your customers goes through this flow once per bank. After that, you use Subscription-Id and Resource-Group-Name for all data retrieval and payment operations — the consent ID is no longer needed.

For full details, see the Onboarding in the API documentation.

Aritma AS — support@aritma.io — +47 55 34 91 50