1. Introduction

1.1 Terms and definitions

TermDefinition
PartnerA 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.
MerchantA merchant is a company, association or organisation which receives payments via Swish. 
Merchants sign Swish agreements with their respective bank.
Merchant Swish SimulatorThe Merchant Swish Simulator is a test tool to test the Swish-API.
ConsumerA consumer is a private Swish customer that can use the Swish app on a mobile device.
CPOCCertificate Point of Contact – person assigned by the company to manage the certificates
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 e-commerce 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-commerceSwish payments from a mobile device made either through an app or via a mobile browser on the same mobile device.
Swish e-commerceSwish payments initiated by the consumer in a browser in equipment other than the mobile device that hosts the Swish app.
Swish customerThis is any customer to Swish, either a consumer (person) or a merchant.
PayeeThis is the Swish customer that receives the payment
PayerThis is the Swish customer that makes the payment
AliasA unique identifier for a Swish customer. For a consumer it is the mobile number and for a merchant it is the Swish number.
Payment requestA payment request is a transaction sent from a merchant to the Swish system to initiate an e-commerce or m-commerce payment.
Payee Payment ReferenceA 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.
RefundA 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://developer.getswish.se/merchants/.

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. The administration GUI includes view, order new/download and revoke certificates.