1.0 Guide Swish API 170324 Utan ändringsmarkering

User Manual:

Open the PDF directly: View PDF .
Page Count: 36

Download
Open PDF In Browser	View PDF

Version 1.6

Guide Swish API
Integration Guide

Datum: 2017/03/24

Table of content
1

Introduction ....................................................................................................................................... 5
1.1

Terms and definitions ................................................................................................................ 5

1.2

Document purpose .................................................................................................................... 6

1.3

Swish overview ......................................................................................................................... 6

1.4

Payment .................................................................................................................................... 6

1.4.1

Swish e-commerce ............................................................................................................ 6

1.4.2

Swish m-commerce ........................................................................................................... 7

1.5

Refund ....................................................................................................................................... 8

1.6

Security ..................................................................................................................................... 8

Use Cases ........................................................................................................................................ 9
2.1

Swish handel application procedure ......................................................................................... 9

2.2

Payment request in the Swish app ......................................................................................... 10

2.2.1

Swish m-commerce ......................................................................................................... 10

2.2.2

Swish e-commerce .......................................................................................................... 11

2.2.3

Reject payment ................................................................................................................ 11

2.3

Refund ..................................................................................................................................... 11

2.4

Termination Swish handel ....................................................................................................... 12

Technical Requirements................................................................................................................. 12

Merchant Setup Process ................................................................................................................ 12

4.1

Technical Integration ............................................................................................................... 12

4.2

Managing certificates .............................................................................................................. 13

4.3

Revoking a certificate .............................................................................................................. 13

Launching Swish app from merchant app ...................................................................................... 14
5.1

Detecting if Swish app is installed on the device .................................................................... 14

5.1.1

iOS (detect) ...................................................................................................................... 14

5.1.2

Android (detect) ............................................................................................................... 14

5.1.3

Windows Phone (call the Swish app) .............................................................................. 15

5.1.4

Detection with mobile web browsers ............................................................................... 15

5.2

Switch to Swish app, and back ............................................................................................... 16

5.2.1

iOS ................................................................................................................................... 16

5.2.2

Android ............................................................................................................................. 17

5.2.3

WinPhone ........................................................................................................................ 18

5.2.4

JavaScript calls and open Swish ..................................................................................... 19

5.2.5

For Chrome version >= 24 ............................................................................................... 19

Test Environment ........................................................................................................................... 20

Production Environment ................................................................................................................. 20

Guidelines for using the Swish API ................................................................................................ 20
8.1

Consumer in control of payment requests .............................................................................. 20

8.2

Use the call-back for payment requests and refunds ............................................................. 21

8.3

Refund transactions – avoid large batches ............................................................................. 21

8.4

Renewal of Client TLS Certificate ........................................................................................... 21

8.5

Displaying the Swish alias to consumers ................................................................................ 21

Versioning the Web Service API .................................................................................................... 21
9.1

Versions .................................................................................................................................. 21
Support ....................................................................................................................................... 22

10.1

Deployment support ............................................................................................................ 22

10.2

Operating information .......................................................................................................... 22

Swish API Description ................................................................................................................ 23

11.1

Payment Request ................................................................................................................ 23

11.1.1

Swish e-commerce .......................................................................................................... 23

11.1.2

Swish m-commerce ......................................................................................................... 24

11.1.3

Create Payment Request ................................................................................................ 24

11.1.4

Retrieve Payment Request .............................................................................................. 26

11.1.5

Callback ........................................................................................................................... 27

11.2

Payment Refund .................................................................................................................. 28

11.2.1

Create Refund.................................................................................................................. 29

11.2.2

Retrieve Refund ............................................................................................................... 30

11.2.3

Callback ........................................................................................................................... 31

11.3

Objects ................................................................................................................................ 31

11.3.1

Payment Request Object ................................................................................................. 31

11.3.2

Refund Object .................................................................................................................. 34

11.3.3

Error Object...................................................................................................................... 35

Date

Version

2015-11-13

0.9.8

2015-12-08

0.9.8.1

Claes Scheffer

2015-12-10

0.9.8.2

Claes Scheffer

2015-12-15

0.9.8.3

Claes Scheffer

2016-01-18

1.0

2016-02-12

1.1

2016-04-22

1.2

Sylvain Schüpp
Roland Mattsson
Sylvain Schüpp

