|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 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-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.|
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/.
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:
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.
It is always the consumer that initiates a payment, and there are two ways to do it; Swish e-commerce or Swish m-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.
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.
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.
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.