Coming soon

The ePayment PSP API is not yet available. This documentation describes the upcoming functionality.

ePayment PSP API checklist

Use this checklist to ensure your ePayment PSP API implementation is complete and production-ready. It covers the key endpoints, quality assurance steps and pitfalls — from payments to captures, refunds, and error handling.

Flow to go live

1. Complete your testing of the ePayment PSP API. Use the list below to ensure you cover all areas of the integration before you submit the checklist.

2. Send your filled out checklist to us at developer@vippsmobilepay.com. Request examples in the checklist must be no more than 1 month old at the time you submit the checklist. Together with the checklist, please include a short description of your solution.

3. 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.

Endpoints to integrate

It is important that you integrate all the ePayment API endpoints.

Purpose	Endpoint
Create a payment	POST /epayment/v1/payments
Get payment status Fetch current status of a payment.	GET /epayment/v1/payments/{reference}
Fetch payment event log Fetch the history of a payment. Often used in support cases to see all events for a specific payment.	GET /epayment/v1/payments/{reference}/events
Cancel payment Communicate to us that the remaining authorized funds are cancelled in your systems or that you want to prevent the payment from being completed.	POST /epayment/v1/payments/{reference}/cancel
Full & partial capture Communicate to us when you have charged the user.	POST /epayment/v1/payments/{reference}/capture
Full & partial refund Communicate to us when you have refunded the user.	POST /epayment/v1/payments/{reference}/refund

Quality assurance

Ensure that your implementation complies with our requirements and recommendations.

Implement both webhooks and polling Use both webhooks and polling to ensure that the user gets the correct status as soon as possible. Set up polling as a fallback in case of delayed webhooks. To minimize polling, you must also implement the Webhooks API to receive real-time updates on payment status changes. The merchant must also always poll GET:/epayment/v1/payments/{reference} to check the status of the payment.

Handle payment states and events Make sure to handle all responses for the payment: Payment states: CREATED AUTHORIZED ABORTED EXPIRED TERMINATED Event statuses: CANCELLED CAPTURED REFUNDED

Handle errors Make sure to handle all errors. All integrations should display errors in a way that the users (customers and merchant employees/administrators) can see and understand them.

Proper logging All integrations should log error responses to be used for later reference in troubleshooting. Logs must include endpoint, headers, request body, error code and message.

Include HTTP headers Send the HTTP headers in all API requests for better tracking and troubleshooting (mandatory for partners and platforms).

Add information to the payment history We recommend adding order details to the payment. This is a great benefit for the end user experience. It is also mandatory for merchants using Content monitoring.

Specify customer interaction For instore solutions it is required to specify the customer interaction by setting "customerInteraction": "CUSTOMER_PRESENT" on payment initiation. This is to determine that the customer is present at the time of purchase.

Sign up for operational updates Subscribe to the Vipps MobilePay Operational Status Page for real-time updates on service availability, incidents, and maintenance.

Avoid integration pitfalls

Avoid these common mistakes to ensure the best user experience.

Send a useful reference ID Follow our reference recommendations to ensure that each transaction is uniquely and reliably identified across all Vipps MobilePay APIs.

Handle redirects For mobile flows the implementation must handle that the returnUrl URL is opened in the default browser on the phone. And not rely on the use of a specific browser, a specific tab, an embedded browser, or a session token. Follow our recommendations regarding handling redirects.

Complete capture before expiration date All payments are reserve capture payments, therefore the implementation must ensure to complete captures before the reservations expire. Once a reservation is expired it is no longer possible to capture.

Cancel authorized payments that will not be captured Authorized payments that will not be captured must be cancelled to ensure that the amount is not unnecessarily reserved on the user's bank account. It is the merchant's/partner's responsibility to cancel the authorized payments using POST:/epayment/v1/payments/{reference}/cancel

Handle cross-border payments Vipps MobilePay is available to users across the Nordic countries and offers cross-border payments. Merchants must be able to handle customers from outside their country.

Follow design guidelines The Vipps MobilePay 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 API endpoints. Our portal, portal.vippsmobilepay.com, is not intended for customer support work, and therefore it must be handled in your own system.