> **Description:** Detailed walkthrough of online payment flows for web shops and e-commerce integrations.

> **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).

# How ePayment works online

This is how payments in web shops or merchant websites work with the ePayment API.
This page follows the customer's journey, from selecting Vipps/MobilePay as the payment method through to the
completed order.

## Details

### 1. Customer selects Vipps or MobilePay as their payment method

On the checkout page of a merchant's website or app, the customer chooses to pay with Vipps/MobilePay.
They can alternatively choose to pay with a card, as shown in
[How it works with freestanding cards](https://developer.vippsmobilepay.com/docs/APIs/epayment-api/how-it-works/freestanding-cards.md).

Show Vipps MobilePay as visibly as the other payment methods at checkout. See the
[brand guidelines for checkout](https://brand.vippsmobilepay.com/document/61#/branding/online/branding-in-the-checkout).

Screenshot: Mobile merchant cart page showing product details and a Pay with [Vipps/MobilePay] button alongside a standard checkout button.

### 2. The merchant creates a payment request

When the customer chooses to pay with Vipps/MobilePay, the merchant creates a payment request with
[`POST:/epayment/v1/payments`](https://developer.vippsmobilepay.com/redocusaurus/epayment-swagger-id.yaml), specifying
`"userFlow": "WEB_REDIRECT"` and a `returnUrl` to return the customer to when the payment session ends.

For a full example, see [ePayment Features: Online](https://developer.vippsmobilepay.com/docs/APIs/epayment-api/api-guide/features/online.md).

### 3. Customer opens the Vipps/MobilePay app

The [Widget SDK](https://developer.vippsmobilepay.com/docs/knowledge-base/widget.md) handles the transition from the merchant's website to the
Vipps/MobilePay app automatically.

If the payment was started from a mobile device, the Vipps or MobilePay app opens
automatically.

If the payment was started on a desktop device, a payment dialog opens. The customer enters their phone number and
the payment request is sent to the app on their phone.

Screenshots showing the flow: 1. The merchant's checkout page with Vipps selected as the payment method. The dialog is not yet open. 2. A dialog showing a phone number entry form. The checkout page is visible and dimmed behind the dialog. 3. A dialog prompting the customer to open the Vipps app to complete the payment.

### 4. Customer confirms the payment in the app

A push notification appears on the customer's phone. They log in to Vipps MobilePay and confirm the payment.

Screenshot: App payment screen showing the merchant name, order description, selected payment card, and a Pay button.

The ePayment API automatically reserves the payment and provides confirmation of the successful payment.

### 5. The merchant learns the outcome from webhooks and polling

The merchant's system has no visibility into what happens in the app, so it must subscribe to webhooks to be
notified when the customer acts on the payment. Register the webhook with the
[Webhooks API](https://developer.vippsmobilepay.com/docs/APIs/webhooks-api/api-guide.md) before creating the payment, so that no event is missed while
the customer is paying, and subscribe to all three outcomes:

* `epayments.payment.authorized.v1`: the customer approved the payment in the app.
* `epayments.payment.aborted.v1`: the customer canceled the payment in the app.
* `epayments.payment.expired.v1`: the customer did not confirm the payment in time, 10 minutes by default.

Webhooks can be delayed or missed, so do not rely on them alone. Back them up by polling
[`GET:/epayment/v1/payments/{reference}`](https://developer.vippsmobilepay.com/redocusaurus/epayment-swagger-id.yaml)
for the payment state, following the [polling guidelines](https://developer.vippsmobilepay.com/docs/knowledge-base/polling-guidelines.md):
start after 5 seconds, then check every 2 seconds.

### 6. The merchant's shop confirms the order

After the customer has approved the payment in the app:

* If the payment was started on a mobile device, the store page or app will open again and confirm that the order was successful.
* If the payment was started on a desktop device, the customer can go back to the webpage, which confirms that the
  order was successful.

### 7. The merchant completes the order and shipping

The merchant completes the order and ships it to the customer.

### 8. The merchant captures the payment

Authorization only reserves the amount. Capturing the payment is what transfers the funds, so the merchant
captures the payment through the ePayment API once the order is ready to ship.
The funds are then transferred to the merchant's account. This may take 2 or 3 days, depending on the bank.

## Sequence diagram

Standard online payment flow

```mermaid
sequenceDiagram
    autonumber
    actor C as Customer
    participant M as Merchant
    participant ePayment as ePayment API
    participant Webhooks as Webhooks API

    C->>M: Select to pay with Vipps or MobilePay
    M->>ePayment: Initiate payment request
    ePayment-->>M: redirectUrl and payment reference
    M->>C: Handle app switch with redirectUrl (tip: use Widget SDK)

    ePayment->>C: Request the payment in the Vipps/MobilePay app
    C->>ePayment: Select a card and click pay
    Webhooks-->>M: Webhook: the payment was authorized, aborted, or expired
    M->>ePayment: Poll for payment info, as a backup if the webhook is delayed or missed
    ePayment-->>M: Current state of the payment

    alt The payment was aborted or expired
        M->>C: Return the customer to the checkout page
    else The payment was authorized
        M->>C: Display order confirmation
        M->>M: Prepare order (pack goods, ready to dispatch)
        M->>ePayment: Capture payment
        ePayment-->>M: Response with capturedAmount
        M->>M: Verify capturedAmount matches expected before shipping
        M->>C: Ship the order (only after full capture verified)
    end
```

  Customer selects to pay with Vipps or MobilePay.
  Merchant initiates a payment request via the ePayment API.
  ePayment API returns a redirectUrl and payment reference to the merchant.
  Merchant handles the app switch with the redirectUrl. We recommend using the Widget SDK for this.
  ePayment API requests the payment in the customer's Vipps or MobilePay app.
  Customer selects a card and clicks pay.
  Webhooks API sends the merchant an authorized, aborted, or expired event.
  Merchant gets the payment from the ePayment API, as a backup if the webhook is delayed or missed.
  ePayment API returns the current state of the payment.
  If the payment was aborted or expired, the customer is returned to the checkout page and the flow
  ends.
  If the payment was authorized, the merchant displays order confirmation to the customer.
  Merchant prepares the order (packs goods, makes ready to dispatch).
  Merchant captures the payment via the ePayment API.
  ePayment API returns a response with the captured amount.
  Merchant verifies the captured amount matches expected before shipping.
  Merchant ships the order (only after full capture is verified).

## Optional features

**Profile sharing** - You can request customer profile information (such as name, address, email, or phone number) during the payment process with explicit user consent. See [Profile sharing feature](https://developer.vippsmobilepay.com/docs/APIs/epayment-api/api-guide/features/profile-sharing.md).

## Alternative flows

**Express** - See [How Express works](https://developer.vippsmobilepay.com/docs/APIs/epayment-api/how-it-works/express.md) for a streamlined one-click checkout with shipping selection in the app.

**Pay with card** - See [How it works with freestanding cards](https://developer.vippsmobilepay.com/docs/APIs/epayment-api/how-it-works/freestanding-cards.md).

## Next steps

For implementation details and the request example, see
[ePayment Features: Online](https://developer.vippsmobilepay.com/docs/APIs/epayment-api/api-guide/features/online.md).

See [Recommended flows: Online payments](https://developer.vippsmobilepay.com/docs/recommended-flows/online/README.md) for an example of this flow with detailed code examples.

See the [ePayment API quick start guide](https://developer.vippsmobilepay.com/docs/APIs/epayment-api/quick-start.md) to start experimenting with the API.