V1 To V2 Migration Guide

This guide is aimed for existing partners using the existing 'ZTL API version 1' (V1), and will highlight the main differences between V1 and V2.

V2 has added support bank services for multiple countries, so there are some changes that are not related for Norway, we will highlight irrelevant changes for Norwegian customers/partners.

The biggest changes made in V2 is in payment services, where the focus has moved from the concept of 'all or nothing' baskets to single payments and signature as a separate functionality.

Please refer to the API documentations for full API documentations: * Version 2 Documentation * Version 1 Documentation

General changes for Version 2

Headers

• The headers from v1: IdempotencyKey, Idempotency-Key and PSU-Geo-Location are no longer used in V2
• All responses has the header ztl-request-id. This is a unique id for each request, and should be used if you need to contact ZTL support regarding problems with a specific API call
• PSU-User-Agent and PSU-IP-Address are used in many endpoints, and indicates if a user is active present. Please only use these headers when user are actually present.

Error handling

Error messages body format has been standarized, with some differences of available failure codes related to each endpoint. Each endpoint specifies which error code it may return. In general, we recommend to minimum handle the following error codes.

• 400 - Bad Request. The message format contains a failure code, see each endpoint for available error codes. We may add more error codes in the future, so we recommend handling of unknown enum values in a runtime-safe way. json { "failure": "Invalid_BBAN", "ztlRequestId": "350eb968-f4cf-474c-8cf2-f8068294d364", "message": "The underlying reason for the error" }

• 409 - Conflict. This error indicates that there are some problems with simultaneity usage of consent. There is a very low chance for this situation to occur, and would normally be resolved by retrying the request.

• 422 - Input validation failed. This error indicates that input validation failed. We specify error code specified for each endpoint and reason in english along with the path from the input that failed. We may add more error codes in the future, so we recommend handling of unknown enum values in a runtime-safe way.

[
  {
    "code": "InvalidBBAN",
    "reason": "Invalid BBAN",
    "path": ".from.account"
  },
  {
    "code": "InvalidDueDate",
    "reason": "Due date cannot be in the past",
    "path": ".dueDate"
  }
]

• 500 - Internal Server Error. Indicates that some unhandled error has occurred. We do not recommend to show the message to end user in case of these error types.

{
  "ztlRequestId": "350eb968-f4cf-474c-8cf2-f8068294d364",
  "message": "The underlying reason for the error"
}

API Changes

Authorization (Partner API token)

No changes from V1. The token is created in the same way as V1, and used in header: Authorization

Onboarding

V2 has a new onboarding solution, currently used for other countries than Norway. Until future notice, continue to use the V1 version of onboarding.

Banks

Added 'branches' in supported banks, see intended usage in Consent section.

Consent

Note that the existing consents from V1 are not compatible for V2 endpoints, so all users needs to create new consent before using V2 endpoints. V2 consents can neither be used for V1 endpoints.

The create consent endpoint creates a new consent, and starts authorization process automatically (sca url is available in response body). The optional body param preferredScaMethod can be ignored in Norway since all banks are using redirect authorization method. Once the consent has been successfully signed, the status can be validated and the consent are ready to use.

