App Payments to ePayment
Migrating from MobilePay App Payments to Vipps MobilePay ePayment is a seamless process due to the similarities between the two APIs. This guide provides a detailed comparison between the MobilePay App Payments facade API and the Vipps MobilePay ePayment API, highlighting the key differences and mapping the endpoints to ensure a smooth transition.
Before you begin, make sure to review our migration readiness guide to prepare for the switch.
Explore the new features available in the ePayment API to enhance your solution and provide more value to 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. The mechanics for verifying webhooks has changed. Find all details in the Webhook 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:
| 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:
| 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:
| 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:
| 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:
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 when you use the Management API. This is especially relevant for partners, as it can also be used to onboard and fetch information about their merchants.
Verification and go live
- Merchants
- Partners
Before going live with your new ePayment solution you must verify your solution. You do this by going through all the points in the ePayment checklist. Please ensure that you have implemented all endpoints and evaluated the Quality assurance and Avoid integration pitfalls. If you have any questions about any of the points in the checklist, please feel free to contact us.
If you complete the integration before end of Q2 2025, we also offer the option that we will verify your integration if you submit the checklist to developer@vippsmobilepay.com (or through your Slack channel) including a video of the payment flow.
Once you are satisfied with the integration and the checklist, you can go live.
Before going live with your new ePayment solution, we must verify your solution. You do this by going through all the points in the ePayment checklist. Please ensure that you have implemented all endpoints and evaluated the Quality assurance and Avoid integration pitfalls.
Once you have filled out the checklist, please send it to developer@vippsmobilepay.com (or through your Slack channel) including a video of the payment flow.
If you complete the integration before end of Q2 2025, we also offer the option for a more thorough verification of your integration. Please contact developer@vippsmobilepay.com if you are interested in this.
Once your checklist is approved, you can go live with your merchants according to your own plan. Please let us know how you plan for going live, whether it is all merchants at once or in batches.