Skip to main content

How ePayment works online

View as Markdown (opens in a new tab)
Install AI tools

Give your assistant up-to-date guidance for our APIs, with our plugin or without it.

The plugin is still under development. See the AI tools page for details.

Run both commands, in order.

claude plugin marketplace add vippsas/agent-toolkit
claude plugin install vipps-developer@agent-toolkit

For troubleshooting, see the full instructions.

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.

Select Vipps in the online shop

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

3. Customer opens the Vipps/MobilePay app​

The Widget SDK 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.

Checkout page with Vipps selected

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.

Vipps payment confirmed

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 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} for the payment state, following the polling guidelines: 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

100%
  1. Customer selects to pay with Vipps or MobilePay.
  2. Merchant initiates a payment request via the ePayment API.
  3. ePayment API returns a redirectUrl and payment reference to the merchant.
  4. Merchant handles the app switch with the redirectUrl. We recommend using the Widget SDK for this.
  5. ePayment API requests the payment in the customer's Vipps or MobilePay app.
  6. Customer selects a card and clicks pay.
  7. Webhooks API sends the merchant an authorized, aborted, or expired event.
  8. Merchant gets the payment from the ePayment API, as a backup if the webhook is delayed or missed.
  9. ePayment API returns the current state of the payment.
  10. If the payment was aborted or expired, the customer is returned to the checkout page and the flow ends.
  11. If the payment was authorized, the merchant displays order confirmation to the customer.
  12. Merchant prepares the order (packs goods, makes ready to dispatch).
  13. Merchant captures the payment via the ePayment API.
  14. ePayment API returns a response with the captured amount.
  15. Merchant verifies the captured amount matches expected before shipping.
  16. 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.

Alternative flows​

Express - See How Express works for a streamlined one-click checkout with shipping selection in the app.

Pay with card - See How it works with freestanding cards.

Next steps​

For implementation details and the request example, see ePayment Features: Online.

See Recommended flows: Online payments for an example of this flow with detailed code examples.

See the ePayment API quick start guide to start experimenting with the API.

Last updated on