ZTL OpenAPI (v2.0)

Below is a very short description of the main categories of services.

• Authentication - Used to create access token, needed in most API calls
• Onboarding - All users must onboard their company before the bank services can be used
• Banks - Services for available banks with product support and constraints
• Consent - Services for end user bank consents
• Accounts - Bank accounts services. Requires a valid consent.
• Payments - Services for domestic and cross-border payments. Requires a valid consent.
• Fx payments - Payment services used for partners which do not use bank integration
• Companies - Services to get an overview of all companies registered by a partner, and functionality to activate/deactivate company
• Country - Gives information about restrictions for sending payment to a country
• Currencies - Services for currency information

The first step to use the API is to have an onboarded company. The onboarding is initiated through the API, which returns an url which the user has to use to complete the onboarding process (KYC questions etc). The user can start to use the services once the user has completed the onboarding, and the onboarding status has been updated to 'Approved'.

To use ZTL open banking services, the user has to give consent which needs to be signed by the user. The consent is personal per user, and is linked to an organization. The consent gives ZTL access to retrieve account information and start payment initiation. Note that the user consent only gives access to start payment initiation, the user still needs to sign(authorize) payments before they are executed by the bank. The consent services has API to initiate the consent creation, and the consentId is used for Accounts and Payments services.

After the user has given consent, the next step is to retrieve available bank accounts the user has access to. Note that this service is only available right after the consent has been created, so it's recommended to fetch and store the account list right after the consent has been created. It's possible to fetch balance and account entries for the accounts.

Payment initiation can be started with consent, but requires an additional signing from the user.

The banks, currencies and country APIs can be used to get useful information like supported banks, products, countries etc.

• Most responses contain a header ztl-request-id. This is a unique id for each request, and should be used if you need to contact ZTL support regarding problems with a specific API call.
• PSU-User-Agent and PSU-IP-Address are used in many endpoints, and indicate if the user is present when a request is made. Please only use these headers when user is actually present(logged on in your system).

Error messages body format has been standardized, with some differences of available failure codes related to each endpoint - see description for available return values for each endpoint. ZTL may add more enums for error codes, so it's recommended to have general parser for the enum values that can handle unknown values. The following http error codes are recommended to handle:

• 400 - Bad Request. The message format contains a failure code, see each endpoint for available error codes.

{
  "failure": "Invalid_BBAN",
  "ztlRequestId": "350eb968-f4cf-474c-8cf2-f8068294d364 ",
  "message": "The provided BBAN was invalid"
}

• 409 - Conflict. This error indicates that there are some problems with simultaneous usage of consent. There is a very low chance for this situation to occur, and would normally be resolved by retrying the request.

• 422 - Input validation failed. This error indicates that there are issues with some of the input values. We provide a specific error code that is defined for each endpoint and error reason in English along with the path for the value that is invalid.

[
  {
    "code": "InvalidBBAN",
    "reason": "Invalid BBAN",
    "path": ".from.account"
  },
  {
    "code": "InvalidDueDate",
    "reason": "Due date cannot be in the past",
    "path": ".dueDate"
  }
]

• 500 - Internal Server Error. Indicates that some unhandled error has occurred. We do not recommend to show the message to end user in case of these error types.

{
  "ztlRequestId": "ENUM",
  "message": "The underlying reason for the error"
}

The following is a list of environments available when developing against or using our API:

Here is a table listing the banks available for use in Sandbox. While other banks may function, they are not officially supported.

Testing with mock bank - Denmark

To help partners test Sandbox flows in Denmark, we provide a dedicated mock bank. The purpose of the mock bank is to make it possible to test supported happy-path flows and ensure all statuses are available in Sandbox. The functionality may change over time based on partner feedback and test needs.

• Consent: If you create a consent with userId set to REJECTED or EXPIRED, the consent will end in that state after the user follows the consent link. All other userId values are accepted.
• Accounts: The Accounts functionality mainly supports happy-path scenarios. Balances and entries are based on completed transactions and are not generated randomly.

Payments

If any payment included in a payment approval uses account number 99990000000011, the approval is rejected. If any payment included in a payment approval uses account number 99990000000012, the approval is cancelled.

The table below lists "to" account numbers with special behaviour. All payments start in Unsigned, and the special logic is applied after the first approval unless otherwise noted.

Bulk payments are currently not supported for the mock bank, but is expected to be available soon.

Most endpoints requires an access-token, which are used in the 'Authorization' header. Please contact ZTL support if you need to create new credentials or change existing secret. The created token is valid for 60 minutes (could be invalidated before), and should be reused until it is invalidated. To use the token, set the header Authorization to Bearer ACCESS_TOKEN. Expired token will result in 401 - Unauthorized, indicating that the partner needs to renew their token.

The first step before using the ZTL API is to onboard the company.

Onboarding lifecycle

An onboarding starts in Created and moves through the lifecycle until it reaches a final status.

The final statuses are:

• Accepted
• Rejected

