Swiss Open Banking Developer Page
Welcome to the Open Banking API developer page describing Ergon's sandbox environment. The aim of our sandbox is to easily develop and test a Third-Party Provider (TPP) application for the Swiss NextGen API. This includes use cases, where a TPP can request to read the customer's bank accounts and create payments in the name of the customer.
The Swiss NextGen API is an extended version of the PSD2 API by the Berlin Group. It meets all special requirements of Swiss payment regulations and strives to become the standard API for open banking in Switzerland.
The sandbox is based on our Swiss Open Banking Solution. It provides a ready-to-run application for banks to integrate and offer the Swiss NextGen API Standard. As a result, they can enter new markets and create improved customer experiences.
Sandbox architecture
Airlock
Airlock is a Secure Access Hub developed by Ergon to protect web applications and grant secure access management. Although integrating Airlock in the architecture is not required, we recommend Airlock's PSD2 module to add custom-made security features to the Swiss Open Banking Solution.
Swiss NextGen API
The Swiss NextGen API, which is applied by the TPP and defined by the OpenbankingProject.
Web application for consent management
A customer web application to view all "active" consents with the option to revoke them.
Web application for consent authorisation
A customer web application to accept or deny account consents and payments. The user is redirected by the TPP to this web application and guided by a user-friendly interface.
Online banking
A mock-up of immutable data to provide functionalities needed for the Swiss NextGen API and the consent management application. In a productive environment it would be replaced by a core banking backend and/or an online banking server.
Strong customer authentication (SCA) method
The Ergon Swiss Open Banking Solution uses redirection for SCA. After initiating a consent or a payment, the sandbox returns a URL to which the TPP redirects its users.
Start testing
The Sandbox provides a simplified environment for developers, therefore the certificate handling and the user login on the consent management is omitted.
Postman
We use Postman to develop and test our Swiss Open Banking Solution. We provide the Postman environment configuration for the sandbox together with the account information requests as well as the payment initiation requests. They provide the configuration to access the sandbox and show examples on how to properly form your requests. Therefore, we recommend downloading the Postman client and to import the files.
Please note that the request collections also contain requests, which the consent management application of the bank would perform, when the user interacts with the user information. These are not requests you have to implement in your TPP application but they provide a faster way to create and approve consents and payments. Feel free to execute these requests instead of interacting manually with the consent-management application.
The requests prefixed with "TPP" indicate requests the TPP application would call. The requests prefixed with "CMS" are called by the consent management application and cannot be called by the TPP in real life, since they are protected via bank login.
Warning
Note that due to this simplified setup, all developers using the sandbox share the same TPP ID and can see other developers' data. Please always use mock data, never real-life data!
Account information use case
Let's assume the TPP is a loan provider who wants to read the customer's bank accounts in order to create a personalised offer for a loan. In this case, the loan application of the TPP would first execute a request to create a new consent.
Postman action
Execute the request no 1 with Postman.
The TPP might pass along a list of accounts, which it received from the customer or simply leave the consent blank to get access to whatever accounts the customer will grant access for. The answer for the request would look roughly like the below:
{
"consentStatus": "received",
"consentId": "MmF5ff5I_EIJySWG-EaC_7moFEieyGS6qLPNfMjfnN_0sJxzjJZwQogVubgNMU_bVk6tDBU-9YRguOF9hI9mcPSdMWF3876hAweK_n7HJlg=_=_psGLvQpt9Q",
"_links": {
"scaRedirect": {
"href": "https://bank.openbanking.ergon.ch/consent-api-psu/app/account/consent/2e4bcf88-5bc2-4c42-a4e6-1667dac238ba/MmF5ff5I_EIJySWG-EaC_7moFEieyGS6qLPNfMjfnN_0sJxzjJZwQogVubgNMU_bVk6tDBU-9YRguOF9hI9mcPSdMWF3876hAweK_n7HJlg=_=_psGLvQpt9Q/43a8b150-e869-44cd-8079-d2f9061b00b5"
},
"self": {
"href": "http://swissnextgenapi.openbanking.ergon.ch/v1/consents/MmF5ff5I_EIJySWG-EaC_7moFEieyGS6qLPNfMjfnN_0sJxzjJZwQogVubgNMU_bVk6tDBU-9YRguOF9hI9mcPSdMWF3876hAweK_n7HJlg=_=_psGLvQpt9Q"
},
"status": {
"href": "http://swissnextgenapi.openbanking.ergon.ch/v1/consents/MmF5ff5I_EIJySWG-EaC_7moFEieyGS6qLPNfMjfnN_0sJxzjJZwQogVubgNMU_bVk6tDBU-9YRguOF9hI9mcPSdMWF3876hAweK_n7HJlg=_=_psGLvQpt9Q/status"
},
"scaStatus": {
"href": "http://swissnextgenapi.openbanking.ergon.ch/v1/consents/MmF5ff5I_EIJySWG-EaC_7moFEieyGS6qLPNfMjfnN_0sJxzjJZwQogVubgNMU_bVk6tDBU-9YRguOF9hI9mcPSdMWF3876hAweK_n7HJlg=_=_psGLvQpt9Q/authorisations/2e4bcf88-5bc2-4c42-a4e6-1667dac238ba"
}
},
"psuMessage": ""
}
The loan application can extract the scaRedirect URL and redirect the customer's browser to this URL. This URL points to the site of the customer's bank and starts the bank's consent management application.
Browser action
To simulate the redirection, please copy the value from the answer you receive in your postman request and paste it into the address bar of your browser.
After logging into the bank account (not needed in sandbox environment), the user is presented with the screens below.
1. Account selection
The user selects the accounts that the TPP is allowed to access. Please note that in the current consent-management application balances and transactions are always included for each selected account.
2. Transaction signing
The user scans the cryptogram and enters the code. Use '0000000' to simulate the TAN.
3. Redirection
This is the redirection screen after confirming the transaction.
At the end of the account-approval process, the bank's consent management application will redirect the user to the URLs the loan application passed along in its first request. They are passed with the headers TPP-Redirect-URL for a successful ending to the process. Alternatively, TPP-Nok_Redirect-URL for an unsuccessful ending or to cancel the process. Therefore, the loan application should choose URLs that determine whether the process was successful or not.
The loan application can call either endpoint in the Account Information Service in the Swiss NextGen API at any point in the process. This allows the loan application to monitor the state of the consent and to retrieve customer-account information. Such information can only be retrieved from specified accounts after the customer has completed the consent approval process.
Postman action
Please note that requests 5-10 of the Account Consent Collection are not required to grant access to an account. Nevertheless, they provide useful information about the status of the request for approval.
Payment use case
Let's assume the TPP is an online shop. The customer has chosen a number of items to buy and opted for open banking as the payment method. The TPP then creates a payment from the customer's bank account to the shop's bank account. The first step would be:
Postman action
Execute the request no 1 in the Complete round trip use case.
This will create a temporary payment instruction, which the user will have to review and approve. A typical answer from this request will look like this:
{
"transactionStatus": "RCVD",
"paymentId": "Ew6fUemXdJrEXvUA1oSUbnTeQDtpRdYvjycq7XHxAfuSGrMvM2ci6Lw2dBiipRuM3t8arzxVIETJPRlC18AIY_SdMWF3876hAweK_n7HJlg=_=_psGLvQpt9Q",
"_links": {
"scaRedirect": {
"href": "https://bank.openbanking.ergon.ch/consent-api-psu/app/payment/approve/a159f0ed-7a1b-4180-9117-1f5143ed3877/Ew6fUemXdJrEXvUA1oSUbnTeQDtpRdYvjycq7XHxAfuSGrMvM2ci6Lw2dBiipRuM3t8arzxVIETJPRlC18AIY_SdMWF3876hAweK_n7HJlg=_=_psGLvQpt9Q/f1a62aff-c09e-4557-ad7c-f3ae175a3135"
},
"self": {
"href": "http://swissnextgenapi.openbanking.ergon.ch/v1/payments/swiss-sepa-credit-transfers/Ew6fUemXdJrEXvUA1oSUbnTeQDtpRdYvjycq7XHxAfuSGrMvM2ci6Lw2dBiipRuM3t8arzxVIETJPRlC18AIY_SdMWF3876hAweK_n7HJlg=_=_psGLvQpt9Q"
},
"status": {
"href": "http://swissnextgenapi.openbanking.ergon.ch/v1/payments/swiss-sepa-credit-transfers/Ew6fUemXdJrEXvUA1oSUbnTeQDtpRdYvjycq7XHxAfuSGrMvM2ci6Lw2dBiipRuM3t8arzxVIETJPRlC18AIY_SdMWF3876hAweK_n7HJlg=_=_psGLvQpt9Q/status"
},
"scaStatus": {
"href": "http://swissnextgenapi.openbanking.ergon.ch/v1/payments/swiss-sepa-credit-transfers/Ew6fUemXdJrEXvUA1oSUbnTeQDtpRdYvjycq7XHxAfuSGrMvM2ci6Lw2dBiipRuM3t8arzxVIETJPRlC18AIY_SdMWF3876hAweK_n7HJlg=_=_psGLvQpt9Q/authorisations/a159f0ed-7a1b-4180-9117-1f5143ed3877"
}
}
}
The online shop application needs to extract the scaRedirect URL and redirect the customer's browser to this URL. The URL points to the site of the customer's bank and will launch the bank's consent management application process.
Browser action
To simulate the redirection, copy the value from the answer you receive in your postman request and paste it into the address bar of your browser.
After logging into the online banking of the bank (not needed in sandbox environment), the user is presented with the screens below. Please note no real bank account is needed for the sandbox.
1. Payment verification
The user verifies the payment.
2. Transaction signing
The user scans the cryptogram and enters the code. Use '0000000' to simulate the TAN code in the sandbox.
3. Redirection
This is the redirection screen after confirming the transaction.
At the end of the payment approval process, the bank's consent management application redirects the user to the URLs the online shop application passed along during its first request. They are passed with the headers TPP-Redirect-URL for a successful ending to the process. Alternatively, TPP-Nok_Redirect-URL for an unsuccessful ending or to cancel the process. Therefore, the online shop application should choose URLs that determine whether the process was successful or not.
The online-shop application can call either endpoint in the payment initiation service in the Swiss NextGen API at any point in the process. They allow the online-shop application to monitor the state of the payment.
Postman action
All TPP requests from 01a to 08b can be called once the initial request has been executed. They return information about the payment and its state and also offer the possibility to cancel a payment.
Glossar
| TPP | Third-party provider |
| SCA | Strong customer authentication |
| AIS | Account Information Service |
| PIS | Payment Initiation Service |
| NextGenPSD2 | PSD2 API specifications by the Berlin Group |
| Swiss NextGen API | Swiss OpenBanking API specifications based on NextGenPSD2. The specifications are being defined by the OpenbankingProject. |
| Ergon Swiss Open Banking Solution | Implementation of the NextGenPSD2 and the SwissNextGenAPI. |
| Airlock | Ergons Secure Access Hub (API Gateway, Web Application Firewall, Identity Access Management, two-factor authentication) |
Contact at Ergon
Open banking in Switzerland? Not so fast!
The brakes are still on open banking in Switzerland. Examples from the UK show that smart regulation releases enormous potential for banks and fintechs.
“Building a good ecosystem within Switzerland”
The OpenBankingProject.ch project got off to a successful start. Adrian Berger, MD Finance & Telecom Solutions at Ergon, on its background and expectations.
Finnova launches Open Banking as a Service solution
Finnova launches Open Banking as a Service solution. Ergon's Swiss open banking solution is a central part of the as-a-service product.