eCom API checklist

Only available for Vipps. All new integrations use the ePayment API.

API version: 2.0.

All new integrations use the ePayment API

eCom checklist	Your comments (include your order ID)
Endpoints to integrate
Initiate POST:/ecomm/v2/payments
Full and partial Capture POST:/ecomm/v2/payments/{orderId}/capture
Cancel PUT:/ecomm/v2/payments/{orderId}/cancel
Full and partial Refund| POST:/ecomm/v2/payments/{orderId}/refund
Details GET:/ecomm/v2/payments/{orderId}/details
Callback POST:[callbackPrefix]/v2/payments/{orderId}
Shipping Details (For Vipps Hurtigkasse /express checkout only) POST:[shippingDetailsPrefix]/v2/payments/{orderId}/shippingDetails
Remove consent (For Vipps Hurtigkasse /express checkout only) DELETE:[consentRemovalPrefix]/v2/consents/{userId}
Quality assurance
Handle callbacks Correctly handle callbacks from Vipps, both for successful and unsuccessful payments. See the API documentation for how callback URLs are built, make test calls to make sure you handle the POST requests correctly. Vipps does not have capacity to manually do this for you.
Handle errors Make sure to log and handle all errors. All integrations should display errors in a way that the users (customers and merchant employees/administrators) can see and understand them.
Include HTTP headers Send the HTTP headers in all API requests for better tracking and troubleshooting (mandatory for partners and platforms, who must send these headers as part of the checklist approval).
Add information to the payment history We recommend using the Order Management API to add receipts and/or images to the payment history. This is a great benefit for the end user experience. It is also mandatory for merchants using Content monitoring.
Avoid integration pitfalls
Send a useful OrderId. Follow our orderId recommendations.
Poll for payment details The Merchant must not rely on fallback or callback alone, and must poll GET:/ecomm/v2/payments/{orderId}/details as documented (this is part of the first item in this checklist, but it's still a common error). Follow our polling recommendations.
Handle redirects The merchant must handle that the fallback URL is opened in the default browser on the phone, and not in a specific browser, in a specific tab, in an embedded browser, requiring a session token, etc. Follow our recommendations regarding handling redirects.
Follow design guidelines The Vipps branding must be according to the Design guidelines.
Educate customer support Make sure your customer support has all the tools and information they need available in your system, through the APIs listed in the first item in this checklist, and that they do not need to visit portal.vippsmobilepay.com for normal work.

Information for partners

Partners, there are additional checklist items for you, as described in Partner checklist.

Partner checklist

Partner checklist	Your comments
Accept partner terms and conditions As a partner, you accept the Partner terms and conditions
Provide technical documentation for merchants How to apply for products (a URL, plain text or PDF is preferred) How to configure and use the solution (a URL, plain text or PDF is preferred) Frequently Asked Questions (FAQs) for merchants (a URL, plain text or PDF is preferred)
Pilot customer Provide one pilot customer to verify the integration in the production environment (send organization number and name).
Description of integration Describe how your integration has been set up, with a link to a demo, or provide screenshots (PDF is preferred).

Send your completed checklist to us at developer@vippsmobilepay.com.

Include examples from the test environment, pilot customer info, and a description of the implemented solution.

We will verify your integration and get back to you as soon as possible. After the checklist is approved, we'll send you the information you need to go live.

Flow to go live for direct integrations

1. The merchant orders Payment Integration.
2. Vipps completes customer control (KYC, PEP, AML, etc.).
3. The merchant receives an email from Vipps saying that they can log in with BankID on portal.vippsmobilepay.com and retrieve API keys.
4. The merchant completes all checklist items above. Please double-check to avoid mistakes.
5. The merchant verifies the integration in the test environment by checking that there are test IDs (orderId) in the Vipps test environment, with the following states:
   • A complete order ending in REFUND (/refund request).
   • A complete order ending in VOID (/cancel request).
   • In the test environment this must be verified using the API itself.
6. The merchant verifies the integration in the production environment (similar to step 5):
   • A complete order ending in REFUND (/refund request).
   • For reserve capture: A complete order ending in VOID (/cancel request after reserve).
   • Please note: Vipps does not do any kind of activation or make any changes based on this checklist. The API keys for the production environment are made available on portal.vippsmobilepay.com as soon as the customer control (see step 2) is completed, independently of this checklist.
7. Partners only: Send your checklist to developer@vippsmobilepay.com. We don't do any kind of activation or make any changes
8. The merchant goes live 🎉

tip

Operational Status Page

We recommend that you subscribe to the Vipps MobilePay Operational Status Page for real-time updates on service availability, incidents, and maintenance.