> **Description:** Comprehensive verification guide for implementing payments, refunds, and webhooks in your ePayment integration.

> **AI agent:** Read [https://developer.vippsmobilepay.com/docs/knowledge-base/ai-tools.md](https://developer.vippsmobilepay.com/docs/knowledge-base/ai-tools.md) first. It covers keeping API keys and secrets out of generated code.

> **Full site overview:** For an overview of the entire site, read [https://developer.vippsmobilepay.com/llms.txt](https://developer.vippsmobilepay.com/llms.txt).

# ePayment API checklist

Use this checklist as your integration requirement specification to ensure your ePayment 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.

Once you have completed your integration, you must use the checklist to ensure that you have covered all areas of the integration.

## Flow to go live

Choose **Merchants** if you integrate directly for your own business, or **Partners** if you integrate on behalf of
merchants.

#### Merchants

**Flow to go live for direct integrations**

1. Order
   [*Payment Integration*](https://vippsmobilepay.com/en-NO/online/payment-integration).
1. We will complete customer control (KYC, PEP, AML, and other compliance checks).
As soon as the customer control is completed, independently of this checklist, we will make the production API keys available on
   [portal.vippsmobilepay.com](https://portal.vippsmobilepay.com) and notify you that you can retrieve your keys.
1. [Retrieve your API keys](https://developer.vippsmobilepay.com/docs/knowledge-base/portal.md#how-to-find-the-api-keys).
1. Complete all the checklist items in the checklist below to ensure your integration is ready for production.
1. Verify the integration in the production environment:
   * A complete order ending in `AUTHORIZED`, `CAPTURED`, `REFUNDED` and `CANCELLED`
      request.
   * We recommend checking this using the API.
1. Go live

#### Partners

**Flow to go live for partner integrations**

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

1. Send your filled out ePayment checklist to us at [developer@vippsmobilepay.com](mailto:developer@vippsmobilepay.com).
Use this [editable PDF](https://developer.vippsmobilepay.com/downloads/epayment-api/epayment-checklistv2.pdf) to fill out and submit. 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 video of your payment flow and a short description of your solution.

1. Fill out the [production sign up form](https://vippsmobilepay.com/en-NO/partner-form) with details about your company and solution.

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

**Download the editable ePayment checklist**

**[Download the PDF](https://developer.vippsmobilepay.com/downloads/epayment-api/epayment-checklistv2.pdf)** -- an editable PDF you can fill out and track your progress.

## ePayment checklist

### Endpoints to integrate

It is important that you integrate *all* non-optional [API endpoints](https://developer.vippsmobilepay.com/redocusaurus/epayment-swagger-id.yaml). For quick examples, see the [quick start guide](https://developer.vippsmobilepay.com/docs/APIs/epayment-api/quick-start.md).

| Purpose | Endpoint |
| --- | --- |
| Create a payment | POST /epayment/v1/payments |
| Create a payment with [Express](https://developer.vippsmobilepay.com/docs/APIs/epayment-api/api-guide/features/express.md) *Optional feature* | POST /epayment/v1/payments |
| Create a payment with [Profile sharing](https://developer.vippsmobilepay.com/docs/APIs/epayment-api/api-guide/features/profile-sharing.md) *Optional feature* | POST /epayment/v1/payments |
| Create a payment with [Minimum user age](https://developer.vippsmobilepay.com/docs/APIs/epayment-api/api-guide/features/minimum-user-age.md) *Optional feature* | 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 Used to cancel pending payments or cancel reserved amounts. | POST /epayment/v1/payments/{'{reference}'}/cancel |
| Full and partial capture All payments are reserve-capture and must therefore be captured in order to withdraw the funds. If payments are not captured, the money will not be paid to the merchant. Read about [capture attempt deadlines](https://developer.vippsmobilepay.com/docs/knowledge-base/reserve-and-capture.md#capture-attempt-deadlines). | POST /epayment/v1/payments/{'{reference}'}/capture |
| Full and partial refund | POST /epayment/v1/payments/{'{reference}'}/refund |

### Branding

| **Branding compliance and checkout visibility**  Following the [terms and conditions for Vipps MobilePay Business Solutions](https://vippsmobilepay.com/en-NO/terms-and-conditions): * Make Vipps MobilePay just as visible and easy to access as other payment methods, including digital wallets and payment apps. * Make Vipps MobilePay directly accessible, with no secondary menus or extra steps. * Show Vipps MobilePay at the same level as comparable payment methods. * Avoid consistently giving Vipps MobilePay a lower priority in the display or checkout flow. * Present Vipps MobilePay in a way that keeps checkout fair, easy to understand and quick to use. [See logos, text, and dos and don'ts for the checkout](https://brand.vippsmobilepay.com/document/61#/branding/online/branding-in-the-checkout) |
| --- |
| #### Use the approved buttons Show only the approved Vipps MobilePay buttons. **Recommended:** The [Widget SDK](https://developer.vippsmobilepay.com/docs/knowledge-base/widget.md) gives you the approved button and takes the customer to the payment for you: the app on a phone or tablet, or a dialog on a computer. It also keeps the button up to date when the brand changes. |

### Quality assurance

Ensure that your implementation complies with our requirements and recommendations.

| #### Implement both webhooks and polling Use both [webhooks](https://developer.vippsmobilepay.com/docs/APIs/webhooks-api/events.md#epayment-api-event-types) and [polling](https://developer.vippsmobilepay.com/docs/knowledge-base/polling-guidelines.md) 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](https://developer.vippsmobilepay.com/docs/knowledge-base/polling-guidelines.md), you must also implement the [Webhooks API](https://developer.vippsmobilepay.com/docs/APIs/webhooks-api/events.md#epayment-api-event-types) to receive real-time updates on payment status changes. The merchant must also always poll [`GET:/epayment/v1/payments/{reference}`](https://developer.vippsmobilepay.com/docs/APIs/epayment-api/api-guide/operations/get_info.md) to check the status of the payment. |
| --- |
| #### Handle payment states and events Make sure to handle all responses for the payment: [Payment states](https://developer.vippsmobilepay.com/docs/APIs/epayment-api/api-guide/concepts.md#state-reference): * `CREATED` * `AUTHORIZED` * `ABORTED` * `EXPIRED` * `TERMINATED` [Event statuses](https://developer.vippsmobilepay.com/docs/APIs/epayment-api/api-guide/concepts.md#payment-modifications): * `CANCELLED` * `CAPTURED` * `REFUNDED` |
| #### Handle errors Make sure to handle [all errors](https://developer.vippsmobilepay.com/docs/APIs/epayment-api/api-guide/errors.md). 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](https://developer.vippsmobilepay.com/docs/knowledge-base/http-headers.md) 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](https://developer.vippsmobilepay.com/docs/APIs/epayment-api/api-guide/features/pre-built-order-management-api-integration.md) to the payment. This is a great benefit for the end user experience. It is also mandatory for merchants using [*Content monitoring*](https://developer.vippsmobilepay.com/docs/APIs/order-management-api/order-management-api-guide.md#content-monitoring). |
| #### Specify customer interaction For in-store solutions, it is required to specify the [customer interaction](https://developer.vippsmobilepay.com/docs/APIs/epayment-api/api-guide/features/customer-present-payments.md) 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](https://status.vippsmobilepay.com/) for real-time updates on service availability, incidents, and maintenance. |

### Avoid integration pitfalls

For the best user experience, avoid these common pitfalls.

| #### Send a useful `reference` ID Follow our [`reference` recommendations](https://developer.vippsmobilepay.com/docs/knowledge-base/orderid.md) 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](https://developer.vippsmobilepay.com/docs/knowledge-base/redirects.md). |
| #### Complete capture before expiration date All payments are [reserve capture](https://developer.vippsmobilepay.com/docs/knowledge-base/reserve-and-capture.md#reserve-capture) payments; therefore, the implementation must ensure that captures are completed before the reservations expire. Once a reservation has 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](https://developer.vippsmobilepay.com/redocusaurus/epayment-swagger-id.yaml). |
| #### Handle cross-border payments Vipps MobilePay is available to users across the [Nordic countries and offers cross-border payments](https://developer.vippsmobilepay.com/docs/knowledge-base/across-borders.md). Merchants must be able to handle customers from outside their country. |
| #### 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](https://portal.vippsmobilepay.com), is not intended for customer support work, and therefore it must be handled in your own system. |