2016-10-04

1.3

David Selander

2016-12-13

1.4

David Selander

Name

Description
Version 0.9.8
Changed document name to Guide Swish API.
1.3 Changed some wording.
2.1 Added personal information that needs to be
registered about the CPOC.
3 Added information about port.
4 Added guidelines for handling keys and
certificate.
8.2 Added refund.
11.1.3 Changed url in code examples.
11.1.4 Changed url in code examples.
11.1.5 Added information about time outs.
11.2.1 Deleted error codes AC05, AC06, AC07,
AC15, AM04, AM14, AM21, and DS0K.
Added error code RF07.
Changed url in code examples.
11.3.1 Clarified mandatory, optional and
response parameters.
Deleted error codes AC05, AC06, AC07, AC15,
AM04, AM14, AM21, and DS0K.
Added error code RF07.
11.3.2 Clarified mandatory, optional and
response parameters.
Deleted error codes AC05, AC06, AC07, AC15,
and AM04.
Added error code RF07.
7 Corrected Swish API URL for paymentrequests
3 Complemented information about the
requirement of TLS certificate for callback
endpoint.
11.1.3 Changed payerAlias number format in
example.
11.1.4 Changed payerAlias number format in
example.
11.2.2 Added possible statuses.
Changed payerAlias number format in example.
11.2.3 Added DEBITED.
11.3.2 Changed CREATED to VALIDATED.
1.5.1 Changed text.
1.5.2 Corrected text.
5.1.1 Corrected text and Changed the heading for
Windows phone example.
Created document version 1.0.
5 Reformatting of code example, App Section
updated.
11.1.4, change m to e-commerce
11.2.1 Change payerAlias to 1231181189
11.2.2 Change payerAlias to 1231181189
11.3.1 Changed text for errorcode RF07
Added error code BANKIDONGOING
11.3.2 Changed text for errorcode RF07

2017-02-22

1.5

Oscar Jonsson
David Selander

2017-03-24

1.6

David Selander

Added 5.2.4 JavaScript calls Swish
Added 5.2.5 For Chrome version >= 24
Changed text 11.1 Payment Request
11.1.5 Cutofftimer changed from 8/5 min to 3 min
11:3:1 Added errorcode BANKIDUNKN
3. SNI not supported.

1 Introduction
1.1 Terms and definitions
Term

Definition

Partner

A partner is a company, working with technical integrations, app development,
platform development and/or payment services that may help and facilitate
merchant integration and operation for Swish.
Banks have agreements with the merchants who in turn may have an
agreement with a partner.

Merchant

A merchant is a company, association or organisation which receives
payments via Swish.
Merchants sign Swish agreements with their respective bank.

Merchant Swish
Simulator

The Merchant Swish Simulator is a test tool to test the Swish-API.

Consumer

A consumer is a private Swish customer that can use the Swish app on a
mobile device.

Swish handel

Swish handel gives the merchants the possibility to use Swish as a payment
method in m- and e-commerce. The service is aimed primarily for m- and ecommerce stores, via apps and browsers.
Swish handel consist of two different payment solutions; Swish m-commerce
and Swish e-commerce, a security solution and a function for refunds. All of
them are reachable for the merchants through Swish API.
The service can be offered by the banks under a different product name than
Swish handel.

Swish m-commerce

Swish payments from a mobile device made either through an app or via a
mobile browser on the same mobile device.

Swish e-commerce

Swish payments initiated by the consumer in a browser in equipment other
than the mobile device that hosts the Swish app.

Swish customer

This is any customer to Swish, either a consumer (person) or a merchant.

Payee

This is the Swish customer that receives the payment

Payer

This is the Swish customer that makes the payment

Alias

A unique identifier for a Swish customer. For a consumer it is the mobile
number and for a merchant it is the Swish number.

Payment request

A payment request is a transaction sent from a merchant to the Swish system
to initiate an e-commerce or m-commerce payment.

Payee Payment
Reference

A payee payment reference is the merchant’s own identifier of the
transaction/order to be paid. It is sent to the Swish system as a parameter to
the payment request and is later returned in confirmation messages.

Refund

A refund is a transaction sent from the merchant to the Swish system to return
the whole amount or part of a payment. The reference to the original payment
must be provided.

