Solutions Swish for merchants API manuals

4. Merchant Setup Process

4. Merchant Setup Process

4.1 Technical Integration

In order to integrate a merchant commerce solution with Swish API the merchant needs to get a client TLS certificate from Swish Certificate Management and install it on their server. The certificate will be used for client authentication of TLS communication with Swish API. The following steps need to be performed:

  1. Generate a pair of 4096 bits RSA keys on your server and create a certificate request (CSR) in a PKCS#10 format.
    This step depends on the type of web server solution that is used and differs between different types of servers. The keys are usually generated to a so-called keystore (e.g. Java keystore, Microsoft Windows keystore) or file (e.g. openSSL on Apache/Tomcat). For details please consult your web solution documentation or your supplier.

    Note: The following examples are to be considered regarding secure handling of cryptographic keys and certificates.  The Customer’s keys should be installed by the Customer in secure cryptographic units or should be protected in a similar manner. The keys should only be installed on units necessary for production and back-up purposes. The keys should be deleted at all instances when no longer operational. The keys should at all times be stored with strong encryption and protected using passwords or more secure procedures, e.g. smart-cards. Passwords used to protect the keys should be handled two jointly and are to be stored in a secure manner so they cannot be lost or subjected to unauthorized access.

    It is highly important to protect the private key from unauthorized access. It is recommended to protect the keys with a password if your server provides this option. Care should be taken to protect the passwords as well.

    There are no requirements on the content of the CSR (names or other parameters), except for the keys that need to be 4096-bit RSA.

    It is possible to install the same certificate on several servers (depending on technical server setup, but no license limitations), or to issue one key pair and certificate per server.

  2. Login to Swish Certificate Management at https://comcert.getswish.net by using mobile BankID, BankID on card or BxID. Only the person(s) registered by the bank for a specific merchant will be able to perform this step.
  3. Provide the organizational number of the merchant and the Swish number for which a certificate is to be generated.
  4. Choose tab “New certificate” and paste the content of the generated CSR into the text field. Choose whether the certificate should to be in PKCS#7 or PEM format. Consult your documentation regarding which format suits your solution.
  5. A new certificate is generated and provided on the screen. Copy the text string and save it to a file. The response (PKCS#7 or PEM) will contain your client certificate and all CA certificates up to the Swish root.
  6. Import the generated certificate and all CA certificates to your server. For details on how to perform this step consult your web solution documentation or your supplier.
  7. The Swish server is set up with a TLS server certificate, which needs to be verified when initiating TLS from your web server to Swish. Choose to trust DigiCert Global Root CA which can be downloaded here https://www.digicert.com/digicert-root-certificates.htm . For details on how to perform this step consult your web solution documentation or your supplier.

After performing the steps 1 – 7 you should be able to set up TLS with the Swish API.

Note: It is necessary provide the generated certificate together with all CA certificates up to the Swish Root CA in order to correctly set up a TLS session with the Swish API.

Note: No error messages will be returned before a TLS session is successfully established with the Swish API. This means that if the wrong certificate has been used, if the validity time of the certificate has expired, or if the certificate has been revoked, no indication of this is given.

Note: It is recommended to require verification of the Swish API TLS certificate and not to ignore this verification, in case your server allows you to disable server certificate verification.

4.2 Managing certificates

Login to Swish Certificate Management at https://comcert.getswish.net by using mobile BankID, BankID on card or BxID. Only the person(s) registered by the bank for a specific merchant will be able to perform this step.

Provide the organizational number of the merchant and the Swish number for which a certificate is to be managed.

After logging in a list is provided with all certificates associated with the specific merchant and Swish number, and the status of them. By clicking on “Download” it is possible to see further details and to attain the certificate again.

4.3 Revoking a certificate

If the integrity of the merchant’s private key has been compromised, if a certificate has been replaced by a new one, if the service has been terminated, or if the merchant needs to revoke a certificate for some other reason, this can be done via the Swish Certificate Management.

Login to Swish Certificate Management at https://comcert.getswish.net by using mobile BankID, BankID on card or BxID. Only the person(s) registered by the bank for a specific merchant will be able to perform this step.

Provide the organizational number of the merchant and the Swish number for which a certificate is to be revoked.

After logging in a list is provided with all certificates associated with the specific merchant and Swish number, and the status of them. By clicking on the trash can it is possible to revoke a specific certificate.

Please be aware that the certificate is irreversibly revoked and that revoking a certificate that is in use may lead to an interruption of the service.