Swedbank is supporting several types of digital certificates - depending on relationship between bank and You as client. If there is signed agreement for using API or API doesn't need authentication, then You are treated as PARTNER flow. If it's used PSD2 API's then it's treated as PSD2 flow.
- Authentication Certificate - used for establishing mTLS between bank and You as client.
- Qualified Web Authentication Certificate (QWAC) for PSD2 or PARTNER flows
- TLS/SSL single domain Certificate for PARTNER flows only
- TLS/SSL wildcard Certificate for PARTNER flows only
- No certificate - for API's that doesn't require authentication, for example ping endpoint.
- e-Seal/signature Certificate - used for signing requests made towards bank.
- Qulified Electronic Seal Certificate (QSEAL) for PSD2 or PARTNER flows
- e-Seal Certificate for PARTNER flows only
- No certificate - for requests that doesn't require signing, check API documentation.
When You have certificate(s) it's needed to onboard them to Swedbank. This is done in Developer Portal
Certificates can be assigned to one or multiple applications. It depends on Your setup, but it's highly recommended not to add production certificates to sandbox applications, just to avoid misuse of them.
- select application, to which should be assigned certificate(s).
- on new page there is button/drop down "Actions" on right side of page, select "Edit Application".
- on new page, on left side there is menu, select "Custom Fields" menu.
Here are two fields: QSeal certificate and QWAC certificate, where You need to add appropriate certificate. If You have PARTNER flow and don't have QWAC/QSEAL certificate, to QWAC field add authentication certificate, and to QSEAL field e-Seal/signature certificate.
First You need to extact/export public certificate into pem file format. This can be done with openssl command:
openssl pkcs12 -in certname.pfx -nokeys -out cert.pem
Open this cert.pem file with text editing application, for example notepad. It should be text starting with "-----BEGIN CERTIFICATE-----" and ending with "-----END CERTIFICATE-----". You should copy text between those two lines and paste into appropriate field.
When certificate fields filled, now press button at the bottom "Next", and on new page button at the bottom "Save". That's it certificates are assigned to Your application. Depending on situation certificate will be activated in swedbanks side from 1 till 5 working days
There is possibility to check status of certificate - refer to mTLS establishment.
All certificates expire, depending on Certificate Authority it can be valid for 1 or 2 years as standard. Before certificate expires, it needs to be issued new certificate and onboarded in Developer Portal. There are two ways to do it:
- Update certificate for same application, to which is assigned expiring certificate - do certificate onboarding steps on application, to which is assigned expiring certificate. Swedbank keeps all onboarded certificates in it's local cache, so overriding certificate does not affect application usage. After onboarding several certificates on same application, all certificates can be used interchangeably, while certificate is valid - not expired, not revoked.
- Create new application and onboard new certificates to it. This solution have one drawback - already issued tokens on old application will not work with new application.
Most of API endpoints require Mutual Transport Layer Security(mTLS), when both client and server are authenticated, this way both know with whom they are talking to. For this to happen both sides are using their private key to encrypt communication.
First it's suggested to check if You are establishing mTLS by requesting https://psd2.api.swedbank.com/support/v2/testMutualSSL. This endpoint usage details can be seen in Developer Portal "Test QWAC" API.
curl -k --key myPrivateKey.key --cert myPublicCert.pem "https://psd2.api.swedbank.com/support/v2/testMutualSSL"
If in response mTLS object, status field is FAILED, then check description field, it will explain what is wrong. It might be that certificate is not set in Developer Portal to any application or it's still in onboarding state.
If in response mTLS object, status field is OK, then You'll get certificate details plus applications names list, to which this certificate is assigned to.
There is also a way to check what is in Swedbank configuration related to certain application, for that You need to provide info from Developer Portal: client_id - API Key (Client ID); client_secret - Shared Secret (Client Secret); redirect_uri - OAuth Callback URL(s) (full field value)
curl -k --key myPrivateKey.key --cert myPublicCert.pem -X POST "https://psd2.api.swedbank.com/support/v2/testMutualSSL" -d"client_id=xxxxxx&client_secret=xxxx&redirect_uri=xxxxxx"
There will be provided providedAuthentication object with details and onboarded certificates with their statuses
Some API endpoint requests require signing, for this is used Signing Certificate. Swedbank API actually doesn't use body signing, it's used some headers signing.
Swedbank have prepared web GUI to debug request signing, You'll need to provide Signing Certificate public pem format, body and some headers. In return it'll provide all values for signature header generation. Try it out on Your own on Test signature page
Further will provide some possible errors and possible way of fixing it, while generating signature header. One of the headers is "digest" - request body SHA256 hash encoded with BASE64. If on this page calculated digest and Your application calculated digest are different, then please check:
- Pay attention to Operating System newline symbol - Windows have 2 chars representing newline, while Linux have one symbol.
- Are body pasted in page and Your application generated bodies are the same, take special attention to newline symbols. Best way to verify is it newline symbol problem - remove all of them and calculate digest. Double check if there is no newline at the end of body.
- Digest calculation should output binary format, which should be base64 encoded. Some applications sha256 hash are returning in HEX format representation.
To verify on Your server try command:
echo -n "{}" | openssl dgst -binary -sha256 | base64
After body digest calculation, we need to construct signing string, which will be signed with Signing Certificate. Signing string consists of header/value list. Here is simple code how it could be created:
signingString = "";
headersString = "";
for header in [digest,date,x-request-id] do;
if ( !signingString.isEmpty() ) {
signingString += char(10); // to avoid mistakes based on OS, use char representation instead of \n
headersString += " ";
}
signingString += header + ": " + http.getHeader( header ); // header value should be taken from http
// request, sometimes there is mistake,
// when date in signingString differs
// from http request.
headersString += header;
done;
Now it's time to sign this signingString, based on Your certificate signing algorithm might be different, here is one of possible commands
echo -en "[signingString]" | openssl dgst -sha256 -binary -sign client_signing.key -passin "pass:changeit" | base64 -w 0
when all components are gathered, need to create signature header: keyId="SN=...,CA=...", algorithm="...", headers="[headersString]", signature="[base64 encoded signingString signature]".
- SN
- Signing certificate serial number in HEX format, if You have doubts check it in Test signature page
- CA
- Signing certificate issuer DN name, some names have none ASCII characters, so it's needed to be base64 encoded. Also different applications output different name, it's best to check it on Test signature page
- algorithm
- certificate algorithm type – rsa-sha256 or rsa-sha512, please check "Signature Algorithm" field in certificate.
- headers
- value from headersString
- signature
- value from signing signingString