openapi: 3.1.0 info: version: v2.0 title: ZTL OpenAPI description: >+ ****Ztl Payment solution api You can download the full spec by clicking on the button above, or at https://docs.ztlpay.io/ztl-api-v2.full.yaml # General 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 ## API usage 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. ## Headers * 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 handling 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. ```json { "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. ```json [ { "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. ```json { "ztlRequestId": "ENUM", "message": "The underlying reason for the error" } ``` ## Environments The following is a list of environments available when developing against or using our API: | Resource | Sandbox | Prod | |-------------------------|------------------------------------------------------------------|--------------------------------------------------| | API Endpoint | [https://api.sandbox.ztlpay-test.io](https://api.sandbox.ztlpay-test.io) | [https://api.ztlpay.io](https://api.ztlpay.io) | | Authentication endpoint | [https://oidc.sandbox.ztlpay-test.io](https://oidc.sandbox.ztlpay-test.io) | [https://oidc.ztlpay.io](https://oidc.ztlpay.io) | | Onboarding endpoint | [https://welcome.sandbox.ztlpay-test.io/onboarding](https://welcome.sandbox.ztlpay-test.io/onboarding) | [https://welcome.ztlpay.io/onboarding](https://welcome.ztlpay.io/onboarding) | ## Testing Here is a table listing the banks available for use in Sandbox. While other banks may function, they are not officially supported. | Bank | Country | BIC | organizationNumber | userId | Notes | |-----------|---------|----------|-------------------------|-------------------------|-----------------------------------------------------------| | DNB | Norway | DNBANOKK | No requirements | TX99999 or TX99998 | Account 12095221031 and 12024833710 requires 2 approvers | | Nordea | Norway | NDEANOKK | Must be 9 digits | Any valid norwegian SSN | | | Nordea | Sweden | NDEASESS | Must be 10 or 12 digits | Non empty value | Issues showing completed status on payments. | | Swedbank | Sweden | SANDSESS | No requirements | Any valid Swedish SSN | Be aware that bic in Sandbox and Production is different. | | Nordea | Denmark | NDEADKKK | Must be 8 digits | Non empty value | | | Mock bank | Denmark | ZTLXDKXX | No requirements | Non empty value | See further details below | ### 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. | Account number | Status | Notes | |----------------|--------------------------------------------------|------------------------------------------------------------------------| | 99990000000001 | Rejected | | | 99990000000002 | CustomerActionRequired / PartlySigned | Requires two different user approvals to change status | | 99990000000003 | CustomerActionRequired / SmsConfirmationRequired | Changes status after approximately 1 hour | | 99990000000004 | CustomerActionRequired / InsufficientFunds | Becomes `InsufficientFunds` on `dueDate`, and `Rejected` the day after | | 99990000000005 | InProgress | Moves to `InProgress` without approval | | 99990000000011 | N/A | Payment approval will be Rejected | | 99990000000012 | N/A | Payment approval will be Cancelled | tags: - name: Authentication description: > 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. Sandbox uses the new OIDC issuer only. Production supports both the new and legacy OIDC issuers during the migration period. 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. x-displayName: Authentication - name: Onboarding description: > The first step before using the ZTL API is to onboard the company. ### Onboarding lifecycle Onboarding status 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. | Status | Meaning | |:-------------------------|:---------------------------------------------------------------------------------------------------------------------| | `Created` | The onboarding has been started, but the user has not yet submitted the onboarding form for signing. | | `AwaitingCustomerAction` | The onboarding form has been submitted, and one or more required signers still need to sign the agreement. | | `Processing` | All required signers have signed, and ZTL is processing the onboarding. This is typically a very short-lived status. | | `ManualHandling` | The onboarding requires manual review by ZTL before it can continue to a final status. | | `Accepted` | The onboarding has been completed successfully, and the company can use the APIs. | | `Rejected` | The onboarding has been rejected, cancelled, or expired and cannot continue further. | ### 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. | Existing state for the organization number | Result when initiating onboarding | |:-----------------------------------------------------------------------------------|:------------------------------------------------------------------------------------------------| | No existing onboarding and no onboarded company exists | A new onboarding is created | | Existing onboarding in `Created` | The existing onboarding ID and onboarding URL are returned instead of creating a new onboarding | | Existing onboarding in `AwaitingCustomerAction`, `Processing`, or `ManualHandling` | A new onboarding cannot be started | | Existing onboarded company already exists | A new onboarding cannot be started in `PRODUCTION` | | Existing onboarding in `Rejected` | A new onboarding can be started | 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`, `Denmark`, and `Sweden`, `SANDBOX` supports both reserved ZTL test scenarios and a normal integrated sandbox flow. - Country-specific testing guidance is provided in the sections below. ### Reserved ZTL test scenarios Reserved ZTL test scenarios are special organization numbers set up by ZTL to always produce a specific onboarding outcome. The country-specific organization numbers differ, and are listed in each country chapter below. For reserved ZTL test scenarios, ZTL does **not** use the normal sandbox or external 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. These reserved organization numbers can also be used repeatedly in `SANDBOX`, even if a company or previous successful onboarding already exists for your partner integration. ## Testing in Norway There are two different ways to test onboarding in Norway `SANDBOX`, depending on what you want to verify. ### Test data There are two types of test data available for Norway in `SANDBOX`: 1. Reserved ZTL test scenarios 2. Integrated sandbox flow #### Reserved ZTL test scenarios The organization numbers below use the reserved ZTL test scenarios described in the general sandbox testing section above. | Organization number | Expected status after signing is completed | |:--------------------|:-------------------------------------------| | `111111111` | `Accepted` | | `222222222` | `ManualHandling` | | `333333333` | `Rejected` | #### Integrated sandbox flow This is the normal Norway sandbox flow. 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/ | Organization number | Organization name | |:--------------------|:------------------| | `312701103` | LEKKER GILD STRUTS UAB | | `312246538` | OPPRETT SKAMFULL STRUTS AB | | `312587629` | NÆR HÅRSÅR STRUTS LTD | | `310211036` | POMPØS KNUSLETE LEOPARD ASA | | `310223719` | FREDELIG TYPISK GIRAFF SPAREBANK | | `313513408` | FALSK ØDE TIGER AS | | `314208641` | EKSTRA KLOK TIGER AS | | `210129812` | SPETTETE INNSIKTSFULL HUND DA | | `314270320` | TRÅDLØS MATT TIGER AS | | `313513580` | OVERSIGHT HELLIG TIGER AS | | `310163449` | SENTRAL UKLAR PUMA | | `310274682` | HEL VERD NISE PENSJONSKASSE | | `310219622` | STOLT UMUSIKALSK ALLIGATOR | ### Testing signing How you should test signing depends on which type of Norway sandbox data you are using. #### Reserved ZTL test scenarios 1. Start onboarding with country `NO` 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 the signing option shown in the onboarding flow. #### Integrated sandbox flow 1. Start onboarding with one of the Tenor organization numbers listed above or another valid Tenor test company. 2. In the onboarding process, select the signing option shown in the onboarding page. 3. Complete signing in Signicat. In most cases, signing in Norway `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](https://developer.signicat.com/identity-methods/nbid/test/#order-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. #### Which should you use? - Use `111111111`, `222222222`, and `333333333` when you want a predictable onboarding result. - Use the integrated sandbox flow when you want to test the normal sandbox integrations with Tenor-based company data. >**Note on Signing Combinations in the Integrated Norway Sandbox Flow**

