Configuration

Connection (Orders > Vipps MobilePay > Connection)

One set of fields per mode. Both modes are kept side by side; a payment is always handled with the mode it was created in.

Field	Meaning
Mode	Test (sandbox) uses the Vipps MobilePay test environment (apitest.vipps.no), no money moves. Live uses api.vipps.no
Merchant Serial Number (MSN)	The number of the sales unit, shown in the business portal next to the API keys: 4 to 10 digits
Sales unit currency	NOK (Norway), DKK (Denmark) or EUR (Finland). One currency per sales unit, set per mode. See “Currencies” below
Client id	From the business portal
Client secret	Stored encrypted (AES-256-GCM), never shown again. Leave empty to keep the stored value
Subscription key (Ocp-Apim-Subscription-Key)	Stored encrypted, never shown again. Leave empty to keep it
Webhook address	Read-only: <shop>/index.php?dispatch=kv_vipps_mobilepay.webhook&c=<account>

Buttons:

• Save stores the fields. Save and test stores them and tests the connection.
• Test connection fetches an access token and reads a payment reference that cannot exist. An answer “not found” (404) means the keys, the MSN and the subscription key are accepted. Wrong keys give a readable error.
• Register webhook registers the webhook address at Vipps MobilePay for the selected mode with seven events (authorized, aborted, expired, terminated, cancelled, captured, refunded) and stores the returned secret encrypted. The secret is shown only once by Vipps MobilePay, so a registration of the same address whose secret we do not hold is deleted and registered again. The button reads Register webhook again once a webhook exists; the page warns when the shop address changed since the registration.

Without a webhook, payments are still confirmed by the customer’s return and the cron; register it for instant updates.

Webhook rules

• Vipps MobilePay accepts only https:// addresses that do not redirect and use common ports (80, 443, 8080). Make sure the storefront does not redirect index.php?dispatch=kv_vipps_mobilepay.webhook (www to non-www, http to https): the address registered is the one shown on the page.
• Each webhook is verified by its HMAC-SHA256 signature (the x-ms-content-sha256 header and Authorization: HMAC-SHA256 SignedHeaders=x-ms-date;host;x-ms-content-sha256&Signature=...). The Authorization header is read with the PHP-FPM fallbacks (HTTP_AUTHORIZATION, REDIRECT_HTTP_AUTHORIZATION, getallheaders(), apache_request_headers()).
• A webhook only triggers a read-back: the payment is always read with GET before anything is booked. If the read-back fails the shop answers 503 so that Vipps MobilePay retries. A bad signature answers 401.
• Your firewall or bot filter must let Vipps MobilePay reach the address. The address is a POST to a front controller dispatch and never a cacheable page, so it works with the 4.21 full page cache switched on.

Currencies and limits

• The currency of the sales unit (NOK, DKK or EUR) is the currency of every payment. A cart in another shop currency is converted once at payment start with the shop’s own currency rate; the shop must have the sales unit currency defined. The amount sent and the order total are stored and never converted again, so a later rate change cannot turn a correct payment into a mismatch.
• Limits of the ePayment API: NOK minimum 1.00, DKK and EUR minimum 0.01, maximum 650000.00. Outside that range the method is not offered at checkout.

Add-on settings (Add-ons > Manage add-ons > Vipps MobilePay Payments > Settings)

