openapi: 3.1.0 info: version: v2.0 title: ZTL OpenAPI license: name: Apache 2.0 identifier: Apache-2.0 description: | # ZTL API The ZTL API supports authentication, company onboarding, bank consent, account information, domestic and cross-border payments, payroll, companies, FX, currencies, and country requirements. Download this exact contract at . ## Partner journey 1. Obtain credentials and fetch an access token. 2. Onboard the company and poll until its status is `Accepted`. 3. Create bank consent and let the user complete SCA. 4. Retrieve and store the authorized accounts. 5. Create a payment or payroll. 6. Start the separate approval phase and let the user complete SCA. 7. Poll the resource until every transaction reaches a final state. ## Request headers Most responses include `ztl-request-id`. Log it with the relevant resource identifier so ZTL support can trace an operation. Some endpoints use `PSU-IP-Address` and `PSU-User-Agent` to state that the end user is actively present. Forward only values observed from the current user session. Never fabricate them, send your server's values, or replay stored values. ## Errors and compatibility Check the HTTP status and then parse the structured failure body defined by the operation. Capture `ztl-request-id` from the header and body when present. New failure codes and status enum values can be added, so clients must preserve and safely handle unknown values. Reconcile ambiguous create or approval outcomes through stored resource IDs, partner references, status operations, and request IDs before sending another request. ## Environments | Resource | Sandbox | Production | | --- | --- | --- | | API | `https://api.sandbox.ztlpay-test.io` | `https://api.ztlpay.io` | | Authentication | `https://oidc.sandbox.ztlpay-test.io` | `https://oidc.ztlpay.io` | | Onboarding | `https://welcome.sandbox.ztlpay-test.io/onboarding` | `https://welcome.ztlpay.io/onboarding` | Supported banks, countries, currencies, and partner enablement must be read from the relevant API and confirmed with ZTL for the target environment. ## Workflow guides - [Onboarding](/guides/onboarding/) - [Consent and account information](/guides/consent-and-accounts/) - [Domestic payments](/guides/domestic-payments/) - [Cross-border payments](/guides/cross-border-payments/) - [Payroll](/guides/payroll/) - [FX without bank integration](/guides/fx-payments/) tags: - name: Authentication description: | Obtain an access token from the current OIDC issuer. See the [authentication guide](/getting-started/authentication/) for safe token storage, reuse, and renewal. x-displayName: Authentication - name: Onboarding description: | Initiate company onboarding, inspect signer state, look up status, and cancel an eligible flow. See the [onboarding guide](/guides/onboarding/) for lifecycle, callback, restart, and country-testing guidance. x-displayName: Onboarding - name: Banks description: Discover supported bank products, branches, and constraints. See [capabilities and constraints](/getting-started/capabilities-and-constraints/). x-displayName: Banks - name: Consent description: | Create, poll, and revoke personal bank consent. See the [consent and account information guide](/guides/consent-and-accounts/). x-displayName: Consent - name: Accounts description: | Retrieve accounts, balances, entries, and entry details. See the [consent and account information guide](/guides/consent-and-accounts/). x-displayName: Accounts - name: Payroll description: | Create, approve, poll, and cancel Norway-only NOK payrolls. See the [payroll guide](/guides/payroll/) for status finality, funding stages, recipient outcomes, and the restricted bulk flow. x-displayName: Payroll - name: Payments description: | Create, approve, poll, cancel, and report domestic or cross-border payments. See the [domestic payment guide](/guides/domestic-payments/) and [cross-border guide](/guides/cross-border-payments/) for complete workflows. x-displayName: Payments - name: Companies description: Retrieve onboarded companies, supported company types, and subscription state. See [capabilities and constraints](/getting-started/capabilities-and-constraints/). x-displayName: Companies - name: Webhooks description: Manage event subscriptions for the authenticated partner. Subscribe to `PAYMENT_STATUS` for all public payment status changes, or a child type such as `PAYMENT_STATUS_COMPLETED` for one status. Events are delivered only for payments belonging to the authenticated partner. See the [webhook guide](/guides/webhooks/) for payloads, receiving, authenticating, and processing deliveries. x-displayName: Webhooks - name: FX Payments description: | Validate, quote, confirm, fund, poll, cancel, and report FX payments funded without ZTL bank integration. See the [FX guide](/guides/fx-payments/) for the exact ID transitions and workflow. x-displayName: FX Payments - name: Currencies description: Discover supported currencies. See [capabilities and constraints](/getting-started/capabilities-and-constraints/). x-displayName: Currencies - name: Country description: Discover destinations and country-specific payment requirements. See [capabilities and constraints](/getting-started/capabilities-and-constraints/). x-displayName: Country paths: /v2/connect/token: servers: - url: https://oidc.ztlpay.io description: Production environment - url: https://oidc.sandbox.ztlpay-test.io description: Sandbox environment post: summary: Fetch OIDC access token description: Use this endpoint for sandbox and production. security: [] operationId: fetchAccessTokenNewIssuer tags: - Authentication x-codeSamples: - lang: bash label: Sandbox request source: | curl --request POST \ --url https://oidc.sandbox.ztlpay-test.io/v2/connect/token \ --header 'content-type: application/x-www-form-urlencoded' \ --data-urlencode 'client_id=YOUR_CLIENT_ID' \ --data-urlencode 'client_secret=YOUR_CLIENT_SECRET' \ --data-urlencode 'grant_type=client_credentials' \ --data-urlencode 'scope=api://ac0d1aea-5e3a-463f-9dd1-194898ee5820/.default' - lang: bash label: Production request source: | curl --request POST \ --url https://oidc.ztlpay.io/v2/connect/token \ --header 'content-type: application/x-www-form-urlencoded' \ --data-urlencode 'client_id=YOUR_CLIENT_ID' \ --data-urlencode 'client_secret=YOUR_CLIENT_SECRET' \ --data-urlencode 'grant_type=client_credentials' \ --data-urlencode 'scope=api://1f115cad-5576-4db9-a7f9-8921c47a86e4/.default' 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 provided by ZTL. client_secret: type: string description: Client secret provided by ZTL. grant_type: type: string description: Must 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 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: Access token. type: string example: jwt example: token_type: Bearer expires_in: 3599 ext_expires_in: 3599 access_token: jwt "401": description: Client authentication failed. content: application/json: schema: type: object /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 - "null" description: Additional context related to the error properties: onboardingId: type: - string - "null" format: uuid description: | The ID of the onboarding used to onboard the existing company. This onboarding is always in status `Accepted` and cannot be modified. `onboardingId` and `additionalInformation` can be null when the original onboarding details are unavailable. example: 9256411a-5c80-40e5-b50c-768dbca443af "500": $ref: "#/components/responses/GeneralError" description: Internal server error "503": $ref: "#/components/responses/GeneralError" description: Service unavailable security: - OAuth2Sandbox: - api://ac0d1aea-5e3a-463f-9dd1-194898ee5820/.default - OAuth2Production: - api://1f115cad-5576-4db9-a7f9-8921c47a86e4/.default /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: In production, ManualHandling is only available for Norway. enum: - Created - AwaitingCustomerAction - Processing - ManualHandling - Accepted - Rejected signingStatus: type: - object - "null" 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 - "null" status: type: string enum: - Signed - Unsigned signingUrl: type: - string - "null" documentSignature: type: - object - "null" properties: signatureMethod: type: - string - "null" fullName: type: - string - "null" firstName: type: - string - "null" lastName: type: - string - "null" middleName: type: - string - "null" signedTime: type: - string - "null" dateOfBirth: type: - string - "null" 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 security: - OAuth2Sandbox: - api://ac0d1aea-5e3a-463f-9dd1-194898ee5820/.default - OAuth2Production: - api://1f115cad-5576-4db9-a7f9-8921c47a86e4/.default /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`. 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: In production, ManualHandling is only available for Norway. enum: - Created - AwaitingCustomerAction - Processing - ManualHandling - Accepted - Rejected signingStatus: type: - object - "null" 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 - "null" status: type: string enum: - Signed - Unsigned signingUrl: type: - string - "null" documentSignature: type: - object - "null" properties: signatureMethod: type: - string - "null" fullName: type: - string - "null" firstName: type: - string - "null" lastName: type: - string - "null" middleName: type: - string - "null" signedTime: type: - string - "null" dateOfBirth: type: - string - "null" 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 security: - OAuth2Sandbox: - api://ac0d1aea-5e3a-463f-9dd1-194898ee5820/.default - OAuth2Production: - api://1f115cad-5576-4db9-a7f9-8921c47a86e4/.default /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. Its not be used without prior agreement, please contact your partner success manager in ZTL. 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 security: - OAuth2Sandbox: - api://ac0d1aea-5e3a-463f-9dd1-194898ee5820/.default - OAuth2Production: - api://1f115cad-5576-4db9-a7f9-8921c47a86e4/.default /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 security: - OAuth2Sandbox: - api://ac0d1aea-5e3a-463f-9dd1-194898ee5820/.default - OAuth2Production: - api://1f115cad-5576-4db9-a7f9-8921c47a86e4/.default /onboarding/international-payments-enablement/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 international payments enablement status description: Returns the international payments enablement status for an existing company belonging to the authenticated partner. operationId: getInternationalPaymentsEnablementStatusByOrganization parameters: - $ref: "#/components/parameters/AuthorizationJwtHeader" - name: country in: query required: true description: Country code for the company example: SE schema: type: string - name: organizationNumber in: query required: true description: Organization number for the company example: "5569994600" schema: type: string responses: "200": description: International payments enablement status headers: ztl-request-id: $ref: "#/components/headers/ztl-request-id" content: application/json: schema: type: object required: - status properties: status: type: string enum: - NOT_STARTED - STARTED - PENDING - ENABLED description: | Current international payments enablement status: * `NOT_STARTED`: The company is not enabled for international payments and the enablement flow has not been started. * `STARTED`: The enablement flow has been started but has not been submitted. * `PENDING`: The enablement request has been submitted and is pending review. * `ENABLED`: The company is enabled for international payments, regardless of how it was enabled. "400": $ref: "#/components/responses/GeneralError" description: Bad request "403": $ref: "#/components/responses/GeneralError" description: Forbidden "404": $ref: "#/components/responses/GeneralError" description: Company not found "500": $ref: "#/components/responses/GeneralError" description: Internal server error "503": $ref: "#/components/responses/GeneralError" description: Service unavailable security: - OAuth2Sandbox: - api://ac0d1aea-5e3a-463f-9dd1-194898ee5820/.default - OAuth2Production: - api://1f115cad-5576-4db9-a7f9-8921c47a86e4/.default /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 security: - OAuth2Sandbox: - api://ac0d1aea-5e3a-463f-9dd1-194898ee5820/.default - OAuth2Production: - api://1f115cad-5576-4db9-a7f9-8921c47a86e4/.default /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: - OAuth2Sandbox: - api://ac0d1aea-5e3a-463f-9dd1-194898ee5820/.default - OAuth2Production: - api://1f115cad-5576-4db9-a7f9-8921c47a86e4/.default /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. Create a consent for the current API before using account information or payment operations. 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: - OAuth2Sandbox: - api://ac0d1aea-5e3a-463f-9dd1-194898ee5820/.default - OAuth2Production: - api://1f115cad-5576-4db9-a7f9-8921c47a86e4/.default 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: - OAuth2Sandbox: - api://ac0d1aea-5e3a-463f-9dd1-194898ee5820/.default - OAuth2Production: - api://1f115cad-5576-4db9-a7f9-8921c47a86e4/.default 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: - OAuth2Sandbox: - api://ac0d1aea-5e3a-463f-9dd1-194898ee5820/.default - OAuth2Production: - api://1f115cad-5576-4db9-a7f9-8921c47a86e4/.default /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: - OAuth2Sandbox: - api://ac0d1aea-5e3a-463f-9dd1-194898ee5820/.default - OAuth2Production: - api://1f115cad-5576-4db9-a7f9-8921c47a86e4/.default /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: - OAuth2Sandbox: - api://ac0d1aea-5e3a-463f-9dd1-194898ee5820/.default - OAuth2Production: - api://1f115cad-5576-4db9-a7f9-8921c47a86e4/.default /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: - OAuth2Sandbox: - api://ac0d1aea-5e3a-463f-9dd1-194898ee5820/.default - OAuth2Production: - api://1f115cad-5576-4db9-a7f9-8921c47a86e4/.default /api/v2/accounts/{accountId}/entries/extended: 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, enriched with available transaction details. Detail enrichment is best-effort and support varies by bank. The maximum date range supported varies with banks, see Supported Banks-endpoint to retrieve the specific banks max date range. summary: Extended Account Entries operationId: accountEntriesExtendedV2 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 enriched 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: - OAuth2Sandbox: - api://ac0d1aea-5e3a-463f-9dd1-194898ee5820/.default - OAuth2Production: - api://1f115cad-5576-4db9-a7f9-8921c47a86e4/.default /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: - OAuth2Sandbox: - api://ac0d1aea-5e3a-463f-9dd1-194898ee5820/.default - OAuth2Production: - api://1f115cad-5576-4db9-a7f9-8921c47a86e4/.default /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: - OAuth2Sandbox: - api://ac0d1aea-5e3a-463f-9dd1-194898ee5820/.default - OAuth2Production: - api://1f115cad-5576-4db9-a7f9-8921c47a86e4/.default /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: - OAuth2Sandbox: - api://ac0d1aea-5e3a-463f-9dd1-194898ee5820/.default - OAuth2Production: - api://1f115cad-5576-4db9-a7f9-8921c47a86e4/.default /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 format: 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: - OAuth2Sandbox: - api://ac0d1aea-5e3a-463f-9dd1-194898ee5820/.default - OAuth2Production: - api://1f115cad-5576-4db9-a7f9-8921c47a86e4/.default /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: - OAuth2Sandbox: - api://ac0d1aea-5e3a-463f-9dd1-194898ee5820/.default - OAuth2Production: - api://1f115cad-5576-4db9-a7f9-8921c47a86e4/.default /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: - OAuth2Sandbox: - api://ac0d1aea-5e3a-463f-9dd1-194898ee5820/.default - OAuth2Production: - api://1f115cad-5576-4db9-a7f9-8921c47a86e4/.default /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 format: 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: - OAuth2Sandbox: - api://ac0d1aea-5e3a-463f-9dd1-194898ee5820/.default - OAuth2Production: - api://1f115cad-5576-4db9-a7f9-8921c47a86e4/.default /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: - OAuth2Sandbox: - api://ac0d1aea-5e3a-463f-9dd1-194898ee5820/.default - OAuth2Production: - api://1f115cad-5576-4db9-a7f9-8921c47a86e4/.default /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: - OAuth2Sandbox: - api://ac0d1aea-5e3a-463f-9dd1-194898ee5820/.default - OAuth2Production: - api://1f115cad-5576-4db9-a7f9-8921c47a86e4/.default /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: - OAuth2Sandbox: - api://ac0d1aea-5e3a-463f-9dd1-194898ee5820/.default - OAuth2Production: - api://1f115cad-5576-4db9-a7f9-8921c47a86e4/.default /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: - OAuth2Sandbox: - api://ac0d1aea-5e3a-463f-9dd1-194898ee5820/.default - OAuth2Production: - api://1f115cad-5576-4db9-a7f9-8921c47a86e4/.default /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 "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: - OAuth2Sandbox: - api://ac0d1aea-5e3a-463f-9dd1-194898ee5820/.default - OAuth2Production: - api://1f115cad-5576-4db9-a7f9-8921c47a86e4/.default /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: - OAuth2Sandbox: - api://ac0d1aea-5e3a-463f-9dd1-194898ee5820/.default - OAuth2Production: - api://1f115cad-5576-4db9-a7f9-8921c47a86e4/.default /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: - OAuth2Sandbox: - api://ac0d1aea-5e3a-463f-9dd1-194898ee5820/.default - OAuth2Production: - api://1f115cad-5576-4db9-a7f9-8921c47a86e4/.default /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: - OAuth2Sandbox: - api://ac0d1aea-5e3a-463f-9dd1-194898ee5820/.default - OAuth2Production: - api://1f115cad-5576-4db9-a7f9-8921c47a86e4/.default /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: - OAuth2Sandbox: - api://ac0d1aea-5e3a-463f-9dd1-194898ee5820/.default - OAuth2Production: - api://1f115cad-5576-4db9-a7f9-8921c47a86e4/.default /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" 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: - OAuth2Sandbox: - api://ac0d1aea-5e3a-463f-9dd1-194898ee5820/.default - OAuth2Production: - api://1f115cad-5576-4db9-a7f9-8921c47a86e4/.default /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" "403": description: Forbidden content: application/json: schema: $ref: "#/components/schemas/GeneralProblem" security: - OAuth2Sandbox: - api://ac0d1aea-5e3a-463f-9dd1-194898ee5820/.default - OAuth2Production: - api://1f115cad-5576-4db9-a7f9-8921c47a86e4/.default /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" "403": description: Forbidden content: application/json: schema: $ref: "#/components/schemas/GeneralProblem" security: - OAuth2Sandbox: - api://ac0d1aea-5e3a-463f-9dd1-194898ee5820/.default - OAuth2Production: - api://1f115cad-5576-4db9-a7f9-8921c47a86e4/.default /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: - OAuth2Sandbox: - api://ac0d1aea-5e3a-463f-9dd1-194898ee5820/.default - OAuth2Production: - api://1f115cad-5576-4db9-a7f9-8921c47a86e4/.default /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: - OAuth2Sandbox: - api://ac0d1aea-5e3a-463f-9dd1-194898ee5820/.default - OAuth2Production: - api://1f115cad-5576-4db9-a7f9-8921c47a86e4/.default /api/webhooks/subscription: servers: - url: https://api.ztlpay.io description: Production environment - url: https://api.sandbox.ztlpay-test.io description: Sandbox environment for testing post: tags: - Webhooks summary: Create webhook subscription description: Creates an enabled subscription. Earlier events are not replayed. The API access token authenticates this request; the optional bearerToken authenticates deliveries to your endpoint. operationId: createWebhookSubscription parameters: - $ref: "#/components/parameters/AuthorizationJwtHeader" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/WebhookSubscriptionCreateRequest" responses: "201": description: Subscription created. Store the returned signing secret securely. content: application/json: schema: $ref: "#/components/schemas/WebhookSubscriptionCreatedResponse" "400": description: Invalid target URL, event type, or bearer token. security: - OAuth2Sandbox: - api://ac0d1aea-5e3a-463f-9dd1-194898ee5820/.default - OAuth2Production: - api://1f115cad-5576-4db9-a7f9-8921c47a86e4/.default /api/webhooks/subscription/list: servers: - url: https://api.ztlpay.io description: Production environment - url: https://api.sandbox.ztlpay-test.io description: Sandbox environment for testing get: tags: - Webhooks summary: List webhook subscriptions operationId: listWebhookSubscriptions parameters: - $ref: "#/components/parameters/AuthorizationJwtHeader" responses: "200": description: Enabled and disabled subscriptions belonging to the authenticated partner. content: application/json: schema: type: array items: $ref: "#/components/schemas/WebhookSubscriptionResponse" "401": description: Authentication failed. security: - OAuth2Sandbox: - api://ac0d1aea-5e3a-463f-9dd1-194898ee5820/.default - OAuth2Production: - api://1f115cad-5576-4db9-a7f9-8921c47a86e4/.default /api/webhooks/subscription/{id}: servers: - url: https://api.ztlpay.io description: Production environment - url: https://api.sandbox.ztlpay-test.io description: Sandbox environment for testing parameters: - $ref: "#/components/parameters/AuthorizationJwtHeader" - $ref: "#/components/parameters/WebhookSubscriptionId" get: tags: - Webhooks summary: Get webhook subscription operationId: getWebhookSubscription responses: "200": description: Subscription belonging to the authenticated partner. content: application/json: schema: $ref: "#/components/schemas/WebhookSubscriptionResponse" "404": description: Subscription was not found. security: - OAuth2Sandbox: - api://ac0d1aea-5e3a-463f-9dd1-194898ee5820/.default - OAuth2Production: - api://1f115cad-5576-4db9-a7f9-8921c47a86e4/.default patch: tags: - Webhooks summary: Update webhook subscription description: Replace the endpoint and event types. Both fields are required. Use the bearer-token endpoint to set or rotate authentication. Already queued deliveries retain their original endpoint and credentials. operationId: updateWebhookSubscription requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/WebhookSubscriptionUpdateRequest" responses: "200": description: Updated subscription. content: application/json: schema: $ref: "#/components/schemas/WebhookSubscriptionResponse" "400": description: Invalid target URL or event type. "404": description: Subscription was not found. security: - OAuth2Sandbox: - api://ac0d1aea-5e3a-463f-9dd1-194898ee5820/.default - OAuth2Production: - api://1f115cad-5576-4db9-a7f9-8921c47a86e4/.default delete: tags: - Webhooks summary: Disable webhook subscription description: Stop queuing new events for this subscription. Already queued deliveries may still be sent. operationId: disableWebhookSubscription responses: "204": description: Subscription disabled. "404": description: Subscription was not found. security: - OAuth2Sandbox: - api://ac0d1aea-5e3a-463f-9dd1-194898ee5820/.default - OAuth2Production: - api://1f115cad-5576-4db9-a7f9-8921c47a86e4/.default /api/webhooks/subscription/{id}/rotate-secret: servers: - url: https://api.ztlpay.io description: Production environment - url: https://api.sandbox.ztlpay-test.io description: Sandbox environment for testing post: tags: - Webhooks summary: Rotate signing secret description: Already queued deliveries retain the previous signing secret. Allow an overlap period in your receiver while those deliveries finish. operationId: rotateWebhookSigningSecret parameters: - $ref: "#/components/parameters/AuthorizationJwtHeader" - $ref: "#/components/parameters/WebhookSubscriptionId" responses: "200": description: New signing secret. Store it securely; it cannot be retrieved again. content: application/json: schema: $ref: "#/components/schemas/WebhookSubscriptionSecretResponse" "404": description: Subscription was not found. security: - OAuth2Sandbox: - api://ac0d1aea-5e3a-463f-9dd1-194898ee5820/.default - OAuth2Production: - api://1f115cad-5576-4db9-a7f9-8921c47a86e4/.default /api/webhooks/subscription/{id}/rotate-bearer-token: servers: - url: https://api.ztlpay.io description: Production environment - url: https://api.sandbox.ztlpay-test.io description: Sandbox environment for testing post: tags: - Webhooks summary: Set or rotate bearer token description: Already queued deliveries retain the previous bearer token. Allow an overlap period in your receiver while those deliveries finish. operationId: rotateWebhookBearerToken parameters: - $ref: "#/components/parameters/AuthorizationJwtHeader" - $ref: "#/components/parameters/WebhookSubscriptionId" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/WebhookBearerTokenRequest" responses: "200": description: Updated subscription. The bearer token is not returned. content: application/json: schema: $ref: "#/components/schemas/WebhookSubscriptionResponse" "400": description: Bearer token must not be blank. "404": description: Subscription was not found. security: - OAuth2Sandbox: - api://ac0d1aea-5e3a-463f-9dd1-194898ee5820/.default - OAuth2Production: - api://1f115cad-5576-4db9-a7f9-8921c47a86e4/.default /api/webhooks/subscription/{id}/test: servers: - url: https://api.ztlpay.io description: Production environment - url: https://api.sandbox.ztlpay-test.io description: Sandbox environment for testing post: tags: - Webhooks summary: Test webhook delivery operationId: testWebhookSubscription description: Sends a `webhook.test` event regardless of selected event types and returns the immediate delivery result. The test event contains `id`, `type`, and `createdAt`. HTTP 200 is returned even when delivery fails; check `succeeded` and `error`. Retryable failures follow the normal delivery retry policy. parameters: - $ref: "#/components/parameters/AuthorizationJwtHeader" - $ref: "#/components/parameters/WebhookSubscriptionId" responses: "200": description: Test delivery result. Check `succeeded` before treating the endpoint as verified. content: application/json: schema: $ref: "#/components/schemas/WebhookTestResponse" "404": description: Enabled subscription was not found. security: - OAuth2Sandbox: - api://ac0d1aea-5e3a-463f-9dd1-194898ee5820/.default - OAuth2Production: - api://1f115cad-5576-4db9-a7f9-8921c47a86e4/.default /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](/api-reference/operations/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: - OAuth2Sandbox: - api://ac0d1aea-5e3a-463f-9dd1-194898ee5820/.default - OAuth2Production: - api://1f115cad-5576-4db9-a7f9-8921c47a86e4/.default /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: - OAuth2Sandbox: - api://ac0d1aea-5e3a-463f-9dd1-194898ee5820/.default - OAuth2Production: - api://1f115cad-5576-4db9-a7f9-8921c47a86e4/.default /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: - OAuth2Sandbox: - api://ac0d1aea-5e3a-463f-9dd1-194898ee5820/.default - OAuth2Production: - api://1f115cad-5576-4db9-a7f9-8921c47a86e4/.default /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: - OAuth2Sandbox: - api://ac0d1aea-5e3a-463f-9dd1-194898ee5820/.default - OAuth2Production: - api://1f115cad-5576-4db9-a7f9-8921c47a86e4/.default /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: - OAuth2Sandbox: - api://ac0d1aea-5e3a-463f-9dd1-194898ee5820/.default - OAuth2Production: - api://1f115cad-5576-4db9-a7f9-8921c47a86e4/.default /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: - OAuth2Sandbox: - api://ac0d1aea-5e3a-463f-9dd1-194898ee5820/.default - OAuth2Production: - api://1f115cad-5576-4db9-a7f9-8921c47a86e4/.default /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" 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: - OAuth2Sandbox: - api://ac0d1aea-5e3a-463f-9dd1-194898ee5820/.default - OAuth2Production: - api://1f115cad-5576-4db9-a7f9-8921c47a86e4/.default /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" "403": $ref: "#/components/responses/GeneralErrorWithoutExample" description: Forbidden security: - OAuth2Sandbox: - api://ac0d1aea-5e3a-463f-9dd1-194898ee5820/.default - OAuth2Production: - api://1f115cad-5576-4db9-a7f9-8921c47a86e4/.default /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 "403": $ref: "#/components/responses/GeneralErrorWithoutExample" description: Forbidden security: - OAuth2Sandbox: - api://ac0d1aea-5e3a-463f-9dd1-194898ee5820/.default - OAuth2Production: - api://1f115cad-5576-4db9-a7f9-8921c47a86e4/.default /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: $ref: "#/components/schemas/AdditionalRemittanceInformationRequired" "403": $ref: "#/components/responses/GeneralErrorWithoutExample" description: Forbidden security: - OAuth2Sandbox: - api://ac0d1aea-5e3a-463f-9dd1-194898ee5820/.default - OAuth2Production: - api://1f115cad-5576-4db9-a7f9-8921c47a86e4/.default components: securitySchemes: OAuth2Sandbox: type: oauth2 description: Use with the Sandbox API server only. flows: clientCredentials: tokenUrl: https://oidc.sandbox.ztlpay-test.io/v2/connect/token scopes: api://ac0d1aea-5e3a-463f-9dd1-194898ee5820/.default: Access the ZTL Sandbox API. OAuth2Production: type: oauth2 description: Use with the Production API server only. flows: clientCredentials: tokenUrl: https://oidc.ztlpay.io/v2/connect/token scopes: api://1f115cad-5576-4db9-a7f9-8921c47a86e4/.default: Access the ZTL Production API. 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 WebhookSubscriptionId: name: id in: path required: true schema: type: string format: uuid 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 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: - 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: title: 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: title: 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: title: 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: title: 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 PaymentAccountBban: title: PaymentAccountBban type: object required: - type - bban properties: type: type: string enum: - bban bban: type: string description: Account number example: "97105048304" PaymentAccountIban: title: PaymentAccountIban type: object required: - type - iban properties: type: type: string enum: - iban iban: type: string example: SE7250000000012341212345 PaymentAccountFik: title: PaymentAccountFik type: object required: - type - value properties: type: type: string enum: - fik value: type: string example: "12345678" SwedishGiro: title: 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: title: 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: title: 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: title: RemittanceInformationFik 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: "000000000000000" 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" CrossBorderContactInformation: 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/CrossBorderContactInformation" - 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: title: 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: title: 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/CrossBorderContactInformation" 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 instance: /api/payments/56563af2-a199-44ec-92a1-d77eed2d8562/status WebhookEventType: type: string description: Case-sensitive subscription type. PAYMENT_STATUS matches all payment status child types. Delivered payment events always identify the specific child type. enum: - PAYMENT_STATUS - PAYMENT_STATUS_UNSIGNED - PAYMENT_STATUS_IN_PROGRESS - PAYMENT_STATUS_REJECTED - PAYMENT_STATUS_COMPLETED - PAYMENT_STATUS_CANCELLED - PAYMENT_STATUS_CUSTOMER_ACTION_REQUIRED WebhookSubscriptionCreateRequest: type: object required: - targetUrl - eventTypes properties: targetUrl: type: string format: uri description: Public HTTPS endpoint with a host and no embedded username or password. Requires a valid publicly trusted TLS certificate. Use the test endpoint to verify reachability. example: https://partner.example/webhooks/ztl eventTypes: type: array minItems: 1 uniqueItems: true items: $ref: "#/components/schemas/WebhookEventType" bearerToken: type: - string - "null" minLength: 1 writeOnly: true description: Optional non-blank token value without the Bearer prefix. Omit or use null for no bearer authentication. ZTL adds the Bearer prefix to the Authorization header on delivery. WebhookSubscriptionUpdateRequest: type: object required: - targetUrl - eventTypes properties: targetUrl: type: string format: uri description: Public HTTPS endpoint with a host and no embedded username or password. Requires a valid publicly trusted TLS certificate. Use the test endpoint to verify reachability. example: https://partner.example/webhooks/ztl eventTypes: type: array minItems: 1 uniqueItems: true items: $ref: "#/components/schemas/WebhookEventType" WebhookBearerTokenRequest: type: object required: - bearerToken properties: bearerToken: type: string minLength: 1 writeOnly: true description: Non-blank token value without the Bearer prefix. This endpoint cannot remove a configured token. WebhookSubscriptionResponse: type: object required: - id - targetUrl - enabled - createdAt - updatedAt - eventTypes - hasBearerToken properties: id: type: string format: uuid targetUrl: type: string format: uri enabled: type: boolean createdAt: type: string format: date-time updatedAt: type: string format: date-time eventTypes: type: array uniqueItems: true items: $ref: "#/components/schemas/WebhookEventType" hasBearerToken: type: boolean WebhookSubscriptionCreatedResponse: allOf: - $ref: "#/components/schemas/WebhookSubscriptionResponse" - type: object required: - signingSecret properties: signingSecret: type: string description: Store securely. It is only returned when creating or rotating a signing secret. WebhookSubscriptionSecretResponse: type: object required: - id - signingSecret properties: id: type: string format: uuid signingSecret: type: string WebhookTestResponse: type: object required: - deliveryId - succeeded properties: deliveryId: type: string format: uuid succeeded: type: boolean error: type: - string - "null" 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: title: Iban type: object description: Country supports Iban bank account format. properties: type: type: string enum: - iban Swift: title: 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: title: 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: Position of this value in unstructured remittance information when applicable. 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 - "null" 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" servers: - url: https://api.ztlpay.io description: Production environment - url: https://api.sandbox.ztlpay-test.io description: Sandbox environment for testing