In the integrated Norway sandbox flow, 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. ## Testing in Denmark 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 The organization numbers below use the reserved ZTL test scenarios described in the general sandbox testing section above. | Organization number | Expected status after signing is completed | |:---------------------|:--------------------------------------------| | `11111111` | `Accepted` | | `22222222` | `ManualHandling` | | `33333333` | `Rejected` | 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. This is why the reserved ZTL test scenarios are useful when you want a stable and repeatable result. #### 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. | Organization number | Person (Name) | |:---------------------|:---------------------------| | `23456788` | Christian Svanholm-Nielsen | | `41773863` | Sven Holst | | `12345674` | Tage Olsen | | `38724991` | Bettina Christiansen | ### 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](https://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. ## Testing in Sweden There are two different ways to test onboarding in Sweden `SANDBOX`, depending on what you want to verify. ### Test data There are two types of test data available for Sweden in `SANDBOX`: 1. Reserved ZTL test scenarios 2. Integrated sandbox flow #### Reserved ZTL test scenarios The organization numbers below use the reserved ZTL test scenarios described in the general sandbox testing section above. | Organization number | Expected status after signing is completed | |:---------------------|:--------------------------------------------| | `1111111111` | `Accepted` | | `2222222222` | `ManualHandling` | | `3333333333` | `Rejected` | #### Integrated sandbox flow This is the normal Sweden sandbox flow. Below is a selection of test data from our sandbox environment that can be used when testing onboarding in Sweden. | Organization number | Person (Personal No / Name) | |:---------------------|:-----------------------------------| | `5560572850` | — | | `5565002465` | — | | `8430025331` | — | | `5569030264` | — | | `6805029268` | 196805029268 – Petra Efternamn2401 | | `5564779444` | 196805029268 – Petra Efternamn2401 | | `5569994600` | 197904182396 – Kuno Efternamn2993 | | `9168937861` | — | | `5590506506` | 196501022773 – Pinoz Harem | | `5164010133` | — | | `5590672613` | — | | `8110022392` | 198110022392 – Ebbe Efternamn3672 | | `9697715770` | — | | `5564866803` | 196805029268 – Petra Efternamn2401 | | `5564881422` | 198110022392 – Ebbe Efternamn3672 | **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 How you should test signing depends on which type of Sweden sandbox data you are using. #### Reserved ZTL test scenarios 1. Start onboarding with country `SE` 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 the signing option shown in the onboarding flow. #### Integrated sandbox flow 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](https://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. #### Which should you use? - Use `1111111111`, `2222222222`, and `3333333333` 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. x-displayName: Onboarding - name: Banks description: >- 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. x-displayName: Banks - name: Consent description: > 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. x-displayName: Consent - name: Accounts description: > 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. x-displayName: Accounts - name: Payroll description: > Payroll V2 only supports **NOK to NOK transactions within Norway**. International payrolls (going to recipients outside Norway) should be handled as [cross-border payments](#tag/Payments/operation/cross-border). ### 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. | Status | Is in a final state | Short description | |--------------------------|---------------------|------------------------------------------------------------------------------| | `Unsigned` | No | It has been created, but the user's bank requires approval before accepting | | `InProgress` | No | The user's bank has approved the payment and is on its way to the recipients | | `CustomerActionRequired` | No | Requires further action from the user | | `Completed` | Yes | The end user has received the payment | | `Rejected` | Yes | Something did not go as expected, and the payroll has been rejected | | `Cancelled` | Yes | The user has chosen to cancel the payroll | 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. ![](./images/payroll-v2-sequence.mermaid.svg) x-displayName: Payroll - name: Payments description: > 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. ![](./images/payments-v2-flow.mermaid.svg) x-displayName: Payments - name: Companies description: >- Services related to companies. Retrieve information about onboarded companies, enable/disable compay and list supported company types. x-displayName: Companies - name: FX Payments description: > FX can either be used with or without bank integration. For bank integration, please see Flow for cross-border payment with bank integration ## FX payment without domestic bank integration flow The partner is responsible to handle the domestic bank integration, or present the required payment instructions for domestic transaction to the user. ![](./images/payments-fx-without-bankintegration.mermaid.svg) x-displayName: FX Payments - name: Currencies description: All currencies supported x-displayName: Currencies - name: Country description: >- Helper methods for cross-border payment support. This API can be used to give user interface for bank account format input, supported currencies and additional payment remittance information requirements. x-displayName: Country paths: /v2/connect/token: servers: - url: https://oidc.ztlpay.io description: New OIDC Production environment - url: https://oidc.sandbox.ztlpay-test.io description: New OIDC Sandbox environment post: summary: Fetch an access token from the new OIDC issuer description: > Use this endpoint for sandbox and production. Sandbox supports the new OIDC issuer only. security: [] operationId: fetchAccessTokenNewIssuer tags: - Authentication x-codeSamples: - lang: json label: Sandbox payload source: | { "client_id": "YOUR_CLIENT_ID", "client_secret": "YOUR_CLIENT_SECRET", "grant_type": "client_credentials", "scope": "api://ac0d1aea-5e3a-463f-9dd1-194898ee5820/.default" } - lang: json label: Production payload source: | { "client_id": "YOUR_CLIENT_ID", "client_secret": "YOUR_CLIENT_SECRET", "grant_type": "client_credentials", "scope": "api://1f115cad-5576-4db9-a7f9-8921c47a86e4/.default" } requestBody: content: application/json: schema: type: object required: - client_id - client_secret - grant_type - scope properties: client_id: type: string description: Client id as provided by ZTL client_secret: type: string description: Client secret as provided by ZTL grant_type: type: string description: Should be 'client_credentials' scope: type: string description: > Use the scope for the target environment: - Sandbox: `api://ac0d1aea-5e3a-463f-9dd1-194898ee5820/.default` - Production: `api://1f115cad-5576-4db9-a7f9-8921c47a86e4/.default` responses: '200': description: Access token headers: {} content: application/json: schema: type: object properties: token_type: description: Token type type: string example: Bearer expires_in: description: Lifetime in seconds of the access token type: integer example: 3599 ext_expires_in: description: Extended lifetime in seconds of the access token type: integer example: 3599 access_token: description: token type: string example: jwt example: token_type: Bearer expires_in: 3599 ext_expires_in: 3599 access_token: jwt '401': description: Token expired and needs to be renewed content: application/json: schema: {} /connect/token: servers: - url: https://oidc.ztlpay.io description: Legacy OIDC Production environment post: summary: Fetch an access token from the legacy OIDC issuer (LEGACY) description: > **__This legacy production endpoint remains available during the migration period. Sandbox supports the new OIDC issuer only.__** security: [] operationId: fetchAccessTokenLegacyIssuer tags: - Authentication requestBody: content: application/x-www-form-urlencoded: schema: type: object required: - client_id - client_secret - grant_type - scope properties: client_id: type: string description: Client id as provided by ZTL client_secret: type: string description: Client secret as provided by ZTL grant_type: type: string description: Should be 'client_credentials' scope: type: string description: Should be 'payments' example: client_id: YOUR_CLIENT_ID client_secret: YOUR_CLIENT_SECRET grant_type: client_credentials scope: payments responses: '200': description: Access token headers: {} content: application/json: schema: type: object properties: access_token: description: token type: string example: >- eyJhbGciOiJSUzI1NiIsImtpZCI6IkE1NEZCQjFGRjgzRTZFRUFEQUI1MTg4QTJBMkVGRDhGNTUzMEUzNDkiLCJ0eXAiOiJKV1QiLCJ4NXQiOiJwVS03SF9nLWJ1cmF0UmlLS2k3OWoxVXc0MGsifQ.eyJuYmYiOjE1NjI4MzE1OTIsImV4cCI6MTU2MjgzNTE5MiwiaXNzIjoiaHR0cHM6Ly9vaWRjLnp0bC5zdGFjY2Zsb3cubmV0IiwiYXVkIjpbImh0dHBzOi8vb2lkYy56dGwuc3RhY2NmbG93Lm5ldC9yZXNvdXJjZXMiLCJ6dGwtYXBpIiwicG9ydGFsLWFwaSJdLCJjbGllbnRfaWQiOiJkZXZjbGllbnQiLCJzY29wZSI6WyJwYXltZW50cyIsInBvcnRhbC1hcGkiXX0.dJuDJNTsSBhQ_xmN3ruqbBZvJdyn2nUkUW3NEwbgXw_l-UA3_XRmtp16rWWdhMLbh-D_HywwG2a0h-MK2tX17C-ggsfp_pDxj8iy8aLleI3dY1qt0VkQY8rOw5_YtWa40HWwIBK9Ll8MqovwBK4lg9Pkq_KLGdkoz87n63QezS5u0JeWYJJnHFuY5ojX_M5szAdSYoVYOyvL0tr30ynxb3joglKrVWlkeawRZztRV4chFN00tlv_Tn54vDYOyDPtBWK6JpMVqhHla8a5JnslJu5dUP82qtgms_lFYOiR1oD2jaa-t0QTE6MVwspG3kwQBSSSZawe-9G4yEBg-nFSGg expires_in: description: Lifetime in seconds of the access token type: integer example: 3600 token_type: description: Lifetime in seconds of the access token type: string example: Bearer scope: type: string description: Granted scope, will always be 'payments' example: payments '401': description: Token expired and needs to be renewed content: application/json: schema: {} /onboarding: servers: - url: https://welcome.ztlpay.io description: Production environment - url: https://welcome.sandbox.ztlpay-test.io description: Sandbox environment for testing post: tags: - Onboarding summary: Initiate onboarding operationId: onboardingInitiation parameters: - $ref: '#/components/parameters/AuthorizationJwtHeader' requestBody: content: application/json: schema: type: object required: - country - organizationNumber properties: country: type: string description: Countrycode for the company being onboarded example: SE organizationNumber: type: string description: Organization number for the company being onboarding example: '5569994600' redirectUrl: type: string description: >- The user is redirected to this URL after the onboarding process has completed as well as if they cancel the onboarding process. Normally this will be the URL of the ERP the end-user originated from. Must start with a protocol (HTTP/HTTPS). example: https://example.org responses: '200': description: Onboarding started successfully headers: ztl-request-id: $ref: '#/components/headers/ztl-request-id' content: application/json: schema: type: object required: - id - url properties: id: type: string description: Id for the started onboarding, used for status format: uuid example: 941d1877-73b8-45bf-8c65-47233b58926a url: type: string format: url example: >- https://welcome.sandbox.ztlpay-test.io/onboarding/941d1877-73b8-45bf-8c65-47233b58926a '400': $ref: '#/components/responses/GeneralError' description: Bad request '403': $ref: '#/components/responses/GeneralError' description: Forbidden '404': description: Not found '409': description: Conflict headers: ztl-request-id: $ref: '#/components/headers/ztl-request-id' content: application/json: schema: type: object required: - ztlRequestId - failure - message properties: failure: type: string const: COMPANY_ALREADY_EXISTS ztlRequestId: type: string format: uuid description: >- Unique RequestId, please provide this Id in case of support requests example: d188e4f9-91fa-4fd8-98be-e725dc44090a message: type: string description: The underlying reason for the error example: >- A company with organization number 5569994600 already exists. Initiation of new onboardings is not permitted. additionalInformation: type: object nullable: true description: Additional context related to the error properties: onboardingId: type: string format: uuid nullable: true description: > The ID of the onboarding used to onboard the existing company. This onboarding is always in status `Accepted` and cannot be modified. Note that `onboardingId` (and `additionalInformation`) will be null if the company was originally onboarded through Onboarding V1. example: 9256411a-5c80-40e5-b50c-768dbca443af '500': $ref: '#/components/responses/GeneralError' description: Internal server error '503': $ref: '#/components/responses/GeneralError' description: Service unavailable /onboarding/{onboardingId}/status: servers: - url: https://welcome.ztlpay.io description: Production environment - url: https://welcome.sandbox.ztlpay-test.io description: Sandbox environment for testing get: tags: - Onboarding summary: Get onboarding status operationId: onboardingStatus parameters: - in: path name: onboardingId schema: type: string format: uuid required: true - $ref: '#/components/parameters/AuthorizationJwtHeader' responses: '200': description: Onboarding status fetched successfully headers: ztl-request-id: $ref: '#/components/headers/ztl-request-id' content: application/json: schema: type: object required: - status properties: status: type: string description: ManualHandling is only available for Norway. enum: - Created - AwaitingCustomerAction - Processing - ManualHandling - Accepted - Rejected signingStatus: nullable: true type: object required: - onboardingSigningStatus properties: onboardingSigningStatus: type: string enum: - Signed - PartiallySigned - Unsigned signers: type: array items: type: object required: - name - status properties: name: type: string personalNumber: type: string nullable: true status: type: string enum: - Signed - Unsigned signingUrl: type: string nullable: true documentSignature: nullable: true type: object properties: signatureMethod: type: string nullable: true fullName: type: string nullable: true firstName: type: string nullable: true lastName: type: string nullable: true middleName: type: string nullable: true signedTime: type: string nullable: true dateOfBirth: type: string nullable: true examples: partiallySignedTwoSigners: summary: Partially signed onboarding with two signers value: status: AwaitingCustomerAction signingStatus: onboardingSigningStatus: PartiallySigned signers: - name: John Doe personalNumber: '01019012345' status: Signed documentSignature: signatureMethod: BANKID_NO fullName: John Doe firstName: John lastName: Doe middleName: null signedTime: '2026-01-03T22:57:23' dateOfBirth: '1990-01-01' - name: Jane Smith personalNumber: null status: Unsigned signingUrl: https://www.google.com documentSignature: null '400': $ref: '#/components/responses/GeneralError' description: Bad request '403': $ref: '#/components/responses/GeneralError' description: Forbidden '404': description: Not found '500': $ref: '#/components/responses/GeneralError' description: Internal server error '503': $ref: '#/components/responses/GeneralError' description: Service unavailable /onboarding/status: servers: - url: https://welcome.ztlpay.io description: Production environment - url: https://welcome.sandbox.ztlpay-test.io description: Sandbox environment for testing get: tags: - Onboarding summary: Get onboarding status by organization number description: >- Returns the onboarding status based on country and organization number. If no onboarding exists but the company already exists, the response returns `Accepted`. This can happen if the company was onboarded through the deprecated Onboarding V1 flow. operationId: onboardingStatusByOrganizationNumber parameters: - in: query name: country schema: type: string enum: - 'NO' - SE - DK required: true - in: query name: organizationNumber schema: type: string required: true - $ref: '#/components/parameters/AuthorizationJwtHeader' responses: '200': description: Onboarding status fetched successfully headers: ztl-request-id: $ref: '#/components/headers/ztl-request-id' content: application/json: schema: type: object required: - status properties: status: type: string description: ManualHandling is only available for Norway. enum: - Created - AwaitingCustomerAction - Processing - ManualHandling - Accepted - Rejected signingStatus: nullable: true type: object required: - onboardingSigningStatus properties: onboardingSigningStatus: type: string enum: - Signed - PartiallySigned - Unsigned signers: type: array items: type: object required: - name - status properties: name: type: string personalNumber: type: string nullable: true status: type: string enum: - Signed - Unsigned signingUrl: type: string nullable: true documentSignature: nullable: true type: object properties: signatureMethod: type: string nullable: true fullName: type: string nullable: true firstName: type: string nullable: true lastName: type: string nullable: true middleName: type: string nullable: true signedTime: type: string nullable: true dateOfBirth: type: string nullable: true examples: existingCompanyWithoutOnboarding: summary: Company exists without onboarding value: status: Accepted existingOnboarding: summary: Existing onboarding with unsigned signers value: status: AwaitingCustomerAction signingStatus: onboardingSigningStatus: Unsigned signers: - name: John Doe personalNumber: '01019012345' status: Unsigned signingUrl: https://www.google.com documentSignature: null '400': $ref: '#/components/responses/GeneralError' description: Bad request '403': $ref: '#/components/responses/GeneralError' description: Forbidden '404': description: Not found '500': $ref: '#/components/responses/GeneralError' description: Internal server error '503': $ref: '#/components/responses/GeneralError' description: Service unavailable /onboarding/registration: servers: - url: https://welcome.ztlpay.io description: Production environment - url: https://welcome.sandbox.ztlpay-test.io description: Sandbox environment for testing post: tags: - Onboarding summary: Register company (AIS only) description: >- This API is for partners using AIS only in Norway. Its not be used without prior agreement. Simple registration for companies. Provides access exclusively to account information services. Supported countries are NO, SE and DK. operationId: onboardingRegistration parameters: - $ref: '#/components/parameters/AuthorizationJwtHeader' requestBody: content: application/json: schema: type: object required: - country - organizationNumber properties: country: type: string description: Country code for the company being registered example: SE organizationNumber: type: string description: Organization number for the company being registered example: '5569994600' responses: '201': description: Company registered successfully headers: ztl-request-id: $ref: '#/components/headers/ztl-request-id' '400': $ref: '#/components/responses/GeneralError' description: Bad request '500': $ref: '#/components/responses/GeneralError' description: Internal server error '503': $ref: '#/components/responses/GeneralError' description: Service unavailable /onboarding/enable-international-payments: servers: - url: https://welcome.ztlpay.io description: Production environment - url: https://welcome.sandbox.ztlpay-test.io description: Sandbox environment for testing post: tags: - Onboarding summary: Initiate enablement of international payments description: >- Starts the enablement flow for international payments for an existing company and returns the frontend URL for the form. operationId: enableInternationalPaymentsInitiation parameters: - $ref: '#/components/parameters/AuthorizationJwtHeader' requestBody: content: application/json: schema: type: object required: - country - organizationNumber properties: country: type: string description: Country code for the company example: SE organizationNumber: type: string description: Organization number for the company example: '5569994600' redirectUrl: type: string description: >- The user is redirected to this URL after the enablement flow has completed as well as if they cancel the process. Must start with a protocol (HTTP/HTTPS). example: https://example.org responses: '200': description: Enablement flow started successfully headers: ztl-request-id: $ref: '#/components/headers/ztl-request-id' content: application/json: schema: type: object required: - url properties: url: type: string format: url description: URL for the international payments enablement form example: >- https://welcome.sandbox.ztlpay-test.io/onboarding/companies/941d1877-73b8-45bf-8c65-47233b58926a/enable-international-payments/company-information '400': $ref: '#/components/responses/GeneralError' description: Bad request '403': $ref: '#/components/responses/GeneralError' description: Forbidden '404': description: Not found '500': $ref: '#/components/responses/GeneralError' description: Internal server error '503': $ref: '#/components/responses/GeneralError' description: Service unavailable /onboarding/{onboardingId}/cancel: servers: - url: https://welcome.ztlpay.io description: Production environment - url: https://welcome.sandbox.ztlpay-test.io description: Sandbox environment for testing post: tags: - Onboarding summary: Cancel onboarding operationId: onboardingCancel parameters: - in: path name: onboardingId schema: type: string format: uuid required: true - $ref: '#/components/parameters/AuthorizationJwtHeader' responses: '204': description: Onboarding cancelled successfully headers: ztl-request-id: $ref: '#/components/headers/ztl-request-id' '400': $ref: '#/components/responses/GeneralError' description: Bad request '500': $ref: '#/components/responses/GeneralError' description: Internal server error '503': $ref: '#/components/responses/GeneralError' description: Service unavailable /api/v2/banks/{countryCode}/supported: servers: - url: https://api.ztlpay.io description: Production environment - url: https://api.sandbox.ztlpay-test.io description: Sandbox environment for testing get: tags: - Banks summary: Supported banks description: >- List of supported banks, with known constraints. Due to variations in the PSD2 APIs of the different banks, initiating a payment with certain banks may be subject to some limitations operationId: getSupportedBanksByCountryCode parameters: - name: countryCode in: path description: Country code, ISO-3166 required: true example: 'NO' schema: type: string format: ISO-3166 responses: '200': description: Successfully retrieved details of supported banks. content: application/json: schema: type: array items: type: object required: - bic - countryCode - name - supportedProducts properties: bic: type: string description: Bank BIC code, 8 digits example: DNBANOKK constraints: $ref: '#/components/schemas/BankConstraint' description: >- Bank constraints on top level. Present on banks without branches, and if constraints are the same for all branches. If the constraints are different, constraints will be contained within each branch in the branches list. countryCode: type: string example: 'NO' name: type: string description: Bank name example: DNB BANK ASA platform: type: string description: >- Platform the PSD2 solution is operating on (e.g. EVRY in Norway, SDC). Included if we have this in our internal system example: EVRY bankAlliance: type: string description: >- Alliance of the bank, Included if we have this in our internal system example: SPAREBANK_1 supportedProducts: type: array items: type: string enum: - PAYMENT_DOMESTIC - PAYMENT_INTERNATIONAL - PAYROLL - ACCOUNT_SERVICE - PAYMENT_BULK example: PAYMENT_DOMESTIC branches: type: array items: type: object required: - name - branch properties: name: type: string example: District description: Name of the branch branch: type: string example: DISTRICT description: >- The branch name that should be sent to us when creating consent constraints: $ref: '#/components/schemas/BankConstraint' description: >- Constraints applicable to this specific branch. Contained only if constraints are different for each branch. description: A supported bank with constraints and branches '400': $ref: '#/components/responses/GeneralError' description: Bad request security: - Authorization: - payments /api/v2/consents: servers: - url: https://api.ztlpay.io description: Production environment - url: https://api.sandbox.ztlpay-test.io description: Sandbox environment for testing post: tags: - Consent description: > Create consent and starts authentication process automatically (SCA details is available in response body). For banks having different branches, please refer to the banks api for available branches. Note that the existing consents from V1 are not compatible for V2 endpoints, so all users needs to create new consent before using V2 endpoints. V2 consents can neither be used for V1 endpoints. summary: Create consent operationId: createConsentV2 parameters: - $ref: '#/components/parameters/PSU-IP-Address-Mandatory' - $ref: '#/components/parameters/PSU-User-Agent-Mandatory' requestBody: content: application/json: schema: type: object required: - userId - bic - callbackUrl - organizationNumber properties: userId: type: string description: >- The userId of the account owner providing consent. Different banks use different userId schema, Could be SSN or a userId provided by the bank. bic: type: string description: >- The bank's international code/address. Also know as Swift code. example: ESSESESS callbackUrl: type: string description: Sca callback url for Redirect authentication example: https://www.google.com organizationNumber: type: string description: The organization number example: '1234567890' preferredScaMethod: type: string enum: - Qr - Redirect description: > The preferred way to perform authorization. There is no guarantee that bank supports the preferred method. * `Qr` Used with bank app to scan image. * `Redirect` Redirect link to redirect authorization flow. bankBranch: type: string description: >- Which branch of the bank if multiple. Can be fetched from supported banks endpoint. responses: '200': description: Successfully created consent headers: ztl-request-id: $ref: '#/components/headers/ztl-request-id' content: application/json: schema: type: object required: - id - status properties: id: type: string format: uuid description: >- An ID that will be used to identify the consent. Used in all AIS and PIS calls. example: B44E9297-934D-4975-8951-7843B16DF63F status: $ref: '#/components/schemas/consentStatus' sca: $ref: '#/components/schemas/Sca' '400': description: Bad Request headers: ztl-request-id: $ref: '#/components/headers/ztl-request-id' content: application/json: schema: type: object required: - ztlRequestId - message properties: failure: type: string enum: - INVALID_USER_ID - INVALID_ORGANIZATION_NUMBER - INVALID_BIC - UNKNOWN_CUSTOMER - AUTHENTICATION_TEMPORARY_UNAVAILABLE description: > * `INVALID_USER_ID` Wrong userId * `INVALID_ORGANIZATION_NUMBER` Wrong Organization Number * `INVALID_BIC` Unsupported Bic * `UNKNOWN_CUSTOMER` Customer does not have an account in the bank, or must specify bankBranch * `AUTHENTICATION_TEMPORARY_UNAVAILABLE` Authentication service is temporary unavailable, most likely due to user already has started another concurrent authentication process ztlRequestId: type: string format: uuid description: >- Unique RequestId, please provide this Id in case of support requests example: 3a797348-ef0c-4f52-b821-fdfcdb98c4d9 message: type: string description: The underlying reason for the error example: Invalid account '403': $ref: '#/components/responses/GeneralError' description: Forbidden '409': $ref: '#/components/responses/GeneralError' description: Conflict '500': $ref: '#/components/responses/GeneralError' description: Internal server error '503': $ref: '#/components/responses/GeneralError' description: Service unavailable security: - Authorization: - payments get: tags: - Consent summary: Consent status operationId: consentStatusV2 parameters: - $ref: '#/components/parameters/consent-id' - $ref: '#/components/parameters/PSU-IP-Address-Optional' - $ref: '#/components/parameters/PSU-User-Agent-Optional' responses: '200': description: Consent status content: application/json: schema: type: object required: - id - status properties: id: type: string format: uuid description: >- An ID that will be used to identify the consent. Used in all AIS and PIS calls. example: B44E9297-934D-4975-8951-7843B16DF63F status: $ref: '#/components/schemas/consentStatus' sca: $ref: '#/components/schemas/Sca' validUntil: type: string format: date example: '2022-01-01' '400': $ref: '#/components/responses/GeneralError' description: Bad Request '403': $ref: '#/components/responses/GeneralError' description: Forbidden '404': $ref: '#/components/responses/GeneralError' description: Not found '409': $ref: '#/components/responses/GeneralError' description: Conflict '500': $ref: '#/components/responses/GeneralError' description: Internal server error '503': $ref: '#/components/responses/GeneralError' description: Service unavailable security: - Authorization: - payments delete: tags: - Consent summary: Revoke consent operationId: revokeConsentV2 parameters: - $ref: '#/components/parameters/consent-id' - $ref: '#/components/parameters/PSU-IP-Address-Mandatory' - $ref: '#/components/parameters/PSU-User-Agent-Mandatory' responses: '204': description: Consent successfully revoked. No content is returned. '400': $ref: '#/components/responses/GeneralError' description: Bad Request '403': $ref: '#/components/responses/GeneralError' description: Forbidden '404': $ref: '#/components/responses/GeneralError' description: Not found '409': $ref: '#/components/responses/GeneralError' description: Conflict '500': $ref: '#/components/responses/GeneralError' description: Internal server error '503': $ref: '#/components/responses/GeneralError' description: Service unavailable security: - Authorization: - payments /api/v2/accounts: servers: - url: https://api.ztlpay.io description: Production environment - url: https://api.sandbox.ztlpay-test.io description: Sandbox environment for testing get: tags: - Accounts description: > Retrieve a list and general information about the account or accounts specified in the authorized account query. summary: List of Accounts operationId: getAccountQueryInfoV2 parameters: - $ref: '#/components/parameters/consent-id' - $ref: '#/components/parameters/PSU-IP-Address-Optional' - $ref: '#/components/parameters/PSU-User-Agent-Optional' responses: '200': description: Successfully fetched accounts content: application/json: schema: type: object properties: accounts: type: array items: $ref: '#/components/schemas/AccountV2' '400': description: Bad Request headers: ztl-request-id: $ref: '#/components/headers/ztl-request-id' content: application/json: schema: $ref: '#/components/schemas/AISErrors' '403': $ref: '#/components/responses/GeneralError' description: Forbidden '404': $ref: '#/components/responses/GeneralError' description: Not found '409': $ref: '#/components/responses/GeneralError' description: Conflict '500': $ref: '#/components/responses/GeneralError' description: Internal server error '503': $ref: '#/components/responses/GeneralError' description: Service unavailable security: - Authorization: - payments /api/v2/accounts/{accountId}/balance: servers: - url: https://api.ztlpay.io description: Production environment - url: https://api.sandbox.ztlpay-test.io description: Sandbox environment for testing get: tags: - Accounts description: >- Retrieve the current available and booked balance for the account specified. summary: Account Balance operationId: accountBalanceV2 parameters: - $ref: '#/components/parameters/consent-id' - $ref: '#/components/parameters/PSU-IP-Address-Optional' - $ref: '#/components/parameters/PSU-User-Agent-Optional' - $ref: '#/components/parameters/account-id' responses: '200': description: Successfully retrieved balance content: application/json: schema: type: object properties: id: type: string description: Unique Identifier for Account example: 11ab5740-f8f5-1234-abcd-b90e4253b7b8 balance: type: object properties: booked: type: object properties: amount: type: number description: The booked balance on the account example: 150.51 currency: type: string description: The currency of the booked balance example: NOK available: type: object properties: amount: type: number description: The available balance on the account example: 100.42 currency: type: string description: The currency of the available balance example: NOK '400': description: Bad Request headers: ztl-request-id: $ref: '#/components/headers/ztl-request-id' content: application/json: schema: $ref: '#/components/schemas/AISErrors' '403': $ref: '#/components/responses/ForbiddenError' description: Forbidden '404': $ref: '#/components/responses/GeneralError' description: Not found '409': $ref: '#/components/responses/GeneralError' description: Conflict '500': $ref: '#/components/responses/GeneralError' description: Internal server error '503': $ref: '#/components/responses/GeneralError' description: Service unavailable security: - Authorization: - payments /api/v2/accounts/{accountId}/entries: servers: - url: https://api.ztlpay.io description: Production environment - url: https://api.sandbox.ztlpay-test.io description: Sandbox environment for testing get: tags: - Accounts description: >- Retrieve the latest transaction entries on the account. The maximum date range supported varies with banks, see Supported Banks-endpoint to retrieve the specific banks max date range. summary: Account Entries operationId: accountEntriesV2 parameters: - $ref: '#/components/parameters/account-id' - $ref: '#/components/parameters/consent-id' - $ref: '#/components/parameters/PSU-IP-Address-Optional' - $ref: '#/components/parameters/PSU-User-Agent-Optional' - name: fromDate in: query description: Entries start date, inclusive required: false schema: type: string format: date, ISO-8601 example: '2025-01-01' - name: toDate in: query description: Entries end date, inclusive required: false schema: type: string format: date, ISO-8601 example: '2025-01-02' responses: '200': description: Successfully retrieved entries content: application/json: schema: type: object properties: accountEntries: type: array items: allOf: - $ref: '#/components/schemas/Transaction' - type: object required: - status '400': description: Bad Request headers: ztl-request-id: $ref: '#/components/headers/ztl-request-id' content: application/json: schema: $ref: '#/components/schemas/AISErrors' '403': $ref: '#/components/responses/ForbiddenError' description: Forbidden '404': $ref: '#/components/responses/GeneralError' description: Not found '409': $ref: '#/components/responses/GeneralError' description: Conflict '500': $ref: '#/components/responses/GeneralError' description: Internal server error '503': $ref: '#/components/responses/GeneralError' description: Service unavailable security: - Authorization: - payments /api/v2/accounts/{accountId}/entries/{transactionId}/details: servers: - url: https://api.ztlpay.io description: Production environment - url: https://api.sandbox.ztlpay-test.io description: Sandbox environment for testing get: tags: - Accounts description: Retrieve the transaction details. Support varies per bank. summary: Account Entry Details operationId: accountEntryDetailsV2 parameters: - $ref: '#/components/parameters/account-id' - $ref: '#/components/parameters/consent-id' - $ref: '#/components/parameters/PSU-IP-Address-Optional' - $ref: '#/components/parameters/PSU-User-Agent-Optional' - name: transactionId in: path description: The ID of the transaction, as retrieved from the list of entries. required: true schema: type: string responses: '200': description: Successfully retrieved transaction details content: application/json: schema: $ref: '#/components/schemas/Transaction' '400': description: Bad Request headers: ztl-request-id: $ref: '#/components/headers/ztl-request-id' content: application/json: schema: allOf: - $ref: '#/components/schemas/AISErrors' - type: object properties: failure: type: string enum: - UNSUPPORTED_PRODUCT_BY_BANK '403': $ref: '#/components/responses/ForbiddenError' description: Forbidden '404': $ref: '#/components/responses/GeneralError' description: Not found '409': $ref: '#/components/responses/GeneralError' description: Conflict '500': $ref: '#/components/responses/GeneralError' description: Internal server error '503': $ref: '#/components/responses/GeneralError' description: Service unavailable security: - Authorization: - payments /api/v2/payroll: servers: - url: https://api.ztlpay.io description: Production environment - url: https://api.sandbox.ztlpay-test.io description: Sandbox environment for testing post: tags: - Payroll description: Initiates a new payroll, and returns a status for successful requests. summary: Payroll initiation operationId: payrollInitiationV2 parameters: - $ref: '#/components/parameters/consent-id' - $ref: '#/components/parameters/PSU-IP-Address-Mandatory' - $ref: '#/components/parameters/PSU-User-Agent-Mandatory' requestBody: content: application/json: schema: $ref: '#/components/schemas/CreatePayroll' responses: '200': description: Payroll initiated successfully content: application/json: schema: $ref: '#/components/schemas/CreatePayrollResponse' '400': $ref: '#/components/responses/PayrollInitiationBadRequest' '403': $ref: '#/components/responses/GeneralError' description: Forbidden '409': $ref: '#/components/responses/GeneralError' description: Conflict '422': $ref: '#/components/responses/ValidationPayrollResponse' '500': $ref: '#/components/responses/GeneralError' description: Internal server error '503': $ref: '#/components/responses/GeneralError' description: Service unavailable security: - Authorization: - payments /api/v2/payroll/approve: servers: - url: https://api.ztlpay.io description: Production environment - url: https://api.sandbox.ztlpay-test.io description: Sandbox environment for testing post: tags: - Payroll description: Start approval/signing process of a payroll summary: Payroll approval operationId: payrollApprovalV2 parameters: - $ref: '#/components/parameters/consent-id' - $ref: '#/components/parameters/PSU-IP-Address-Mandatory' - $ref: '#/components/parameters/PSU-User-Agent-Mandatory' requestBody: content: application/json: schema: $ref: '#/components/schemas/ApprovePayroll' responses: '200': description: Approval initiated successfully content: application/json: schema: $ref: '#/components/schemas/ApprovalResponse' '400': $ref: '#/components/responses/PayrollBadRequest' '403': $ref: '#/components/responses/GeneralError' description: Forbidden '404': $ref: '#/components/responses/GeneralError' description: Not found '409': $ref: '#/components/responses/GeneralError' description: Conflict '500': $ref: '#/components/responses/GeneralError' description: Internal server error '503': $ref: '#/components/responses/GeneralError' description: Service unavailable security: - Authorization: - payments /api/v2/payroll/{payrollId}/status: servers: - url: https://api.ztlpay.io description: Production environment - url: https://api.sandbox.ztlpay-test.io description: Sandbox environment for testing get: tags: - Payroll description: Retrieves latest payroll status. summary: Payroll status operationId: payrollStatusV2 parameters: - name: payrollId in: path required: true description: Id received when creating the payroll schema: type: string form: uuid example: 7c628b2e-9094-4bf8-af23-1d517c6fc4f5 responses: '200': description: Payroll status content: application/json: schema: $ref: '#/components/schemas/PayrollStatus' '400': $ref: '#/components/responses/PayrollBadRequest' '403': $ref: '#/components/responses/GeneralError' description: Forbidden '404': $ref: '#/components/responses/GeneralError' description: Not found '500': $ref: '#/components/responses/GeneralError' description: Internal server error '503': $ref: '#/components/responses/GeneralError' description: Service unavailable security: - Authorization: - payments /api/v2/payroll/cancel: servers: - url: https://api.ztlpay.io description: Production environment - url: https://api.sandbox.ztlpay-test.io description: Sandbox environment for testing post: tags: - Payroll description: Cancels a payroll. May require approval. summary: Cancel payroll operationId: cancelPayrollV2 parameters: - $ref: '#/components/parameters/consent-id' - $ref: '#/components/parameters/PSU-IP-Address-Optional' - $ref: '#/components/parameters/PSU-User-Agent-Optional' requestBody: content: application/json: schema: $ref: '#/components/schemas/CancelPayroll' responses: '200': description: Payroll cancellation created, check status content: application/json: schema: $ref: '#/components/schemas/CancelPayrollResponse' '400': $ref: '#/components/responses/PayrollBadRequest' '403': $ref: '#/components/responses/GeneralError' description: Forbidden '404': $ref: '#/components/responses/GeneralError' description: Not found '409': $ref: '#/components/responses/GeneralError' description: Conflict '500': $ref: '#/components/responses/GeneralError' description: Internal server error '503': $ref: '#/components/responses/GeneralError' description: Service unavailable security: - Authorization: - payments /api/v2/payroll/bulk: servers: - url: https://api.ztlpay.io description: Production environment - url: https://api.sandbox.ztlpay-test.io description: Sandbox environment for testing post: tags: - Payroll description: >- Should not be used without informing ZTL in advance. This is only for Danske Bank. Initiates a new payroll for banks using bulk, and returns a SCA requiring the user to approve. summary: Payroll Bulk initiation operationId: payrollBulkInitiationV2 parameters: - $ref: '#/components/parameters/AuthorizationJwtHeader' - $ref: '#/components/parameters/consent-id' - $ref: '#/components/parameters/PSU-IP-Address-Mandatory' - $ref: '#/components/parameters/PSU-User-Agent-Mandatory' requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateBulkPayroll' responses: '200': description: Payroll initiated successfully content: application/json: schema: $ref: '#/components/schemas/CreateBulkPayrollResponse' '400': $ref: '#/components/responses/PayrollInitiationBadRequest' '403': $ref: '#/components/responses/GeneralError' description: Forbidden '409': $ref: '#/components/responses/GeneralError' description: Conflict '422': $ref: '#/components/responses/ValidationPayrollResponse' '500': $ref: '#/components/responses/GeneralError' description: Internal server error '503': $ref: '#/components/responses/GeneralError' description: Service unavailable security: - Authorization: - payments /api/v2/payroll/bulk/{bulkId}/status: servers: - url: https://api.ztlpay.io description: Production environment - url: https://api.sandbox.ztlpay-test.io description: Sandbox environment for testing get: tags: - Payroll description: >- Should not be used without informing ZTL in advance. This is only for Danske Bank. Retrieves latest payroll status for bulk. summary: Payroll bulk status operationId: payrollBulkStatusV2 parameters: - name: bulkId in: path required: true description: Id received when creating the bulk payroll schema: type: string form: uuid example: 7c628b2e-9094-4bf8-af23-1d517c6fc4f5 responses: '200': description: Payroll status content: application/json: schema: $ref: '#/components/schemas/PayrollBulkStatus' '400': $ref: '#/components/responses/PayrollBadRequest' '403': $ref: '#/components/responses/GeneralError' description: Forbidden '404': $ref: '#/components/responses/GeneralError' description: Not found '500': $ref: '#/components/responses/GeneralError' description: Internal server error '503': $ref: '#/components/responses/GeneralError' description: Service unavailable security: - Authorization: - payments /api/v2/payments: servers: - url: https://api.ztlpay.io description: Production environment - url: https://api.sandbox.ztlpay-test.io description: Sandbox environment for testing post: tags: - Payments description: > Initiates a new domestic payment, and returns status. Normally the status will be `Unsigned`, indicating that the payment needs to be approved before executed. Some payments do not require signing, this is dependent on the bank account configuration. This endpoint is supported if the bank contains the product PAYMENT_DOMESTIC. summary: Domestic payment initiation operationId: paymentInitiationV2 parameters: - $ref: '#/components/parameters/consent-id' - $ref: '#/components/parameters/PSU-IP-Address-Mandatory' - $ref: '#/components/parameters/PSU-User-Agent-Mandatory' requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateDomesticPaymentRequest' responses: '200': description: Payment initiated successfully content: application/json: schema: $ref: '#/components/schemas/CreateDomesticPaymentResponse' '400': $ref: '#/components/responses/PaymentInitiationBadRequest' '403': $ref: '#/components/responses/GeneralError' description: Forbidden '404': $ref: '#/components/responses/GeneralError' description: Not found '409': $ref: '#/components/responses/GeneralError' description: Conflict '422': $ref: '#/components/responses/ValidationResponse' '500': $ref: '#/components/responses/GeneralError' description: Internal server error '503': $ref: '#/components/responses/GeneralError' description: Service unavailable security: - Authorization: - payments /api/v2/payments/approve: servers: - url: https://api.ztlpay.io description: Production environment - url: https://api.sandbox.ztlpay-test.io description: Sandbox environment for testing post: tags: - Payments description: >- Start approval/signing process of a list of unsigned or partlySigned transactions. Can be both domestic and cross-border transactions. summary: Payment approval operationId: paymentApprovalV2 parameters: - $ref: '#/components/parameters/consent-id' - $ref: '#/components/parameters/PSU-IP-Address-Mandatory' - $ref: '#/components/parameters/PSU-User-Agent-Mandatory' requestBody: content: application/json: schema: type: object required: - payments - callbackUrl properties: payments: type: array items: type: string format: uuid uniqueItems: true minLength: 1 example: - 175be5fc-4185-4cf1-af70-df34ead1a9ec - 4b24e1e8-f2ba-4d84-86a4-f5d5e4ae9af7 callbackUrl: type: string description: Sca callback url for redirect authentication example: https://www.google.com preferredScaMethod: type: string description: >- The preferred way to perform authorization. There is no guarantee that bank supports the preferred method. enum: - Redirect - Qr responses: '200': description: Approval initiated successfully content: application/json: schema: $ref: '#/components/schemas/ApprovalStatus' '400': $ref: '#/components/responses/PaymentBadRequest' '403': $ref: '#/components/responses/GeneralError' description: Forbidden '404': $ref: '#/components/responses/GeneralError' description: Not found '409': $ref: '#/components/responses/GeneralError' description: Conflict '500': $ref: '#/components/responses/GeneralError' description: Internal server error '503': $ref: '#/components/responses/GeneralError' description: Service unavailable security: - Authorization: - payments /api/v2/payments/{paymentId}/status: servers: - url: https://api.ztlpay.io description: Production environment - url: https://api.sandbox.ztlpay-test.io description: Sandbox environment for testing get: tags: - Payments description: Retrieves latest payments status. summary: Payment status operationId: paymentStatusV2 parameters: - name: paymentId in: path required: true description: Id received when creating the payment schema: type: string format: uuid example: 7c628b2e-9094-4bf8-af23-1d517c6fc4f5 responses: '200': description: Payment status content: application/json: schema: $ref: '#/components/schemas/PaymentStatus' '400': $ref: '#/components/responses/PaymentBadRequest' '403': $ref: '#/components/responses/GeneralError' description: Forbidden '404': $ref: '#/components/responses/GeneralError' description: Not found '409': $ref: '#/components/responses/GeneralError' description: Conflict '500': $ref: '#/components/responses/GeneralError' description: Internal server error '503': $ref: '#/components/responses/GeneralError' description: Service unavailable security: - Authorization: - payments /api/v2/payments/approve/{id}: servers: - url: https://api.ztlpay.io description: Production environment - url: https://api.sandbox.ztlpay-test.io description: Sandbox environment for testing get: tags: - Payments description: > Approval status indicates the status of a started payment approval. If the QR Sca approach are used, this endpoint gives updated QR picture. This picture is only valid for a short time, so a new picture has to be fetched every 1 second. QR is only available in Sweden. summary: Payment approval status operationId: paymentApprovalStatusV2 parameters: - $ref: '#/components/parameters/consent-id' - $ref: '#/components/parameters/PSU-IP-Address-Mandatory' - $ref: '#/components/parameters/PSU-User-Agent-Mandatory' - name: id in: path required: true description: Id received when creating an approval for payments schema: type: string format: uuid example: 7c628b2e-9094-4bf8-af23-1d517c6fc4f5 responses: '200': description: Approval status content: application/json: schema: $ref: '#/components/schemas/ApprovalStatus' '400': $ref: '#/components/responses/PaymentBadRequest' '403': $ref: '#/components/responses/GeneralError' description: Forbidden '404': $ref: '#/components/responses/GeneralError' description: Not found '409': $ref: '#/components/responses/GeneralError' description: Conflict '500': $ref: '#/components/responses/GeneralError' description: Internal server error '503': $ref: '#/components/responses/GeneralError' description: Service unavailable security: - Authorization: - payments /api/v2/payments/cancel: servers: - url: https://api.ztlpay.io description: Production environment - url: https://api.sandbox.ztlpay-test.io description: Sandbox environment for testing post: tags: - Payments description: >- Cancels a payment. May required approval (dependent on bank and payment status). summary: Cancel payment operationId: cancelPaymentV2 parameters: - $ref: '#/components/parameters/consent-id' - $ref: '#/components/parameters/PSU-IP-Address-Optional' - $ref: '#/components/parameters/PSU-User-Agent-Optional' requestBody: content: application/json: schema: type: object required: - paymentId - callbackUrl properties: paymentId: type: string description: Payment id to be cancelled example: 7c628b2e-9094-4bf8-af23-1d517c6fc4f5 callbackUrl: type: string description: Callback url for redirect authentication example: https://www.google.com preferredScaMethod: type: string description: Prefered sca method. Qr only supported in Sweden. enum: - Redirect - Qr responses: '200': description: Payment cancellation created, check status content: application/json: schema: type: object required: - cancellationRequestStatus - currentPaymentStatus properties: id: type: string format: uuid description: >- An ID that can be used to identify the cancellation attempt sca: $ref: '#/components/schemas/Sca' description: > Sca for approving cancellation. Present if status is AUTHORIZATION_REQUIRED There is no guarantee that the used sca approach used by bank matches the preferred sca approach from request. * `redirect` For redirect, the end user must use the redirect url to start the authentication process * `qr` The QR image has to be presented to the end user, who has to scan the image with bank authentication app. The qr image needs to be refreshed every second, see approval status for refreshed QR image. Only used in Sweden cancellationRequestStatus: type: string description: > Status of the cancellation, note that this is not the same as payment status. * `ACCEPTED` the cancellation has been successfully * `REJECTED` the cancellation was rejected * `AUTHORIZATION_REQUIRED` the cancellation requires approval/signing enum: - ACCEPTED - REJECTED - AUTHORIZATION_REQUIRED currentPaymentStatus: $ref: '#/components/schemas/PaymentStatus' description: >- Latest status of the payment after the cancellation request has been accounted for reason: type: string description: Additional information example: null '400': $ref: '#/components/responses/PaymentBadRequest' '403': $ref: '#/components/responses/GeneralError' description: Forbidden '404': $ref: '#/components/responses/GeneralError' description: Not found '409': $ref: '#/components/responses/GeneralError' description: Conflict '500': $ref: '#/components/responses/GeneralError' description: Internal server error '503': $ref: '#/components/responses/GeneralError' description: Service unavailable security: - Authorization: - payments /api/v2/payments/cross-border: servers: - url: https://api.ztlpay.io description: Production environment - url: https://api.sandbox.ztlpay-test.io description: Sandbox environment for testing post: tags: - Payments description: > Initiates a cross-border payment, this includes all transactions involving currency accounts. If the transaction requires exchange it will result in a psd2 domestic payment to ZTL's client account, these payment must be signed within deadline (2 or 5 minutes), if not it gets automatically cancelled. Payments that do not require exchange will go through the bank as cross-border payments. We request that when a cross-border payment 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 payment being delayed or in worst case cancelled. See Country and Currencies endpoint supported countries, currencies and constraints. summary: Initiate cross-border payment operationId: cross-border parameters: - $ref: '#/components/parameters/consent-id' - $ref: '#/components/parameters/PSU-IP-Address-Mandatory' - $ref: '#/components/parameters/PSU-User-Agent-Mandatory' requestBody: content: application/json: schema: $ref: '#/components/schemas/CrossBorderPaymentRequest' responses: '200': description: Initiated cross-border payment content: application/json: schema: $ref: '#/components/schemas/CrossBorderPaymentResponse' '400': $ref: '#/components/responses/CrossBorderInitiationBadRequest' '403': description: Forbidden content: application/json: schema: allOf: - type: object properties: failure: type: string enum: - COMPANY_DISABLED_FOR_INTERNATIONAL_PAYMENTS - $ref: '#/components/schemas/GeneralErrorObject' '404': $ref: '#/components/responses/GeneralError' description: Not found '409': $ref: '#/components/responses/GeneralError' description: Conflict '422': $ref: '#/components/responses/CrossBorderValidationResponse' '500': $ref: '#/components/responses/GeneralError' description: Internal server error '503': $ref: '#/components/responses/GeneralError' description: Service unavailable security: - Authorization: - payments /api/v2/payments/bulk: servers: - url: https://api.ztlpay.io description: Production environment - url: https://api.sandbox.ztlpay-test.io description: Sandbox environment for testing post: tags: - Payments description: > Initiates a list of payments with started approval/signing. This endpoint is exclusively supported for banks that do not support single payments/approval - see banks supported products (PAYMENT_BULK). This is currently only supported by Danske Bank and Handelsbanken Sweden. The response gives an id for the bulk status, which must be used in fetch status for bulk endpoint. This endpoint gives Id for the payments, which again can be used to fetch payment status. In some cases, the payment Ids are only available after the approval/signing process has completed. summary: Initiate bulk payment(s) operationId: initiateBulkPayments parameters: - $ref: '#/components/parameters/consent-id' - $ref: '#/components/parameters/PSU-IP-Address-Mandatory' - $ref: '#/components/parameters/PSU-User-Agent-Mandatory' requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateBulkRequest' responses: '200': description: Bulk created successfully content: application/json: schema: type: object required: - id properties: id: type: string format: uuid description: ID of bulk sca: allOf: - $ref: '#/components/schemas/Sca' description: > There is no guarantee that the used sca approach used by bank matches the preferred sca approach from request. * `redirect` For redirect, the end user must use the redirect url to start the authentication process * `qr` The QR image has to be presented to the end user, who has to scan the image with bank authentication app. The qr image needs to be refreshed every second, see approval status for refreshed QR image. Only used in Sweden transactions: type: array items: type: object required: - endToEndId properties: id: type: string format: uuid description: Id of the transaction endToEndId: type: string description: endToEndId as used in initial request costAmount: $ref: '#/components/schemas/AmountAndCurrency' description: Cost amount exchangeRate: type: number description: The exchange rate quoteExpiryTime: type: string format: datetime, ISO-8601 description: Expiry time for quote intermediaryAccount: type: object description: >- The Client account for the funding domestic psd2 transaction related to the payment. Account owned by ZTL. allOf: - $ref: '#/components/schemas/Beneficiary' '400': $ref: '#/components/responses/PaymentInitiationBadRequest' '403': description: Forbidden content: application/json: schema: allOf: - type: object properties: failure: type: string enum: - COMPANY_DISABLED_FOR_INTERNATIONAL_PAYMENTS - $ref: '#/components/schemas/GeneralErrorObject' '404': $ref: '#/components/responses/GeneralError' description: Not found '409': $ref: '#/components/responses/GeneralError' description: Conflict '422': $ref: '#/components/responses/BulkValidationResponse' '500': $ref: '#/components/responses/GeneralError' description: Internal server error '503': $ref: '#/components/responses/GeneralError' description: Service unavailable security: - Authorization: - payments /api/v2/payments/bulk/{bulkId}/status: servers: - url: https://api.ztlpay.io description: Production environment - url: https://api.sandbox.ztlpay-test.io description: Sandbox environment for testing get: tags: - Payments description: Fetches the status of a bulk along with the individual payments. summary: Fetch status for bulk payment operationId: bulkStatus parameters: - name: bulkId in: path required: true description: Id received when creating bulk payment schema: type: string format: uuid example: 7c628b2e-9094-4bf8-af23-1d517c6fc4f5 responses: '200': description: Bulk status content: application/json: schema: type: object properties: bulkStatus: type: string enum: - CREATED - ACCEPTED - REJECTED description: >- * `CREATED` Bulk is created * `ACCEPTED` Bulk have been successfully initiated, check status of individual transactions * `REJECTED` Initiation failed transactions: type: array items: type: object properties: id: type: string format: uuid description: >- Unique identifier for the payments. Can be used in payment status endpoint. endToEndId: type: string description: >- End-to-end identifier for the payments, used to match with the payment Id from bulk list. required: - id - endToEndId required: - bulkStatus '400': $ref: '#/components/responses/PaymentBadRequest' '403': $ref: '#/components/responses/GeneralError' description: Forbidden '404': $ref: '#/components/responses/GeneralError' description: Not found '409': $ref: '#/components/responses/GeneralError' description: Conflict '500': $ref: '#/components/responses/GeneralError' description: Internal server error '503': $ref: '#/components/responses/GeneralError' description: Service unavailable security: - Authorization: - payments /api/v2/payments/regulatory-reporting/codes/{countryCode}: servers: - url: https://api.ztlpay.io description: Production environment - url: https://api.sandbox.ztlpay-test.io description: Sandbox environment for testing get: tags: - Payments description: > Retrieves a list of regulatory reporting codes for a specific country. Currently only supported for NO and SE. These codes are used for regulatory reporting when making cross-border payments. Commonly required for payments above 100 000 NOK in Norway, and 150 000 SEK in Sweden. summary: Get regulatory reporting codes operationId: getRegulatoryReportingCodes parameters: - name: countryCode in: path required: true description: ISO 3166 country code schema: type: string example: 'NO' responses: '200': description: List of regulatory reporting codes for the specified country content: application/json: schema: type: object required: - codes properties: codes: type: array items: type: object required: - code - description properties: code: type: string description: The regulatory reporting code example: '14' description: type: string description: Description of the regulatory reporting code example: Kjøp/salg av varer '400': $ref: '#/components/responses/GeneralError' description: Bad request - invalid country code format '404': $ref: '#/components/responses/GeneralError' description: Not found - country code not supported '500': $ref: '#/components/responses/GeneralError' description: Internal server error '503': $ref: '#/components/responses/GeneralError' description: Service unavailable security: - Authorization: - payments /api/v2/payments/{paymentId}/progress-pdf: servers: - url: https://api.ztlpay.io description: Production environment - url: https://api.sandbox.ztlpay-test.io description: Sandbox environment for testing get: tags: - Payments description: >+ Generates a PDF report detailing the current progress of a payment. A PDF report can only be generated for cross-border payments with an exchange and payment status is in one of the following states: - InProgress When the payment is in the 'InProgress' state and funds have not yet been received by ZTL, the PDF will show payment status "Scheduled" When the payment is in the 'InProgress' state and funds have been received by ZTL, the PDF will show payment status "In progress" - Completed When the payment is in the 'Completed' state, the PDF will show payment status "Sent to bank"
Scheduled In progress Sent
summary: Payment Progress PDF operationId: internationalPaymentsProgressPDFV2 parameters: - name: paymentId in: path required: true description: Id received when creating the payment schema: type: string format: uuid example: 7c628b2e-9094-4bf8-af23-1d517c6fc4f5 responses: '200': description: Successfully generated payment progress PDF headers: ztlRequestId: description: >- Unique RequestId, please provide this Id in case of support requests schema: type: string format: uuid example: 3a797348-ef0c-4f52-b821-fdfcdb98c4d9 Content-Type: description: MIME type of the payload. schema: type: string example: application/pdf content: application/pdf: schema: type: string format: binary '400': $ref: '#/components/responses/GeneralErrorWithoutExample' description: Bad request '403': $ref: '#/components/responses/GeneralErrorWithoutExample' description: Forbidden '404': $ref: '#/components/responses/GeneralErrorWithoutExample' description: Not found '500': $ref: '#/components/responses/GeneralErrorWithoutExample' description: Internal server error security: - Authorization: - payments /api/companies: servers: - url: https://api.ztlpay.io description: Production environment - url: https://api.sandbox.ztlpay-test.io description: Sandbox environment for testing get: tags: - Companies description: Get list of all companies onboarded by the partner summary: Onboarded companies operationId: getCompanies parameters: - $ref: '#/components/parameters/AuthorizationJwtHeader' responses: '200': description: Successfully retrieved entries content: application/json: schema: type: array items: $ref: '#/components/schemas/Company' security: - Authorization: - payments /api/companies/supported/{countryCode}: servers: - url: https://api.ztlpay.io description: Production environment - url: https://api.sandbox.ztlpay-test.io description: Sandbox environment for testing get: tags: - Companies description: Get list of supported company types summary: Supported company types operationId: getSupportedCompanyTypes parameters: - $ref: '#/components/parameters/AuthorizationJwtHeader' - name: countryCode in: path required: true example: 'NO' schema: type: string responses: '200': description: Successfully retrieved entries content: application/json: schema: type: array items: $ref: '#/components/schemas/SupportedCompanyType' security: - Authorization: - payments /api/companies/subscription/activate/{countryCode}/{organizationNumber}: servers: - url: https://api.ztlpay.io description: Production environment - url: https://api.sandbox.ztlpay-test.io description: Sandbox environment for testing patch: tags: - Companies description: Activate the subscription for the given company summary: Activate subscription operationId: activateSubscription parameters: - $ref: '#/components/parameters/AuthorizationJwtHeader' - name: countryCode in: path required: true example: 'NO' schema: type: string - name: organizationNumber in: path required: true schema: type: string responses: '200': description: Successfully activated subscription '400': description: Request is not valid content: application/json: schema: $ref: '#/components/schemas/GeneralProblem' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/GeneralProblem' security: - Authorization: - payments /api/companies/subscription/cancel/{countryCode}/{organizationNumber}: servers: - url: https://api.ztlpay.io description: Production environment - url: https://api.sandbox.ztlpay-test.io description: Sandbox environment for testing patch: tags: - Companies description: Cancel the subscription for the given company summary: Cancel subscription operationId: cancelSubscription parameters: - name: countryCode in: path required: true example: 'NO' schema: type: string - name: organizationNumber in: path required: true schema: type: string responses: '200': description: Successfully cancelled subscription '400': description: Request is not valid content: application/json: schema: $ref: '#/components/schemas/GeneralProblem' security: - Authorization: - payments /api/fx/payments/validate: servers: - url: https://api.ztlpay.io description: Production environment - url: https://api.sandbox.ztlpay-test.io description: Sandbox environment for testing post: tags: - FX Payments description: > International payment validation request. It is strongly recommended to use [country-specific requirements endpoint](https://docs.ztlpay.io/ztl-api-v2.html#tag/Country/operation/getCountryRequirements) before forming a validation/initiation request to provide a good user experience. summary: Validation operationId: internationalPaymentsValidation parameters: - $ref: '#/components/parameters/AuthorizationJwtHeader' requestBody: content: application/json: schema: $ref: '#/components/schemas/QuoteRequest' responses: '200': description: Successfully validated request '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/MalformedRequestBody' '403': description: Forbidden content: text/plain: schema: type: string example: Company is not onboarded '422': description: Validation failed content: application/json: schema: type: array items: $ref: '#/components/schemas/QuoteValidationFailed' security: - Authorization: - payments /api/fx/payments: servers: - url: https://api.ztlpay.io description: Production environment - url: https://api.sandbox.ztlpay-test.io description: Sandbox environment for testing post: tags: - FX Payments description: > International payment quote request We request that when a fx payment 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 before calling confirm. Reason for this warning is to remind those who are lacking funds that they do not have funds and to avoid the payment being delayed or in worst case cancelled. summary: Payment Initiation operationId: internationalPaymentsQuote parameters: - $ref: '#/components/parameters/AuthorizationJwtHeader' requestBody: content: application/json: schema: $ref: '#/components/schemas/QuoteRequest' responses: '200': description: Successfully acquired foreign exchange quote content: application/json: schema: $ref: '#/components/schemas/QuoteResponse' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/MalformedRequestBody' '403': description: Forbidden content: text/plain: schema: type: string example: Company is not onboarded '422': description: Validation failed content: application/json: schema: type: array items: $ref: '#/components/schemas/QuoteValidationFailed' security: - Authorization: - payments /api/fx/payments/{quoteId}/confirm: servers: - url: https://api.ztlpay.io description: Production environment - url: https://api.sandbox.ztlpay-test.io description: Sandbox environment for testing post: tags: - FX Payments description: International payment confirmation. summary: Payment Confirmation operationId: internationalPaymentsPaymentConfirmation parameters: - name: quoteId in: path description: quote id as for payment required: true schema: type: string - $ref: '#/components/parameters/AuthorizationJwtHeader' responses: '200': description: Successfully confirmed payment content: application/json: schema: type: object required: - paymentId - statusUrl properties: paymentId: type: string description: The ID assigned to the confirmed payment example: 0db94e47-858c-4486-a0e9-a453e4da025d statusUrl: type: string description: A URL that can be used to get the payment's current status example: >- https://api.sandbox.ztlpay-test.io/api/fx/payments/0db94e47-858c-4486-a0e9-a453e4da025d/status '400': description: Request is not valid content: application/json: schema: type: object properties: message: type: string description: A message detailing the reason for the call failing example: Quote has expired. correlationId: type: string description: A unique identifier used for tracing the call example: 7757cdcb-128f-41ba-b3a6-58722e56b0f8 '404': description: Payment with given `paymentId` was not found security: - Authorization: - payments /api/fx/payments/{paymentId}/confirmPaid: servers: - url: https://api.ztlpay.io description: Production environment - url: https://api.sandbox.ztlpay-test.io description: Sandbox environment for testing post: tags: - FX Payments description: Cross-border payment funding confirmation. summary: Funding Payment Confirmation operationId: internationalPaymentsFundingPaymentConfirmation parameters: - name: paymentId in: path description: paymentId for the payment to be confirmedPaid required: true schema: type: string - $ref: '#/components/parameters/AuthorizationJwtHeader' responses: '200': description: Successfully confirmed payment content: application/json: schema: type: object required: - paymentId - statusUrl properties: paymentId: type: string description: The ID assigned to the confirmed payment example: 0db94e47-858c-4486-a0e9-a453e4da025d statusUrl: type: string description: A URL that can be used to get the payment's current status example: >- https://api.sandbox.ztlpay-test.io/api/fx/payments/0db94e47-858c-4486-a0e9-a453e4da025d/status '400': description: Request is not valid content: application/json: schema: type: object properties: message: type: string description: A message detailing the reason for the call failing example: Payment funding has already been confirmed correlationId: type: string description: A unique identifier used for tracing the call example: 7757cdcb-128f-41ba-b3a6-58722e56b0f8 '404': description: Payment with given `paymentId` was not found security: - Authorization: - payments /api/fx/payments/{paymentId}/status: servers: - url: https://api.ztlpay.io description: Production environment - url: https://api.sandbox.ztlpay-test.io description: Sandbox environment for testing get: tags: - FX Payments description: International payment status inquiry. summary: Payment Status operationId: internationalPaymentsStatus parameters: - name: paymentId in: path description: paymentId for the payment required: true schema: type: string - $ref: '#/components/parameters/AuthorizationJwtHeader' responses: '200': description: Successfully confirmed payment content: application/json: schema: type: object required: - status properties: status: type: string description: The current payment status enum: - Created - Confirmed - PaymentInProgress - Completed - Cancelled - PaymentFailed example: PaymentFailed message: type: string description: >- A technical message describing the current status reason (optional - normally not included). This message is not intended for end users. example: Technical error. '404': description: Payment with given `paymentId` was not found security: - Authorization: - payments /api/fx/payments/{paymentId}/cancel: servers: - url: https://api.ztlpay.io description: Production environment - url: https://api.sandbox.ztlpay-test.io description: Sandbox environment for testing post: tags: - FX Payments description: International payment funding payment confirmation. summary: Payment Cancellation operationId: internationalPaymentsCancel parameters: - name: paymentId in: path description: paymentId for the payment to cancel required: true schema: type: string - $ref: '#/components/parameters/AuthorizationJwtHeader' responses: '204': description: Successfully canceled payment '400': description: Request is not valid content: application/json: schema: type: object properties: message: type: string description: A message detailing the reason for the call failing example: Payment has not been booked yet correlationId: type: string description: A unique identifier used for tracing the call example: 7757cdcb-128f-41ba-b3a6-58722e56b0f8 '404': description: Payment with given `paymentId` was not found security: - Authorization: - payments /api/fx/payments/{paymentId}/progress-pdf: servers: - url: https://api.ztlpay.io description: Production environment - url: https://api.sandbox.ztlpay-test.io description: Sandbox environment for testing get: tags: - FX Payments summary: Payment Progress PDF description: >+ Generates a PDF report detailing the current progress of an FX payment. A PDF report can only be generated if the payment status is in one of the following states: - Confirmed When the payment is in the 'Confirmed' state the PDF will show payment status "Scheduled" - PaymentInProgress When the payment is in the 'PaymentInProgress' state the PDF will show payment status "In progress" - Completed When the payment is in the 'Completed' state the PDF will show payment status "Sent to bank"
Scheduled In progress Sent
operationId: internationalPaymentsProgressPDF parameters: - name: paymentId in: path description: The paymentId of the payment for which to generate the progress PDF required: true schema: type: string - $ref: '#/components/parameters/AuthorizationJwtHeader' responses: '200': description: Successfully generated payment progress PDF headers: ztlRequestId: description: >- Unique RequestId, please provide this Id in case of support requests schema: type: string format: uuid example: 3a797348-ef0c-4f52-b821-fdfcdb98c4d9 Content-Type: description: MIME type of the payload. schema: type: string example: application/pdf content: application/pdf: schema: type: string format: binary '400': $ref: '#/components/responses/GeneralErrorWithoutExample' description: Bad request '403': $ref: '#/components/responses/GeneralErrorWithoutExample' description: Forbidden '404': $ref: '#/components/responses/GeneralErrorWithoutExample' description: Not found '500': $ref: '#/components/responses/GeneralErrorWithoutExample' description: Internal server error security: - Authorization: - payments /api/currencies: servers: - url: https://api.ztlpay.io description: Production environment - url: https://api.sandbox.ztlpay-test.io description: Sandbox environment for testing get: tags: - Currencies description: Get details of supported currencies international payments summary: Supported currencies operationId: getSupportedCurrencies responses: '200': description: All supported currencies content: application/json: schema: type: array items: $ref: '#/components/schemas/SupportedCurrency' security: - Authorization: - payments /api/country: servers: - url: https://api.ztlpay.io description: Production environment - url: https://api.sandbox.ztlpay-test.io description: Sandbox environment for testing get: tags: - Country description: >- List all supported countries (possible to pay to). ZTL supports all non-sanctioned countries in the world. summary: All countries operationId: getCountries responses: '200': description: Supported countries content: application/json: schema: type: array items: type: object required: - countryCode - countryName properties: countryCode: type: string description: 2-letters country code example: SE countryName: type: string example: Sweden security: - Authorization: - payments /api/country/{country}/paymentrequirement: servers: - url: https://api.ztlpay.io description: Production environment - url: https://api.sandbox.ztlpay-test.io description: Sandbox environment for testing get: tags: - Country description: >- Gives additional payment requirements per country. If the country additional remittance information, this information is mandatory. summary: Cross-border payment requirements operationId: getCountryRequirements parameters: - name: country in: path description: 2-letters country code required: true schema: type: string responses: '200': description: Payment Requirements content: application/json: schema: type: object required: - countryCode - localCurrency - acceptedCurrencies - supportedBankAccountFormats properties: countryCode: type: string description: 2-letters country code example: SE countryName: type: string description: Country name (English) example: Sweden localCurrency: type: string description: 3-letter currency code example: NOK acceptedCurrencies: type: array description: All currency the receiving county supports items: type: string description: 3-letter currency code example: EUR supportedBankAccountFormats: type: array description: >- Required bank account format for receiving country. Can be one or multiple account formats. items: anyOf: - $ref: '#/components/schemas/Iban' - $ref: '#/components/schemas/Swift' - $ref: '#/components/schemas/SwiftWithBankRouting' paymentRequirements: type: array description: Additional payment requirements for receiving country. items: anyOf: - $ref: >- #/components/schemas/AdditionalRemittanceInformationRequired security: - Authorization: - payments components: parameters: AuthorizationJwtHeader: name: Authorization in: header schema: type: string format: Bearer JWT description: >- Bearer Authorization token - A JWT token used to authenticate the request. Please refer to the Authorization section of our docs. example: >- Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6IkE1NEZCQjFGRjgzRTZFRUFEQUI1MTg4QTJBMkVGRDhGNTUzMEUzNDkiLCJ0eXAiOiJKV1QiLCJ4NXQiOiJwVS03SF9nLWJ1cmF0UmlLS2k3OWoxVXc0MGsifQ.eyJuYmYiOjE1NjI4MzE1OTIsImV4cCI6MTU2MjgzNTE5MiwiaXNzIjoiaHR0cHM6Ly9vaWRjLnp0bC5zdGFjY2Zsb3cubmV0IiwiYXVkIjpbImh0dHBzOi8vb2lkYy56dGwuc3RhY2NmbG93Lm5ldC9yZXNvdXJjZXMiLCJ6dGwtYXBpIiwicG9ydGFsLWFwaSJdLCJjbGllbnRfaWQiOiJkZXZjbGllbnQiLCJzY29wZSI6WyJwYXltZW50cyIsInBvcnRhbC1hcGkiXX0.dJuDJNTsSBhQ_xmN3ruqbBZvJdyn2nUkUW3NEwbgXw_l-UA3_XRmtp16rWWdhMLbh-D_HywwG2a0h-MK2tX17C-ggsfp_pDxj8iy8aLleI3dY1qt0VkQY8rOw5_YtWa40HWwIBK9Ll8MqovwBK4lg9Pkq_KLGdkoz87n63QezS5u0JeWYJJnHFuY5ojX_M5szAdSYoVYOyvL0tr30ynxb3joglKrVWlkeawRZztRV4chFN00tlv_Tn54vDYOyDPtBWK6JpMVqhHla8a5JnslJu5dUP82qtgms_lFYOiR1oD2jaa-t0QTE6MVwspG3kwQBSSSZawe-9G4yEBg-nFSGg consent-id: in: header name: consent-id description: A valid consentId required: true schema: type: string format: uuid example: 3a797348-ef0c-4f52-b821-fdfcdb98c4d9 PSU-IP-Address-Optional: in: header name: PSU-IP-Address description: >- AAA IP Address of the end-user initiating the payment. DO NOT use any other IP address than what you can collect from the current user session that uses your system (don't use something stored in your DB). This information is used by the banks to manage traffic and handle security. required: false schema: type: string example: 192.158.1.38 PSU-User-Agent-Optional: in: header name: PSU-User-Agent required: false description: >- The forwarded Agent header field of the HTTP request between PSU and TPP. example: Mozilla/5.0 (Windows NT 10.0; …) Gecko/20100101 Firefox/63.0 schema: type: string PSU-IP-Address-Mandatory: in: header name: PSU-IP-Address description: >- AAA IP Address of the end-user initiating the payment. DO NOT use any other IP address than what you can collect from the current user session that uses your system (don't use something stored in your DB). This information is used by the banks to manage traffic and handle security. required: true schema: type: string example: 192.158.1.38 PSU-User-Agent-Mandatory: in: header name: PSU-User-Agent required: true description: >- The forwarded Agent header field of the HTTP request between PSU and TPP. example: Mozilla/5.0 (Windows NT 10.0; …) Gecko/20100101 Firefox/63.0 schema: type: string account-id: in: path name: accountId description: > The ID of the account, as retrieved from the list of accounts. The account ID is sometimes the same as the account bban, but this is not always the case. Also, the account ID may change each time a consent is created/refreshed. required: true schema: type: string headers: ztl-request-id: description: Unique RequestId, please provide this Id in case of support requests schema: type: string format: uuid example: 3a797348-ef0c-4f52-b821-fdfcdb98c4d9 schemas: GeneralErrorObject: type: object required: - ztlRequestId - message properties: ztlRequestId: type: string format: uuid description: Unique RequestId, please provide this Id in case of support requests example: 3a797348-ef0c-4f52-b821-fdfcdb98c4d9 message: type: string description: The underlying reason for the error example: Invalid account consentStatus: type: string enum: - AWAITING_AUTHORIZATION - VALID - REJECTED - EXPIRED - REVOKED description: > * `AWAITING_AUTHORIZATION` Requires user approval * `VALID` Valid consent, can be used for AIS and PIS. * `REJECTED` Consent creation or authentication failed. * `EXPIRED` Consent has expired, a new consent must be created to replace the expired consent. * `REVOKED` Consent was revoked either by user or bank. A new consent must be created to replace the revoked consent. example: AWAITING_AUTHORIZATION BankConstraint: type: object required: - maxBasketSize - maxInformationFieldLength - maxUnstructuredRemittanceInfoLength - cancelSCARequired - validInformationFieldCharactersPattern properties: maxBasketSize: type: integer description: >- The maximum number of transactions that can be bundled in the same basket. example: 20 maxInformationFieldLength: type: integer description: >- The maximum length of information fields such as debtor name or creditor address. example: 35 maxUnstructuredRemittanceInfoLength: type: integer description: >- The maximum length of unstructured remittance information (i.e., payment message) that may be sent in the initiate payment request. example: 108 aisMaxDateRangeMonths: type: integer description: The maximum range for retrieving account entries for an account. example: 12 cancelSCARequired: type: boolean description: >- If true, then the bank requires SCA for cancelling payments. If false, cancelling payments do not require SCA. example: true validInformationFieldCharactersPattern: type: string description: >- Regex for allowed symbols in information fields such as debtor name or remittance info. example: '[A-ZÆØÅa-zæøå0-9\\D]' aisMaxDateRangeNote: type: string description: Additional information about ais date range example: Supports up to 24 months if consent age < 1h maxBulkSize: type: integer description: >- The maximum number of transactions that can be bundled in a bulk payment. example: 20 Sca: oneOf: - type: object title: redirect required: - type - url properties: type: type: string enum: - redirect description: >- Redirect link to redirect authorization flow. After the redirect, the url will contain the query parameter `status`, with the possible values [`success`, `rejected`, `cancelled`] url: type: string example: >- https://api.ztlpay.io/api/v2/consents/sca/redirect/start/6212d401-1785-4739-8843-55fe4eb9dad4 description: Url to start authorization redirect flow - type: object title: qr required: - type - qrImage - qrType properties: type: type: string enum: - qr description: Qr image, used with bank app to scan image for authentication qrCode: type: string example: >- https://app.bankid.com/?autostarttoken=bankid.7591e8ad-26c0-40d7-a550-28fe8edf66d5.0.e45135e764eaab1e58a6bdbbf6d4d004269711c86a21da264d66a95f3cc6de36&redirect=null description: >- Qr code which can be used to generate Qr image. Can be used to customize image. Might not be available for all banks. qrImage: type: string example: >- iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+A8AAQUBAScY42YAAAAASUVORK5CYII= description: Qr code as image, base64 encoded qrType: type: string enum: - Dynamic - Static description: > * `Dynamic` Dynamic image, valid for 1 sec. Must be refreshed by fetching updated approval status. * `Static` Static image, valid for a longer period dependent on bank. Usually 30 seconds. Transaction: type: object required: - type - postedAmount - remittanceInformation properties: transactionId: type: string description: Unique Identifier for entry provided by ASPSP example: d1f669f2-1234-abcd-aabb-ff0cc229b485 postedAmount: type: object properties: amount: type: number description: >- The monetary amount, two decimals, max value 999999999999.99, always positive example: 99.5 currency: type: string description: The currency of the transaction example: NOK description: Amount for transaction type: type: string description: Posting type enum: - Debit - Credit status: type: string description: Status of the posting enum: - Pending - Booked bookingDateTime: type: string format: date example: '2025-01-02' valueDateTime: type: string format: date example: '2025-01-01' purposeText: type: string description: Purpose of transfer. example: Overføring Innland remittanceInformation: type: object properties: reference: type: string example: 75025049 unstructured: type: string example: Transfer of funds description: Remittance information creditor: $ref: '#/components/schemas/CashAccountV2' debtor: $ref: '#/components/schemas/CashAccountV2' endToEndId: type: string CashAccountV2: type: object properties: name: type: string description: Name of the account holder bban: type: string description: Account number in BBAN format format: bban example: 12043175449 iban: type: string description: Account number in IBAN format format: iban example: NO0812043175449 AccountV2: type: object required: - id - iban - currency properties: id: type: string description: >- Unique Identifier for Account provided by Bank. This id should be used as reference for other endpoints under account services. Note: Two consents can have different id for same account example: 11ab5740-f8f5-1234-abcd-b90e4253b7b8 name: type: string description: Name of the account example: Main savings account bic: type: string description: Identifier code for the accounts bank example: DNBANOKK bban: type: string description: Account number in BBAN format format: bban example: '12043175449' iban: type: string description: Account number in IBAN format format: iban example: NO0812043175449 country: type: string description: Required for BBAN accounts example: 'NO' type: type: string description: Type of account, value is different depending on bank example: Debit currency: type: string format: iso-4217 description: Account currency example: NOK ownerName: type: string description: >- The name of the Account Owner. This information is not available for all banks AISErrors: type: object required: - ztlRequestId - message properties: failure: type: string enum: - INVALID_CONSENT - INVALID_ACCOUNT - ACCESS_DENIED description: | * `INVALID_CONSENT` Consent is invalid * `INVALID_ACCOUNT` Account is either missing or invalid * `ACCESS_DENIED` PSU is not allowed to access resource ztlRequestId: type: string format: uuid description: Unique RequestId, please provide this Id in case of support requests example: 3a797348-ef0c-4f52-b821-fdfcdb98c4d9 message: type: string description: The underlying reason for the error example: Invalid account ForbiddenErrorObject: type: object required: - ztlRequestId - message properties: failure: type: string enum: - INACTIVE_SUBSCRIPTION description: > * `INACTIVE_SUBSCRIPTION` The company does not have an active subscription to ZTL's services ztlRequestId: type: string format: uuid description: Unique RequestId, please provide this Id in case of support requests example: 3a797348-ef0c-4f52-b821-fdfcdb98c4d9 message: type: string description: The underlying reason for the error CancelPayrollResponse: type: object required: - cancellationRequestStatus - currentPayrollStatus properties: id: type: string format: uuid description: An ID that can be used to identify the cancellation attempt sca: $ref: '#/components/schemas/PayrollSca' cancellationRequestStatus: type: string description: > Status of the cancellation, note that this is not the same as payroll status. * `ACCEPTED` the cancellation has been successfully * `REJECTED` the cancellation was rejected * `AUTHORIZATION_REQUIRED` the cancellation requires approval/signing enum: - ACCEPTED - REJECTED - AUTHORIZATION_REQUIRED currentPayrollStatus: $ref: '#/components/schemas/PayrollStatusCancelled' description: >- Latest status of the payroll after the cancellation request has been accounted for reason: type: string description: Additional information example: null ApprovalResponse: type: object required: - id - status properties: id: type: string format: uuid description: >- An ID that can be used to identify the approval and check for statuses example: 7c628b2e-9094-4bf8-af23-1d517c6fc4f5 status: type: string enum: - STARTED - ACCEPTED - REJECTED - CANCELLED sca: $ref: '#/components/schemas/PayrollSca' CreatePayrollResponse: type: object required: - payrollId - transactions properties: payrollId: type: string format: uuid description: Used for approval, cancellation, and status check example: 7c628b2e-9094-4bf8-af23-1d517c6fc4f5 transactions: type: array description: >- `Unsigned` will be the status unless the account has some other rules items: $ref: '#/components/schemas/PayrollTransactionStatus' CreateBulkPayrollResponse: type: object required: - id - payrolls - status properties: id: type: string format: uuid description: Bulk identifier example: 7c628b2e-9094-4bf8-af23-1d517c6fc4f5 payrolls: type: array description: An array of payrolls items: $ref: '#/components/schemas/CreatePayrollResponse' status: type: string description: The status of the approval. enum: - STARTED - ACCEPTED - REJECTED - CANCELLED example: STARTED sca: type: object description: Redirect SCA the user needs to perform before payroll is approved. $ref: '#/components/schemas/PayrollSca' PayrollStatus: type: object required: - transactions description: >- The initial payroll status indicates if the payroll was accepted, and if it needs to be signed before it will be executed in the bank properties: transactions: type: array items: $ref: '#/components/schemas/PayrollTransactionStatus' PayrollBulkStatus: type: object required: - bulkStatus - payrolls description: >- The initial payroll status indicates if the payroll was accepted, and if it needs to be signed before it will be executed in the bank properties: bulkStatus: type: string description: The status of the bulk enum: - CREATED - ACCEPTED - REJECTED payrolls: type: array items: $ref: '#/components/schemas/PayrollBulkTransactionStatus' CreatePayroll: type: object required: - name - dueDate - purposeCode - from - transactions properties: from: type: object description: Account information for debtor required: - account - name properties: account: type: object required: - bban properties: bban: type: string description: A valid bban from one of the accounts on the consent. example: 97105048304 name: type: string description: The name of the organization making the payroll example: ZTL Payment Solution AS organizationNumber: type: string description: Organization number for the company example: 920970931 transactions: type: array description: A List of transactions for each individual payout in the payroll items: type: object required: - account - name - amount - remittanceInformation - metadata properties: metadata: type: object description: Metadata for a single transaction required: - endToEndId properties: endToEndId: type: string description: identifier for the single transaction example: 71a2e752-8b71-446f-b9e9-b19bfb70becb name: type: string description: The name of the receiver example: Ola Nordmann account: type: object description: A receiver account required: - bban properties: bban: type: string description: A valid bban from one of the accounts on the consent. example: 97105048304 amount: $ref: '#/components/schemas/AmountAndCurrency' remittanceInformation: type: object description: > Remittance information, either OCR or Text message * `RemittanceInformationMessage` Text message, will be visible to receiver. Typically order number or description for payroll * `RemittanceInformationOcr` OCR must be used if the receiving account is OCR account. anyOf: - $ref: '#/components/schemas/RemittanceInformationMessagePayroll' - $ref: '#/components/schemas/RemittanceInformationOcrPayroll' dueDate: type: string format: date, ISO-8601 description: The due date for the payroll example: '2024-01-15' purposeCode: type: string description: Purpose code for payroll enum: - SALA CreateBulkPayroll: type: object required: - callbackUrl - payrolls properties: callbackUrl: type: string description: Sca callback url for redirect authentication example: https://www.google.com payrolls: type: array items: $ref: '#/components/schemas/CreatePayroll' ApprovePayroll: type: object description: >- If both `payrollId` and `payrolls` are provided, `payrolls` will be used. anyOf: - $ref: '#/components/schemas/ApprovePayrollList' - $ref: '#/components/schemas/ApprovePayrollId' ApprovePayrollList: type: object required: - payrolls - callbackUrl properties: payrolls: type: array description: A list of payroll ids to be approved example: - 71a2e752-8b71-446f-b9e9-b19bfb70becb items: type: string description: The id returned from the initiation process callbackUrl: type: string description: Sca callback url for redirect authentication example: https://www.google.com ApprovePayrollId: type: object required: - callbackUrl - payrollId properties: payrollId: deprecated: true type: string description: The id returned from the initiation process callbackUrl: type: string description: Sca callback url for redirect authentication example: https://www.google.com CancelPayroll: type: object required: - payrollId - callbackUrl properties: payrollId: type: string description: Payroll id to be cancelled example: 7c628b2e-9094-4bf8-af23-1d517c6fc4f5 callbackUrl: type: string description: Callback url for redirect authentication example: https://www.google.com PayrollStatusCancelled: type: string enum: - Unsigned - InProgress - Completed - Rejected - Cancelled - CustomerActionRequired example: Cancelled PayrollSca: type: object title: redirect required: - type - url properties: type: type: string enum: - redirect description: Redirect link to redirect authorization flow. url: type: string example: >- https://api.ztlpay.io/api/v2/consents/sca/redirect/start/6212d401-1785-4739-8843-55fe4eb9dad4 description: Url to start authorization redirect flow RemittanceInformationOcrPayroll: type: object required: - type - value properties: type: type: string description: Please use 'ocr', 'kid' are deprecated enum: - kid - ocr value: type: string example: 24646 RemittanceInformationMessagePayroll: type: object required: - type - value properties: type: type: string enum: - message value: type: string description: Message for receiver example: Payment for invoice 12345 AmountAndCurrency: type: object description: Amount and currency to be paid required: - amount - currency properties: amount: type: string description: Amount to be paid example: '1000.50' currency: type: string description: The currency the amount is specified in example: NOK PayrollTransactionStatus: type: object required: - endToEndId - payrollStatus - timestamp properties: endToEndId: type: string description: Same identifier as when creating a transaction timestamp: type: string description: >- The timestamp of the most recent internal update to the payroll status. example: '2025-12-30 06:43:45.569610 +00:00' payrollStatus: type: string enum: - Unsigned - InProgress - Completed - Rejected - Cancelled - CustomerActionRequired description: >- * `Unsigned` The user must approve the payroll. * `InProgress` The transaction is ongoing. * `Completed` The transaction/salary has been paid out. * `Rejected` The transaction has been rejected. * `Cancelled` The transaction has been cancelled. * `CustomerActionRequired` The payroll requires further action from the user. payrollStatusReason: type: string enum: - PartlySigned - SmsConfirmationRequired - InsufficientFunds description: >- * `PartlySigned` Indicates that the payments needs additional signing. This requirement may be set up for the bank account. * `SmsConfirmationRequired` The user needs additional confirmation with responding SMS received. Only used by a few banks * `InsufficientFunds` The payment has been stopped by the bank due to lack of funds PayrollBulkTransactionStatus: type: object required: - id - transactions properties: id: type: string description: Bulk identifier transactions: type: array items: $ref: '#/components/schemas/PayrollTransactionStatus' PaymentStatus: type: object required: - status - timestamp description: >- The initial payment status indicates if the payment was accepted, and if it needs to be signed before it will be executed in the bank properties: status: type: string enum: - Unsigned - InProgress - Completed - Rejected - Cancelled - CustomerActionRequired description: >- * `Unsigned` The user must approve the transaction. * `InProgress` The payment is ongoing. * `Completed` The payment has been completed by the bank. * `Rejected` The bank rejected the payment. * `Cancelled` The payment has been cancelled. * `CustomerActionRequired` The payment requires further action from the user. See statusReason for details. statusReason: type: string description: > * `PartlySigned` Indicates that the payments needs additional signing. This requirement may be set up for the bank account. * `SmsConfirmationRequired` The user needs additional confirmation with responding SMS received. Only used by a few banks * `InsufficientFunds` The payment has been stopped by the bank due to lack of funds enum: - PartlySigned - SmsConfirmationRequired - InsufficientFunds example: PartlySigned statusReasonText: type: string description: Payment status reason, unmapped reason text from bank. timestamp: type: string description: Timestamp when the status was fetched from bank example: '2024-03-19T09:34:57.657733682+01:00' CreateDomesticPaymentRequest: type: object required: - metadata - from - to - amount - dueDate properties: metadata: type: object description: Metadata for the payment required: - endToEndId properties: endToEndId: type: string description: An ID that can be used to identify the payment example: 73300aefd8494872b0c6f44e07a841f3 from: type: object description: Account information for debtor required: - account - contactInformation - currency properties: account: description: Bban is recommended when available, support for iban varies. anyOf: - $ref: '#/components/schemas/PaymentAccountBban' - $ref: '#/components/schemas/PaymentAccountIban' contactInformation: $ref: '#/components/schemas/ContactInformation' currency: type: string description: Currency on from account example: NOK organizationNumber: type: string description: Organization number for the company example: 920970931 to: type: object description: Account information for creditor required: - account - contactInformation properties: account: description: > * `PaymentAccountBban` Domestic account number * `PaymentAccountIban` Iban account number (support for iban varies, bban is recommended for domestic payments) * `PaymentAccountFik` Fik number, only used in Denmark * `SwedishGiro` Swedish Giro, only used in Sweden anyOf: - $ref: '#/components/schemas/PaymentAccountBban' - $ref: '#/components/schemas/PaymentAccountIban' - $ref: '#/components/schemas/PaymentAccountFik' - $ref: '#/components/schemas/SwedishGiro' contactInformation: $ref: '#/components/schemas/ContactInformation' amount: $ref: '#/components/schemas/AmountAndCurrency' dueDate: type: string format: date, ISO-8601 description: The due date for the payment example: '2024-01-15' remittanceInformation: type: object description: > Remittance information, either OCR or Text message * `RemittanceInformationMessage` Text message, will be visible to receiver. Typically order number or description for payment * `RemittanceInformationOcr` OCR must be used if the receiving account is OCR account. * `RemittanceInformationFik` FIK, only used in Denmark anyOf: - $ref: '#/components/schemas/RemittanceInformationMessage' - $ref: '#/components/schemas/RemittanceInformationOcr' - $ref: '#/components/schemas/RemittanceInformationFik' purposeCode: type: string description: Purposecode for payment enum: - SUPP - TAXS - SALA - VATX - OTHR ApprovalRedirectRequestDetails: type: object description: Redirect required: - method - confirmationUrl properties: method: type: string enum: - redirect confirmationUrl: type: string description: >- A URL that the user will be returned to in the event of a completed approval example: >- https://www.mypartner.comm/approval/013dda96-12c2-45a2-b1f3-10f361dc8385/return ApprovalRedirectResponseData: type: object required: - method - approvalRedirectUrl properties: method: type: string enum: - redirect approvalRedirectUrl: type: string example: https://bank.com/approve/85da7574-ea2e-4050-9f44-e5200bdd40e2 ApprovalDetachedRequestDetails: type: object description: Detached required: - method properties: method: type: string enum: - detached approvalCodeImage: type: string ApprovalDetachedResponseData: type: object required: - method - validationCodeImage properties: method: type: string enum: - detached validationCodeImage: type: string example: https://bank.com/codes/e60f3307-dadc-4028-b8c1-c2db8c6f9626.png PaymentAccountBban: type: object required: - type - bban properties: type: type: string enum: - bban bban: type: string description: Account number example: 97105048304 PaymentAccountIban: type: object required: - type - iban properties: type: type: string enum: - iban iban: type: string example: SE7250000000012341212345 PaymentAccountFik: type: object required: - type - value properties: type: type: string enum: - fik value: type: string example: 12345678 SwedishGiro: type: object description: >- Swedish giro, used for either BankGiro or PlusGiro. Requires RemittanceInformation of either message (invoiceRef) or ocr (giroOcrReference) required: - type - giroNumber - giroType properties: type: type: string enum: - swedishgiro giroNumber: type: string description: Reference to a Swedish BankGiro or PlusGiro account example: 123-4567 giroType: type: string enum: - BANKGIRO - PLUSGIRO RemittanceInformationOcr: type: object required: - type - value properties: type: type: string description: Please use 'ocr', 'kid' are deprecated enum: - kid - ocr value: type: string example: 24646 debtorReference: type: string description: > Reference text or message intended for display to the debtor only. It can be used to provide debtor-facing payment details or context. Availability depends on bank support and is included only when accepted by the receiving institution. RemittanceInformationMessage: type: object required: - type - value properties: type: type: string enum: - message value: type: string description: Message for receiver example: Payment for invoice 12345 debtorReference: type: string description: > Reference text or message intended for display to the debtor only. It can be used to provide debtor-facing payment details or context. Availability depends on bank support and is included only when accepted by the receiving institution. RemittanceInformationFik: allOf: - type: object required: - type - paymentType properties: type: type: string enum: - fik paymentType: type: string enum: - TYPE_01 - TYPE_04 - TYPE_15 - TYPE_71 - TYPE_73 - TYPE_75 message: type: string example: Message for receiver ocr: type: string example: 0 debtorReference: type: string description: > Reference text or message intended for display to the debtor only. It can be used to provide debtor-facing payment details or context. Availability depends on bank support and is included only when accepted by the receiving institution. ApprovalStatus: type: object required: - id - status properties: id: type: string format: uuid description: >- An ID that can be used to identify the approval and check for statuses example: 7c628b2e-9094-4bf8-af23-1d517c6fc4f5 status: type: string enum: - STARTED - ACCEPTED - REJECTED - CANCELLED sca: allOf: - $ref: '#/components/schemas/Sca' description: > There is no guarantee that the used sca approach used by bank matches the preferred sca approach from request. * `redirect` For redirect, the end user must use the redirect url to start the authentication process * `qr` The QR image has to be presented to the end user, who has to scan the image with bank authentication app. The qr image needs to be refreshed every second, see approval status for refreshed QR image. Only used in Sweden CreateDomesticPaymentResponse: type: object required: - paymentId - paymentStatus properties: paymentId: type: string format: uuid description: Used for approval and status check example: 7c628b2e-9094-4bf8-af23-1d517c6fc4f5 paymentStatus: $ref: '#/components/schemas/PaymentStatus' CreateBulkRequest: type: object properties: payments: type: array items: oneOf: - title: Domestic payment allOf: - type: object properties: type: type: string enum: - domestic - $ref: '#/components/schemas/CreateDomesticPaymentRequest' - title: Cross-border payment allOf: - type: object properties: type: type: string enum: - cross-border required: - type - $ref: '#/components/schemas/CrossBorderPaymentRequest' minItems: 1 callbackUrl: type: string description: Sca callback url for redirect authentication example: https://www.google.com required: - payments - callbackUrl CrossBorderPaymentRequest: type: object required: - metadata - from - to - amount - dueDate - remittanceInformation properties: metadata: $ref: '#/components/schemas/PaymentMetadata' from: $ref: '#/components/schemas/From' to: $ref: '#/components/schemas/To' amount: $ref: '#/components/schemas/AmountAndCurrency' dueDate: type: string format: date description: > The due date for the psd2 transaction from user account to ZTL client account. Payout to creditor account are usually 2 business days later remittanceInformation: type: object required: - message properties: message: type: string additionalInformation: type: array items: type: object properties: type: type: string enum: - TaxCode - Reason - Purpose description: > Type of additional information. Must be compliant with receiving country rules * `Reason` Text to describe the reason for payment * `Purpose` A valid PurposeCode of the payment * `TaxCode` Receiver Tax code example: Reason value: type: string description: Value of the property debtorReference: type: string description: > Reference text or message intended for display to the debtor only. It can be used to provide debtor-facing payment details or context. Availability depends on bank support and is included only when accepted by the receiving institution. regulatoryReporting: type: object description: >- Information used for regulatory reporting, only applicable in Norway and Sweden. Required for payments above 100 000 NOK in Norway, and 150 000 SEK in Sweden. required: - code properties: code: type: string description: Code used for regulatory reporting example: '14' information: type: string description: Information for regulatory reporting, only applicable in Norway CrossBorderPaymentResponse: type: object required: - paymentId - paymentStatus properties: paymentId: type: string paymentStatus: $ref: '#/components/schemas/PaymentStatus' costAmount: $ref: '#/components/schemas/AmountAndCurrency' exchangeRate: type: string description: The exchange rate per single unit example: 1.0346 quoteExpiryTime: type: string format: datetime, ISO-8601 example: '2023-01-15T09:32:00+01:00' description: >- Expiry time for quote, the payment may be automatically cancelled by ZTL if it's not signed before this deadline intermediaryAccount: type: object description: >- The Client account for the funding domestic psd2 transaction related to the payment. Account owned by ZTL. allOf: - $ref: '#/components/schemas/Beneficiary' ContactInformation: type: object required: - name properties: name: type: string description: The name of the organization example: ZTL Payment Solution AS telephoneNumber: type: string description: Phone number for the organization example: '+4740000858' address: type: object description: Address information for payee properties: streetName: type: string description: Street name example: Akersgata buildingNumber: type: string description: Building number example: '32' city: type: string description: City or town name example: Oslo postCode: type: string description: Post code example: '0180' country: type: string description: Country format: ISO 3166-1 example: 'NO' PaymentMetadata: type: object required: - endToEndId properties: endToEndId: type: string description: External EndToEndId for the payment AccountBban: type: object required: - type - bic - bban properties: type: type: string enum: - bban bic: type: string description: Bank Identification Code example: ESSESESS bban: type: string description: Bank Account number in Bban format example: 12341212345 ContactInformation-2: type: object required: - name - address properties: name: type: string description: > The name of the organization. Maximum length depends on whether the payment includes currency exchange: - Without currency exchange: check debtor bank maxInformationFieldLength requirements - With currency exchange: 70 characters example: ZTL Payment Solution AS address: type: object required: - streetName - buildingNumber - city - postCode - country description: Address information for payee properties: streetName: type: string description: Street name example: Akersgata buildingNumber: type: string description: Building number example: 32 city: type: string description: City or town name example: Oslo postCode: type: string description: Post code example: '0180' country: type: string description: Country format: ISO 3166-1 example: 'NO' From: type: object required: - account - contactInformation - currency properties: account: $ref: '#/components/schemas/AccountBban' contactInformation: allOf: - $ref: '#/components/schemas/ContactInformation-2' - type: object properties: telephoneNumber: type: string description: Phone number for the organization example: '+4740000858' currency: type: string description: Sender accounts Currency example: NOK organizationNumber: type: string description: Organization number for the company example: 920970931 AccountBbanWithClearingCode: type: object required: - type - bic - bban properties: type: type: string enum: - bban bic: type: string description: Bank Identification Code example: ESSESESS bban: type: string description: Bank Account number in Bban format example: 12341212345 clearingCode: type: string description: Code required for payments to certain countries example: 1234 AccountIban: type: object required: - type - bic - iban properties: type: type: string enum: - iban bic: type: string description: Bank Identification Code example: ESSESESS iban: type: string description: Bank account number in Iban format. example: SE7250000000012341212345 To: type: object required: - account - contactInformation properties: account: anyOf: - $ref: '#/components/schemas/AccountBbanWithClearingCode' - $ref: '#/components/schemas/AccountIban' contactInformation: $ref: '#/components/schemas/ContactInformation-2' telephoneNumber: null BeneficiaryAccount: type: object description: Account information for creditor properties: iban: type: string description: International Bank Account Number example: SE7250000000012341212345 bban: type: string description: Basic Bank Account Number example: 12341212345 bic: type: string description: Bank Identification Code example: ESSESESS clearingCode: type: string description: Code required for payments to certain countries example: 1234 AddressTo: type: object description: Address information for payee required: - streetName - buildingNumber - city - postCode - country properties: streetName: type: string description: Street name example: Eriksbergsgatan buildingNumber: type: string description: Building number example: 10 city: type: string description: City or town name example: Sweden postCode: type: string description: Post code example: 11430 country: type: string description: Country format: ISO 3166-1 example: SE ContactInformationTo: type: object required: - name - address properties: name: type: string description: The name of the organization making the payment example: ZTL Payment Solution AS address: type: object description: The address of the organization making the payment allOf: - $ref: '#/components/schemas/AddressTo' Beneficiary: type: object required: - account - contactInformation properties: account: type: object description: >- Account information for creditor. Required fields depend on creditorCountry, but bban or iban should always be present. allOf: - $ref: '#/components/schemas/BeneficiaryAccount' contactInformation: type: object description: Creditor contact information allOf: - $ref: '#/components/schemas/ContactInformationTo' GeneralErrorWithoutExampleObject: allOf: - $ref: '#/components/schemas/GeneralErrorObject' - type: object properties: message: type: string description: The underlying reason for the error Company: type: object properties: organizationNumber: type: string activeSubscription: type: boolean description: Payroll cancellation response SupportedCompanyType: required: - code - description type: object properties: code: type: string example: AS description: Company type code description: type: string description: Company type description example: Aksjeselskap GeneralProblem: type: object required: - title properties: type: type: string format: uri description: Type of error, used to group similar errors title: type: string description: The title of the error detail: type: string description: Detailed information of the error cause instance: type: string description: Endpoint that caused the failure request traceId: type: string description: ID to identify the failure request example: type: urn:quote-failed title: Payment rejected detail: null instance: /api/payments/56563af2-a199-44ec-92a1-d77eed2d8562/status QuoteValidationFailed: type: object properties: code: type: string example: InvalidFromAccount description: > The validation error code. Possible values: - `InvalidCreationTime`: Payment initiation is not supported during weekends/bank holidays - `InvalidDueDate`: Available due date range is dependent on initiation time - `InvalidFromAccount`: Sender's and recipient's account numbers cannot have the same value - `InvalidFromCountry`: Provided sender's country does not match provided sender's BIC - `InvalidToAddress`: One of the recipient's address fields are invalid (specified in the reason field) - `InvalidToAccount`: IBAN and BBAN values cannot be equal - `InvalidBbanOrIban`: Either IBAN or BBAN must be provided for the recipient account - `InvalidIban`: IBAN is either missing or invalid - `IbanBicMismatch`: The IBAN does not match the provided BIC - `InvalidBIC`: BIC is either missing or invalid - `InvalidBeneficiaryCountry`: Recipient's country is not supported - `InvalidAmount`: Requested amount exceeds the limit amount of the currency for the chosen due date - `InvalidQuoteCurrencyScale`: Invalid scale for requested currency - `InvalidCurrency`: Given currency is not accepted by the recipient's country - `CurrencyPairMismatch`: Funding currency and requested currency cannot be the same - `InvalidRecipientInfo`: Recipient country specific payment requirements are not met (check /api/country/{country}/paymentrequirement for specifics) - `InvalidRemittanceInformation`: (Additional) remittance information is missing or invalid enum: - InvalidCreationTime - InvalidDueDate - InvalidFromAccount - InvalidFromCountry - InvalidToAddress - InvalidToAccount - InvalidBbanOrIban - InvalidIban - IbanBicMismatch - InvalidBIC - InvalidBeneficiaryCountry - InvalidAmount - InvalidQuoteCurrencyScale - InvalidCurrency - CurrencyPairMismatch - InvalidRecipientInfo - InvalidRemittanceInformation reason: type: string description: The underlying reason for the error example: InvalidToAccount path: type: string description: Path to the related input param with validation error example: .from.bban MalformedRequestBody: type: object properties: code: type: string description: The parsing error type example: InvalidJsonRequest reason: type: string description: The underlying reason for the error example: Malformed request body path: type: string description: Path to the related input param with parsing error example: .from.bban QuoteRequest: type: object required: - metadata - from - to - amount - dueDate - remittanceInformation properties: metadata: type: object description: Metadata for quote request allOf: - $ref: '#/components/schemas/QuoteMetadata' from: type: object description: Information about the debtor allOf: - $ref: '#/components/schemas/QuoteFrom' to: type: object description: Information about the creditor allOf: - $ref: '#/components/schemas/QuoteTo' amount: type: object description: The amount and currency for the quote allOf: - $ref: '#/components/schemas/QuoteRequestedAmount' dueDate: type: string format: date, ISO-8601 description: >- The due date for the payment. NOTE: there are limitations on due date in the further example: '2023-01-15' remittanceInformation: type: object description: Remittance information allOf: - $ref: '#/components/schemas/QuoteRemittanceInformation' purposeCode: type: string description: >- A code stating the purpose of the payment. (Required by some countries). Deprecated - use Information.RemittanceInformation.AdditionalInformation (type - Purpose) instead example: S1008 deprecated: true QuoteResponse: type: object required: - quoteId - endToEndId - requestedAmount - costAmount - exchangeRate - quoteExpiryTime - referenceCode - intermediaryAccount properties: quoteId: type: string description: The quote ID to use for booking format: UUID example: d6f06bfe-4830-4358-b483-c24c66cfb431 endToEndId: type: string description: An ID that can be used to identify the payment example: 7c628b2e-9094-4bf8-af23-1d517c6fc4f5 requestedAmount: type: object description: The amount and currency that will be paid out allOf: - $ref: '#/components/schemas/QuoteRequestedAmount' costAmount: type: object description: >- The amount and currency of the resulting cost (funding) for the quote allOf: - $ref: '#/components/schemas/QuoteCostAmount' exchangeRate: type: string description: The exchange rate per single unit example: 1.0346 quoteExpiryTime: type: string format: datetime, ISO-8601 example: '2023-01-15T09:32:00+01:00' referenceCode: type: string description: >- The reference code to add to the payment's unstructured remittance info example: ZTL-d6f06bfe intermediaryAccount: type: object description: The account to deposit funding amount to when initiating payment allOf: - $ref: '#/components/schemas/QuoteIntermediaryAccount' QuoteRequestedAmount: type: object required: - amount - currency properties: amount: type: string description: The amount to get a quote for example: '1000.50' currency: type: string description: The currency the amount is specified in example: SEK QuoteCostAmount: type: object required: - amount - currency properties: amount: type: string description: The amount it will cost to buy the requested / quoted amount example: 1034.62 currency: type: string description: The currency the amount is specified in example: NOK QuoteRemittanceInformation: type: object required: - unstructured properties: unstructured: type: string description: Message for receiver example: Payment for consulting services additionalInformation: type: array items: type: object required: - type - value properties: type: type: string enum: - TaxCode - Reason - Purpose description: > Type of additional information. Must be compliant with receiving country rules * `Reason` Text to describe the reason for payment * `Purpose` A valid PurposeCode of the payment * `TaxCode` Receiver Tax code example: Reason value: type: string description: Value of the property QuoteFrom: type: object required: - bban - bic - contactInformation - currency - country properties: bban: type: string description: Basic Bank Account Number example: 12341212345 bic: type: string description: Bank Identification Code example: DNBANOKK contactInformation: type: object description: Debtor contact information allOf: - $ref: '#/components/schemas/QuoteContactInformation' currency: type: string description: The base(funding) currency for the payment example: NOK country: type: string format: ISO 3166-1 description: The country that the payment is being initiated from example: 'NO' QuoteIntermediaryAccount: type: object required: - account - contactInformation properties: account: type: object description: Account information for funding client account required: - iban - bban - bic properties: iban: type: string description: International Bank Account Number example: SE7250000000012341212345 bban: type: string description: Basic Bank Account Number example: 12341212345 bic: type: string description: Bank Identification Code example: CITIXXXX contactInformation: type: object description: Creditor contact information allOf: - $ref: '#/components/schemas/QuoteContactInformationTo' QuoteTo: type: object required: - account - contactInformation properties: account: type: object description: >- Account information for creditor. Required fields depend on creditorCountry, but bban or iban should always be present. allOf: - $ref: '#/components/schemas/QuoteAccount' contactInformation: type: object description: Creditor contact information allOf: - $ref: '#/components/schemas/QuoteContactInformationTo' currency: type: string description: The payout currency for the payment (only used for SELL deal type) example: SEK QuoteContactInformationTo: type: object required: - name - address properties: name: type: string description: The name of the organization making the payment example: ZTL Payment Solution AS address: type: object description: The address of the organization making the payment allOf: - $ref: '#/components/schemas/QuoteAddressTo' QuoteContactInformation: type: object required: - name - address properties: name: type: string description: The name of the organization making the payment example: ZTL Payment Solution AS address: type: object description: The address of the organization making the payment allOf: - $ref: '#/components/schemas/QuoteAddress' QuoteAddress: type: object description: Address information for payer required: - streetName - buildingNumber - city - postCode - country properties: streetName: type: string description: Street name example: Kristian IVs gate buildingNumber: type: string description: Building number example: 15 city: type: string description: City or town name example: Oslo postCode: type: string description: Post code example: '0164' country: type: string description: Country format: ISO 3166-1 example: 'NO' QuoteAddressTo: type: object description: Address information for payee required: - streetName - buildingNumber - city - postCode - country properties: streetName: type: string description: Street name example: Eriksbergsgatan buildingNumber: type: string description: Building number example: 10 city: type: string description: City or town name example: Sweden postCode: type: string description: Post code example: 11430 country: type: string description: Country format: ISO 3166-1 example: SE QuoteMetadata: type: object description: Quote request metadata required: - organizationCountryCode - organizationNumber - endToEndId properties: organizationCountryCode: type: string description: Country format: ISO 3166-1 example: 'NO' organizationNumber: type: string description: The organization number of the company initiating the payment example: 920970931 endToEndId: type: string description: An ID that can be used to identify the payment example: 73300aef-d849-4872-b0c6-f44e07a841f3 QuoteAccount: type: object description: Account information for creditor required: - bic properties: iban: type: string description: International Bank Account Number example: SE7250000000012341212345 bban: type: string description: Basic Bank Account Number example: 12341212345 bic: type: string description: Bank Identification Code example: ESSESESS clearingCode: type: string description: Code required for payments to certain countries example: 1234 SupportedCurrency: required: - code - currencyName - isoScale - symbol - maxForwardTransactionAmount type: object properties: code: type: string example: EUR description: 3 letter currency code as defined by ISO-4217 format: iso-4217 currencyName: type: string description: The currency name in English as defined by ISO-4217 example: Euro isoScale: type: integer description: >- Number of decimals after the comma separator as defined by ISO-4217, used when displaying amounts in the given currency. E.g. 100 EUR is displayed as 100.00, while 100 JPY is displayed as 100 example: 2 symbol: type: string example: € maxForwardTransactionAmount: type: number description: > The maximum allowable amount for a transaction involving currency exchange that is classified as a *forward payment*. Transactions with a due date of today or tomorrow are considered *spot payments* and are not subject to this limit. Transactions with later due dates are considered *forward payments* and are restricted by this maximum amount. example: 0 Iban: type: object description: Country supports Iban bank account format. properties: type: type: string enum: - iban Swift: type: object description: >- Country supports Swift bank account format. A combination of BIC and local bank account number (bban) is required properties: type: type: string enum: - swift SwiftWithBankRouting: type: object description: >- Country supports Swift bank account format with additional bank routing/clearing code. A combination of BIC, local bank account number (bban) and BankRouting/ClearingCode is required properties: type: type: string enum: - swiftBankRouting routingName: type: string description: Local name for routingnumber/clearingnumber example: IFSC routingDescription: type: string description: >- Description of the required routingnumber/clearingnumer for the receiver country routingPattern: type: string description: ReqEx pattern for the routingnumber/clearingnumber value AdditionalRemittanceInformationRequired: type: object properties: type: type: string enum: - additionalRemittanceInformationRequired description: type: string description: Text description of the requirement requirementType: type: string enum: - PurposeCode - TaxCode - Reason description: > * `PurposeCode` A valid purpose code, either from validCodes list or pattern * `TaxCode` The receivers TaxId are required * `Reason` A reason for the payment (text) must be provided pattern: type: string description: RegEx pattern used to validate the value validCodes: type: array description: A list of accepted codes for the value items: type: object properties: code: type: string description: description: Description of the value type: string painArrayIndex: type: integer description: >- Pain XLM Array index for this value in unstructured remittance info (V1 payment only) responses: GeneralError: description: General error headers: ztl-request-id: description: Unique RequestId, please provide this Id in case of support requests schema: type: string format: uuid example: 3a797348-ef0c-4f52-b821-fdfcdb98c4d9 content: application/json: schema: $ref: '#/components/schemas/GeneralErrorObject' ForbiddenError: description: General error headers: ztl-request-id: description: Unique RequestId, please provide this Id in case of support requests schema: type: string format: uuid example: 3a797348-ef0c-4f52-b821-fdfcdb98c4d9 content: application/json: schema: $ref: '#/components/schemas/ForbiddenErrorObject' ValidationPayrollResponse: description: Input validation fails content: application/json: schema: type: array items: type: object properties: code: type: string enum: - InvalidDueDate - InvalidAmount - InvalidBBAN - InvalidRequest - InvalidCharacters - SenderNameTooLong - RecipientNameTooLong - InvalidAccountNumber - InvalidRemittanceInfo description: The error code reason: type: string description: The underlying reason for the error example: Due date cannot be in the past path: type: string description: Path from request body where the validation failed example: .dueDate PayrollBadRequest: description: Bad Request content: application/json: schema: type: object required: - ztlRequestId - message properties: failure: type: string enum: - INVALID_CONSENT - AUTHENTICATION_TEMPORARY_UNAVAILABLE - UNSUPPORTED_PRODUCT_BY_BANK description: > * `INVALID_CONSENT` Consent is invalid * `AUTHENTICATION_TEMPORARY_UNAVAILABLE` Authentication service is temporary unavailable, most likely due to user already has started another concurrent authentication process * `UNSUPPORTED_PRODUCT_BY_BANK` Product is not supported by bank ztlRequestId: type: string format: uuid description: >- Unique RequestId, please provide this Id in case of support requests example: 3a797348-ef0c-4f52-b821-fdfcdb98c4d9 message: type: string description: The underlying reason for the error example: Invalid Bban PayrollInitiationBadRequest: description: Bad Request content: application/json: schema: type: object required: - ztlRequestId - message properties: failure: type: string enum: - INVALID_CONSENT - AUTHENTICATION_TEMPORARY_UNAVAILABLE - UNSUPPORTED_PRODUCT_BY_BANK - INVALID_OCR - ACCESS_DENIED description: > * `INVALID_CONSENT` Consent is invalid * `AUTHENTICATION_TEMPORARY_UNAVAILABLE` Authentication service is temporary unavailable, most likely due to user already has started another concurrent authentication process * `UNSUPPORTED_PRODUCT_BY_BANK` Product is not supported by bank * `INVALID_OCR` OCR is either missing or invalid, or invalid OCR agreement * `ACCESS_DENIED` PSU does not have access to resource. Ensure debtorAccount is correct and user have payment access to account. ztlRequestId: type: string format: uuid description: >- Unique RequestId, please provide this Id in case of support requests example: 3a797348-ef0c-4f52-b821-fdfcdb98c4d9 message: type: string description: The underlying reason for the error example: Invalid Bban ValidationResponse: description: Input validation fails content: application/json: schema: type: array items: type: object properties: code: type: string enum: - InvalidBBAN - SenderNameTooLong - RecipientNameTooLong - InvalidAccountNumber - InvalidAmount - InvalidDueDate - InvalidRemittanceInfo - InvalidCharacters - InvalidRequest description: The error code reason: type: string description: The underlying reason for the error example: Due date cannot be in the past path: type: string description: Path from request body where the validation failed example: .dueDate CrossBorderValidationResponse: description: Input validation fails content: application/json: schema: type: array items: type: object properties: code: type: string enum: - InvalidRequest - InvalidCreationTime - InvalidDueDate - IbanBicMismatch - InvalidIbanFormat - InvalidFromAccount - InvalidBbanOrIban - InvalidForwardAmount - InvalidForwardCurrency - InvalidQuoteCurrencyScale - InvalidForwardExchangeServiceTime - InvalidJsonRequest - InvalidBeneficiaryCountry - InvalidBIC - InvalidToAddress description: The error code reason: type: string description: The underlying reason for the error example: Invalid account path: type: string description: Path for the error example: .from.account BulkValidationResponse: description: Bulk input validation fails content: application/json: schema: type: array items: type: object properties: code: type: string enum: - InvalidBBAN - SenderNameTooLong - RecipientNameTooLong - InvalidAccountNumber - InvalidAmount - InvalidDueDate - InvalidRemittanceInfo - InvalidCharacters - InvalidRequest - InvalidBulkSize - InvalidCreationTime - IbanBicMismatch - InvalidIbanFormat - InvalidFromAccount - InvalidBbanOrIban - InvalidForwardAmount - InvalidForwardCurrency - InvalidQuoteCurrencyScale - InvalidForwardExchangeServiceTime - InvalidJsonRequest - InvalidBeneficiaryCountry - InvalidBIC - InvalidToAddress description: The error code reason: type: string description: The underlying reason for the error example: EndToEndId must be unique within the same bulk path: type: string description: Path for the error example: .payments endToEndId: type: string nullable: true description: >- End-to-end identifier of the payment that failed validation, when available example: '197102754228134604603270233998' PaymentBadRequest: description: Bad Request content: application/json: schema: type: object required: - ztlRequestId - message properties: failure: type: string enum: - INVALID_CONSENT - AUTHENTICATION_TEMPORARY_UNAVAILABLE - UNSUPPORTED_PRODUCT_BY_BANK - ACCESS_DENIED description: > * `INVALID_CONSENT` Consent is invalid * `AUTHENTICATION_TEMPORARY_UNAVAILABLE` Authentication service is temporary unavailable, most likely due to user already has started another concurrent authentication process * `UNSUPPORTED_PRODUCT_BY_BANK` Product is not supported by bank * `ACCESS_DENIED` User does not have sufficient permissions ztlRequestId: type: string format: uuid description: >- Unique RequestId, please provide this Id in case of support requests example: 3a797348-ef0c-4f52-b821-fdfcdb98c4d9 message: type: string description: The underlying reason for the error example: Invalid Bban PaymentInitiationBadRequest: description: Bad Request content: application/json: schema: type: object required: - ztlRequestId - message properties: failure: type: string enum: - INVALID_CONSENT - AUTHENTICATION_TEMPORARY_UNAVAILABLE - UNSUPPORTED_PRODUCT_BY_BANK - INVALID_OCR - ACCESS_DENIED description: > * `INVALID_CONSENT` Consent is invalid * `AUTHENTICATION_TEMPORARY_UNAVAILABLE` Authentication service is temporary unavailable, most likely due to user already has started another concurrent authentication process * `UNSUPPORTED_PRODUCT_BY_BANK` Product is not supported by bank * `INVALID_OCR` OCR is either missing or invalid, or invalid OCR agreement * `ACCESS_DENIED` PSU does not have access to resource. Ensure debtorAccount is correct and user have payment access to account. ztlRequestId: type: string format: uuid description: >- Unique RequestId, please provide this Id in case of support requests example: 3a797348-ef0c-4f52-b821-fdfcdb98c4d9 message: type: string description: The underlying reason for the error example: Invalid Bban CrossBorderInitiationBadRequest: description: Bad Request content: application/json: schema: type: object required: - ztlRequestId - message properties: failure: type: string enum: - MAX_AMOUNT_EXCEEDED - SERVICE_CLOSED - UNSUPPORTED_DUE_DATE - INVALID_CONSENT - AUTHENTICATION_TEMPORARY_UNAVAILABLE - UNSUPPORTED_PRODUCT_BY_BANK - ACCESS_DENIED description: > * `MAX_AMOUNT_EXCEEDED` Max amount exceeded for currency with due date in future, change due-date to today * `SERVICE_CLOSED` Service is currently closed * `UNSUPPORTED_DUE_DATE` Due date is not supported for the currency/due-date pair * `INVALID_CONSENT` Consent is invalid * `AUTHENTICATION_TEMPORARY_UNAVAILABLE` Authentication service is temporary unavailable, most likely due to user already has started another concurrent authentication process * `UNSUPPORTED_PRODUCT_BY_BANK` Product is not supported by bank * `ACCESS_DENIED` PSU does not have access to resource. Ensure debtorAccount is correct and user have payment access to account. ztlRequestId: type: string format: uuid description: >- Unique RequestId, please provide this Id in case of support requests example: 3a797348-ef0c-4f52-b821-fdfcdb98c4d9 message: type: string description: The underlying reason for the error example: >- Max amount exceeded for currency with due date in future, change due-date to today GeneralErrorWithoutExample: description: General error headers: ztl-request-id: description: Unique RequestId, please provide this Id in case of support requests schema: type: string format: uuid example: 3a797348-ef0c-4f52-b821-fdfcdb98c4d9 content: application/json: schema: $ref: '#/components/schemas/GeneralErrorWithoutExampleObject' securitySchemes: Authorization: type: oauth2 flows: clientCredentials: tokenUrl: https://oidc.sandbox.ztlpay-test.io/connect/token scopes: payments: ZTL PSD2 API