3. API Description

3.1 Swish QR codes for terminals

There are three main flows for commerce payment requests: m-commerce, e-commerce and QR codes (q-commerce). M-commerce and e-commerce are described in Guide Swish API. This document describes the q-commerce case.

The main difference between e-commerce and m-commerce on one hand, and q-commerce on the other hand, is that for q-commerce, there is no merchant app that communicates directly with the Swish app or a webstore. Q-commerce is used for payment in stores, where the cashier presents a QR code to the consumer, who opens the Swish app and scans the QR code to initiate the payment.

This is a step-by-step description of the q-commerce payment flow, with the merchant integration points in bold:

1. The consumer chooses to pay with Swish in the store.
2. The cashier starts the payment in the merchant system.
3. The merchant system sends a payment request to the Swish system using the API. The transaction contains data such as: amount, currency, merchant (payee) payment reference and an optional message to the consumer.
4. The merchant system receives a Request Token.
5. The merchant system generates a QR-code for the received Request Token, either using the Swish QR-generator or creating it locally.
6. The QR code is displayed to the consumer on the point-of-sale terminal.
7. The consumer starts the Swish app and scans the QR-code. The Swish app displays the payment request to the consumer.
8. The consumer clicks Pay (”Betala”) and the Mobile BankID app opens automatically for signature of the payment transaction.
9. The consumer confirms the payment transaction by signing with the Mobil BankID using his/her password.
10. The amount is transferred in real-time from the consumer’s account to the merchant’s account.
11. The consumer stays in the Swish app.
12. The merchant receives a confirmation of the successful payment, via a callback from the Swish system to the merchant system.
13. The cashier informs the consumer about the outcome of the payment.
14. The consumer can view the payment in the events section (“Händelser”) as any other payment in the Swish app.

For brevity, “behind the scenes” interactions, for example the Swish system’s interaction with BankID and the consumer’s bank, are not included in the steps listed above.

The integration points that need to be implemented in the merchant system are:

• Create a payment request. This initiates the payment.
• Retrieve payment request token. The token identifies the payment request and is encoded in the QR code.
• Generate a QR code. The payment request token is embedded in the QR code, which is scanned by the customer using the Swish app.
• Receive a confirmation callback when the payment is finished.

3.1.1 Create payment request

A payment request is created by posting the relevant information to the Swish for merchants API:

POST /api/v1/paymentrequests

Example:

curl -v --request POST https://cpc.getswish.net/swish-cpcapi/api/v1/paymentrequests \
--header "Content-Type: application/json" --data @- << !
{
"payeePaymentReference": "0123456789",
"callbackUrl": "https://example.com/api/swishcb/paymentrequests",
"payeeAlias": "1234760039",
"amount": "100",
"currency": "SEK",
"message": "Kingston USB Flash Drive 8 GB"
} !
< HTTP/1.1 201 Created
< Location: https://cpc.getswish.net/swish- cpcapi/api/v1/paymentrequests/AB23D7406ECE4542A80152D909EF9F6B
< PaymentRequestToken: umP7Eg2HT_OUId8Mc0FHPCxhX3Hkh4qI

3.1.2 Retrieve payment request

GET api/v1/payment-requests/{id}

Example:

curl -v --request GET https://cpc.getswish.net/swish- cpcapi/api/v1/paymentrequests/AB23D7406ECE4542A80152D909EF9F6B
<HTTP/1.1 200 OK
{
"id": "AB23D7406ECE4542A80152D909EF9F6B",
"payeePaymentReference": "0123456789",
"paymentReference": "6D6CD7406ECE4542A80152D909EF9F6B",
"callbackUrl": "https://example.com/api/swishcb/paymentrequests",
"payeeAlias": "1231234567890", "amount": "100",
"currency", "SEK",
"message": "Kingston USB Flash Drive 8 GB",
"status": "PAID",
"dateCreated": "2015-02-19T22:01:53+01:00",
"datePaid": "2015-02-19T22:02:12+01:00"
}

3.1.3 Generate QR code

There are two ways to generate a QR code:

• using the Swish QR-generator, or
• generating it locally according to guidelines provided by Swish.

What is described in this section is how to use the Swish QR-generator, but if you expect to generate large volumes of QR codes, do not hesitate to contact us.

The QR code to display to the customer is generated by posting the payment request token to the Swish QR-generator API.

The string represented by the QR code will be the token, prefixed with the capital letter D. So in the current example, the token is umP7Eg2HT_OUId8Mc0FHPCxhX3Hkh4qI, and the QR code will contain the string DumP7Eg2HT_OUId8Mc0FHPCxhX3Hkh4qI.

The QR-generator API is described in detail in the QR Code Integration API document, see https://developer.getswish.se/qr/

POST /api/v1/commerce

Example:

curl -v --request POST https://mpc.getswish.net/qrg-swish/api/v1/commerce --header "Content-Type: application/json" --data @- << !
{
"format": "png",
"size": 300,
"token": "umP7Eg2HT_OUId8Mc0FHPCxhX3Hkh4qI"
}
!

The returned QR code, containing the string DumP7Eg2HT_OUId8Mc0FHPCxhX3Hkh4qI:

3.1.4 Callback

Swish will make a callback HTTPS POST request with the Payment Request Object JSON as payload, to the Callback URL supplied in the Create Payment Request operation when either of the following events (as set in the status property of the Payment Request Object) happens:

• PAID – The payment was successful.
• DECLINED – The payer declined to make the payment.
• ERROR – Some error occurred, like payment was blocked, payment request timed out etc. See the list of error codes for all potential error conditions.

A payment request has to be accepted or declined by the consumer within three (3) minutes. When the time has elapsed an ERROR status is returned to the Callback URL. If the consumer accepts the payment request a status is returned to the Callback URL within 12 seconds.

The callback endpoint has to use HTTPS, and IP filtering is highly recommended as well. It is up to the merchant to make sure the endpoint is available.

Swish will only make the callback request once. If the merchant has not received a callback response after the timeout, the merchant can choose to retrieve the payment request to check the result. Swish will always try to make a callback request before the timeout period, but if it times out, a timeout callback is sent with status ERROR and the error code value TM01.