Below is an overview of the onboarding statuses and what they mean.

General implementation considerations

When implementing onboarding in your integration, keep the following in mind.

All onboarding behavior described below applies per partner integration. This means that a company may already be onboarded through another ZTL partner without affecting your ability to onboard the same organization number in your own integration.

In addition:

• In PRODUCTION, each company can only have one active onboarding at a time until it reaches a final status.
• If an onboarding remains in Created or AwaitingCustomerAction for more than 45 days, it is automatically cancelled by the system and moved to Rejected.
• If an onboarding has been moved to Rejected due to inactivity, the company must restart the onboarding flow from the beginning before it can use the APIs.

Sandbox behavior

Sandbox behavior differs somewhat from production, because available test data varies between countries.

• In Norway, sandbox behavior is closer to production because a large set of test companies is available.
• In Denmark and Sweden, sandbox may allow repeated onboarding attempts for the same company because test data is more limited.
• Country-specific testing guidance is provided in the sections below.

Test data

Below is a selection of test data from our test environment that can be used as input when testing our APIs. The list below is not an exhaustive overview of all available test data. We use Tenor as the source for test data. Tenor is provided by the Norwegian Tax Administration and contains thousands of test companies that can be used for development and testing purposes.

All available test data can be found at: https://www.skatteetaten.no/testdata/

Testing signing

In most cases, signing in SANDBOX works with the standard Norwegian test credentials below:

• one-time password: otp
• password: qwer1234

How it normally works

By default, the signer’s SSN is prefilled to Signicat. Because of this, the signer is normally asked only for one-time password and password, and not for SSN.

Important note about shared test users

The pre-generated Norwegian test users are shared by everyone using Sandbox. This means they can occasionally become unavailable if someone enters the wrong password too many times.

If signing fails for this reason, create your own test user in Signicat instead: Create your own Norwegian test user

This avoids conflicts with shared users and is the recommended fallback if the standard flow does not work.

If the default credentials do not work

If signing does not work with the prefilled signer, Signicat may ask you to enter SSN manually.

In that case:

1. Enter the SSN for your own Signicat test user
2. Use:
   • one-time password: otp
   • password: qwer1234

Because this is your own generated test user, it should not conflict with other Sandbox users.

Recommendation

If you test Norway signing often, it is a good idea to create your own Signicat test user and keep the SSN available for reuse in later tests.

Note on Signing Combinations in the Test Environment

All company information except signing combinations is sourced from Tenor, allowing access to a large and realistic set of test companies.

However, signing combinations are currently provided by a separate data source with a limited set of predefined test companies. As a result, when a Tenor company is used in the test environment, it is internally mapped to one of a small number (approximately 10) of signing-combination test companies.

As a result, different test companies may therefore return identical signing combinations. This behavior is expected and does not indicate an error or incorrect company data. This mapping is only applicable in the test environment and exists to ensure consistent and predictable signing-combination behavior during development and testing.

There are two different ways to test onboarding in Denmark SANDBOX, depending on what you want to verify.

Test data

There are two types of test data available for Denmark in SANDBOX:

1. Reserved ZTL test scenarios
2. Integrated sandbox flow

Reserved ZTL test scenarios

These are special organization numbers set up by ZTL to always produce a specific onboarding outcome.

For these organization numbers, ZTL does not use the normal external sandbox integrations for company data, beneficial owners, signing combinations, and screening.

Instead, ZTL provides the test data directly in our own sandbox logic. This is done to make the result deterministic, so you can reliably test the onboarding lifecycle and reach the same final status every time.

With the normal Denmark sandbox flow, several parts of the onboarding depend on external test environments. Those environments have limited and sometimes inflexible test data, and they are not designed to guarantee that a given onboarding always ends in exactly the status you want.

The reserved ZTL test scenarios solve this by mocking the relevant onboarding data and screening outcome inside ZTL, so the result is stable and repeatable.

Integrated sandbox flow

This is the normal Denmark sandbox flow.

For these organization numbers, ZTL uses the external sandbox environments in the usual way:

• Company information is fetched from external test data sources
• Beneficial owners are fetched from external test data sources
• Signing combinations are fetched from external test data sources
• Screening is performed in the AML provider’s test environment

This means the onboarding is closer to the normal integrated flow, but it is also less predictable if your goal is to force a specific final status.

Testing signing

How you should test signing depends on which type of Denmark sandbox data you are using.

Reserved ZTL test scenarios

1. Start onboarding with country DK and one of the organization numbers above.
2. Fill in the onboarding as normal, but make sure to keep beneficial owners as is (do not edit, add, or remove them).
3. Complete signing with any available sandbox test user.
   • You do not need to create a specific signer identity for these organization numbers.
   • You can use any available sandbox signing method that works in your setup.

Integrated sandbox flow

1. Create a test MitID here: pp.mitid.dk/test-tool/frontend/#/create-identity
2. Use the name connected to the organization number you want to test.
3. Start onboarding with that organization number.
4. In the onboarding page, select the signing option shown.
5. Sign with the matching test MitID user.

