Vipps MobilePay Payments for OpenCart

Overview

Take Vipps and MobilePay payments in Norway (NOK), Denmark (DKK) and Finland (EUR) on the Vipps MobilePay ePayment API. On a phone the customer's app opens by itself, on a computer the Vipps MobilePay landing page asks for the mobile number and the customer approves in the app. The amount is reserved and you capture it when the order ships.

What it does

• The normal Vipps MobilePay flow. WEB_REDIRECT: app switch on phones, landing page on computers, back to your shop afterwards.
• Paid means approved. A webhook is a hint. The order moves to your "Approved" status only after the shop has read the payment back from Vipps MobilePay as AUTHORIZED, with the amount it asked for AND the amount the order costs now.
• Signed webhooks. Registered with one button; every webhook is checked with its HMAC signature before anything happens. Lost webhooks are recovered by the customer's return, the waiting page and an hourly cron.
• Capture when you ship. Automatically when the order reaches a status you choose (default Shipped), right after approval, or by hand. Partial captures, full or partial refunds, release of the rest of the reservation, from the order page or by order status.
• Never twice. Every create, capture, refund and cancel is written down before it is sent, with its own idempotency key; an unclear answer is sent again with the same key, never with a new one.
• No double payment. A customer who comes back before the payment is decided gets an empty basket and a waiting page; a second approval of a paid order, or an approval that no longer matches the order total, is not booked and its reservation is released.
• Your keys, kept safe. Client secret, subscription key and webhook secret are stored encrypted and never shown again.
• Updates keep your data. Uninstalling keeps the payment records, settings and keys, so the OpenCart 4 update path loses nothing.

Requirements

• OpenCart 4.1.0.0 or newer 4.1.x, PHP 8.1 or newer with cURL and OpenSSL.
• A shop on HTTPS (Vipps MobilePay returns customers and sends webhooks only to https addresses; webhooks on port 80, 443 or 8080).
• A Vipps MobilePay merchant agreement with the ePayment (online payments) product and the API keys of your sales unit.
• The currency of your sales unit (NOK, DKK or EUR) enabled in OpenCart; other cart currencies are converted with its rate.

Vipps MobilePay, Vipps and MobilePay are trademarks of Vipps MobilePay AS. This extension is independent software that integrates with the Vipps MobilePay ePayment API; it is not affiliated with or endorsed by Vipps MobilePay AS. The paymarks it shows are the unaltered official files from the Vipps MobilePay brand book.

Installation

1. Install the extension. Extensions > Installer > Upload kv_vipps.ocmod.zip, then Install.
2. Install the payment method. Extensions > Extensions > Payments > Vipps MobilePay Payments > Install, then Edit.
3. Connection tab, test environment first.
   • Enter the merchant serial number (MSN), client id, client secret and subscription key of your test sales unit (business portal, For developers, API keys) and choose the currency of the sales unit (NOK, DKK or EUR).
   • Press Save and test connection. "Vipps MobilePay test connection OK" means the keys and the MSN work together.
   • Press Register webhook for the test mode. Your shop must be reachable from the internet over HTTPS for webhooks; without them payments still complete, only through the customer's return and the cron.
4. Payment tab: switch the method on. Leave "Name at checkout" empty to show the brand your customers know (Vipps in Norway, MobilePay in Denmark and Finland until 12 January 2027, Vipps afterwards).
5. Capture and statuses tab: choose when to capture (default: when the order reaches Shipped) and the statuses for approved, captured and refunded orders.
6. Place a test order with the Vipps MobilePay test app (MT) and a test user. Test mode is hidden from your customers until you tick "I confirm: show Vipps MobilePay to real customers in test mode" on the Connection tab; tick it only on a test shop. Test orders get the note "TEST MODE (Vipps MobilePay test environment): no money was reserved" and no e-mail.
7. Go live. Enter the production keys in the Live block, register the live webhook, 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 and resends unanswered captures and refunds.

Updating

Uninstall the payment method (Extensions > Payments > Uninstall), uninstall and delete the old files in the Installer, upload the new zip, install, install the payment method. Payment records, operations, the log, your settings and keys are kept. Open the settings page once afterwards. After an FTP update, open the settings page once: it applies any database change.

Removing all data

Uninstalling keeps your data on purpose. Settings > Log and cron > Remove all data (type DELETE) deletes the payment records, the log, the cached tokens, the API keys and the kept settings. It is refused while a payment is open or still holds a reservation. The licence stays.

