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.

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 a user must do to use the ZTL API is to onboard its company.

The Version 2 of onboarding API are only implemented for Sweden and Denmark. For Norwegian company onboarding, please use the version 1 of the Onboarding API.

Things to consider in your implementation:

• in PRODUCTION each company should be allowed to start an onboarding only once until it reaches a final status, which is either "Approved" or "Rejected"
• SANDBOX allows to start several onboardings per company for testing purposes and due to the limited test data, see the list below

Testing signing in Sweden

To test the whole onboarding flow including signing the agreement in SANDBOX you need to follow these steps:

• create a test BankID here: https://www.bankid.com/en/utvecklare/test/skaffa-testbankid using one of the personal numbers provided with the organization numbers in the list below
• use the same organization number to start an onboarding
• in the onboarding process, when choosing a signing combination pick the combination with a single person matching the name of the personal number used for creation of test BankID and complete the signing process

Test organization numbers:

• 5560572850
• 5565002465
• 8430025331
• 5569030264
• 6805029268 (personal number 196805029268, Efternamn2401, Petra)
• 5564779444 (personal number 196805029268, Efternamn2401, Petra)
• 5569994600 (personal number 197904182396, Efternamn2993, Kuno)
• 9168937861
• 5590506506 (personal number 196501022773, Pinoz Harem)
• 5565002465
• 5164010133
• 5590672613
• 8110022392 (personal number 198110022392, Efternamn3672, Ebbe)
• 9697715770
• 5564866803 (personal number 196805029268, Efternamn2401, Petra)
• 5564881422 (personal number 198110022392, Efternamn3672, Ebbe)

Testing signing in Denmark

To test the whole onboarding flow including signing the agreement in SANDBOX you need to follow these steps:

• create a test MitID here: https://pp.mitid.dk/test-tool/frontend/#/create-identity using one of the names provided with the organization numbers in the list below (rest of the data can be autofilled)
• use the same organization number to start an onboarding
• in the onboarding process, when choosing a signing combination pick the combination with a single person matching the name used for creation of test MitID and complete the signing process

Test organization numbers:

• 23456788 (name: Christian Svanholm-Nielsen)
• 41773863 (name: Sven Holst)
• 12345674 (name: Tage Olsen)
• 38724991 (name: Bettina Christiansen)

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.

Restrictions

Sandbox environment does not work at the payroll provider. Only testing in production environment is possible

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 InPogress 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.