Skip to main content

App Payments to ePayment

Below, you can find comparison between the existing MobilePay App Payments facade API and the ePayment API. The two APIs are very similar, catering to an easy switch between the two solutions.

Before you begin, make sure to check out how to get started with the migration.

New features

Remember to check out the new features you can use to enhance your solution and create more value for your and your customers

Key differences between App Payments and ePayment


Instead of API keys or OpenId, the ePayment API uses an Access Token solution.


The reference (also called orderId) must be unique for the sales unit Merchant Serial Number (MSN) (i.e., the ID of the sales unit). The reference doesn't need to be globally unique, so several MSNs may use the same reference, as long as it's unique for each sales unit. The reference is case-sensitive. We strongly recommend using a format like acme-shop-123-order123abc, instead of just 123456. For more details please visit our 'Recommendations for payment identifier' page.


The paymentDescription can no longer exceed 100 characters. If a payment description exceeds this length, the request will fail with 400 Bad Request and reason: "The field PaymentDescription must be a string with a minimum length of 3 and a maximum length of 100."


Webhooks have more and different events. Read more in the Webhooks section.

Request authentication of webhooks

The mechanics for verifying webhooks has changed. Find all details in the Webhook request authentication section.

Mapping between the APIs


OperationMobilePay App PaymentsePayment
Initiate PaymentPOST:/v1/paymentsPOST:/epayment/v1/payments
Fetch Single PaymentGET:/v1/payments/{paymentid}GET:/epayment/v1/payments/{reference}
Fetch a list of paymentsGET /v1/paymentsN/A
Query payment logN/AGET:/epayment/v1/payments/{reference}/events
Capture PaymentPOST:/v1/payments/{paymentid}/capturePOST:/epayment/v1/payments/{reference}/capture
Cancel PaymentPOST:/v1/payments/{paymentid}/cancelPOST:/epayment/v1/payments/{reference}/cancel
Issue new refundPOST:/v1/refundsPOST:/epayment/v1/payments/{reference}/refund
fetch a list of refundsGET:/v1/refundsN/A
fetch single refundGET:/v1/refunds/{refundid}GET:/epayment/v1/payments/{reference}

Authentication and headers

We have simplified the authentication method and introduced a joint solution across our API platform. Please read more in the authentication section.


MobilePay App PaymentsePayment
apiKey or openIdAuthorization (POST:/accesstoken/get)
N/AVipps-System-Version (see HTTP headers)
N/AVipps-System-Name (see HTTP headers)
N/AVipps-System-Plugin-Name (see HTTP headers)
N/AVipps-System-Plugin-Version (see HTTP headers)
X-MobilePay-Idempotency-KeyIdempotency-Key (see Idempotency)
N/AOcp-Apim-Subscription-Key (see API keys)
N/AMerchant-Serial-Number (MSN)

Initiate Payment


MobilePay App PaymentsePayment
amountamount (currency, value)
customerPhoneNumber (Used for dual device flows on web)customer (phoneNumber)
N/AcustomerInteraction ("CUSTOMER_NOT_PRESENT")
N/ApaymentMethod (type "WALLET")
paymentIdreference (set in paymentInitiation)

Query Payment


MobilePay App PaymentsePayment
amountamount (currency, value)
N/Aaggregate (authorizedAmount, cancelledAmount, capturedAmount, refundedAmount)
N/ApaymentMethod (type)
N/Aprofile (sub) (see What is the sub?)

Capture, Cancel and Refund Payment


MobilePay App paymentsePayment
amountmodificationAmount (currency, value) not applicable for cancel
N/Aamount (currency, value)
N/Aaggregate (authorizedAmount, cancelledAmount, capturedAmount, refundedAmount)
refundId only applicable for refundN/A



New features

Now that you are moving to the ePayment solution, you can take advantage of some new features to improve your solution and enhance user experience.

Freestanding card payments

The ePayment API supports freestanding card payments, where any user can pay with a card without using the app. This allows merchants to accept payments from customers in countries where the Vipps / MobilePay app is not yet available.

Receipt directly in the app

Need to show an invoice or don't want paper receipts? The ePayment API comes with pre-built order management API integration, making it easy to supply order information at payment creation. You can add order lines to attach a receipt shown to the user in the app. Alternatively, supply a URL to show the user an invoice or similar. All are accessible before the user accepts the payment.

User data

Remove the hassle of the user inputting their data manually. The ePayment API lets merchants ask for the user's profile information (such as phone number or email address) as part of the payment flow with profile sharing.


Need an easy way to log your users in to your app? You don't have to stick with the ePayment API, you are free to use all our APIs including Login that can be used to retrieve user data or as a login option.

Merchant and sales unit data through the API

There is no need to go through the portal to fetch you merchant serial number, you can just use the Management API. This is especially relevant for partners, as it can also be used to onboard and fetch information about their merchants.

Help us improve our documentation

Did you find what you were looking for?