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

Authentication

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

Reference

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.

Description

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

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

Endpoints

Operation	MobilePay App Payments	ePayment
Initiate Payment	POST:/v1/payments	POST:/epayment/v1/payments
Fetch Single Payment	GET:/v1/payments/{paymentid}	GET:/epayment/v1/payments/{reference}
Fetch a list of payments	GET /v1/payments	N/A
Query payment log	N/A	GET:/epayment/v1/payments/{reference}/events
Capture Payment	POST:/v1/payments/{paymentid}/capture	POST:/epayment/v1/payments/{reference}/capture
Cancel Payment	POST:/v1/payments/{paymentid}/cancel	POST:/epayment/v1/payments/{reference}/cancel
Issue new refund	POST:/v1/refunds	POST:/epayment/v1/payments/{reference}/refund
fetch a list of refunds	GET:/v1/refunds	N/A
fetch single refund	GET:/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.

See:

• Access token API

MobilePay App Payments	ePayment
apiKey or openId	Authorization (POST:/accesstoken/get)
N/A	Vipps-System-Version (see HTTP headers)
N/A	Vipps-System-Name (see HTTP headers)
N/A	Vipps-System-Plugin-Name (see HTTP headers)
N/A	Vipps-System-Plugin-Version (see HTTP headers)
X-MobilePay-Idempotency-Key	Idempotency-Key (see Idempotency)
N/A	Ocp-Apim-Subscription-Key (see API keys)
N/A	Merchant-Serial-Number (MSN)

Initiate Payment

See:

• Create

MobilePay App Payments	ePayment
amount	amount (currency, value)
idempotencyKey	Idempotency-Key
reference	reference
paymentPointId	Merchant-Serial-Number
redirectUri	returnUrl
description	paymentDescription
customerPhoneNumber (Used for dual device flows on web)	customer (phoneNumber)
N/A	customerInteraction ("CUSTOMER_NOT_PRESENT")
N/A	paymentMethod (type "WALLET")
N/A	userFlow ("NATIVE_REDIRECT" or "WEB_REDIRECT")
Response
paymentId	reference (set in paymentInitiation)

Query Payment

See:

• Get payment
• Get payment event log

MobilePay App Payments	ePayment
paymentId	reference
Response
paymentId	reference
amount	amount (currency, value)
description	N/A
state	state
N/A	aggregate (authorizedAmount, cancelledAmount, capturedAmount, refundedAmount)
N/A	paymentMethod (type)
N/A	profile (sub) (see What is the sub?)
N/A	pspReference

Capture, Cancel and Refund Payment

See:

• Capture
• Cancel
• Refund

MobilePay App payments	ePayment
paymentId	reference
amount	modificationAmount (currency, value) not applicable for cancel
Response
N/A	amount (currency, value)
N/A	state
N/A	aggregate (authorizedAmount, cancelledAmount, capturedAmount, refundedAmount)
refundId only applicable for refund	N/A
N/A	pspReference
N/A	reference

Webhooks

See:

• Webhooks

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.

Login

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.