1.2 Document purpose
The integration guide is for anyone who wishes to understand and implement Swish handel in their
services and systems. The integration guide explains how to connect to the Swish API and includes
information about the payment and refund options related to the Swish handel service. More
information about the service can be found at https://www.getswish.se/handel.

1.3 Swish overview
By enrolling to the service Swish handel at the merchant’s bank and getting access to the Swish API,
merchants can handle payments in e-commerce and m-commerce scenarios in a way which is very
convenient and familiar to millions of Swedish consumers. The service builds on the ease-of-use of the
person-to-person payment service. Enrolled to the service the merchant can receive payments from all
private persons using Swish.
It is also possible for merchants to make refunds in real time using Swish using the API. Some banks
will also provide the possibility to initiate refunds from the bank’s digital channels.
In brief, a payment involves the following steps:



The merchant creates a payment request using the Swish API that the consumer views and
accepts in the Swish app.
The consumer and the merchant receive payment confirmations instantly when the amount
has been transferred from the consumer’s to the merchant’s account. For security reasons the
payment request is only valid during a limited period time for the consumer in the Swish app.

When enrolling to the service, the merchant obtains a Swish alias to one of the merchant’s bank
accounts. The merchant will also give authorize Certificate Point of Contact persons during enrollment.
These persons will use the Swish Certificate Management System to manage digital certificates, which
is one component of securing the access to the API.
The business transaction when a payment is made using Swish is between the merchant and the
consumer and this transaction implies that the consumer makes an advance payment for purchased
goods or services.

1.4 Payment
It is always the consumer that initiates a payment, and there are two ways to do it; Swish e-commerce
or Swish m-commerce.

1.4.1 Swish e-commerce

The consumer initiates the payment on the merchant’s web shop. In this case the consumer needs to
open the Swish-app.

The consumer opens the
Swish app, which is
preloaded with payment
information.

The consumer signs the
payment with Mobile
BankID

A payment confirmation is
shown in the Swish app.

1.4.2 Swish m-commerce

The consumer initiates the payment on the merchant’s app using a mobile device. In this case the
consumer does not need to open the Swish-app.

The consumer
chooses to pay
with Swish from the
merchant’s app or
website.

The Swish app is
activated
automatically and
preloaded with
payment
information.

The consumer
signs the payment
with Mobile
BankID.

The consumer gets
the payment
confirmation in the
merchant’s app or
website.

1.5 Refund
A merchant that has received a Swish payment can refund the whole or part of the original transaction
amount to the consumer.
A refund can only be done on an existing payment. The number of refunds on one payment is
unlimited, until the total amount reaches the amount of the original payment. A payer Order payment
reference ID and message to the consumer can be attached to the refund but these are optional. If the
refund is successful, a message will be sent to the payee’s app.
A refund can be made on a payment for 12 months.

1.6 Security
In order to protect the Swish API and to ensure the identity of the parties, the security solution
encrypts the traffic and authenticates the identities of the merchant and Swish server.
The security solution is implemented as PKI based TLS client/server certificates, where the certificates
are issued upon order by the merchant or someone appointed by the merchant. A certificate is valid
for 2 years.
A merchant appoints up to 5 persons via their bank, who will be able to logon to an administrative GUI
connected to the security solution (identified by BankID/BxID on card or Mobile BankID). An appointed

person can administer their certificates using the GUI. An administration of certificates includes view,
order new/download and revoke.

2 Use Cases
The user stories below act as example to increase the understanding of the service Swish handel on a
high level.

2.1 Swish handel application procedure
This user story describes on a high level how a merchant applies for the service Swish handel.
1. The merchant contacts a Swish connected bank to sign an agreement for the service.
2. The merchant confirms the business terms and signs the agreement with the bank.
a. The bank obtains and registers the necessary merchant information, including info
about the appointed recipients of the API certificate - CPOC (Certificate Point Of
Contact). The following personal information is mandatory about the CPOC: Social
Security Number, Name, Company Registration Number. Optionally, some banks will
also require additional information such as E-mail and phone number.
b. A Swish number is created for the agreement.
c. The bank sends an enrollment request to Swish security solution.
3. The security solution receives and registers info about the CPOC connected to the Swish
number. The CPOC’s are granted access to the certificate management system in the Swish
security solution.

