openapi: 3.1.0 info: version: v1.0 title: ZTL OpenAPI description: > Ztl Payment solution api You can download the full spec on the button above or at https://docs.ztlpay.io/ztl-api.full.yaml # General - All responses contains a header called `Ztl-Request-Id`. This is our reference for the operation performed and you should at least log these to enable better tracing and debugging. - Error handling follows HTTP error codes as closely as possible - Please take extra care to handle 5xx and avoid getting the user to try again immediately. While we try to make sure 503s are in fact temporary; some times it is related to longer downtimes. servers: - url: https://api.ztlpay.io description: Production environment - url: https://api.sandbox.ztlpay-test.io description: Sandbox environment for testing tags: - name: Authentication description: oAuth Authentication x-displayName: Authentication - name: Onboarding description: Onboarding x-displayName: Onboarding - name: Consent description: Manage the End User Consent (SCA) x-displayName: Consent - name: Accounts description: APIs available for doing the AISP operations x-displayName: Accounts - name: Payments description: Payments x-displayName: Payments - name: Payroll description: Payroll x-displayName: Payroll - name: Banks description: Retrieve available details for supported banks x-displayName: Banks - name: Companies description: >- Services related to companies. Retrieve information about onboarded companies, enable/disable compay and list supported company types. x-displayName: Companies - name: FX Payments description: > FX can either be used with or without bank integration. For bank integration, please see Flow for cross-border payment with bank integration ## FX payment without domestic bank integration flow The partner is responsible to handle the domestic bank integration, or present the required payment instructions for domestic transaction to the user. ![](./images/payments-fx-without-bankintegration.mermaid.svg) x-displayName: FX Payments - name: Currencies description: All currencies supported x-displayName: Currencies - name: Country description: >- Helper methods for cross-border payment support. This API can be used to give user interface for bank account format input, supported currencies and additional payment remittance information requirements. x-displayName: Country paths: /connect/token: servers: - url: https://oidc.ztlpay.io description: Oidc Production environment - url: https://oidc.sandbox.ztlpay-test.io description: Oidc Sandbox environment post: summary: Fetch an access token security: [] operationId: fetchAccessToken tags: - Authentication requestBody: content: application/x-www-form-urlencoded: schema: type: object required: - client_id - client_secret - grant_type - scope properties: client_id: type: string description: Client id as provided by ZTL client_secret: type: string description: Client secret as provided by ZTL grant_type: type: string description: Should be 'client_credentials' scope: type: string description: Should be 'payments' example: client_id: YOUR_CLIENT_ID client_secret: YOUR_CLIENT_SECRET grant_type: client_credentials scope: payments responses: '200': description: Access token headers: {} content: application/json: schema: type: object properties: access_token: description: token type: string example: >- eyJhbGciOiJSUzI1NiIsImtpZCI6IkE1NEZCQjFGRjgzRTZFRUFEQUI1MTg4QTJBMkVGRDhGNTUzMEUzNDkiLCJ0eXAiOiJKV1QiLCJ4NXQiOiJwVS03SF9nLWJ1cmF0UmlLS2k3OWoxVXc0MGsifQ.eyJuYmYiOjE1NjI4MzE1OTIsImV4cCI6MTU2MjgzNTE5MiwiaXNzIjoiaHR0cHM6Ly9vaWRjLnp0bC5zdGFjY2Zsb3cubmV0IiwiYXVkIjpbImh0dHBzOi8vb2lkYy56dGwuc3RhY2NmbG93Lm5ldC9yZXNvdXJjZXMiLCJ6dGwtYXBpIiwicG9ydGFsLWFwaSJdLCJjbGllbnRfaWQiOiJkZXZjbGllbnQiLCJzY29wZSI6WyJwYXltZW50cyIsInBvcnRhbC1hcGkiXX0.dJuDJNTsSBhQ_xmN3ruqbBZvJdyn2nUkUW3NEwbgXw_l-UA3_XRmtp16rWWdhMLbh-D_HywwG2a0h-MK2tX17C-ggsfp_pDxj8iy8aLleI3dY1qt0VkQY8rOw5_YtWa40HWwIBK9Ll8MqovwBK4lg9Pkq_KLGdkoz87n63QezS5u0JeWYJJnHFuY5ojX_M5szAdSYoVYOyvL0tr30ynxb3joglKrVWlkeawRZztRV4chFN00tlv_Tn54vDYOyDPtBWK6JpMVqhHla8a5JnslJu5dUP82qtgms_lFYOiR1oD2jaa-t0QTE6MVwspG3kwQBSSSZawe-9G4yEBg-nFSGg expires_in: description: Lifetime in seconds of the access token type: integer example: 3600 token_type: description: Lifetime in seconds of the access token type: string example: Bearer scope: type: string description: Granted scope, will always be 'payments' example: payments '401': description: Token expired and needs to be renewed content: application/json: schema: {} /api/onboarding: post: summary: Start an onboarding operationId: startOnboarding tags: - Onboarding requestBody: content: application/json: schema: $ref: '#/components/schemas/OnboardingInitiation' responses: '200': description: >- Returned in case there is an earlier initiated onboarding process, ID of the original process is returned headers: {} content: application/json: schema: $ref: '#/components/schemas/OnboardingInitiationResponse' '201': description: An ID for the onboarding headers: {} content: application/json: schema: $ref: '#/components/schemas/OnboardingInitiationResponse' '400': description: Bad request headers: {} content: application/json: schema: $ref: '#/components/schemas/BadRequest' default: description: Error content: application/json: schema: $ref: '#/components/schemas/Error' security: - Authorization: - payments /api/onboarding/{flowId}/status: get: summary: Get onboarding status and information tags: - Onboarding parameters: - name: flowId in: path description: Onboarding flowId, returned after initiating an onboarding. required: true schema: type: string responses: '200': description: Successfully received onboarding information content: application/json: schema: $ref: '#/components/schemas/Onboarding' '404': description: An onboarding with given `flowId` was not found default: description: Error content: application/json: schema: $ref: '#/components/schemas/Error' security: - Authorization: - payments /api/onboarding/{flowId}: delete: summary: Delete an onboarding tags: - Onboarding parameters: - name: flowId in: path description: Onboarding flowId, returned after initiating an onboarding. required: true schema: type: string responses: '202': description: Delete onboarding request accepted headers: {} default: description: Error content: application/json: schema: $ref: '#/components/schemas/Error' security: - Authorization: - payments /api/payments: post: summary: Initiate a payment operationId: initiatePayment tags: - Payments parameters: - $ref: '#/components/parameters/PsuIpAddressHeaderRequired' - name: PSU-Geo-Location in: header description: Geo Location of the one initiating the payment required: false schema: type: string - name: PSU-User-Agent in: header description: User agent of the one initiating the payment required: false schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/PaymentInitiation' responses: '201': description: Payment successfully initiated headers: {} content: application/json: schema: $ref: '#/components/schemas/PaymentInitiationResponse' '400': description: Pain validation failed content: application/json: schema: $ref: '#/components/schemas/PainValidationFailed' security: - Authorization: - payments /api/payments/validate: post: summary: Validate a payment operationId: validatePayment tags: - Payments parameters: - $ref: '#/components/parameters/PsuIpAddressHeaderRequired' - name: PSU-Geo-Location in: header description: Geo Location of the one initiating the payment required: false schema: type: string - name: PSU-User-Agent in: header description: User agent of the one initiating the payment required: false schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/PaymentInitiation' responses: '200': description: Payment is valid headers: {} '400': description: Pain validation failed content: application/json: schema: $ref: '#/components/schemas/PainValidationFailed' security: - Authorization: - payments /api/payments/{flowId}/status: get: summary: Get payment information tags: - Payments parameters: - name: flowId in: path description: Payment ID required: true schema: type: string format: uuid responses: '200': description: Payment content: application/json: schema: $ref: '#/components/schemas/Payment' security: - Authorization: - payments /api/payments/available-due-dates/{initiatingCountry}: post: deprecated: true summary: >- DEPRECATED: Use /api/payments/availability instead. Used to be: List available due dates for a payment tags: - Payments parameters: - name: initiatingCountry in: path description: >- Initiating country code, currently the only supported country code is 'NO' required: true example: 'NO' schema: type: string format: ISO-3166 requestBody: content: application/json: schema: $ref: '#/components/schemas/AvailableDueDatesRequest' responses: '200': description: >- List of available due dates for a payment based on amount and currency. Note that an empty list for international transaction might indicate that the currency exchange service is closed, eg in weekends. headers: {} content: application/json: schema: $ref: '#/components/schemas/DueDatesList' '400': description: Request is not valid content: application/json: schema: $ref: '#/components/schemas/Problem' example: title: Invalid request detail: 'Unsupported currency: AAA' security: - Authorization: - payments /api/payments/availability: post: summary: List payment availability and requirements tags: - Payments requestBody: content: application/json: schema: $ref: '#/components/schemas/PaymentAvailabilityRequest' responses: '200': description: >- Support for the currency together with a list of requirements for payments of a given currency to the specified country as well as a list of available due dates for a payment. headers: {} content: application/json: schema: $ref: '#/components/schemas/PaymentAvailabilityResponse' security: - Authorization: - payments /api/payroll: post: summary: Initiate a payroll payment operationId: initiatePayrollPayment tags: - Payroll parameters: - $ref: '#/components/parameters/PsuIpAddressHeaderRequired' - name: PSU-Geo-Location in: header description: Geo Location of the one initiating the payment required: false schema: type: string - name: PSU-User-Agent in: header description: User agent of the one initiating the payment required: false schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/PayrollPaymentInitiation' responses: '201': description: Payroll payment successfully initiated headers: {} content: application/json: schema: $ref: '#/components/schemas/PayrollPaymentInitiationResponse' '400': description: Missing or malformed request body content: application/json: schema: $ref: '#/components/schemas/MissingRequestBody' '422': description: Payroll payment request failed validation content: application/json: schema: $ref: '#/components/schemas/FailedPayrollValidation' security: - Authorization: - payments /api/payroll/status/{payrollId}: get: summary: Get payroll payment status tags: - Payroll parameters: - name: payrollId in: path description: Payroll Payment ID required: true schema: type: string format: uuid responses: '200': description: Payroll payment status content: application/json: schema: $ref: '#/components/schemas/PayrollPaymentStatus' '404': description: Payroll payment with given `payrollId` was not found security: - Authorization: - payments /api/payroll/cancel: post: summary: Cancel payroll payment tags: - Payroll description: >- Creates a payroll payment cancellation that is authorized by an existing consent parameters: - name: Idempotency-Key in: header description: Unique identifier for idempotency required: true schema: type: string format: uuid example: 49ae0cfe-6b72-4310-81f5-ad4eef897fe3 - $ref: '#/components/parameters/PsuIpAddressHeader' - name: PSU-User-Agent in: header description: >- The forwarded Agent header field of the HTTP request between PSU and TPP, if available schema: type: string example: Mozilla/5.0 (Windows NT 10.0; …) Gecko/20100101 Firefox/63.0 - name: PSU-Geo-Location in: header description: >- The forwarded value of the Geo Location of the corresponding HTTP request between the PSU and TPP, if available schema: type: string example: GEO:52.506931;13.144558 requestBody: description: Payroll Cancellation Request content: application/json: schema: $ref: '#/components/schemas/PayrollCancellationRequest' required: true responses: '200': description: >- Payroll payment cancellation created, check status and links for next action content: application/json: schema: $ref: '#/components/schemas/PayrollCancellationResponse' '400': description: Request is not valid content: application/json: schema: $ref: '#/components/schemas/Problem' example: status: 400 title: Bad request detail: Missing required request header Idempotency-Key '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/Problem' example: title: Failed to cancel payroll payment. detail: Payroll not found. '423': description: Locked content: application/json: schema: $ref: '#/components/schemas/Problem' example: title: Failed to cancel payroll payment. detail: Payroll already cancelled. '500': description: Internal Error content: application/json: schema: $ref: '#/components/schemas/InternalError' example: status: 500 title: Sorry we were unable to process your request detail: Sorry we were unable to process your request security: - Authorization: - payments /api/banks/{countryCode}/supported: 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 only supported country code is 'NO' 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: $ref: '#/components/schemas/BankV1' '400': description: Request is not valid content: application/json: schema: $ref: '#/components/schemas/Problem' example: type: about:blank title: Invalid country code security: - Authorization: - payments /api/accounts/{accountId}/balance: get: tags: - Accounts description: >- Retrieve the current available and booked balance for the account or accounts specified in the authorized query. summary: Account Balance operationId: getSingleAccountBalance parameters: - $ref: '#/components/parameters/PsuIpAddressHeader' - name: PSU-User-Agent in: header description: >- PSU-User-Agent - The forwarded Agent header field of the HTTP request between PSU and TPP, if available. Example: Mozilla/5.0 (Windows NT 10.0; WOW64; rv:54.0) required: false schema: type: string - name: PSU-Geo-Location in: header description: >- PSU-Geo-Location - The forwarded Geo Location of the corresponding HTTP request between PSU and TPP if available. Example: GEO:52.506931;13.144558 required: false schema: type: string - name: accountId in: path 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 - name: consentAuthorizationId in: query description: >- The Consent Authorization Id, as retrieved from the `Create Consent`-request. required: true schema: type: string - name: consentReference in: query description: >- The Consent Reference, as retrieved from the `Create Consent`-request. required: true schema: type: string format: uuid example: b0fc2430-3d87-470d-83f5-a4e94d540f6f responses: '200': description: Successfully retrieved balance content: application/json: schema: $ref: '#/components/schemas/BalanceReport' '400': description: Request is not valid content: application/json: schema: $ref: '#/components/schemas/AISProblem' example: type: urn:consent-expired title: Consent is either missing or invalid '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ForbiddenAISProblem' '500': description: Internal Error content: application/json: schema: $ref: '#/components/schemas/InternalError' example: status: 500 type: urn:unknown-error title: Sorry we were unable to process your request detail: Sorry we were unable to process your request uuid: e54df47f-85f5-416e-8fc0-768b018d73a3 Naas-Request-Id: 548176f5-21c9-4b5d-bf59-60b719b05643 security: - Authorization: - payments /api/accounts/{accountId}/entries: get: tags: - Accounts description: >- Retrieve the latest transaction entries on the account or accounts specified in the authorized query. summary: Account Entries operationId: getSingleAccountEntries parameters: - $ref: '#/components/parameters/PsuIpAddressHeader' - name: PSU-User-Agent in: header description: >- PSU-User-Agent - The forwarded Agent header field of the HTTP request between PSU and TPP, if available. Example: Mozilla/5.0 (Windows NT 10.0; WOW64; rv:54.0) required: false schema: type: string - name: PSU-Geo-Location in: header description: >- PSU-Geo-Location - The forwarded Geo Location of the corresponding HTTP request between PSU and TPP if available. Example: GEO:52.506931;13.144558 required: false schema: type: string - name: accountId in: path 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 - name: consentAuthorizationId in: query description: >- The Consent Authorization Id, as retrieved from the `Create Consent`-request. required: true schema: type: string - name: consentReference in: query description: Consent Reference required: true schema: type: string format: uuid example: b0fc2430-3d87-470d-83f5-a4e94d540f6f - name: fromDate in: query description: Entries start date, inclusive required: false schema: type: string format: date, ISO-8601 example: '2022-01-01' - name: toDate in: query description: Entries end date, inclusive required: false schema: type: string format: date, ISO-8601 example: '2022-01-02' responses: '200': description: Successfully retrieved entries content: application/json: schema: $ref: '#/components/schemas/EntryReport' '400': description: Request is not valid content: application/json: schema: $ref: '#/components/schemas/AISProblem' example: type: urn:consent-expired title: Consent is either missing or invalid '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ForbiddenAISProblem' '500': description: Internal Error content: application/json: schema: $ref: '#/components/schemas/InternalError' example: status: 500 type: urn:unknown-error title: Sorry we were unable to process your request detail: Sorry we were unable to process your request uuid: e54df47f-85f5-416e-8fc0-768b018d73a3 Naas-Request-Id: 548176f5-21c9-4b5d-bf59-60b719b05643 '503': description: Service Unavailable content: application/json: schema: $ref: '#/components/schemas/InternalError' example: status: 503 type: urn:service-unavailable title: Bank not available detail: Bank not available uuid: e54df47f-85f5-416e-8fc0-768b018d73a3 Naas-Request-Id: 548176f5-21c9-4b5d-bf59-60b719b05643 security: - Authorization: - payments /api/accounts/{accountId}/entries/{transactionId}/details: get: tags: - Accounts description: >- Obtain detailed information about a specific transaction by utilizing the unique transactionId, which is accessible through the entries endpoint. For a complete set of details, use this endpoint in conjunction with the entries endpoint. summary: Entry details operationId: getSingleAccountEntryDetails parameters: - $ref: '#/components/parameters/PsuIpAddressHeader' - name: PSU-User-Agent in: header description: >- PSU-User-Agent - The forwarded Agent header field of the HTTP request between PSU and TPP, if available. Example: Mozilla/5.0 (Windows NT 10.0; WOW64; rv:54.0) required: false schema: type: string - name: PSU-Geo-Location in: header description: >- PSU-Geo-Location - The forwarded Geo Location of the corresponding HTTP request between PSU and TPP if available. Example: GEO:52.506931;13.144558 required: false schema: type: string - name: accountId in: path 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 - name: transactionId in: path description: The ID of the transaction, as retrieved from the list of entries. required: true schema: type: string - name: consentAuthorizationId in: query description: >- The Consent Authorization Id, as retrieved from the `Create Consent`-request. required: true schema: type: string - name: consentReference in: query description: Consent Reference required: true schema: type: string format: uuid example: b0fc2430-3d87-470d-83f5-a4e94d540f6f responses: '200': description: Successfully retrieved entry details content: application/json: schema: $ref: '#/components/schemas/Entry' '400': description: Request is not valid content: application/json: schema: $ref: '#/components/schemas/AISProblem' example: type: urn:consent-expired title: Consent is either missing or invalid '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ForbiddenAISProblem' '500': description: Internal Error content: application/json: schema: $ref: '#/components/schemas/InternalError' example: status: 500 type: urn:unknown-error title: Sorry we were unable to process your request detail: Sorry we were unable to process your request uuid: e54df47f-85f5-416e-8fc0-768b018d73a3 Naas-Request-Id: 548176f5-21c9-4b5d-bf59-60b719b05643 '503': description: Service Unavailable content: application/json: schema: $ref: '#/components/schemas/InternalError' example: status: 503 type: urn:service-unavailable title: Bank not available detail: Bank not available uuid: e54df47f-85f5-416e-8fc0-768b018d73a3 Naas-Request-Id: 548176f5-21c9-4b5d-bf59-60b719b05643 security: - Authorization: - payments /api/accounts/info: get: tags: - Accounts description: >- Retrieve a list and general information about the account or accounts specified in the authorized account query. Note that this information can only be fetched during 1 hour after created consent. summary: List of Accounts operationId: getAccountQueryInfo parameters: - $ref: '#/components/parameters/PsuIpAddressHeader' - name: PSU-User-Agent in: header description: >- PSU-User-Agent - The forwarded Agent header field of the HTTP request between PSU and TPP, if available. Example: Mozilla/5.0 (Windows NT 10.0; WOW64; rv:54.0) required: false schema: type: string - name: PSU-Geo-Location in: header description: >- PSU-Geo-Location - The forwarded Geo Location of the corresponding HTTP request between PSU and TPP if available. Example: GEO:52.506931;13.144558 required: false schema: type: string - name: consentAuthorizationId in: query description: Consent Authorization Id required: true schema: type: string - name: consentReference in: query description: Consent Reference required: true schema: type: string format: uuid example: b0fc2430-3d87-470d-83f5-a4e94d540f6f - name: withBalance in: query description: >- With Balance - Whether or not balance information should be added to the account details. required: false schema: type: boolean - name: withCard in: query description: >- With Card - Whether or not card information should be added to the multiple accounts required: false schema: type: boolean responses: '200': description: Successfully retrieved status content: application/json: schema: $ref: '#/components/schemas/InfoReport' '400': description: Request is not valid content: application/json: schema: $ref: '#/components/schemas/AISProblem' example: type: urn:consent-expired title: Consent is either missing or invalid '403': description: Request is not valid content: application/json: schema: $ref: '#/components/schemas/Problem' example: type: urn:consent-is-more-than-one-hour-old title: Bad request detail: >- Account list can only be fetched one hour after issuing a new consent. '500': description: Internal Error content: application/json: schema: $ref: '#/components/schemas/InternalError' example: status: 500 type: urn:unknown-error title: Sorry we were unable to process your request detail: Sorry we were unable to process your request uuid: e54df47f-85f5-416e-8fc0-768b018d73a3 Naas-Request-Id: 548176f5-21c9-4b5d-bf59-60b719b05643 security: - Authorization: - payments /api/consents: get: tags: - Consent summary: Check status of the consent operationId: checkConsentStatus parameters: - name: consentAuthorizationId in: query description: Consent Authorization Id required: true schema: type: string responses: '200': description: Successfully retrieved status of consent. content: application/json: schema: $ref: '#/components/schemas/ConsentStatusResponse' '400': description: Request is not valid content: application/json: schema: $ref: '#/components/schemas/Problem' example: type: urn:input-validation-failed title: Bad request detail: Request parameter consentAuthorizationid is missing '403': description: Request is not valid content: application/json: schema: $ref: '#/components/schemas/Problem' example: type: urn:unknown-error title: >- NAAS Authorization Id is either invalid or does not belong to TPP detail: DEVELOPER_TEXT_MISSING security: - Authorization: - payments post: tags: - Consent summary: Create consent operationId: createConsent parameters: - name: Idempotency-Key in: header description: Unique identifier for idempotency required: true schema: type: string format: UUID example: 49ae0cfe-6b72-4310-81f5-ad4eef897fe3 - $ref: '#/components/parameters/PsuIpAddressHeaderRequired' requestBody: description: Consent request object content: application/json: schema: $ref: '#/components/schemas/ConsentRequest' required: true responses: '200': description: Successfully created consent content: application/json: schema: $ref: '#/components/schemas/CreateConsentResponse' '400': description: Request is not valid content: application/json: schema: $ref: '#/components/schemas/Problem' example: type: urn:input-validation-failed title: Bad Request detail: Callback-URL must not be blank security: - Authorization: - payments delete: tags: - Consent summary: Revoke Consent operationId: revokeConsent parameters: - name: Consent-Reference in: header description: Consent Reference to be revoked required: true schema: type: string format: UUID example: b0fc2430-3d87-470d-83f5-a4e94d540f6f responses: '204': description: Successfully revoked consent '400': description: Request is not valid content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: urn:input-validation-failed title: Bad Request detail: Missing required header Consent-Reference security: - Authorization: - payments /api/payments/cancel: post: tags: - Payments summary: Cancel Payments description: Creates a payment cancellation that is authorized by an existing consent operationId: cancelPayments parameters: - name: Idempotency-Key in: header description: Unique identifier for idempotency required: true schema: type: string format: UUID example: 49ae0cfe-6b72-4310-81f5-ad4eef897fe3 - name: consentReference in: query description: >- Unique Reference ID given to the Generic Consent request after SCA is completed along with the sca_status, provided in TPP callback URL required: true schema: type: string format: UUID example: b0fc2430-3d87-470d-83f5-a4e94d540f6f - $ref: '#/components/parameters/PsuIpAddressHeader' - name: PSU-User-Agent in: header description: >- The forwarded Agent header field of the HTTP request between PSU and TPP, if available schema: type: string example: Mozilla/5.0 (Windows NT 10.0; …) Gecko/20100101 Firefox/63.0 - name: PSU-Geo-Location in: header description: >- The forwarded value of the Geo Location of the corresponding HTTP request between the PSU and TPP, if available schema: type: string example: GEO:52.506931;13.144558 requestBody: description: Payment Cancellation Request content: application/json: schema: $ref: '#/components/schemas/PaymentCancellationRequest' required: true responses: '201': description: Payment cancellation created, check status and links for next action content: application/json: schema: $ref: '#/components/schemas/PaymentCancellationResponse' '400': description: Request is not valid content: application/json: schema: $ref: '#/components/schemas/Problem' example: type: urn:input-validation-failed status: 400 title: Bad request detail: Missing required request header Idempotency-Key uuid: d7bdf7a6-63c7-458c-bf79-e51584e72d4c '500': description: Internal Error content: application/json: schema: $ref: '#/components/schemas/InternalError' example: status: 500 type: urn:unknown-error title: Sorry we were unable to process your request detail: Sorry we were unable to process your request uuid: e54df47f-85f5-416e-8fc0-768b018d73a3 Naas-Request-Id: 548176f5-21c9-4b5d-bf59-60b719b05643 security: - Authorization: - payments /api/companies: get: tags: - Companies description: Get list of all companies onboarded by the partner summary: Onboarded companies operationId: getCompanies parameters: - $ref: '#/components/parameters/AuthorizationJwtHeader' responses: '200': description: Successfully retrieved entries content: application/json: schema: type: array items: $ref: '#/components/schemas/Company' security: - Authorization: - payments /api/companies/supported/{countryCode}: get: tags: - Companies description: Get list of supported company types summary: Supported company types operationId: getSupportedCompanyTypes parameters: - $ref: '#/components/parameters/AuthorizationJwtHeader' - name: countryCode in: path required: true example: 'NO' schema: type: string responses: '200': description: Successfully retrieved entries content: application/json: schema: type: array items: $ref: '#/components/schemas/SupportedCompanyType' security: - Authorization: - payments /api/companies/subscription/activate/{countryCode}/{organizationNumber}: patch: tags: - Companies description: Activate the subscription for the given company summary: Activate subscription operationId: activateSubscription parameters: - $ref: '#/components/parameters/AuthorizationJwtHeader' - name: countryCode in: path required: true example: 'NO' schema: type: string - name: organizationNumber in: path required: true schema: type: string responses: '200': description: Successfully activated subscription '400': description: Request is not valid content: application/json: schema: $ref: '#/components/schemas/GeneralProblem' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/GeneralProblem' security: - Authorization: - payments /api/companies/subscription/cancel/{countryCode}/{organizationNumber}: patch: tags: - Companies description: Cancel the subscription for the given company summary: Cancel subscription operationId: cancelSubscription parameters: - name: countryCode in: path required: true example: 'NO' schema: type: string - name: organizationNumber in: path required: true schema: type: string responses: '200': description: Successfully cancelled subscription '400': description: Request is not valid content: application/json: schema: $ref: '#/components/schemas/GeneralProblem' security: - Authorization: - payments /api/fx/payments/validate: post: tags: - FX Payments description: > International payment validation request. It is strongly recommended to use [country-specific requirements endpoint](https://docs.ztlpay.io/ztl-api-v2.html#tag/Country/operation/getCountryRequirements) before forming a validation/initiation request to provide a good user experience. summary: Validation operationId: internationalPaymentsValidation parameters: - $ref: '#/components/parameters/AuthorizationJwtHeader' requestBody: content: application/json: schema: $ref: '#/components/schemas/QuoteRequest' responses: '200': description: Successfully validated request '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/MalformedRequestBody' '403': description: Forbidden content: text/plain: schema: type: string example: Company is not onboarded '422': description: Validation failed content: application/json: schema: type: array items: $ref: '#/components/schemas/QuoteValidationFailed' security: - Authorization: - payments /api/fx/payments: post: tags: - FX Payments description: > International payment quote request We request that when a fx payment is initiated and due date is today or tomorrow (if initiated after 16:00) that you give user a warning if balance is less than value of the payment before calling confirm. Reason for this warning is to remind those who are lacking funds that they do not have funds and to avoid the payment being delayed or in worst case cancelled. summary: Payment Initiation operationId: internationalPaymentsQuote parameters: - $ref: '#/components/parameters/AuthorizationJwtHeader' requestBody: content: application/json: schema: $ref: '#/components/schemas/QuoteRequest' responses: '200': description: Successfully acquired foreign exchange quote content: application/json: schema: $ref: '#/components/schemas/QuoteResponse' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/MalformedRequestBody' '403': description: Forbidden content: text/plain: schema: type: string example: Company is not onboarded '422': description: Validation failed content: application/json: schema: type: array items: $ref: '#/components/schemas/QuoteValidationFailed' security: - Authorization: - payments /api/fx/payments/{quoteId}/confirm: post: tags: - FX Payments description: International payment confirmation. summary: Payment Confirmation operationId: internationalPaymentsPaymentConfirmation parameters: - name: quoteId in: path description: quote id as for payment required: true schema: type: string - $ref: '#/components/parameters/AuthorizationJwtHeader' responses: '200': description: Successfully confirmed payment content: application/json: schema: type: object required: - paymentId - statusUrl properties: paymentId: type: string description: The ID assigned to the confirmed payment example: 0db94e47-858c-4486-a0e9-a453e4da025d statusUrl: type: string description: A URL that can be used to get the payment's current status example: >- https://api.sandbox.ztlpay-test.io/api/fx/payments/0db94e47-858c-4486-a0e9-a453e4da025d/status '400': description: Request is not valid content: application/json: schema: type: object properties: message: type: string description: A message detailing the reason for the call failing example: Quote has expired. correlationId: type: string description: A unique identifier used for tracing the call example: 7757cdcb-128f-41ba-b3a6-58722e56b0f8 '404': description: Payment with given `paymentId` was not found security: - Authorization: - payments /api/fx/payments/{paymentId}/confirmPaid: post: tags: - FX Payments description: Cross-border payment funding confirmation. summary: Funding Payment Confirmation operationId: internationalPaymentsFundingPaymentConfirmation parameters: - name: paymentId in: path description: paymentId for the payment to be confirmedPaid required: true schema: type: string - $ref: '#/components/parameters/AuthorizationJwtHeader' responses: '200': description: Successfully confirmed payment content: application/json: schema: type: object required: - paymentId - statusUrl properties: paymentId: type: string description: The ID assigned to the confirmed payment example: 0db94e47-858c-4486-a0e9-a453e4da025d statusUrl: type: string description: A URL that can be used to get the payment's current status example: >- https://api.sandbox.ztlpay-test.io/api/fx/payments/0db94e47-858c-4486-a0e9-a453e4da025d/status '400': description: Request is not valid content: application/json: schema: type: object properties: message: type: string description: A message detailing the reason for the call failing example: Payment funding has already been confirmed correlationId: type: string description: A unique identifier used for tracing the call example: 7757cdcb-128f-41ba-b3a6-58722e56b0f8 '404': description: Payment with given `paymentId` was not found security: - Authorization: - payments /api/fx/payments/{paymentId}/status: get: tags: - FX Payments description: International payment status inquiry. summary: Payment Status operationId: internationalPaymentsStatus parameters: - name: paymentId in: path description: paymentId for the payment required: true schema: type: string - $ref: '#/components/parameters/AuthorizationJwtHeader' responses: '200': description: Successfully confirmed payment content: application/json: schema: type: object required: - status properties: status: type: string description: The current payment status enum: - Created - Confirmed - PaymentInProgress - Completed - Cancelled - PaymentFailed example: PaymentFailed message: type: string description: >- A technical message describing the current status reason (optional - normally not included). This message is not intended for end users. example: Technical error. '404': description: Payment with given `paymentId` was not found security: - Authorization: - payments /api/fx/payments/{paymentId}/cancel: post: tags: - FX Payments description: International payment funding payment confirmation. summary: Payment Cancellation operationId: internationalPaymentsCancel parameters: - name: paymentId in: path description: paymentId for the payment to cancel required: true schema: type: string - $ref: '#/components/parameters/AuthorizationJwtHeader' responses: '204': description: Successfully canceled payment '400': description: Request is not valid content: application/json: schema: type: object properties: message: type: string description: A message detailing the reason for the call failing example: Payment has not been booked yet correlationId: type: string description: A unique identifier used for tracing the call example: 7757cdcb-128f-41ba-b3a6-58722e56b0f8 '404': description: Payment with given `paymentId` was not found security: - Authorization: - payments /api/fx/payments/{paymentId}/progress-pdf: get: tags: - FX Payments summary: Payment Progress PDF description: >+ Generates a PDF report detailing the current progress of an FX payment. A PDF report can only be generated if the payment status is in one of the following states: - Confirmed When the payment is in the 'Confirmed' state the PDF will show payment status "Scheduled" - PaymentInProgress When the payment is in the 'PaymentInProgress' state the PDF will show payment status "In progress" - Completed When the payment is in the 'Completed' state the PDF will show payment status "Sent to bank"
Scheduled In progress Sent
operationId: internationalPaymentsProgressPDF parameters: - name: paymentId in: path description: The paymentId of the payment for which to generate the progress PDF required: true schema: type: string - $ref: '#/components/parameters/AuthorizationJwtHeader' responses: '200': description: Successfully generated payment progress PDF headers: ztlRequestId: description: >- Unique RequestId, please provide this Id in case of support requests schema: type: string format: uuid example: 3a797348-ef0c-4f52-b821-fdfcdb98c4d9 Content-Type: description: MIME type of the payload. schema: type: string example: application/pdf content: application/pdf: schema: type: string format: binary '400': $ref: '#/components/responses/GeneralErrorWithoutExample' description: Bad request '403': $ref: '#/components/responses/GeneralErrorWithoutExample' description: Forbidden '404': $ref: '#/components/responses/GeneralErrorWithoutExample' description: Not found '500': $ref: '#/components/responses/GeneralErrorWithoutExample' description: Internal server error security: - Authorization: - payments /api/currencies: get: tags: - Currencies description: Get details of supported currencies international payments summary: Supported currencies operationId: getSupportedCurrencies responses: '200': description: All supported currencies content: application/json: schema: type: array items: $ref: '#/components/schemas/SupportedCurrency' security: - Authorization: - payments /api/country: get: tags: - Country description: >- List all supported countries (possible to pay to). ZTL supports all non-sanctioned countries in the world. summary: All countries operationId: getCountries responses: '200': description: Supported countries content: application/json: schema: type: array items: type: object required: - countryCode - countryName properties: countryCode: type: string description: 2-letters country code example: SE countryName: type: string example: Sweden security: - Authorization: - payments /api/country/{country}/paymentrequirement: get: tags: - Country description: >- Gives additional payment requirements per country. If the country additional remittance information, this information is mandatory. summary: Cross-border payment requirements operationId: getCountryRequirements parameters: - name: country in: path description: 2-letters country code required: true schema: type: string responses: '200': description: Payment Requirements content: application/json: schema: type: object required: - countryCode - localCurrency - acceptedCurrencies - supportedBankAccountFormats properties: countryCode: type: string description: 2-letters country code example: SE countryName: type: string description: Country name (English) example: Sweden localCurrency: type: string description: 3-letter currency code example: NOK acceptedCurrencies: type: array description: All currency the receiving county supports items: type: string description: 3-letter currency code example: EUR supportedBankAccountFormats: type: array description: >- Required bank account format for receiving country. Can be one or multiple account formats. items: anyOf: - $ref: '#/components/schemas/Iban' - $ref: '#/components/schemas/Swift' - $ref: '#/components/schemas/SwiftWithBankRouting' paymentRequirements: type: array description: Additional payment requirements for receiving country. items: anyOf: - $ref: >- #/components/schemas/AdditionalRemittanceInformationRequired security: - Authorization: - payments components: responses: Unauthorized: description: You are not authorized to do this operation Forbidden: description: Accessing the resource you were trying to reach is forbidden MethodNotAllowed: description: Method not allowed NotAcceptable: description: Not Acceptable RequestTimeout: description: Request Timeout UnsupportedMediaType: description: Unsupported Media Type ServiceUnavailable: description: Service Unavailable 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' schemas: InternalError: description: Internal Error type: object properties: type: type: string format: uri default: urn:internal-server-error title: type: string default: Internal server error allOf: - $ref: '#/components/schemas/Problem' Error: required: - code - message properties: code: type: string message: type: string example: code: SYSTEM_ERROR message: Server error BadRequest: required: - title - message - detail properties: title: type: string message: type: string detail: type: string errors: type: array items: type: string example: title: Invalid request payload detail: The organizationId that was provided is invalid message: The organizationId that was provided is invalid errors: - The organizationId that was provided is invalid OnboardingInitiation: required: - organizationId properties: organizationId: type: string webhookUrl: type: string redirectUrl: type: string example: organizationId: '981078365' webhookUrl: https://example.org redirectUrl: https://example.org OnboardingInitiationResponse: type: object required: - flowId - onboardingUrl properties: flowId: type: string description: >- Unique identifier for the onboarding, can be used in combination with the status endpoint for fetching the status of an onboarding. onboardingUrl: type: string description: The url where the user completes the onboarding. example: flowId: 8665acd8-c033-4386-b9ca-ccc6c6a81243 onboardingUrl: >- https://onboarding.sandbox.ztlpay-test.io/onboarding/8665acd8-c033-4386-b9ca-ccc6c6a81243 Onboarding: type: object required: - orgNo - status - tasks - redirectUrl - webhookStatuses properties: orgName: type: string orgNo: type: string status: type: string description: >- Status of the onboarding. Detailed descriptions for each status are available in the full documentation. enum: - failed - manual-handling - pending - processing - document-signed-awaiting-packaging - document-signed-packaging-complete - initiating - completed - already-onboarded - company-not-found - declined-enk-no-vat - declined-risk-evaluation - declined-unsupported-company-type - declined-missing-company-type - signorder-expired - archived - voluntary-credit-block-bisnode tasks: type: array description: Lists any active or failed task(s) for the onboarding. items: type: object required: - id - flowId - status - category - type properties: id: type: string description: Unique identifier for the task. flowId: type: string description: The flowId the task belongs to. status: type: string description: The current status of the task. enum: - pending - completed - cancelled - failed category: type: string description: Which category of task this is. enum: - service-task - user-task - message-task - event-task type: type: string description: Which type of task this is. context: type: object description: >- The context of the current task. This will vary depending on where the customer is currently in the onboarding. redirectUrl: type: string webhookStatuses: type: object description: >- Status for any provided webhooks. Only a `complete` webhook is currently supported. properties: complete: type: object required: - status - timestamp properties: status: type: string description: Current status of this webhook enum: - success - pending - failed - not-provided timestamp: type: string archivedBy: type: object description: Details on how the onboarding was archived, if applicable required: - role properties: role: type: string enum: - case-worker - unknown example: orgName: Ztl orgNo: '12345678' status: completed tasks: [] redirectUrl: https://example.org webhookStatuses: complete: status: success timestamp: '2021-12-16T18:19:55.267Z' PaymentInitiation: required: - base64Pain001 - organizationId - countryCode - scaRedirectUrl - consentReference - idempotencyKey properties: idempotencyKey: type: string format: uuid description: >- Unique identifier for the payment request. This could also be used as a query parameter in the scaRedirectUrl for identifying the payment when the user returns from SCA. organizationId: type: string description: The organization number of the debtor example: 920970931 countryCode: type: string format: ISO 3166-1 description: Country code for the organization example: 'NO' consentReference: type: string description: The consent reference given when creating a consent. scaRedirectUrl: type: string example: https://example.com/callback description: The url the user is redirected to after confirming payment with SCA base64Pain001: type: string format: iso20022 Payment initiation v03 (PAIN) description: >- Encoded in base64. See https://docs.ztlpay.io/#initiate-payment for details. example: idempotencyKey: 123123-123-12-2222 countryCode: 'NO' organizationId: '123456789' scaRedirectUrl: https://example.com/callback consentReference: 123123-123123-123123-2 base64Pain001: >- PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0idXRmLTgiP...mZJbml0bj4NCjwvRG9jdW1lbnQ+DQo= PaymentInitiationResponse: type: object required: - flowId - statusUrl properties: flowId: type: string description: Ztl Id for payment, used in payment status endpoint example: c766e7e0-ea15-4b4a-9574-a27c763f6c17 statusUrl: type: string description: Url for updated payment status example: >- https://api.sandbox.ztlpay-test.io/api/payments/c766e7e0-ea15-4b4a-9574-a27c763f6c17/status example: flowId: 8665acd8-c033-4386-b9ca-ccc6c6a81243 statusUrl: >- https://api.sandbox.ztlpay-test.io/api/payments/8665acd8-c033-4386-b9ca-ccc6c6a81243/status PainValidationFailed: type: object required: - type - title - detail properties: type: type: string example: urn:pain-invalid description: Type of error, used to group similar errors title: type: string example: Invalid Pain description: The title of the error detail: type: string example: There are 2 errors description: Detailed information of the error cause detail2: type: string errors: type: array description: List of errors items: type: object properties: type: type: string example: transaction description: Type of error errors: type: array items: type: object properties: code: type: string example: urn:bban-invalid description: NAAS Error Code message: type: string example: Sender's account number is invalid description: Text description of the error path: type: string example: >- cstmrCdtTrfInitn.PmtInf[0].creditTransferTx[0].cdtrAcct.id.bban developerText: type: string example: Invalid debtor BBAN 854095477406 description: Additional/detailed information if available traceId: type: string example: b3515c0f-a474-470c-a58f-0d2478f3268f description: ID to identify the failure request example: type: urn:pain-invalid title: Invalid Pain detail: There are 2 errors detail2: '' errors: - type: transaction endToEndId: '966700472476787235510074468580' errors: - code: urn:max-length-exceeded path: CstmrCdtTrfInitn.PmtInf[0].CdtTrfTxInf[0].rmtInf message: Payment reference is too long for the receiver's bank developerText: >- Unstructured remittance info is too long for debtor agent DNBANOKK. The current length is 46, while the maximum length is 35. - type: general errors: - code: urn:country-missing path: cstmrCdtTrfInitn.PmtInf[0].Dbtr.PstlAdr.Ctry message: Country is required for debtor postal address developerText: Country tag is required for traceId: 03f55df4-d7d7-416a-add6-0f427eec7f92 Payment: type: object required: - flowId - processStatus properties: flowId: type: string processStatus: type: string enum: - processing - active - pending - completed description: >- * `active` The payment-process is ongoing * `completed` The payment-process is completed, note that this does not necessarily mean a successful payment - just that the payment process has terminated. * `pending` The payment-process has not been started and is pending. * `archived` The payment processed was manually archived by someone, e.g. a case worker. For all intents and purposes, this status can be treated the same as "Completed" error: $ref: '#/components/schemas/Problem' scaUrl: type: string description: The URL where the user can complete the SCA when applicable scaStatus: type: string description: >- The SCA status registered through us. This status can differ from the bank's status in cases where the PSU signs the payment in the bank. In such cases it may remain as 'AuthorizationRequired'. enum: - AuthorizationRequired - Accepted - Rejected - Timeout messageId: type: string description: Old Id - Not in use anymore deprecated: true transactions: type: array items: type: object properties: endToEndID: type: string purposeCode: type: string description: >- The purpose code as input from the pain001. If none was provided in the PAIN001-file this will not be provided. errors: $ref: '#/components/schemas/TransactionErrors' status: type: string enum: - Imported - Initialized - AuthorizationRequired - AcceptedSettlementInProgress - Rejected - Cancelled - AcceptedSettlementCompleted - Booked - RejectedFundsNotReceivedInTime - HeldByBank - UnknownStateInProgress description: >- * `Imported` ZTL has imported and parsed the transaction, but no further action has been taken. * `Initialized` ZTL has initialized the transaction, but the status from the bank is still unknown. * `AuthorizationRequired` The user needs to complete SCA and the URL for that is in the API response. * `Rejected` The bank rejected the payment. * `Cancelled` The payment has been cancelled or SCA has timed out. * `AcceptedSettlementInProgress` The bank has accepted the transaction, and the payment is ongoing. * `AcceptedSettlementCompleted` The payment has been completed by the bank. * `Booked` Payment is successful and process completed at ZTL. * `RejectedFundsNotReceivedInTime` ZTL has rejected the payment due to not having received the funds by the due date. This is often due to insufficient funds in the debtor account. Take care that, unless the payment is also cancelled in/by the bank, the initial payment may still be processed and paid to ZTL at a later time. In this scenario, ZTL will not forward the funds to the creditor. Instead ZTL will return the funds to the debtor. * `HeldByBank` Transaction is temporary stopped by the bank. Customer should contact bank. This status is only shown for partners who have enabled this feature. * `UnknownStateInProgress` Transaction is in an unknown state (last known status was `Rejected`) and can be assumed to be in progress until status is updated. The status is a temporary status used for Evry banks. It will be updated some time after the due date of the payment. statusReason: type: string transactionAmount: type: object description: Amount in local currency for a transaction properties: amount: type: string description: The transaction amount currency: type: string description: The currency the amount is specified in commission: type: object description: The commission amount/partner margin properties: amount: type: string description: The commission amount/partner margin currency: type: string description: The currency the amount is specified in exchangeRate: type: number description: >- The exchange rate the customer has been given (always per 1.0 for all currencies) displayExchangeRate: type: number description: >- Exchangerate following standard display rules. Eg. EURNOK are displayed per 1 (9.87), while SEKNOK per 100 (98,27) exchangeRateExpiration: type: string format: date-time example: '2022-08-05T13:13:59.633957965+02:00' description: >- Expiration for given exchangeRate/quote. Only shown for international transactions fromCurrency: type: string description: Debtor's currency toCurrency: type: string description: Creditor's currency paymentId: type: string description: >- Transaction Id generated by psd2 aggregator/bank. Used for transaction cancel. dueDate: type: string format: date description: >- The domestic psd2 due date (money goes from debtor account to ztl client account) example: scaUrl: https://example-sca-url.com flowId: 6613c5c0-642f-4ae7-98ee-a8ccdaa486bb processStatus: active scaStatus: Accepted messageId: 20200415-0741-4280-BECA-3A8B2BD86091 transactions: - endToEndID: 296edf186a374b0a89edfa8e9fd054c5 status: AcceptedSettlementInProgress statusReason: >- Payment accepted at Aspsp and needs to be signed by PSU. Please initiate payment signing process purposeCode: OTHR transactionAmount: amount: '1235' currency: NOK commission: amount: '0' currency: NOK fromCurrency: NOK toCurrency: NOK exchangeRate: 1 paymentId: 0fsdfasdfsa3e4d46218b80179d5c19f796 dueDate: '2022-02-08' - endToEndID: wd459dp10b7plasjdl202aas5 status: AcceptedSettlementInProgress statusReason: >- Payment accepted at Aspsp and needs to be signed by PSU. Please initiate payment signing process purposeCode: OTHR transactionAmount: amount: '9608.8' currency: SEK commission: amount: '1.5' currency: NOK fromCurrency: NOK toCurrency: SEK exchangeRate: 0.9688 displayExchangeRate: 96.88 exchangeRateExpiration: '2022-08-05T14:48:14.133+02:00' paymentId: 5fdff9c50523460585c7fc93038791ae dueDate: '2022-02-08' Problem: 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 Naas-Request-Id: type: string description: Aggregator reference naasRequestId: type: string description: Aggregator reference example: type: urn:quote-failed title: Payment rejected detail: null instance: /api/payments/56563af2-a199-44ec-92a1-d77eed2d8562/status AISProblem: type: object required: - title properties: type: type: string format: uri description: >- Error type: Categorization of similar errors. * `urn:consent-expired` The user's consent has expired. * `urn:account-invalid` The account is invalid. * `urn:service-unavailable` The service is unavailable. Please try again later. * `urn:access-denied` Access is denied. * `urn:aspsp-error` An unspecified error has occurred. title: type: string description: The title of the error detail: type: string description: Detailed information of the error cause Naas-Request-Id: type: string description: Aggregator reference naasRequestId: type: string description: Aggregator reference example: type: urn:quote-failed title: Payment rejected detail: null instance: /api/payments/56563af2-a199-44ec-92a1-d77eed2d8562/status ForbiddenAISProblem: type: object required: - title properties: type: type: string format: uri description: >- Error type: Categorization of similar errors. * `urn:inactive-subscription` The company do not have an active subscription to ZTL's services title: type: string description: The title of the error detail: type: string description: Detailed information of the error cause example: type: urn:inactive-subscription title: Inactive subscription detail: >- 920970931 does not have an active subscription with ZTL. Customer may contact ZTL at for assistance TransactionErrors: type: array items: type: object properties: type: type: string format: uri detail: type: string example: - type: urn:payment:invalid-due-date detail: Due date can be maximum 8 business days ahead DueDatesList: type: array items: type: string format: date example: - '2022-03-24' - '2022-03-26' PayrollPaymentInitiation: required: - base64Pain001 - legalId - consentReference - callbackUrl properties: base64Pain001: type: string description: A base64 encoded pain001 xml file legalId: type: string description: >- The organization identifier of the one initiating the payroll payment consentReference: type: string description: The ID of the payment consent callbackUrl: type: string description: >- The url the customer is redirected to after confirming payment with SCA example: base64Pain001: >- PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0idXRmLTgiP...mZJbml0bj4NCjwvRG9jdW1lbnQ+DQo= legalId: NO754987902 consentReference: hf7f7ds-f454g callbackUrl: http://callback PayrollPaymentInitiationResponse: type: object required: - payrollId - sca properties: payrollId: type: string description: The payroll ID used to uniquely identify the payroll payment sca: type: string description: The SCA link. SCA must be completed for the payroll to be processed. example: payrollId: 8665acd8-c033-4386-b9ca-ccc6c6a81243 sca: https://www.dnb.no/segb/appo/logon/psd2Start?blob=P98u8VFpnug... PayrollPaymentStatus: type: object required: - statusName - statusReason - timestamp properties: statusName: type: string enum: - AWAITING_AUTHORIZATION - SETTLEMENT_IN_PROGRESS - SETTLEMENT_COMPLETED - CANCELLED - SETTLEMENT_NOT_COMPLETED_IN_TIME - PAYROLL_PAYMENT_INITIATED - PAYROLL_PAYMENT_ACCEPTED_TECHNICAL_VALIDATION - ACCEPTED_FOR_EXECUTION - EXECUTION_COMPLETED - FAILED statusReason: type: string description: The reason that the payroll has the given status. timestamp: type: string description: The timestamp of the status check example: statusName: SETTLEMENT_IN_PROGRESS statusReason: Initiated Payment has been accepted for execution timestamp: 021-11-30T10:54:34.489808485+01:00 PayrollCancellationRequest: type: object required: - payrollId - consentReference - instructionId - callbackUrl properties: payrollId: type: string description: The payroll ID used to uniquely identify the payroll payment example: 3738a8d3-9f39-49d4-8b4f-6657abb0469f consentReference: type: string description: The ID of the payroll consent example: hf7f7ds-f454g callbackUrl: description: >- will be used by the bank to generate a URL where the end user has to provide Strong Customer Authentication. This callbackUrl will include the provided payrollId, allowing the user to track which payroll is being cancelled type: string example: >- http://callback&instructionId=HEyKZacHyZ&payrollId=eb42984d-4d7d-4d50-829e-7c531501177c&sca=success instructionId: description: TPP reference for this payment cancellation, used for callback type: string example: 62f930b774464383ab47576c54fef125 PayrollCancellationResponse: type: object properties: statusReason: $ref: '#/components/schemas/CancellationStatusReason' scaUrl: type: string description: Payroll cancellation response AvailableDueDatesRequest: required: - amount - toCurrency - debtorBic type: object properties: amount: type: string description: >- The monetary amount, two decimals, max value 999999999999.99, always positive toCurrency: type: string description: The currency used in the payment debtorBic: type: string description: Debtor's bank BIC PaymentAvailabilityRequestFrom: required: - currency - bic type: object properties: currency: type: string description: The currency of the transaction example: NOK bic: type: string description: Identifier code for the accounts bank example: DNBANOKK PaymentAvailabilityRequestTo: required: - currency - bic - amount type: object properties: currency: type: string description: The currency of the transaction example: NOK bic: type: string description: Identifier code for the accounts bank example: DNBANOKK amount: type: string description: >- The monetary amount, two decimals, max value 999999999999.99, always positive example: '99.50' ErrorMessageEnum: type: string example: urn:not-supported description: > A unique identifier for the availability message. * `urn:not-supported` - The currency is not currently supported * `urn:kid-invalid` - Payment reference is not valid * `urn:bban-invalid` - Sender's account number is invalid * `urn:currency-invalid` - Given currency is not supported * `urn:due-date-invalid` - Requested execution date is invalid * `urn:currency-scale-mismatch` - Provided amount scale is not valid for given currency * `urn:bic-or-iban-required` - Either creditor BIC or IBAN is required enum: - urn:not-supported - urn:kid-invalid - urn:bban-invalid - urn:currency-invalid - urn:due-date-invalid - urn:currency-scale-mismatch - urn:bic-or-iban-required PaymentRequirement: required: - type - validationPattern - description type: object properties: type: type: string enum: - IBAN - BBAN - BIC - CLEARING_CODE - REASON - PURPOSE_CODE description: > The constraint type for the payment requirement. * `IBAN` - International Bank Account Number * `BBAN` - Basic Bank Account Number * `BIC` - Bank Identification Code * `CLEARING_CODE` - Code used to route the payment to the correct financial institution, typically identifying a specific bank or branch * `REASON` - Reason for payment (sent as unstructured remittance information) * `PURPOSE_CODE` - Code that specifies the reason or intended use of the payment, often used for regulatory reporting and compliance example: BIC validationPattern: type: string description: The regex used to validate the constraint example: '[A-Z]{6,6}[A-Z2-9][A-NP-Z0-9]([A-Z0-9]{3,3}){0,1}' description: type: string description: >- A description detailing the reason in the event of a Regex pattern not matching the constraint. example: Invalid BIC RequirementInformation: required: - paymentRequirements - validDates type: object properties: paymentRequirements: type: array items: $ref: '#/components/schemas/PaymentRequirement' validDates: type: array items: type: string description: A date in the format 'YYYY-MM-DD' (ISO-8601) format: date, ISO-8601 example: '2022-11-15' AvailabilityMessage: required: - type - message type: object properties: type: $ref: '#/components/schemas/ErrorMessageEnum' message: type: string description: >- Detailed information on the availability of the requested country-currency pair. example: We don't support THB PaymentAvailabilityRequest: required: - from - to type: object properties: from: $ref: '#/components/schemas/PaymentAvailabilityRequestFrom' to: $ref: '#/components/schemas/PaymentAvailabilityRequestTo' PaymentAvailabilityResponse: required: - resultCode - messages type: object properties: resultCode: type: string enum: - NOT_SUPPORTED - SUPPORTED description: | Whether the currency is supported or not. * `SUPPORTED` - The currency is currently supported * `NOT_SUPPORTED` - The currency is not supported messages: type: array items: $ref: '#/components/schemas/AvailabilityMessage' paymentRequirementInformation: $ref: '#/components/schemas/RequirementInformation' Amount: type: object properties: amount: type: string description: >- The monetary amount, two decimals, max value 999999999999.99, always positive example: '99.50' currency: type: string description: The currency of the transaction example: NOK description: Amount for transaction BookedBalance: type: object properties: amount: type: string description: The booked balance on the account example: '150.00' currency: type: string description: The currency of the booked balance example: NOK AvailableBalance: type: object properties: amount: type: string description: The available balance on the account example: '100.00' currency: type: string description: The currency of the available balance example: NOK Balance: type: object properties: booked: $ref: '#/components/schemas/BookedBalance' available: $ref: '#/components/schemas/AvailableBalance' BalanceReport: type: object properties: id: type: string description: Unique Identifier for Account provided by ASPSP example: 22cc5740-f8f5-1234-abcd-b90e42531234 name: type: string description: Name of the account. Savings, salary etc example: Spending 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 enum: - Debit - Credit - Current - Savings - Business - CACC - Tax - Not Provided - Cash Pool currency: type: string format: ISO-4127 example: NOK description: The currency of the account balance: $ref: '#/components/schemas/Balance' CashAccount: 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 CancellationStatusReason: required: - origin - status type: object properties: reason: type: string description: Reason for status example: >- Payment accepted at Aspsp and needs to be signed by PSU. Please initiate payment signing process status: type: string description: >- Status code. Both Accepted and Cancelled implies the request was successful. enum: - Accepted - AuthorizationRequired - Rejected - Cancelled example: AuthorizationRequired origin: type: string description: Origin of the Response example: NAAS Entry: required: - type - status - postedAmount type: object properties: transactionId: type: string description: Unique Identifier for entry provided by ASPSP example: d1f669f2-1234-abcd-aabb-ff0cc229b485 postedAmount: $ref: '#/components/schemas/Amount' 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-time example: '2022-01-02' valueDateTime: type: string format: date-time example: '2022-01-01' purposeText: type: string description: Purpose of transfer. example: Overføring Innland remittanceInformation: $ref: '#/components/schemas/RemittanceInformation' creditor: $ref: '#/components/schemas/CashAccount' debtor: $ref: '#/components/schemas/CashAccount' endToEndId: type: string GeneralAccountInfo: type: object properties: id: type: string description: Unique Identifier for Account provided by ASPSP example: 11ab5740-f8f5-1234-abcd-b90e4253b7b8 name: type: string description: Name of the account. Savings, salary etc 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 enum: - Debit - Credit - Current - Savings - Business - CACC - Tax - Not Provided - Cash Pool currency: type: string format: iso-4217 description: The currency of the account example: NOK ownerName: type: string description: >- The name of the Account Owner. This information is not available for all banks EntryReport: properties: account: $ref: '#/components/schemas/GeneralAccountInfo' accountEntries: type: array items: $ref: '#/components/schemas/Entry' RemittanceInformation: type: object properties: reference: type: string example: 75025049 unstructured: type: string example: Transfer of funds description: Remittance information InfoReport: type: object properties: accounts: type: array items: $ref: '#/components/schemas/GeneralAccountInfo' ConsentRequest: required: - callbackUrl - debtorBankBic - instructionId - accountOwnerSsn - accountOwnerOrganizationReference type: object properties: callbackUrl: type: string pattern: ^(http|https)://.*$ description: Sca callback url can be configured here accountOwnerSsn: type: string description: Private identification number accountOwnerOrganizationReference: type: string description: Corporate ID required for corporate consent creation at ASPSP. debtorBankBic: type: string description: Bic to identify the bank instructionId: type: string maxLength: 36 description: Instruction id usage: type: string enum: - BUSINESS - PRIVATE description: >- If the consent applies to private or business accounts, the default is business. Private accounts are only permitted for ENK companies and only available for selected partners, contact us if you want access. description: >- Consent request. Must have both accountOwnerSsn and accountOwnerOrganizationReference. CreateConsentResponse: required: - consentAuthorizationId - status type: object properties: scaUrl: type: string description: >- SCA URL from ASPSP used to provide authorization or confirmation by an authorized entity consentAuthorizationId: type: string description: Unique ID given to the Generic Consent request by NAAS. status: type: string description: Status code reason: type: string description: Reason for status expirationDate: type: string format: date-time ConsentState: type: object properties: aisExpired: type: boolean pisExpired: type: boolean cafExpired: type: boolean PaymentCancellationResponse: type: object properties: statusReason: $ref: '#/components/schemas/CancellationStatusReason' scaUrl: type: string description: Payment cancellation response PaymentCancellationRequest: type: object required: - paymentId - instructionId - callbackUrl properties: paymentId: description: PSD2 Payment ID, available from the payment status endpoint type: string example: dba8a99a40f24ca594e6c313d1e88018 callbackUrl: description: >- will be used by the bank to generate a URL where the end user has to provide Strong Customer Authentication. This callbackUrl will include the provided instructionId, allowing the user to track which payment is being cancelled type: string instructionId: description: TPP reference for this payment cancellation, used for callback type: string example: 62f930b774464383ab47576c54fef125 ConsentStatusResponse: type: object properties: reason: type: string description: Reason for status status: type: string description: Status code authorizationType: type: string description: >- Authorization Type of the status, comma separated list of the following enum: SINGLE_AIS,RECURRING_AIS,SINGLE_PIS,RECURRING_PIS,RECURRING_CAF example: SINGLE_AIS,RECURRING_AIS consentState: $ref: '#/components/schemas/ConsentState' expirationDate: type: string format: date-time AspspId: type: object properties: type: type: string example: BIC value: type: string example: DNBANOKK AspspJson: type: object properties: id: $ref: '#/components/schemas/AspspId' name: type: string example: DNB Norge country: type: string example: 'NO' enabled: type: string example: true Account: type: object required: - type properties: type: type: string enum: - IBAN - BBAN example: IBAN pattern: type: string example: ^NO\d{13}$ ClearingCode: type: object required: - description properties: description: type: string example: Country specific clearing code are mandatory pattern: type: string example: ^[A-Z]{4}0[A-Z0-9]{6}$ MissingRequestBody: type: object required: - title - instance 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: null title: Invalid payroll payment request format detail: null instance: /api/payroll FailedPayrollValidation: type: object required: - title - validationErrors - errors properties: title: type: string validationErrors: type: array items: $ref: '#/components/schemas/ValidationElement' errors: type: array items: $ref: '#/components/schemas/ValidationElement' example: title: Failed to process payroll payment request validationErrors: - type: urn:input-validation-failed title: Payment contains invalid fields detail: transactions[0] Invalid debtor BBAN errors: - code: urn:currency-invalid path: CdtTrfTxInf.InstdAmt.Amt.Ccy message: Given currency is not supported for payroll payments developerText: Invalid currency EUR, only NOK is supported for payroll ValidationProblem: type: object properties: type: type: string format: uri description: Type of error, used to group similar errors default: urn:input-validation-failed title: type: string default: Input Validation Failed description: The title of the error violations: type: array items: $ref: '#/components/schemas/FieldError' allOf: - $ref: '#/components/schemas/Problem' BicNotFound: type: object properties: type: type: string format: uri default: urn:bic-not-found title: type: string default: Bic Not Found bic: type: string allOf: - $ref: '#/components/schemas/Problem' InvalidConsentAuthorizationId: type: object properties: type: type: string format: uri default: urn:invalid-consent-authorization-id title: type: string default: Invalid Consent Authorization Id allOf: - $ref: '#/components/schemas/Problem' InvalidConsentReference: type: object properties: type: type: string format: uri default: urn:invalid-consent-reference title: type: string default: Invalid Consent Reference allOf: - $ref: '#/components/schemas/Problem' ConsentNotFound: type: object properties: type: type: string format: uri default: urn:consent-not-found title: type: string default: Consent Not Found allOf: - $ref: '#/components/schemas/Problem' ConsentExpired: type: object properties: type: type: string format: uri default: urn:consent-expired title: type: string default: Consent error allOf: - $ref: '#/components/schemas/Problem' ConsentInvalid: type: object properties: type: type: string format: uri default: urn:consent-invalid title: type: string default: Invalid Consent allOf: - $ref: '#/components/schemas/Problem' IdempotencyKeyInvalid: type: object properties: type: type: string format: uri default: urn:idempotency-key-invalid title: type: string default: Invalid Idempotency Key idempotencyKey: type: string format: uuid allOf: - $ref: '#/components/schemas/Problem' PaymentIdInvalid: type: object properties: type: type: string format: uri default: urn:payment-id-invalid title: type: string default: Invalid Payment Id paymentId: type: string allOf: - $ref: '#/components/schemas/Problem' ExecutionDateInvalid: type: object properties: type: type: string format: uri default: urn:execution-date-invalid title: type: string default: Invalid Execution Date executionDate: type: string format: date-time allOf: - $ref: '#/components/schemas/Problem' MaxBulkPaymentSizeExceeded: type: object properties: type: type: string format: uri default: urn:max-bulk-payment-size-exceeded title: type: string default: Max Bulk Payment Size Exceeded maxSize: type: integer allOf: - $ref: '#/components/schemas/Problem' AspspError: type: object properties: type: type: string format: uri default: urn:aspsp-error title: type: string default: Error from ASPSP (Bank) allOf: - $ref: '#/components/schemas/Problem' FieldError: type: object properties: field: type: string description: The field that caused the validation error message: type: string description: Detailed error message explaining which validation rule was broken ValidationElement: type: object properties: code: type: string description: Distinct code for given error type example: urn:bban-invalid path: type: string description: Invalid element path example: CstmrCdtTrfInitn.PmtInf[0].CdtTrfTxInf[0].CdtrAcct.Id.bban message: type: string description: Detailed information of the error cause example: Sender's account number is invalid detail: type: string description: >- Detailed information of the error cause (copy of 'message' field, remains for backward compatibility, will be deleted later) example: Sender's account number is invalid developerText: type: string description: More detailed error message, provided when possible example: Invalid debtor BBAN "984327679453" BankV1: required: - bic - constraints - countryCode - name - supportedProducts type: object properties: bic: type: string description: Bank BIC code, 8 digits example: DNBANOKK constraints: required: - maxBasketSize - maxInformationFieldLength - maxUnstructuredRemittanceInfoLength - cancelSCARequired - validInformationFieldCharactersPattern type: object 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 description: Bank constrains countryCode: type: string example: 'NO' name: type: string description: Bank name example: DNB BANK ASA supportedProducts: type: array items: type: string enum: - PAYMENT_DOMESTIC - PAYMENT_INTERNATIONAL - PAYROLL - ACCOUNT_SERVICE - PAYMENT_BULK example: PAYMENT_DOMESTIC description: A supported bank with constraints Company: type: object properties: organizationNumber: type: string activeSubscription: type: boolean description: Payroll cancellation response SupportedCompanyType: required: - code - description type: object properties: code: type: string example: AS description: Company type code description: type: string description: Company type description example: Aksjeselskap GeneralProblem: type: object required: - title properties: type: type: string format: uri description: Type of error, used to group similar errors title: type: string description: The title of the error detail: type: string description: Detailed information of the error cause instance: type: string description: Endpoint that caused the failure request traceId: type: string description: ID to identify the failure request example: type: urn:quote-failed title: Payment rejected detail: null instance: /api/payments/56563af2-a199-44ec-92a1-d77eed2d8562/status QuoteValidationFailed: type: object properties: code: type: string example: InvalidFromAccount description: > The validation error code. Possible values: - `InvalidCreationTime`: Payment initiation is not supported during weekends/bank holidays - `InvalidDueDate`: Available due date range is dependent on initiation time - `InvalidFromAccount`: Sender's and recipient's account numbers cannot have the same value - `InvalidFromCountry`: Provided sender's country does not match provided sender's BIC - `InvalidToAddress`: One of the recipient's address fields are invalid (specified in the reason field) - `InvalidToAccount`: IBAN and BBAN values cannot be equal - `InvalidBbanOrIban`: Either IBAN or BBAN must be provided for the recipient account - `InvalidIban`: IBAN is either missing or invalid - `IbanBicMismatch`: The IBAN does not match the provided BIC - `InvalidBIC`: BIC is either missing or invalid - `InvalidBeneficiaryCountry`: Recipient's country is not supported - `InvalidAmount`: Requested amount exceeds the limit amount of the currency for the chosen due date - `InvalidQuoteCurrencyScale`: Invalid scale for requested currency - `InvalidCurrency`: Given currency is not accepted by the recipient's country - `CurrencyPairMismatch`: Funding currency and requested currency cannot be the same - `InvalidRecipientInfo`: Recipient country specific payment requirements are not met (check /api/country/{country}/paymentrequirement for specifics) - `InvalidRemittanceInformation`: (Additional) remittance information is missing or invalid enum: - InvalidCreationTime - InvalidDueDate - InvalidFromAccount - InvalidFromCountry - InvalidToAddress - InvalidToAccount - InvalidBbanOrIban - InvalidIban - IbanBicMismatch - InvalidBIC - InvalidBeneficiaryCountry - InvalidAmount - InvalidQuoteCurrencyScale - InvalidCurrency - CurrencyPairMismatch - InvalidRecipientInfo - InvalidRemittanceInformation reason: type: string description: The underlying reason for the error example: InvalidToAccount path: type: string description: Path to the related input param with validation error example: .from.bban MalformedRequestBody: type: object properties: code: type: string description: The parsing error type example: InvalidJsonRequest reason: type: string description: The underlying reason for the error example: Malformed request body path: type: string description: Path to the related input param with parsing error example: .from.bban QuoteRequest: type: object required: - metadata - from - to - amount - dueDate - remittanceInformation properties: metadata: type: object description: Metadata for quote request allOf: - $ref: '#/components/schemas/QuoteMetadata' from: type: object description: Information about the debtor allOf: - $ref: '#/components/schemas/QuoteFrom' to: type: object description: Information about the creditor allOf: - $ref: '#/components/schemas/QuoteTo' amount: type: object description: The amount and currency for the quote allOf: - $ref: '#/components/schemas/QuoteRequestedAmount' dueDate: type: string format: date, ISO-8601 description: >- The due date for the payment. NOTE: there are limitations on due date in the further example: '2023-01-15' remittanceInformation: type: object description: Remittance information allOf: - $ref: '#/components/schemas/QuoteRemittanceInformation' purposeCode: type: string description: >- A code stating the purpose of the payment. (Required by some countries). Deprecated - use Information.RemittanceInformation.AdditionalInformation (type - Purpose) instead example: S1008 deprecated: true QuoteResponse: type: object required: - quoteId - endToEndId - requestedAmount - costAmount - exchangeRate - quoteExpiryTime - referenceCode - intermediaryAccount properties: quoteId: type: string description: The quote ID to use for booking format: UUID example: d6f06bfe-4830-4358-b483-c24c66cfb431 endToEndId: type: string description: An ID that can be used to identify the payment example: 7c628b2e-9094-4bf8-af23-1d517c6fc4f5 requestedAmount: type: object description: The amount and currency that will be paid out allOf: - $ref: '#/components/schemas/QuoteRequestedAmount' costAmount: type: object description: >- The amount and currency of the resulting cost (funding) for the quote allOf: - $ref: '#/components/schemas/QuoteCostAmount' exchangeRate: type: string description: The exchange rate per single unit example: 1.0346 quoteExpiryTime: type: string format: datetime, ISO-8601 example: '2023-01-15T09:32:00+01:00' referenceCode: type: string description: >- The reference code to add to the payment's unstructured remittance info example: ZTL-d6f06bfe intermediaryAccount: type: object description: The account to deposit funding amount to when initiating payment allOf: - $ref: '#/components/schemas/QuoteIntermediaryAccount' QuoteRequestedAmount: type: object required: - amount - currency properties: amount: type: string description: The amount to get a quote for example: '1000.50' currency: type: string description: The currency the amount is specified in example: SEK QuoteCostAmount: type: object required: - amount - currency properties: amount: type: string description: The amount it will cost to buy the requested / quoted amount example: 1034.62 currency: type: string description: The currency the amount is specified in example: NOK QuoteRemittanceInformation: type: object required: - unstructured properties: unstructured: type: string description: Message for receiver example: Payment for consulting services additionalInformation: type: array items: type: object required: - type - value properties: type: type: string enum: - TaxCode - Reason - Purpose description: > Type of additional information. Must be compliant with receiving country rules * `Reason` Text to describe the reason for payment * `Purpose` A valid PurposeCode of the payment * `TaxCode` Receiver Tax code example: Reason value: type: string description: Value of the property QuoteFrom: type: object required: - bban - bic - contactInformation - currency - country properties: bban: type: string description: Basic Bank Account Number example: 12341212345 bic: type: string description: Bank Identification Code example: DNBANOKK contactInformation: type: object description: Debtor contact information allOf: - $ref: '#/components/schemas/QuoteContactInformation' currency: type: string description: The base(funding) currency for the payment example: NOK country: type: string format: ISO 3166-1 description: The country that the payment is being initiated from example: 'NO' QuoteIntermediaryAccount: type: object required: - account - contactInformation properties: account: type: object description: Account information for funding client account required: - iban - bban - bic properties: iban: type: string description: International Bank Account Number example: SE7250000000012341212345 bban: type: string description: Basic Bank Account Number example: 12341212345 bic: type: string description: Bank Identification Code example: CITIXXXX contactInformation: type: object description: Creditor contact information allOf: - $ref: '#/components/schemas/QuoteContactInformationTo' QuoteTo: type: object required: - account - contactInformation properties: account: type: object description: >- Account information for creditor. Required fields depend on creditorCountry, but bban or iban should always be present. allOf: - $ref: '#/components/schemas/QuoteAccount' contactInformation: type: object description: Creditor contact information allOf: - $ref: '#/components/schemas/QuoteContactInformationTo' currency: type: string description: The payout currency for the payment (only used for SELL deal type) example: SEK QuoteContactInformationTo: type: object required: - name - address properties: name: type: string description: The name of the organization making the payment example: ZTL Payment Solution AS address: type: object description: The address of the organization making the payment allOf: - $ref: '#/components/schemas/QuoteAddressTo' QuoteContactInformation: type: object required: - name - address properties: name: type: string description: The name of the organization making the payment example: ZTL Payment Solution AS address: type: object description: The address of the organization making the payment allOf: - $ref: '#/components/schemas/QuoteAddress' QuoteAddress: type: object description: Address information for payer required: - streetName - buildingNumber - city - postCode - country properties: streetName: type: string description: Street name example: Kristian IVs gate buildingNumber: type: string description: Building number example: 15 city: type: string description: City or town name example: Oslo postCode: type: string description: Post code example: '0164' country: type: string description: Country format: ISO 3166-1 example: 'NO' QuoteAddressTo: type: object description: Address information for payee required: - streetName - buildingNumber - city - postCode - country properties: streetName: type: string description: Street name example: Eriksbergsgatan buildingNumber: type: string description: Building number example: 10 city: type: string description: City or town name example: Sweden postCode: type: string description: Post code example: 11430 country: type: string description: Country format: ISO 3166-1 example: SE QuoteMetadata: type: object description: Quote request metadata required: - organizationCountryCode - organizationNumber - endToEndId properties: organizationCountryCode: type: string description: Country format: ISO 3166-1 example: 'NO' organizationNumber: type: string description: The organization number of the company initiating the payment example: 920970931 endToEndId: type: string description: An ID that can be used to identify the payment example: 73300aef-d849-4872-b0c6-f44e07a841f3 QuoteAccount: type: object description: Account information for creditor required: - bic properties: iban: type: string description: International Bank Account Number example: SE7250000000012341212345 bban: type: string description: Basic Bank Account Number example: 12341212345 bic: type: string description: Bank Identification Code example: ESSESESS clearingCode: type: string description: Code required for payments to certain countries example: 1234 SupportedCurrency: required: - code - currencyName - isoScale - symbol - maxForwardTransactionAmount type: object properties: code: type: string example: EUR description: 3 letter currency code as defined by ISO-4217 format: iso-4217 currencyName: type: string description: The currency name in English as defined by ISO-4217 example: Euro isoScale: type: integer description: >- Number of decimals after the comma separator as defined by ISO-4217, used when displaying amounts in the given currency. E.g. 100 EUR is displayed as 100.00, while 100 JPY is displayed as 100 example: 2 symbol: type: string example: € maxForwardTransactionAmount: type: number description: > The maximum allowable amount for a transaction involving currency exchange that is classified as a *forward payment*. Transactions with a due date of today or tomorrow are considered *spot payments* and are not subject to this limit. Transactions with later due dates are considered *forward payments* and are restricted by this maximum amount. example: 0 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 GeneralErrorWithoutExampleObject: allOf: - $ref: '#/components/schemas/GeneralErrorObject' - type: object properties: message: type: string description: The underlying reason for the error Iban: type: object description: Country supports Iban bank account format. properties: type: type: string enum: - iban Swift: type: object description: >- Country supports Swift bank account format. A combination of BIC and local bank account number (bban) is required properties: type: type: string enum: - swift SwiftWithBankRouting: type: object description: >- Country supports Swift bank account format with additional bank routing/clearing code. A combination of BIC, local bank account number (bban) and BankRouting/ClearingCode is required properties: type: type: string enum: - swiftBankRouting routingName: type: string description: Local name for routingnumber/clearingnumber example: IFSC routingDescription: type: string description: >- Description of the required routingnumber/clearingnumer for the receiver country routingPattern: type: string description: ReqEx pattern for the routingnumber/clearingnumber value AdditionalRemittanceInformationRequired: type: object properties: type: type: string enum: - additionalRemittanceInformationRequired description: type: string description: Text description of the requirement requirementType: type: string enum: - PurposeCode - TaxCode - Reason description: > * `PurposeCode` A valid purpose code, either from validCodes list or pattern * `TaxCode` The receivers TaxId are required * `Reason` A reason for the payment (text) must be provided pattern: type: string description: RegEx pattern used to validate the value validCodes: type: array description: A list of accepted codes for the value items: type: object properties: code: type: string description: description: Description of the value type: string painArrayIndex: type: integer description: >- Pain XLM Array index for this value in unstructured remittance info (V1 payment only) securitySchemes: Authorization: type: oauth2 flows: clientCredentials: tokenUrl: https://oidc.sandbox.ztlpay-test.io/connect/token scopes: payments: ZTL PSD2 API parameters: PsuIpAddressHeaderRequired: name: PSU-IP-Address in: header 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. Mandatory in all calls in Sweden. required: true schema: type: string example: 192.158.1.38 PsuIpAddressHeader: name: PSU-IP-Address in: header 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. Mandatory in all calls in Sweden. required: false schema: type: string example: 192.158.1.38 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