Nordea and Danske Bank has different bank branches under the same Bic number. To be able to distinguish these from each other, use the optional body param `bankBranch'. The available branches are available in the Supported banks endpoint.

The 'consentReference' from callbackUrl are no longer used. Instead, just use the consent-id header parameter for all endpoints which require consent.

Accounts

Note that there are some restrictions in the PSD2 regulations for how often a Third Party Provider (TPP) may utilize account information services without user presents, up to max 4 times per day for some banks.

There only differences worth mention between V1 and V2 in Accounts services is that the response bodies has been simplified by removing account information in balance and entries endpoints.

Payments

The payment services has significant changes. Where the V1 payment initiation was focused on basket of payments ('all-or-nothing'), V2 focuses on single payments, with signing of a list of initiated payments. The main benefits for the changes are:

• V2 operates single payment initiation rather than a list of payments (basket) from XML file. This gives the following benefits:

  • Instant feedback on payment initiation (succeeded, failed, validation error etc) for each single payment. In case of validation errors, 422 error are given for payment initiation and cross-border payments
  • No need to handle 'partly failed basket initiation'
  • Each transaction has unique Id, rather than needing to match end-to-end-id from basket/flowId
  • Status check for each transaction rather than on the whole basket
  • No need to handle complex XML format (PAIN ISO standard)

• Authorization/SCA has been separated from transaction initiation

  • Start signing process based on created transactions
  • If Sca fails, it's possible to create new Sca for the same transactions
  • We no longer cancel payments in basket based on Sca timeout
  • Easier to handle transactions that does not need SCA (eg: transactions from bank accounts owned by same company)
  • Easier to handle 4-eyes requirements
  • Once the signing is successfully completed, there is no need to check for future signing statuses

Payment initiation

This endpoint should be used for domestic payments. For international payments and currency account payments, use crossborder payment.

Payment initiation for single payments has the benefit that it gives instant feedback if the payment request is valid, and if initiation in bank is successfully initiated.

The request format is new compared to V1, where we have changed from XML to Json. There are some elements that are not used in Norway:

Also note that we support Iban bank account numbers. We reccomend to continue using bban numbers for domestic payments in Norway. This is included as there are some banks in other countires that only accepts Iban format even for domestic payments, but all Norwegian banks supports bban.

The expected responses types are: * 200 - Payment was successfully initiated and accepted by bank. Note that the payment status is available in the initial response * 400 - The payment request has been validated OK, but bank did not accept the payemnt request * 422 - Payment request validation failed.

The payment has to be signed if the initial payment status is Unsigned, see Payment Approval below.

Initiate crossborder payment

Cross border payments have slightly different body request compared to domestic payments. The response gives information about currency exchange rate, price in local currency, expiration date and intermidaryAccount (ZTL client account for funding).

The currency exchange quote is, just like for V1, valid for 2 or 5 minutes. We will automatically attempt to cancel the PSD2 funding payment if the payment is not signed within the quoteExpiryTime. Note that we do notguarantee that unsigned crossborder payments get successfully canceled as there might be bank variations.

The initial partner margin information has intentionally been removed compared with V1.

Bulk payment

Unfortunately, there are some banks that only support bulk payments. The functional flow are a bit different, as the SCA is directly linked to a list of payments on creation time, very similar to payments in V1. We have only implemented bulk for the few banks that does not support our preferred PSD2 payment initiation methods, and we're pushing the banks to be compliant with normal PSD2 functionalities in this area. For Norway, we only support this feature for Danske Bank (which does not support normal payment initiation/authorization). If you want to add support for this bank, please contact us for more details for our recommendations.

Status

Payment status can be fetched for both normal payments and crossborder payments.

Unsigned payments means that it has to be signed before executed.

CustomerActionRequred indicates that there is additional steps required for the payment to be executed. Note the PartlySigned enum in reason, that indicates that the payment requires additional signature (4-eyes). It is possible to create a new authorization request for the same payment for a different user/consent who has access to this account, and set up as secondary signer.

Detailed status overview

Here is an overview of the statuses available in V2, and the equivalent in V1.

Payment approval

With exception of bulk payment, the Signing process/SCA must be started after the payment has been created. The input is a list of payments ready to be signed (paymentstatus Unsigned). preferredScaMethod is not relevant for Norway, since Norwegian banks only supports redirect. Note that it is possible to create a new SCA request for a transaction that was previously included in a failed SCA.

Its also possible to retrieve the SCA status to verify if a user has completed a SCA signing. Note that this is only status for the signing itself, where the payment status has to be checked for the actual payment. The sca redirect url is only visible as long as the sca is unsigned.

Domestic from FX

This is deprecated and should not be used in Norway. Please use crossborder payment instead to initiate international payments.

FX Payments

These API are intended for partners which are not using the PSD integration, these API should be ignored for partners using bank integration. Please use cross-border payment instead.

Payroll

Payroll V2 has several similar significant changes as Payment V2 has, as described above. Payroll V1 treated a payroll as a single entity, meaning that you would get statuses for the whole operation, while in V2 you will get statuses on the individual transactions within the payroll. Similar with Payment V2, creating a payroll and approving it has been separated.

An important restriction with Payroll V2 is that it only supports NOK to NOK payments within Norway. If other types of payments are required, see cross-border payments.

The main changes and benefits of V2 are: * Payroll V2 uses the familiar JSON format for creating payrolls instead of the Pain XML format * Able to get statuses on the individual transactions rather than the payroll as a whole * Authorization/SCA has been separated from transaction initiation * Start signing process based on created payroll * If Sca fails, it's possible to create new Sca for the same transactions * Easier to handle 4-eyes requirements

Payroll initiation

A payroll request supports multiple transactions within the same request that are paid out to multiple different recipients.

The expected responses types are: * 200 - Payroll was successfully initiated and accepted by bank. Note that the påyroll status is available in the initial response * 400 - The payroll request has been validated OK, but bank did not accept the payroll request * 422 - Payroll request validation failed.

The payroll has to be signed if the initial payroll status is Unsigned, which is most of the time, see Payroll Approval below.

Payroll approval

The Signing process/SCA must be started after the payroll has been created. The input is the payroll id that was in the response body of the creation. Note that it is possible to create a new SCA request for a payroll that was previously included in a failed SCA.

Payroll Status

Unsigned payments means that it has to be signed before executed.

CustomerActionRequred indicates that there is additional steps required for the payment to be executed.

Detailed status overview

Here is an overview of the statuses available in V2, and the equivalent in V1.

There has been a major simplification of the statuses that are needed to handle which ultimately represents the same status, e.g. InProgress. They are also made to be very similar to Payment V2 statuses.

Currencies, Country and Companies

No changes, same endpoints as V1