4. The merchant is now ready for Swish API access.

5. The merchant or the partner needs to generate a csr-file (Certificate Signing Request).
This is normally done by the CPOC.
6. The CPOC logs in to the certificate management system using Mobile BankID, BankID on
card or BxID and creates the certificate.
7. The CPOC installs the certificate in the merchant’s server and connects it to Swish API. If
needed, Swish support function can assist with the connection.
8. The merchant verifies the connection.

2.2 Payment request in the Swish app
2.2.1 Swish m-commerce
The m-commerce flow should be used when the Swish app is on the same device as the merchant’s
mobile site or app – hence a mobile device.
1. Consumer chooses to pay with Swish for a product or a service in the merchant app.
2. The merchant sends a payment request to the Swish system using the API.
a. The transaction contains data such as: amount, receiving Swish-number, merchant
(payee) payment reference and an optional message to the consumer.
3. The merchant receives a Request Token.
4. Consumer’s Swish app is opened automatically by the merchant’s site or app showing the
payment section that is preloaded with payment information.
a. The app is opened with the request token as a parameter.
5. Consumer clicks Pay (”Betala”) and the Mobile BankID app opens automatically for signature of
the payment transaction.
6. Consumer confirms the payment transaction by signing with the Mobil BankID using his/her
password.
7. The amount is transferred in real-time from the consumer’s account to the merchant’s account.
8. Consumer is linked back to the merchant app for payment transaction confirmation.
a. Note: the confirmation screen in Swish-app is not displayed in this flow.
9. The merchant receives a confirmation of successful payment.
10. Consumer can view the payment in the events section “Händelser” as a sent payment in the
Swish app.

2.2.2 Swish e-commerce
The e-commerce flow should be used when the Swish app is on another device than the merchant’s
site.
1. Consumer chooses to pay with Swish for a product or a service at the merchant website and
enters his/her mobile phone number which is enrolled to Swish.
2. Information on the merchant website should inform the consumer to open the Swish app to
confirm the transaction.
3. The merchant sends a payment request to the Swish system using the API.
a. The transaction contains data such as: amount, receiving Swish-number, consumer’s
mobile phone number, merchant payment reference and an optional message to the
consumer.
4. Consumer opens the Swish app showing the payment section, which is preloaded with the
information in the payment request.
5. Consumer clicks Pay (”Betala”) and the Mobile BankID app opens automatically for signature of
the payment transaction.
6. Consumer confirms the payment transaction by signing with the Mobil BankID using his/her
password.
7. The amount is transferred in real-time from the consumer’s account to the merchant’s account.
8. Consumer receives a payment confirmation in the Swish app.
9. The merchant receives a confirmation of successful payment.
10. Consumer receives a payment confirmation at the merchant website.
11. Consumer can view the payment in the event section “Händelser” as a sent payment in the Swish
app.

2.2.3 Reject payment
Consumer wants to dismiss the payment request in the Swish app and clicks on “Avbryt”. The rejected
payment request is deleted from the Consumer’s Swish app.

2.3 Refund
There are two ways to make a refund: through the bank channel or through the API channel. This
section describes the API channel on a high level.
As a merchant, I have received a Swish payment and wish for some reason to refund the whole or part
of the original amount to the payer.
The merchant chooses which payment that is to be completely or partially refunded. The merchant
specifies the refund amount and sends the refund.
The merchant will also be able to send its own information that will be shown to the payer in the event
section in the Swish app, and also on the payee bank account statement. The information will also be
used by the company for tallying.
The merchant receives a confirmation that the refund has been completed.
As recipient of a refund, the payee receives a payment notification in the Swish app. The payment
notification is marked "Återbetalning" in the event section in the Swish app.
Alternative flow – ”payment notification”:
In cases when the recipient of a refund cannot receive data push notifications at the moment, the
refund will be visible in the Swish app next time the recipient logs in. The refund will also appear in the
recipient´s bank account statement.

Alternative flow – ”refund receiver not connected to Swish”:
In cases when the recipient of a refund has terminated the Swish agreement since the original
payment occurred, the merchant will receive an error message stating that the refund cannot be
processed. Refund must in this case be done via another channel.

