Swish Payments for OpenCart

Overview

Take Swish payments in Swedish kronor. Customers pay in the Swish app the way they expect: on a phone the shop opens the app, on a computer it shows a QR code to scan (or asks for the mobile number), and the order is marked paid only after the shop has read the payment back from Swish.

What it does

• Three ways to pay. Swish app on the same phone (app switch), QR code on a computer, or the customer's mobile number (a request appears in their Swish app).
• Paid means paid. A callback is a hint. The order moves to your "Paid" status only after the payment request was read back from Swish over the mutually authenticated connection with status PAID, the registered amount, currency SEK and your Swish number.
• Lost callbacks are recovered. The checkout page, the customer's return from the app and the cron read the payment back on Swish's documented schedule (10 seconds, then 20, 40, 80).
• No double payment. A returning customer whose payment is still open gets an empty basket and a waiting page; an order that is already paid cannot be paid again; a cancelled or declined request can be started again.
• Refunds from the order page. Full or partial, each with its own refund id. A refund whose answer is lost is looked up with its id and never sent twice.
• Your certificate, kept safe. Upload the Swish merchant certificate once (.p12 or PEM). It is checked, stored encrypted and never shown again; a test button proves that Swish accepts it.
• Test without a bank agreement. Test mode uses the Swish simulator (MSS) with Swish's public test certificate.
• Updates keep your data. Uninstalling keeps the payment records, settings and certificate, so the OpenCart 4 update path (uninstall, install) loses nothing.

Requirements

• OpenCart 4.1.0.0 or newer 4.1.x, PHP 8.1 or newer with cURL and OpenSSL.
• A shop that runs on HTTPS (port 443): Swish refuses callback addresses without it.
• Swish for Merchants (Swish Handel) from your bank and a merchant certificate from the Swish certificate portal, for live payments.
• SEK as the shop currency, or an enabled SEK currency in OpenCart (other currencies are converted with its rate).

Swish is a registered trademark of Getswish AB. This extension is independent software and is not affiliated with or endorsed by Swish or Getswish AB.

Installation

