When a payment is initiated through the Aritma Banking API, it follows one of two paths depending on the account's configuration. Understanding this distinction is critical for partners integrating with the API, as it directly affects both the API calls required and the end-user experience.
Pre-approved payments means the customer authorises the payment within the accounting system before it is sent to the bank, while complying with regulatory authority requirements. With pre-approved payments, the users don't need to approve payments in the corporate online bank.
How it works:
- Initiate a payment via
POST /api/bulk-payments/credit-transfer - The payment enters status
RCVD(received) and awaits signing/approval - Create a signing basket containing one or more payment IDs — these can be individual payment line IDs, bulk payment IDs, or a mix of both
- An authorised user signs the basket using BankID, MitID, or Swedish BankID
- Once the required number of approvers (1 or 2, depending on the
requiredAuthorizationssetting) have signed, the payment is automatically forwarded to the bank - The bank accepts the payment and queues it for processing on the due date
When to use: Use this mode if you customers want to manage payment approval themself, within the application, rather than relying on the bank. Most partners use this configuration in production.
Account Settings: To use this mode, the account's parameters must have accountingApprovedPayments = true (RGB on) and requiredAuthorizations = 1 or requiredAuthorizations = 2 . The number of required Signers/Authorisations is set via the numberOfApprovers field in the consent properties and potentially configurations in the online bank.
Not all of these account settings for payment approval can be configurable through the API. For some banks these settings are determined by the configurations the customer has set up directly with their bank, and can only be changed there.
Payments can be sent directly to the bank without prior authorisation in the accounting system. Depending on the account's bank configuration and country-specific regulations, the customer may then need to approve the payment manually in their online bank, or the bank may accept it automatically.
How it works:
- Initiate a payment via
POST /api/bulk-payments/credit-transfer - The payment is sent directly to the bank — no signing basket is required
- The bank processes the payment and returns status updates
- Depending on the bank's configuration, the customer may then need to approve the payment manually in their online bank
When to use: This is typically the case when the customer prefers to review and approve each payment themselves in their online bank, rather than approving payments directly from the accounting system.
Agreement Settings: The account's parameters are accountingApprovedPayments = false (RGB OFF) and requiredAuthorizations = 0 .
Not all of these account settings for payment approval can be configurable through the API. For some banks these settings are determined by the configurations the customer has set up directly with their bank, and can only be changed there.
The approval mode is determined by the settings on the account, not by a property on the payment itself. These settings is set by a combination of the properties in the consent flow and the configuration the customer has in their online bank. Aritma receives information regarding account settings from the bank once the customer has ordered the integration in their online bank.
| Setting | Agreement value | Behaviour |
|---|---|---|
| Approve payments in the accounting system | accountingApprovedPayments: true (RGB on) & requiredAuthorizations > 0 | Payments require signing basket before forwarding to bank |
| Approving payments in the online bank | accountingApprovedPayments: false (RGB off) | Payments go straight to bank without signing |
The rgb property in the consent properties object can also controls this:
"rgb": "true"— indicates that pre-approved payments should be enabled"rgb": "false"— pre-approved payments is wished disabled
When an account has pre-approved payments enabled, all payments must go through the signing basket flow before they are forwarded to the bank.
- Mock serverhttps://developer.aritma.com/_mock/apis/banking/v4/openapi/banking-openapi/bulk-payments/{paymentProduct}
- https://banking.aritma.io/api/bulk-payments/{paymentProduct}
curl -i -X POST \
https://developer.aritma.com/_mock/apis/banking/v4/openapi/banking-openapi/bulk-payments/credit-transfer \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
-H 'Channel-Type: unspecified' \
-H 'Consent-ID: string' \
-H 'Content-Type: application/json' \
-H 'PSU-IP-Address: string' \
-H 'Resource-Group-Name: string' \
-H 'Scopes: /subscriptions/7fdf00601dfb/resource-groups/my-company' \
-H 'Subscription-Id: string' \
-H 'TPP-Redirect-URI: http://example.com' \
-H 'api-version: string' \
-d '{
"debtorAccount": {
"iban": "NO5036086104622"
},
"debtorName": "Company AS",
"batchBookingPreferred": false,
"paymentLines": [
{
"endToEndIdentification": "PAYMENT-001",
"instructedAmount": {
"currency": "NOK",
"amount": "1500.00"
},
"creditorAccount": {
"iban": "NO6036407513651"
},
"creditorName": "Supplier AS",
"remittanceInformationUnstructured": "Invoice #1234",
"instructionPriority": "normal"
}
]
}'Result: The payment enters status RCVD and remains there until it is signed/approved.
- Mock serverhttps://developer.aritma.com/_mock/apis/banking/v4/openapi/banking-openapi/signing-baskets
- https://banking.aritma.io/api/signing-baskets
curl -i -X POST \
https://developer.aritma.com/_mock/apis/banking/v4/openapi/banking-openapi/signing-baskets \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
-H 'Channel-Type: unspecified' \
-H 'Consent-ID: string' \
-H 'Content-Type: application/json' \
-H 'PSU-IP-Address: string' \
-H 'Resource-Group-Name: string' \
-H 'Scopes: /subscriptions/7fdf00601dfb/resource-groups/my-company' \
-H 'Subscription-Id: string' \
-H 'TPP-Redirect-URI: http://example.com' \
-H 'api-version: string' \
-d '{
"paymentIds": [
"p1pbb64b18233714bf38204314e3faa03bc",
"p1pcm64b16566772bf37206317e3mdd03ss"
]
}'Multiple payments can be approved at once by including them in the same basket. The response returns a basketId and the current approvalState.
- Mock serverhttps://developer.aritma.com/_mock/apis/banking/v4/openapi/banking-openapi/signing-baskets/{basketId}/authorizations
- https://banking.aritma.io/api/signing-baskets/{basketId}/authorizations
curl -i -X POST \
https://developer.aritma.com/_mock/apis/banking/v4/openapi/banking-openapi/signing-baskets/4f0d36c610d44e60af3c244259aa7779/authorizations \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
-H 'Content-Type: application/json' \
-H 'PSU-IP-Address: string' \
-H 'TPP-Redirect-URI: http://example.com' \
-H 'api-version: string' \
-d '{
"authenticationMethodId": null,
"authenticationMethodAcrValues": null
}'The response includes:
authorizationIdscaRedirect.href— a URL where the user completes BankID verification
The PSU/User will be redirected to complete SCA for all payments in the basket.
- Redirect the user to
scaRedirect.href - User authenticates with BankID
- User approves the signing basket
- Flow redirects back to the configured redirect URL
After successful authorisation, the payments in the basket are forwarded to the bank for processing.
Navigate to Payment statuses for more information
This happens when a payment is sent from an account with pre-approved payments enabled, but the signing basket flow has not been completed. The payment is waiting for authorisation.
Solution: Create a signing basket with the payment ID and complete the authorisation flow.
This is expected behaviour if the accounts have different agreement configurations. Check the agreement settings:
- Account with RGB off: payments go through immediately
- Account with RGB on: payments require signing basket
Where payments can be approved is set up in the customer's online bank, usually during onboarding (ordering of Bank Integration). The exact steps differ from bank to bank. For Swedish banks:
- SEB: Choose "Godkänna betalningar i affärssystemet" (approve in system) for pre-approved, or "Godkänna i banken" for bank approval
- Nordea: Configured during Corporate Access setup
- Swedbank / Handelsbanken: Configured via Cash Management advisor
The bank agreement must match the Aritma agreement configuration. If the bank expects pre-approved payments but the Aritma agreement has RGB off (or vice versa), payments may fail or behave unexpectedly.
In the dev environment, accounts are typically set up with different configurations to allow testing both flows:
- Account with RGB off
(requiredAuthorizations = 0): Use for testing payments without approval/signing - Account with RGB on
(requiredAuthorizations > 0): Use for testing the full signing basket flow with SCA
For BankID demo testing during the signing basket flow, see the BankID Dev Environment documentation.
Partners sometimes interpret "pre-approved" as meaning the payment goes through without approval. The Aritma definition is the opposite:
| Term | Aritma definition |
|---|---|
| Pre-approved | Customer signs the payment in the accounting system before sending to bank |
| Non pre-approved | Payment is sent directly to bank without prior signing |