Setting	Default	Meaning
Enable	on	When off, no new work is started (the method is not offered). Payments, webhooks, captures and refunds already under way are still processed
Marketplace owner mode	on	Multi-Vendor only. On: every order is paid to the marketplace owner’s sales unit. Off: each vendor connects their own sales unit and receives the payments for their orders directly
Capture	When the order reaches the capture status	Vipps MobilePay reserves the amount when the customer approves; capture takes the money. When the order reaches the capture status (recommended: when the goods are sent), At once after approval, or By hand on the order page
Capture status	Complete	The order status that captures the reserved amount. A Multi-Vendor vendor order captures its own share
Order status after approval	Processed	Status of an order whose payment was approved (the amount is reserved)
Order status when not paid	Failed	Status of an order whose payment was cancelled in the app, expired or was withdrawn. A pending payment never gets this status
Release status	Canceled	The order status that releases the reserved, not yet captured amount, and withdraws a payment the customer has not approved yet. An approval that arrives for an order in this status is released; the order is never revived
Refund status	empty	The order status that refunds the captured money of the order (queued, runs with the cron). Leave empty to refund only by hand
Payment reference prefix	cs	Letters, digits and dashes (up to 20). The reference sent to Vipps MobilePay is prefix-order id-random part; use a different prefix per shop when several shops share one sales unit
Debug log	off	Also stores every HTTP call with its masked request and response. Secrets are never stored. Switch off when you are done
Log retention (days)	90	Older log entries are removed by the cron run
Cron		The command line and the secret web address of the cron
License		Your license key and status

An order is moved to “Order status after approval” only when the read-back says AUTHORIZED, the amount equals the amount created, and the order total still equals the total stored at payment start.

Payment method settings (Administration > Payment methods, processor “Vipps MobilePay”)

Field	Meaning
Show the local brand name	On by default. Checkout shows “Vipps” for a NOK sales unit and “MobilePay” for DKK and EUR sales units, with the matching official paymark; from 12 January 2027 MobilePay becomes Vipps in Denmark and Finland and the name switches by itself. Untick to show the name of the payment method instead
Text in the app	Shown to the customer in the app before “order ” (paymentDescription, 3 to 100 characters). Usually the shop name

The Connection button on this page opens the Connection page.

What the customer sees at checkout

The official paymark (the “Pay Mark Small” file of the Vipps MobilePay brand book, unchanged), the brand book line “Pay safely and easily. No fees, no matter the amount.”, three short steps (on a phone the app opens by itself; on a computer you enter your mobile number and approve in the app; the amount is reserved now and charged when your order is processed), a “TEST MODE” line while the sales unit is in test mode, and the trademark line.

Multi-Vendor

Owner mode on (default). All orders are paid to the marketplace owner’s sales unit; vendors have no Connection tab and can look at the payment tab of their orders but can never capture, refund or release. A cart with several vendors is one payment on the parent order. Each vendor (child) order captures its own share when it reaches the capture status (the last one takes the rounding rest) and refunds only its own share. A cancelled vendor order’s share is never captured by another vendor; the rest of the reservation is released once every vendor order is captured or cancelled. Vendor payouts stay with Multi-Vendor (commissions and payouts).

Owner mode off (direct payments to vendors). Each vendor connects their own sales unit under Orders > Vipps MobilePay > Connection in the vendor panel and registers their own webhook. A single-vendor cart is paid to that vendor’s sales unit and the vendor captures and refunds their own orders. A cart with several vendors does not offer Vipps MobilePay, and a vendor without a sales unit is not offered.

In this mode the money goes straight to the vendor’s sales unit, not to the marketplace. Multi-Vendor’s payouts and commissions still count such an order as collected by the marketplace unless you use the core Direct payments add-on (vendors’ own payment methods and separate checkout) or settle the commission with the vendor yourself (for example as a payout adjustment). Owner mode on keeps all money with the marketplace and the usual payouts.

A sales unit (MSN) cannot be replaced while it still has open or reserved payments: settle them first (capture or release), otherwise the Connection page refuses the change.

Cron

The cron reads open payments that were not read for a minute (lost webhooks, customers who never returned), settles unanswered operations, runs queued jobs (refund at the refund status), warns about reservations close to their capture deadline and removes old log entries. Use either:

• php admin.php --dispatch=kv_vipps_mobilepay.cron (from the shop folder), or
• the secret web address shown in the Cron section of the settings (a wrong key answers 403).

Money in flight is always finished by the cron, whether the license is valid or not.

Order statuses and permissions

• Orders and the add-on pages follow the order privileges; the Connection, Log and Jobs pages and their actions need the settings privileges.
• Make sure the order statuses you choose exist and that the Complete (capture) status is not set automatically by something else before the goods are sent.