1. Install the extension. Extensions > Installer > Upload kv_swish.ocmod.zip, then Install.
2. Install the payment method. Extensions > Extensions > choose Payments > Swish Payments > Install, then Edit.
3. Connection tab, test mode first.
   • Enter the Swish number 1234679304 (the number of Swish's public test certificate; the simulator accepts any number).
   • Download the MSS test certificates from developer.swish.nu (Environments, "MSS certificates"), unzip, and upload Swish_Merchant_TestCertificate_1234679304.p12 with the password swish.
   • Press Save and test connection. "Swish test connection OK" means the certificate was accepted.
4. Payment tab: switch the method on, set the name customers see, optionally upload the official Swish logo (see Configuration).
5. Order statuses tab: choose the Paid status (default Processing) and optionally the fully refunded status.
6. Place a test order on the shop with Swish. The simulator pays after a few seconds; the order becomes Paid.
7. Go live. Order Swish for Merchants at your bank, create the merchant certificate in the Swish certificate portal (portal.swish.nu), upload it in the Live slot with your own Swish number (it starts with 123), switch the mode to Live and test the connection again.
8. Cron. Make sure the OpenCart cron runs (*/10 * * * * php /path/to/cron.php). The extension adds an hourly job that reads open payments back.

Updating

Replace the extension through Extensions > Installer: uninstall the payment method (Extensions > Payments > Uninstall), uninstall and delete the old extension files in the Installer, upload the new zip, install, install the payment method. Payment records, refunds, the log, your settings and the certificate are kept. Open the settings page once afterwards.

If you update by copying files over FTP, open the settings page once: it applies any database change.

Removing all data

Uninstalling keeps your data on purpose. To delete it, drop the tables oc_kv_swish_txn, oc_kv_swish_refund, oc_kv_swish_log and the rows with code payment_kv_swish in oc_setting by SQL.

Configuration

Payment tab

• Status. Swish is offered only while this is on, the connection is complete and the cart currency is SEK (or the store has an enabled SEK currency).
• Name at checkout. The text customers see in the payment method list.
• Payment reference prefix. Optional. The order number is sent to Swish as your payment reference (letters, digits and "-", at most 35 characters).
• Swish logo. Optional. Download the official Swish logo for merchants from the Swish brand toolbox and upload the PNG, JPG or WebP file unchanged. It is shown at a fixed height and never edited. Follow the Swish brand guidelines for clear space and colours. Without a file only the word Swish appears.
• Geo zone, sort order. As for any OpenCart payment method.

Connection tab

• Mode. Test (the Swish simulator MSS) or Live.
• Swish number of the shop. The number that starts with 123. Do not show it to customers.
• Certificate. Upload a .p12 / .pfx file with its password, or a PEM certificate with its .key file. If a .p12 from an older Swish portal cannot be read by your server's OpenSSL 3, convert it once: openssl pkcs12 -legacy -in file.p12 -out cert.pem -nodes and upload cert.pem. The card shows the certificate owner and the days left; the private key is never shown. Swish certificates are valid for five years: create the next one in the portal before it expires (the settings page and the log warn 30 days ahead).
• Save and test connection. Opens the secured connection of the selected mode and checks that Swish accepts the certificate.
• Callback address. Sent to Swish with every payment; nothing to enter in the Swish portal. It must be reachable from the internet over HTTPS port 443.

Order statuses tab

• While waiting for payment. Keep the order invisible (a missing order) until it is paid, or show it in a status of your choice as soon as the payment request is created.
• Paid. Set when Swish confirms. An order that is already further along is never moved back; a comment is added instead.
• Fully refunded. Optional.
• E-mail the customer when the order becomes paid.

Log and cron tab

Debug log (every request and response with identifiers and keys masked), the cron command and the secret cron address, and the log table.

Using Swish

Your customers

• On a phone: "Open the Swish app on this phone" is preselected. The shop opens Swish, the customer approves with BankID, and Swish returns to the shop. If the app does not open there is a button.
• On a computer: "Scan a QR code with the Swish app" is preselected. The customer opens Swish, scans the code and approves. The checkout page notices the payment and continues by itself. The other choice is the mobile number: the request appears in the customer's Swish app.
• The customer has three minutes. A declined, cancelled or timed-out request shows a message and the customer can try again.
• If the customer comes back from the app before Swish has decided, the basket is emptied (so the same order cannot be paid twice) and a waiting page continues to the confirmation when Swish confirms.

Orders

• The order is created at checkout and stays a missing order until it is paid (or shows the status you chose).
• When Swish confirms, the order gets your Paid status and a history entry with the Swish payment reference.
• The order page has a Swish tab: the payment, its request id, state and error code, a Read back button and the refunds.

Refunds

Open the order, tab Swish, enter an amount (empty = the rest) and a reason, press Refund. Swish answers with DEBITED and later PAID; the refund shows as completed on PAID, and the order gets the fully refunded status when the last part is done. Swish can refund a payment up to 13 months after it was made. If Swish does not answer, the refund is shown as unconfirmed, the amount stays reserved and no second refund can start until the shop has asked Swish for it (automatically, or with Read back). Do not press Refund again meanwhile.

If something looks wrong

• Settings > Log and cron shows every call and its answer (errors are always logged).
• "Not offered at checkout": check status, certificate, Swish number, SEK currency, geo zone, licence.
• "The payment could not be started": see the log; common Swish codes are explained there in plain English (for example BE18 invalid mobile number, RP03 callback address not HTTPS).

Developer notes

Every endpoint and field, with its source

All pages are on https://developer.swish.nu (Swish Developer Documentation, read 2026-11-07). The site is a single page application; the text was read from its own content API and the calls were also checked against the real Merchant Swish Simulator (MSS) with Swish's public test certificate (tests/mss-live.php, 12 checks) and its answers stored in tests/samples/.

Unverifiable or flagged

• Swish logo and brand rules. The Swish brand guidelines page (swish.nu, Marketing toolbox, Logotype) could not be read from here (it needs a browser session). The extension therefore ships no Swish logo: the merchant uploads the official file from the Swish toolbox and the extension shows it unchanged at a fixed height. The trademark line wording "Swish is a registered trademark of Getswish AB" must be checked against the guidelines.
• Status CREATED. The payment request status table lists PAID, DECLINED, ERROR and CANCELLED; the real simulator and the Swish app flow also return CREATED for an open request. Anything not in the table is treated as "still open".
• Sandbox (staging) environment. Needs enrolment through Swish support and test apps on a phone; not used here. Only MSS (test) and production are offered.
• Production for Merchants. Needs a bank agreement and a production certificate; not available to us. See docs/conformance.md for what was proven where.

Internals worth knowing

• A payment is paid only after GET returned PAID with the registered amount, currency SEK and (live mode) the shop's own Swish number; a mismatch is stored as error / MISMATCH and written to the order history.
• kv_swish_txn.instruction_uuid is unique; the row exists before the create call. A create call whose answer is lost is looked up with the same id and adopted (e-commerce); for m-commerce the token is lost with the answer, so the request is cancelled and the customer starts again.
• Refund rows carry their own uuid (never reused). creating / unknown rows are resolved with GET /refunds/{id}; 404 after 15 minutes releases the reserved amount.
• Locks: GET_LOCK('kvswish_<txn id>') around every state change; atomic status updates; a final state is never replaced.
• Certificate: Cert::seal() stores one sealed value (AES-256-GCM, installation key in kv_seal); Cert::files() writes 0600 files in DIR_STORAGE/kv_swish for one call; Cert::sweep() (cron) removes leftovers.
• Tests: php81 tests/unit.php and php83 tests/unit.php (needs node tests/mock-server/server.js 11960 and MariaDB), php83 tests/mss-live.php (real simulator, needs internet), node tests/e2e.js on a dev store. The hidden setting payment_kv_swish_base_url (loopback hosts only) points the extension to the mock.

Conformance with the Swish documentation (OpenCart)

Checked line by line against the Swish Developer Documentation (https://developer.swish.nu: API reference Payment request v2, Refunds v2, QR Codes v1; guides Create a payment request, Refund a payment, Trigger the Swish app; Environments; Guidelines; change log), read 2026-11-07. The extension was proven three ways: unit tests against a local stand-in that follows the documentation and the real simulator answers (149 checks, PHP 8.1 and 8.3), a live run against the real Merchant Swish Simulator (MSS) with Swish's public test certificate (12 checks: mutual TLS, create, read back, cancel, refund, simulated decline, QR service), and browser tests on OpenCart 4.1.0.4 (against the stand-in). It has not been run against production Swish for Merchants (needs a bank agreement and a production certificate) or the staging "Sandbox" (needs enrolment and Swish test apps on a phone), and no real Swish app approved a payment. Confirm the points under "To confirm" once with your own agreement.

To confirm with your own agreement

• A real approval. Make one payment with the Swish app on a phone (test with a small amount in live mode, or in the Sandbox if Swish enrolled you) and one refund.
• Callback reachability. Production callbacks come from Swish's egress hosts (the documentation names egress.api.getswish.se for firewall allow-lists); the simulator calls from 89.46.83.171. A firewall, bot filter or Cloudflare rule must let them reach the callback address. Without callbacks the checkout page and the cron still settle payments, only slower.
• Status CREATED. The status table lists four values; an open request is treated as pending whatever its text.
• Brand rules. The Swish brand guidelines could not be read from here. No Swish logo is shipped; you upload the official file and follow the guidelines. Check the trademark line against them.
• Payer age and personal number checks (ageLimit, payerSSN) are not used.

Not covered in 1.0.0

Recurring payments (Swish Recurring), payouts, other currencies, Swish Sandbox as a third mode, subscriptions.

Trademark: Swish is a registered trademark of Getswish AB; this extension is independent software and is not affiliated with or endorsed by Swish or Getswish AB.

FAQ

Do I need a bank agreement?

For live payments yes: Swish for Merchants (Swish Handel) from your bank, then a certificate from the Swish certificate portal. For testing no: the Swish simulator accepts Swish's public test certificate.

Which currencies?

Swish only settles SEK. A shop in another currency needs an enabled SEK currency in OpenCart; the order total is converted with its rate.

Does it work without HTTPS?

No. Swish rejects callback addresses that are not HTTPS on port 443 (error RP03). The settings page warns about it.

Where is my private key kept?

Encrypted in the database (AES-256-GCM, with a key that belongs to this installation). It is written to a short-lived file in the OpenCart storage folder (outside the web root) only while a request to Swish is running, and removed right after. It is never shown again.

Why does my .p12 not upload?

Old .p12 files from some portals use encryption that OpenSSL 3 only reads with the legacy provider. Convert once with openssl pkcs12 -legacy -in file.p12 -out cert.pem -nodes and upload the PEM file.

A customer paid but the order is not paid. Open the order, tab Swish, press Read back. The shop asks Swish for the state and books it. The cron and the checkout page do the same automatically.

Can the same order be paid twice?

No: a paid order answers "paid" to a second attempt, and a returning customer with an open payment gets an empty basket. A second payment that still arrives (for example from another device) is flagged as a duplicate with a note on the order, so you can refund it.

Does it support recurring payments, payouts or Swish for subscriptions?

Not in 1.0.0 (payments and refunds only).

Other languages?

The extension is in English.

Swish is a registered trademark of Getswish AB. This extension is independent software and is not affiliated with or endorsed by Swish or Getswish AB.