Configuration

Usage

Checkout. The customer picks the method and presses "Pay with Vipps" (or MobilePay). The browser opens Vipps MobilePay: on a phone the app, on a computer the landing page. After approval the customer comes back to the success page. If the result is not known yet, a waiting page watches the payment (it never calls a pending payment cancelled) and the basket is emptied so the order cannot be paid twice.

Order page. A Vipps MobilePay tab shows every attempt: reserved, captured, refunded and released amounts, reference, PSP reference, the capture deadline (shop time) and every operation with who started it. Buttons: Capture (any part of the reserved rest), Refund (any part of the captured rest, with a reason), Release (the uncaptured rest), Read back.

Automatic actions. Capture at your capture status, release at your cancel status (also when you change the status on the order page). Approvals that do not match the order total, and second approvals of a paid order, are released automatically and flagged with the order status "Payment amount mismatch" or a history note.

When an answer is lost. The operation shows "Operation awaiting answer"; the cron or Read back sends it again with the same idempotency key, so it happens once.

Log and cron tab. API log (errors and money operations always, everything with Debug log), the cron command and a secret cron address.

Notes.

• Capture by status runs when the order status really changes to the capture status or one of your complete statuses (through OpenCart's order history). A reservation near its capture deadline is shown as a warning on the settings page.
• A capture, refund or release without a clear answer is checked on the next read-back: if Vipps MobilePay shows it done, it is marked done; otherwise it is sent again with the same key for up to 24 hours, then closed with a note to check the business portal.
• If the shop is in maintenance mode, webhooks get the maintenance page; the cron and the next read-back settle the payments afterwards.
• An order cancelled while the customer has not approved yet: the payment is cancelled; an approval that still arrives is released and the order stays cancelled.

Developer notes

Every endpoint, header, field and state, with its source

Sources, all read 2026-11-07 (copies in the build workspace, scratchpad/oc-vipps/apidocs/):

• ePayment API OpenAPI spec 1.8.5: https://developer.vippsmobilepay.com/redocusaurus/epayment-swagger-id.yaml ("ePayment spec")
• Webhooks API OpenAPI spec v1: https://developer.vippsmobilepay.com/redocusaurus/webhooks-swagger-id.yaml ("Webhooks spec")
• Access Token API OpenAPI spec: https://developer.vippsmobilepay.com/redocusaurus/access-token-swagger-id.yaml ("Token spec")
• Guide pages under https://developer.vippsmobilepay.com/docs/: APIs/epayment-api/api-guide/operations/create|capture|refund|cancel/, APIs/epayment-api/api-guide/webhooks/, APIs/webhooks-api/request-authentication/, APIs/webhooks-api/api-guide/, APIs/access-token-api/standard-authentication/, knowledge-base/http-headers/, knowledge-base/polling-guidelines/, knowledge-base/errors/, knowledge-base/orderid/, knowledge-base/test-environment/, knowledge-base/design-guidelines/

Unverifiable or flagged

• The documented sample signature does not verify. The sample on the Webhook authentication page (secret AAAA...==, body {"some-unique-content":...}, date Thu, 30 Mar 2023 08:38:32 GMT, host webhook.site) gives the documented content hash lNlsp1XA03N34HrQsVzPgJKtC+r7l/RBF4V3JQUWMj4=, but the page's signature agAiSy... is not what its own sample code computes from those values (with the secret as a UTF-8 string, as in the JavaScript and C# samples, the result is u4zz3dyO3c3xJwl36rPpn1n7WF75u6r2epjH70MZTGM=; with a base64-decoded key also not). We follow the sample code (UTF-8 key). Confirm with the first real webhook from the test environment (owner item).
• No timestamp window. The docs do not define a maximum age for x-ms-date, and retries run up to 7 days, so no age check is made; replay is harmless because the state always comes from GET.
• Idempotency of cancel. Not in the spec's parameter list, sent anyway (Refund page example).
• Same reference, different Idempotency-Key and same key, different body: the docs do not say what the API answers (409 is listed as a possible status of create). The extension never does either: one key and one reference per attempt; on 409 it looks the reference up.
• Real test merchant. No Vipps MobilePay test sales unit is available to us: every flow was proven against tests/mock-server/server.js, built from the specs above. See docs/conformance.md.
• Rename 2027-01-12. "MobilePay becomes Vipps in Denmark and Finland on 12 January"; the docs move to developer.vipps.no then. API hosts are api.vipps.no already; nothing in the integration changes, the default title and paymark switch automatically.

Internals worth knowing

• Payments::start(): settles an earlier attempt of the order first (paid = success, open = cancel with cancelTransactionOnly and read back), writes the row with reference and key, calls create once more with the same key when the first call got no clear answer, adopts a payment found by reference.
• Payments::applyRemote(): under GET_LOCK('kvvipps_<txn>'); AUTHORIZED is accepted only when the amount equals the attempt AND the current order total (Orders::matchesNow()); otherwise error / MISMATCH, a visible order status "Payment amount mismatch" and an automatic release. A second approval of a paid order is a duplicate and is released. Automatic actions run after the lock is released.
• Operations (kv_vipps_op): creating -> done / failed / unknown; each row stores the aggregate value before the call (base_minor). Before any resend the payment is read back: done = marked done; not done and younger than 24 h = resent with its key; older = failed / NOT_CONFIRMED. Amounts of open operations are reserved locally.
• Locks: GET_LOCK names carry a hash of database + table prefix (two shops on one server never wait for each other); the order lock is taken before the payment lock (start, approval); the webhook path waits at most 5 s (Vipps MobilePay waits 10 s for an answer).
• Amount check: the order total is stored at create in the order's own currency with the order's stored rate (order_currency, order_total), so a later store rate update never turns a correct payment into a mismatch.
• An order in the cancel status is never revived: an approval that arrives afterwards is released; cancelling the order while the payment is open cancels it with cancelTransactionOnly.
• Payments::onStatus(): acts only when the order status really changes (the previous history row has another status), never inside its own history writes.
• Tests: php81 tests/unit.php and php83 tests/unit.php (needs node tests/mock-server/server.js 11971 and MariaDB 3307), node tests/e2e.js on a dev store (STORE=oc41). The hidden setting payment_kv_vipps_base_url (loopback hosts only) points the extension to the mock.

Conformance with the Vipps MobilePay documentation (OpenCart)

Checked against the ePayment API spec 1.8.5, the Webhooks API spec, the Access Token API spec and the guide pages (see developer.md for every source), read 2026-11-07.

How it was proven: unit tests against a local stand-in that follows those specs (PHP 8.1 and 8.3, including the documented webhook signature algorithm), browser tests on OpenCart 4.1.0.4 against the same stand-in (settings, keys, webhook registration and signed delivery to the shop's endpoint, checkout redirect, return, waiting page, abort, amount mismatch, capture / refund / release, capture and release on admin status changes, cron), and the OpenCart 4 update path. It has not been run against the real Vipps MobilePay test environment: we have no test sales unit yet, and no real app approved a payment. Confirm the points below once with your own test keys.

To confirm with your own test keys

• One payment approved in the MT test app and the authorized webhook arriving with a signature that verifies (the documented sample signature itself does not verify with its sample secret; see developer.md).
• One capture, one partial refund and one release, and their webhooks.
• Your firewall or bot filter lets Vipps MobilePay webhooks reach /extension/kv_vipps/notify.php.

Not covered in 1.0.0

Freestanding card payments (CARD), Express checkout and dynamic shipping, profile sharing (userinfo), long-living payments, QR / push-message flows, recurring payments, OpenCart 3.

FAQ

Do I need an agreement with Vipps MobilePay?

Yes, a merchant agreement with online payments (ePayment) and the API keys of your sales unit. The test environment uses the test keys of the same agreement.

Which countries and currencies?

Norway (NOK), Denmark (DKK) and Finland (EUR): the currency of your sales unit. One sales unit per mode.

When is the money taken?

It is reserved at approval and taken when you capture: at your capture status, at once, or by hand.

Is an order paid when the customer comes back?

Only when Vipps MobilePay confirms it on read-back.

What if the webhook does not arrive?

The return, the waiting page and the hourly cron read the payment back.

Can a refund or capture happen twice?

No. Each is stored with its idempotency key before it is sent and sent again only with the same key.

What happens on 12 January 2027?

MobilePay becomes Vipps in Denmark and Finland. With an empty "Name at checkout" the extension switches the name and paymark by itself; your keys and payments keep working.

Card payments without the app (CARD), Express checkout, recurring?

Not in 1.0.

OpenCart 3?

No, OpenCart 4.1 only.

Is it affiliated with Vipps MobilePay?

No. It integrates with the public ePayment API.