2.4 Termination Swish handel
1. The merchant terminates the agreement with the bank. The service will stop working.
2. The merchant is responsible for termination/revocation of the API certificates.
3. Refunds will not be possible to do on the terminated Swish number.

3 Technical Requirements
The Swish server requires TLS 1.1 or higher.
The merchant must be able to receive the callback HTTPS POST request from the Swish server over
TLS. The callback endpoint has to use HTTPS on port 443 and it is highly recommended to use IP
filtering as well. For the callback Swish will be acting client and the merchant server is acting server.
Swish will validate the merchant callback server TLS certificate against a list of commonly recognized
CAs.
For now that Swish API does not support Server Name Indication (SNI) for the callback functionality.

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 2048 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 2048-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://getswishcert.bankgirot.se 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 Swish Root CA (o=Getswish AB,
ou=Swish Member CA, cn=Swish Root CA v1). The certificate chain for the Swish server TLS
certificate, i.e. the Swish Root CA certificate and the Intermediate CA certificate, are available
via the Certificate Management GUI via the link “Download Swish server TLS certificate”. 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://getswishcert.bankgirot.se 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://getswishcert.bankgirot.se 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.

5 Launching Swish app from merchant
app
5.1 Detecting if Swish app is installed on the device
Merchant apps, excluding web browsers, can detect if the Swish app is installed on the device. Below
are code snippets that shows this. Notice that it is not possible from a Windows Phone application to
detect if the Swish app is installed on the device.

