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:

We refer to bank's sandbox documentation for updated info about valid test data.

While some banks above are not verified, some functionality works. Depending on your use-case you can test and see. Account services usually work for all of them.

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.

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.

Services related to companies. Retrieve information about onboarded companies, enable/disable compay and list supported company types.

FX can either be used with or without bank integration. For bank integration, please see Flow for Currency CrossBorder transaction with bank integration

The partner is responsible to handle the domestic bank integration, or present the required payment instructions for domestic transaction to the user.