Which should you use?

• Use 11111111, 22222222, and 33333333 when you want a predictable onboarding result.
• Use the integrated sandbox flow when you want to test the normal integrated sandbox flow against external test environments.

Test data

Below is a selection of test data from our sandbox environment that can be used when testing onboarding in Sweden.

Important

• Not all organization numbers have a signer that can be used for end-to-end signing tests.
• If the table shows —, the company can still be used for some onboarding testing, but not for a full signing flow with a matching signer identity.
• If you want to test the full onboarding flow including signing, choose an organization number that has a personal number and name listed.

Testing signing

To test the full onboarding flow in Sweden, including signing the agreement in SANDBOX, follow these steps:

1. Create a test BankID here: www.bankid.com/en/utvecklare/test/skaffa-testbankid
2. Use one of the personal numbers listed in the table above.
3. Start onboarding with the matching organization number.
4. In the onboarding process, select the signing option shown in the onboarding page.
5. Complete signing with the BankID test user that matches the personal number used when creating the test BankID.

Services for all bank-related information. Gives list of all banks ZTL supports, which products support each bank and bank-specific restrictions like max data length for fields.

A valid Consent is required to use the Accounts and Payments services. A consent has to be signed by a user to be valid, and is personal for that user and limited to bank services for the bank the consent was created with. A newly created consent is normally valid for 180 days, but note that it may be invalidated at any time. Consents created by V1 API are not compatible for V2 endpoints, and V2 consents can neither be used for V1 endpoints.

API for getting account information. We try to provide a failure enum when possible, you should expect us to add more values here continuously.

The banks make a VERY IMPORTANT distinction between if the user is present or not through the PSU-IP-Address and PSU-User-Agent headers. Numbers of account information calls without the user present may be restricted by banks to up to max 4 usages per day. As long as a user is present, there is no limits. Under no circumstances should the IP address of the user be sent if it can not be fetched from the actual user and browser using your system.

Banks may respond respond slow, and sometimes with errors if bank entries are retrieved in batches - therefore it's strongly recommend to spread account entries usages out over time. One easy way of doing this is to create a loop that runs often but checks any accounts that has not been updated since X hours ago.

Payroll V2 only supports NOK to NOK transactions within Norway. International payrolls (going to recipients outside Norway) should be handled as cross-border payments.

How it works

Payroll is similar to Payments, but with some simplicity to accommodate the end user. All salaries can be made in a single request. These salaries will accumulate to a single payment at the user's bank. The money will arrive in a client account with ZTL, where the salaries will be paid out to the recipients.

Each transaction in the payroll will have their own individual status and should be treated as individual payments. Until the money has left the user's account, they will effectively all share the same status. After being removed from the user's account, they will potentially have different statuses like InProgress, Completed, or Rejected.

If you are familiar with Payroll V1 you will see that the statuses are simplified to ultimately represent what is important.

Creating a payroll

A singular payroll can contain many recipients and the amount will be drawn from a single account. When creating the payroll, a payrollId will be returned, which needs to be saved.

We request that when a payroll is initiated and due date is today or tomorrow (if initiated after 16:00) that you give user a warning if balance is less than value of the payment. Reason for this warning is to remind those who are lacking funds that they do not have funds and to avoid the salary being delayed or in worst case cancelled.

Approving a payroll

When a payroll has been created, it has only been initiated but not approved. The user then needs to approve this by performing an SCA with the user's bank. The payrollId is sent in the request body, created in the previous step, and a link for approving the SCA will be in the response body.

Getting the status of a payroll

Use the payrollId in the path parameter to get the status of a payroll.

More info on CustomerActionRequired will come.

Note that the status InProgress can mean different things, including

1. The payroll has been approved
2. The amount has been deducted from the account and arrived in the ZTL client account
3. The amount has been deducted from the ZTL client account, but not yet arrived at the recipient

Cancelling a payroll

Canceling a payroll can only be done in a non-final state, i.e. Unsigned, InProgress, or CustomerActionRequired, but also only if the money has not been drawn out of the user's account, which can occur in the InProgress state until it has been paid out to the recipients.

If the payroll has been approved, cancelling a payroll requires an SCA like when approving. This is usually the case, but is up to the banks to decide when it requires an SCA or not.

Normally payments are initiated one at a time. The payment status is immediately returned, in most cases the payment needs to be signed before it will be executed. There are different endpoints for domestic and cross-border payments, resulting in a payment reference including an unsigned bank transaction to ZTL client account. The approval/signing endpoint starts signing process of a list of unsigned payments, where the user has to perform SCA before the payment execution are accepted by the bank. If an approval for some reason is rejected, it's possible to start a new approval with the same payment(s).

Bulk payment is a special case implement to be able to support a few banks which does not support single payment/approve functionality. The supported products for each bank is available in bank services.