FAQ
What is PSD2?
The Second Payment Services Directive obliges banks to open up payments infrastructure and customer data to other organisations (third party service providers) with customers consent.
Are there any restrictions to sandbox usage?
No. Sandbox is free and available for everybody to test and develop.
What kind of data your Sandbox contains?
Our sandbox contains dynamic data to get the best out of testing.
Who maintains Open Banking Developer Portal?
Portal is maintained by Oy Samlink Ab.
How can I gain access to production environment?
Production PSD2 API for each bank will be available at omasp-psdapi.samlink.fi, pop-psdapi.samlink.fi and sp-psdapi.samlink.fi respectively. Production TPP registration API for all banks will be available at reg.samlink.fi. Production authorization service for all banks will be available at authservice.samlink.fi.
When API was available in production?
API has been available in production since 9th of September 2019.
Accessibility
Accessibility is the practice of making your websites usable by as many people as possible.
It includes:
Semantic HTML, which improves accessibility.
Caring about accessibility demonstrates good ethics and morals, which improves your public image.
Other good practices that improve accessibility also make your site more usable by other groups, such as mobile phone users or those on low network speed.
PSD2 Fallback solution
Service Location
The PSD2 fallback solution can only be accessed via following addresses:
POP Bank: https://www5.poppankki.fi/
OmaSp: https://www5.omasp.fi/
Login
In order to log into NetBank on behalf of a customer, a TPP has to sign the login request using a valid eIDAS QSEAL certificate. This signature proves that the TPP is legally allowed to act as a service provider. The login request to be signed is the HTTP POST message generated from the username input form submission (or username/password when TAN list is used) on the NetBank login page.
Signing uses the same mechanism as used in the Berlin Group PSD2 API v1.3: [ https://tools.ietf.org/html/draft-cavage-http-signatures-10 ]. Headers that must be included in the login message are:
Digest: SHA-256 or SHA-512 digest of the message content, as specified by Berlin Group Implementation Guideline.
X-Request-ID: UUID, as specified by Berlin Group Implementation Guideline.
TPP-Signature-Certificate: TPP's eIDAS QSEAL certificate, as specified by Berlin Group Implementation Guideline.
Signature: as specified by Berlin Group Implementation Guideline (chapter 12.2), constructed from headers Digest, X-Request-ID and TPP-Redirect-URI.
The Digest and X-Request-ID headers must be included in the signature.
Example
Assuming a TPP login on behalf of a customer who has user identifier '00000000' and password 'password'.
The HTML form element in this login page instance has form identifier "id27" and thus the HTTP POST message is: [id27_hf_0=&fakeUserKeyDoNotRemove11=&username=00000000&password=password&loginButton=1].
The SHA-256 digest generated from the message body is: [SHA-256=RLCxP4W48XJU69Q22/glEa6BzmI9j77dM2qNFs53P0Q=].
A random UUID generated for the X-Request-ID is: [fa2d5609-b5ba-4bd2-a4d4-254e69a2972e]
Thus the headers are (the actual signature and certificate below are truncated to be human readable)
Digest: SHA-256=RLCxP4W48XJU69Q22/glEa6BzmI9j77dM2qNFs53P0Q=Signature: keyId="SN=f3abe28bee1e8f10,CA=OID.2.5.4.97=PSDFI-ABC-123456, C=FI, O=Samlink, CN=PSD2",\algorithm="rsa-sha512",\headers="Digest X-Request-ID",\signature="Ntxy.....Sg=="TPP-Signature-Certificate: MIIDDjCCAfYCCQDzq+KL7h6PEDANBg.....nRK7aXUSsmLQQDlMRtPHIbOR4sOzXXX-Request-ID: fa2d5609-b5ba-4bd2-a4d4-254e69a2972e
Change log
24-9-2023
ACFC status code can now be received for Savings Bank & Oma Savings Bank payments.
27-8-2023
PDNG status code can now be received with all payment types.
2023-06-11
OmaSb Visa Business Credit cards for private customers added to AIS API
Changes to PIS authorization error response
The following payment cancellation reason codes were added to the error response that is returned when a payment authorization request is cancelled by the PSU before the payment is confirmed.
AM04: Insufficient Funds
MS02: Not Specified Reason Customer Generated
New payment cancellation reason codes are returned using the error_description query parameter defined in the OAuth 2.0 specification.
Examples:
Previous response sent when the PSU cancels payment confirmation:
HTTP/1.1 302 Found
New response sent when the PSU cancels payment confirmation due to insufficient funds:
HTTP/1.1 302 Found
New generic response sent when the PSU cancels payment:
HTTP/1.1 302 Found
2023-04-23
The maximum validity time for consents was increased from 90 to 180 days. Existing consents, which were made before this change, remain unchanged and have the previous maximum validity time of 90 days. The fetched transaction history through the AIS API remains unchanged (only up to 90 days old transactions are returned, when SCA not applied).
2023-03-12
Added support for registering multiple OAuth2 redirect URIs in the TPP Registration API.
2022-10-30
The OAuth token-request no longer accepts duplicate key-values in the client_assertion (signed JWT) headers and instead throws an exception.
2022-08-28
V1 endpoint of PSD2 AIS api has been deprecated.
2022-03-06
New V2 of PSD2 AIS api. V1 will be deprecated on Sunday, August 28th 2022. All to-be-deprecated operations are marked in the documentation section.
V2 of the 'Read Transaction List' operation has been reworked. Querying for booked transactions with a provided timerange will now return up to 100 transactions instead of 1000 transactions. An error will no longer be thrown if more than 1000 booked transactions exist. Subsequent searches in blocks of 100 can be done by providing an entryReferenceKey. Executing further queries with a provided entryReferenceKey will not count towards the consent usage limit. This is a breaking change.
All versions of the 'Read Account Details' operation will now contain a list of the account owners in the 'ownerName'-field. This is not a breaking change.
{
"_links": {
"balances": "/payments/sepa-credit-transfers/1234-wertiq-983",
"transactions": "/payments/sepa-credit-transfers/1234-wertiq-983"
},
"bic": "XXXXFIHH",
"ownerName": "JOE SCHMOE, JOHN DOE",
"cashAccountType": "CASH",
"currency": "EUR",
"iban": "FI1648830010033144",
"name": "My account",
"product": "SÄÄSTÖTILI",
"resourceId": "e556ea77-615f-4b3f-affe-49ee3dfbcfb7",
"status": "enabled"
}V1 of the 'Get Payment Information' and 'Get Periodic Payment Information' operations will now contain a list of the debtor accounts owners in the 'debtorName'-field.
{
"creditorAccount": {
"bban": "BARC12345612345678",
"currency": "EUR",
"iban": "FI1648830010033144",
"maskedPan": "123456xxxxxx1234",
"msisdn": "+49 170 1234567",
"pan": "5409050000000000"
},
"creditorAddress": {
"buildingNumber": "string",
"city": "string",
"country": "SE",
"postalCode": "string",
"street": "string"
},
"creditorAgent": "AAAADEBBXXX",
"creditorName": "Creditor Name",
"debtorAccount": {
"bban": "BARC12345612345678",
"currency": "EUR",
"iban": "FI1648830010033144",
"maskedPan": "123456xxxxxx1234",
"msisdn": "+49 170 1234567",
"pan": "5409050000000000"
},
"debtorName": "Debtor Name, Debtor Name2",
"endToEndIdentification": "string",
"instructedAmount": {
"amount": "5877.78",
"currency": "EUR"
},
"remittanceInformationUnstructured": "Ref Number Merchant",
"transactionStatus": "ACCC"
}2021-12-12
App-to-app linking. CodeApp will be opened automatically during OAuth authorization process after user selects it and enters userid, when using a supported browser and mobile device. Both iOS and Android CodeApp clients are supported, with Chrome and Safari browsers.
2021-06-06
Extended consent usage counters, 90 day restriction for transaction queries, and single SCA for payments.
Consent usage counter, which allows queries four times per day, will be updated to be consent, account and request specific. A separate usage counter will be added to the transaction query parameters booked and pending allowing requests with both of these parameters to be executed four times per day.
The support for "withBalance" URL parameter will be added to ListAccounts request: GET /v1/accounts?withBalance=true
TPP can make an account inquiry and receive account and card transactions from 90 days with a valid consent. The valid consent will allow for fetching transactions up to 12 + 1 months in the past for a short time period after authorization, before limiting to 90 days of history data.
Changes in strong authentication within the payment flow. Strong authentication is done at the start of the payment authorization, and separate strong authentication is no longer required in connection with the payment confirmation. This will fulfill the single-SCA requirement. The PSD2 UI (suostumus- ja vahvistuspalvelu) displays the payment information (dynamic linking) to the user in connection with the payment confirmation.
2020-12-09
Added Card Account operations, and made debtorAccount optional in payment initiation.
Read List of Card Accounts: GET /v1/card-accounts
Read Card Account Transaction List: GET /v1/card-accounts/{account-id}/transactions
DebtorAccount is now optional in Payment initiation request. Leaving the field empty will allow the PSU to select the account after login.
2020-03-08
Added support for future dated payments with requestedExecutionDate in the future.
New sandbox endpoint /management/execute-future-dated-payments to help with testing future payments.
2020-02-06
Consent and Payment initiation response _links/scaOAuth now points to OAuth metadata endpoint, instead of straight to authorize endpoint:
{
"_links": {
"scaOAuth": "https://sml-prod-psd2.azure-api.net/.wellknown/oauth-authorization-server",
"self": "/psd2/v1/consents/gqHPIqjwpp",
"status": "/psd2/v1/consents/gqHPIqjwpp/status"
},
"consentId": "gqHPIqjwpp",
"consentStatus": "received",
"scaMethods": []
}Metadata endpoint https://sml-prod-psd2.azure-api.net/.wellknown/oauth-authorization-server will return a JSON with the authorization and token endpoints:
{
"issuer" : "https://sml-prod-psd2.azure-api.net",
"authorization_endpoint" : "https://sml-prod-psd2.azure-api.net/samlink-api-sandbox/oauth/authorize",
"token_endpoint" : "https://sml-prod-psd2.azure-api.net/samlink-api-sandbox/oauth/token"
}Payment initiation response now contains the _links element as above, and transactionFeeIndicator element with value "false".
Consent usage counts are now not increased if the request contains PSU-IP-Address header, which indicates that the consent user is active in the TPP application while the request was made.
2020-03-08
Added support for future dated payments with requestedExecutionDate in the future.
New sandbox endpoint /management/execute-future-dated-payments to help with testing future payments.
2020-12-09
Added Card Account operations, and made debtorAccount optional in payment initiation.
Read List of Card Accounts: GET /v1/card-accounts
Read Card Account Transaction List: GET /v1/card-accounts/{account-id}/transactions
DebtorAccount is now optional in Payment initiation request. Leaving the field empty will allow the PSU to select the account after login.