5.1.1 iOS (detect)
static inline bool isSwishAppInstalled(void)
{
return [[UIApplication sharedApplication
canOpenURL:[NSURL URLWithString:@"swish://"]];
}

5.1.2 Android (detect)

//Swish package name is “se.bankgirot.swish”
protected boolean isSwishAppInstalled(Context _context, String
SwishPackageName) {
boolean isSwishInstalled = false;
try {
_context.getPackageManager().getApplicationInfo(SwishPackageName, 0);
isSwishInstalled = true;
} catch(PackageManager.NameNotFoundException e) {
}
return isSwishInstalled;
}

5.1.3 Windows Phone (call the Swish app)
// The URI to launch
string uriToLaunch = @"swish://paymentrequest";
// Create a Uri object from a URI string
var uri = new Uri(uriToLaunch);
// Launch the URI
async void DefaultLaunch(){
// Launch the URI
var success = await Windows.System.Launcher.LaunchUriAsync(uri);
if (success) {
// URI launched
}
else
{
// URI launch failed
}
}

5.1.4 Detection with mobile web browsers
The investigation of the abilities to determine if Swish is installed on a device shows that there is an
absence of a standard, documented way to do this from the web browsers. The found workaround is
based on the time during which the return to the browser was performed. The idea of this approach is
that JavaScript code on current page will be frozen right after calling Swish application because the
control flow will be given to the Swish if it started successfully. Control flow will be returned back to
JavaScript when Swish will be finished.
Thus if the JavaScript code continue executing after short time from the moment of the trying to call
Swish - this means that Swish is not installed on the device. The JavaScript code snippet given below:

//remember the time of start application
timestart = new Date().getTime();

//try to run application (Swish) in the frame by opening custom URL-SCHEME

createIFrame(url+"&browser="+browserName+"&back="+encodeURIComponent(location.toString())+"&us
eragent="+encodeURIComponent(userAgent));

//remember time of returning from application
timeend = new Date().getTime();

//if from the moment of the attempt
//control returns back to this code
//most probably this means that the
//the user spent the time using the

to run the application to moment when the
passed enough much time (more then 3 sec),
application was successfully started and
application

if(timeend — timestart > 3000) {
isSwishInstalled = true;
} else {
isSwishInstalled = false;
}

But, as investigations show, this approach does not work for WinPhone and Android Chrome version
25 and newer. Moreover, because Android’s default browser is now based on Chrome core, this is
also true for default browser.
In the 3 variants, WinPhone browser (Internet Explorer), Android default platform browser and Android
Chrome from version 25, they do not immediately return the control to the JavaScript code when the
called application (Swish) is not installed on the device - instead they open a dialog and offer the user
to go to the platform's market to download the required application (Swish).
This means, that in this case the browser will either successfully open Swish or ask the user to go to
the market to download and install Swish.

5.2 Switch to Swish app, and back
The merchant apps, including mobile web browsers, will call the Swish app using the Custom URL
Scheme "swish://paymentrequest".
The merchant app has to send the Swish app the following:



Payment request token
The merchant receives the payment request token from the CPC.
A callback URL
This is a string that Swish will use as parameter to switch back to the merchant app after
payment is finished. The goal of this parameter is to force the application to open a given GUI
view - or for a browser, to open a specific URL.
The callback URL should be passed in in URL-encoded format.

Both parameters are required, so the correct URL to open Swish app is:
swish://paymentrequest?token=&callbackurl=
When Swish is finished, it (or BankID app) will call the provided callback URL. For the merchant app to
react on this call, the merchant app needs to register for that URL scheme and provide code for
handling the request.
Code snippets describing switch to Swish as well as information about declaring URL scheme and
handling calls to it are provided below for each platform.
Note that the URL Sheme “merchant:\\” is used in the examples below. This is only an example – each
merchant shall use its own unique scheme.

5.2.1 iOS
The following code can be used to switch to Swish from the merchant app

// character set is used to encode callback URL properly
NSCharacterSet *notAllowedCharactersSet =
[NSCharacterSet characterSetWithCharactersInString:@"!*'();:@&=+$,/?%#[]"];
NSCharacterSet *allowedCharactersSet =
[notAllowedCharactersSet invertedSet];
NSString *callbackURLStr = @"merchant://";
NSString *encodedCallbackURLStr =
[callbackURLStr
stringByAddingPercentEncodingWithAllowedCharacters:allowedCharactersSet];
NSString *swishURLStr = [NSString
stringWithFormat:@"swish://paymentrequest?token=%@&callbackurl=%@", token,
encodedCallbackURLStr];
NSURL *swishURL = [[NSURL alloc] initWithString: swishURLStr];
if ([[UIApplication sharedApplication] canOpenURL:swishURL]) {
if ([[UIApplication sharedApplication] openURL:swishURL]) {
// Success
}
else {
// Error handling
}
}
else {
// Swish app is not installed
// error handling
}

The enable the switch back from Swish, the merchant app needs to register a URL scheme. This is
done by including a CFBundleURLTypes key in the app’s Info.plist.
The merchant app must also implement the following function that will be called when the switch back
happens.
-(BOOL)application:(UIApplication *)application openURL:(NSURL *)url
sourceApplication:(NSString *)sourceApplication annotation:(id)annotation;

5.2.2 Android

The following code can be used to switch to Swish from the merchant app.
public static boolean startSwish(Activity activity, String token, String
callBackUrl, int requestCode) {
If ( token == null || token.length() == 0 || callBackUrl == null ||
callBackUrl.length() == 0 || activity == null) {
return false;
}
Uri scheme =
Uri.parse("swish://paymentrequest?token="+token+"&callbackurl="+callBackUrl
);
Intent intent = new Intent(Intent.ACTION_VIEW, scheme);
intent.setPackage("se.bankgirot.swish");
boolean started=true;
try {
activity.startActivityForResult(intent, requestCode);
} catch (Exception e){
started=false;
}
return started;
}

The app manifest file is used to register the URL scheme in the merchant app :

The merchant app also needs to process then intent in onCreate and onNewIntent methods when
switch back happens.

5.2.3 WinPhone
The following code can be used to switch to Swish from the merchant app.
// Create the URI string
var uriToLaunch =
string.Format("swish://paymentrequest?token={0}&callbackurl={1}",
, Uri.EscapeDataString("merchant://"));
// Create the URI to launch from a string.
var uri = new Uri(uriToLaunch);
// Launch the URI.
bool success = await Windows.System.Launcher.LaunchUriAsync(uri);

If the Swish app is not present on the device the operating system presents a dialogue asking to open
Windows Phone store. Merchant app must inform the user.
The merchant app registers an URL scheme in Visual Studio as:
1.
2.
3.
4.

Open Package.appxmanifest
Open the tab Declarations.
Add a "Protocol". Under name enter ”merchant”.
Enter a logo and a "Display name".

Merchant must also implement the following to be successfully re-launched by Swish App. In Visual
Studio add the class AssociationUriMapper:
///
/// The association uri mapper.
///
internal class AssociationUriMapper : UriMapperBase {
///
/// When overridden in a derived class, converts a requested uniform
resource identifier (URI) to a new URI.
///
///
/// A URI to use for the request instead of the value in the
parameter.
///
/// The original URI value to be mapped to a new
URI.
public override Uri MapUri(Uri uri) {
var tempUri = System.Net.HttpUtility.UrlDecode(uri.ToString());
// URI association launch.
if (tempUri.StartsWith("/Protocol")) {
// Here we can redirect to the correct page, but for now we don't
return new Uri("/MainPage.xaml", UriKind.Relative);
}
// Otherwise perform normal launch.
return uri;
}
}

In App.xaml.cs, add AssociationUriMapper as UriMapper by adding the following line to the method
InitializePhoneApplication:
// Assign the URI-mapper class to the application frame.
RootFrame.UriMapper = new AssociationUriMapper();

5.2.4 JavaScript calls and open Swish
For the browser Safari you can use:
swish://paymentrequest?token=value&callbackurl=back_scheme

5.2.5 For Chrome version >= 24
For the browser Chrome you can use this intent-based URI:
obj.href="intent://view/#Intent;;;;;;;end"
The basic syntax for an intent-based URI is as follows:
intent:
HOST/URI-path // Optional host
#Intent;
package=[string];
action=[string];

category=[string];
component=[string];
scheme=[string];
end;
To check which browser that is used, use the value of userAgent in JavaScript

6 Test Environment
A Merchant Swish Simulator is available for merchants to test their integration with Swish API. The
Merchant Swish Simulator will validate requests and return simulated but correctly formatted
responses. The Merchant Swish Simulator will return a simulated result of the request in the callback
URL. It is also possible to retrieve the payment request status, and to simulate different error
situations.
A user guide for the Merchant Swish Simulator, can be be found at https://www.getswish.se/handel.

7 Production Environment
The Swish server IP address for IP filtering:
194.242.111.220:443
Swish API URL:
https://swicpc.bankgirot.se/swish-cpcapi/api/v1/paymentrequests
https://swicpc.bankgirot.se/swish-cpcapi/api/v1/refunds
Swish server TLS certificate is issued under the following root CA that should to be configured as
trusted:
cn=Swish Root CA v1
ou=Swish Member Banks CA
o=Getswish AB
The complete certificate chain of the Swish server TLS certificate is available through Swish Certificate
Management.

8 Guidelines for using the Swish API
When integrating with Swish API the following guidelines will support stable performance of the
system and a smooth consumer experience.

8.1 Consumer in control of payment requests

Each payment request transaction sent to the API must be initiated by a physical paying consumer.
The merchant must make sure that the consumer does not receive what he/she perceives as “spam”
or unwanted payment requests.

8.2 Use the call-back for payment requests and refunds
When sending the payment request or refund a call-back is provided to the merchant of the status of
the payment. This is the normal usage scenario, which should be used in most cases.
As a backup there is also a “Retrieve” for Payment Requests and Refunds for reconciliation in the
case that the normal call-back fails for some reason. Note that this is a backup – and not the standard
flow for receiving payment status.

8.3 Refund transactions – avoid large batches
The “create refund” message is intended for real-time one-by-one calls. It is not intended for batching
up a large quantity and then sending the whole batch in a short period of time.
There should be at least 1 second between each refund transaction and if more than 100 transactions
are to be sent in a sequence they should be sent during night time.

8.4 Renewal of Client TLS Certificate
The validity of the client TLS certificate is two years. It is the merchant's responsibility to generate new
keys and certificate in due time, prior to the expiry of the old certificate, in order to ensure
uninterrupted functionality of the commerce site. The merchant could authorise another company (a
partner to the merchant) to manage the certificate renewal process.

8.5 Displaying the Swish alias to consumers
When enrolling to Swish the merchant will receive a Swish alias (123 XXX YYYY) which uniquely
identifies the enrolment and which is used as an alias to the payee’s bank account.
We recommend e-commerce and m-commerce merchants not to expose this to consumers since it
1. Can be used for unprompted payments by entering the Swish alias in the Swish app.
2. Some banks may block unprompted payments to Swish aliases enrolled to “Swish Handel”
The Swish alias for transactions generated by payment requests or refunds will not be displayed by
the Swish app or the bank’s consumer interfaces.

9 Versioning the Web Service API
9.1 Versions
Changes may be made to the API to correct errors or to introduce new functionality. When changed, a
new version of the API will be made available via a new URL. Merchant should always use the latest
version of the API.
The general rule is that old versions of the API will be discontinued two years after the release of the
successor. But if deemed necessary, for example for security reasons, a version of the API may be

discontinued prematurely. As new functionality is introduced to the system the behaviour of an existing
version of the API may change, e.g. existing faults may also be used in new situations.

10 Support
10.1 Deployment support
Please see the manuals and FAQ available at https://www.getswish.se/handel
If you can’t find the technical information you need, you can contact the deployment support
organisation. The contact details are also published at https://www.getswish.se/handel.
For all commercial questions, please contact your bank.

10.2 Operating information
Operating information is available at https://getswish.se/driftsinformation

11 Swish API Description
11.1 Payment Request
Payment requests are created/retrieved with the operations listed below. There are two main flows to
this use case, one for Swish m-commerce and one for Swish e-commerce. The main difference is that
in the Swish e-commerce case the consumer is prompted for his/her mobile phone number, and then
the consumer has to manually open the Swish app. But in the Swish m-commerce case the
consumer’s mobile phone number is initially not known to the merchant. So instead, in this case, the
API returns a Payment request token. This token is used to build a so called Swish URL, which the
merchant can use to call the Swish app from their app. The Payment request token is then a
parameter to the Swish URL. Once the paymentrequest reached to final state(either Paid , Timeout or
Error), the Merchant provided Callback URL will be called by Swish. Even though this callback
contains the payment status information, the merchant server should retrieve the result of the payment
request directly from the Swish server (refer to Retrieve Payment Request for further details).These
flows are illustrated in the pictures below.

11.1.1 Swish e-commerce

11.1.2 Swish m-commerce

11.1.3 Create Payment Request
POST

/api/v1/paymentrequests

The Http request body have to contain a Payment Request Object.

Potential Http status codes returned:


201 Created: Returned when Payment request was successfully created. Will return a
Location header and if it is Swish m-commerce case, it will also return
PaymentRequestToken header.



400 Bad Request: Returned when the Create Payment Request operation was
malformed.



401 Unauthorized: Returned when there are authentication problems with the certificate.
Or the Swish number in the certificate is not enrolled. Will return nothing else.



403 Forbidden: Returned when the payeeAlias in the payment request object is not the
same as merchant’s Swish number.



415 Unsupported Media Type: Returned when Content-Type header is not
"application/json". Will return nothing else.



422 Unprocessable Entity: Returned when there are validation errors. Will return an Array
of Error Objects.



500 Internal Server Error: Returned if there was some unknown/unforeseen error that
occurred on the server, this should normally not happen. Will return nothing else.

Potential Error codes returned on Error Objects when validation fails (HTTP status code 422 is
returned):


FF08 - PaymentReference is invalid



RP03 - Callback URL is missing or does not use Https



BE18 - Payer alias is invalid



RP01 - Missing Merchant Swish Number



PA02 - Amount value is missing or not a valid number



AM06 - Specified transaction amount is less than agreed minimum



AM02 - Amount value is too large



AM03 - Invalid or missing Currency



RP02 - Wrong formated message



RP06 - A payment request already exist for that payer. Only applicable for Swish ecommerce.



ACMT03 - Payer not Enrolled



ACMT01 - Counterpart is not activated



ACMT07 - Payee not Enrolled

Create Payment request example (Swish e-commerce):
curl -v --request POST https://swicpc.bankgirot.se/swishcpcapi/api/v1/paymentrequests \
--header "Content-Type: application/json" \
--data @- <
Source Exif Data:
File Type : PDF
File Type Extension : pdf
MIME Type : application/pdf
PDF Version : 1.5
Linearized : No
Page Count : 36
Language : sv-SE
Tagged PDF : Yes
Title : 1.0
Author : Maria Wannefalk
Creator : Microsoft® Word 2010
Create Date : 2017:03:24 08:56:57+01:00
Modify Date : 2017:03:24 08:56:57+01:00
Producer : Microsoft® Word 2010

EXIF Metadata provided by EXIF.tools

1.0 Guide Swish API 170324 Utan ändringsmarkering

Navigation menu

Versions of this User Manual:

Views

Navigation