Skip to main content

How ePayment works online

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

Our plugin gives your assistant up-to-date guidance for payments and login. Full instructions

Run both commands, in order.

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

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 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 select to pay with a card, as shown in How it works with freestanding cards.

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 selects to pay with Vipps/MobilePay, the merchant creates a payment request with: POST:/epayment/v1/payments.

Detailed example for payment request

For example:

curl -X POST https://apitest.vipps.no/epayment/v1/payments \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR-ACCESS-TOKEN" \
-H "Ocp-Apim-Subscription-Key: YOUR-SUBSCRIPTION-KEY" \
-H "Merchant-Serial-Number: YOUR-MSN" \
-H "Vipps-System-Name: acme" \
-H "Vipps-System-Version: 3.1.2" \
-H "Vipps-System-Plugin-Name: acme-webshop" \
-H "Vipps-System-Plugin-Version: 4.5.6" \
-d '{
  "amount": {
    "currency": "NOK",
    "value": 1000
  },
  "paymentMethod": {
    "type": "WALLET"
  },
  "customer": {
    "phoneNumber": "4712345678"
  },
  "reference": "acme-shop-123-order123abc",
  "returnUrl": "https://yourwebsite.com/redirect?reference=abcc123",
  "userFlow": "WEB_REDIRECT",
  "paymentDescription": "One pair of socks"
}'

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.

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

6. The merchant completes the order and shipping​

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

7. The merchant captures the payment​

The merchant captures the order through the ePayment API. The payment is transferred to the merchant's account. This may take 2 or 3 days, depending on the bank.

Sequence diagram​

View sequence diagram

Standard online payment flow

100%
  1. Merchant initiates a payment request via the ePayment API.
  2. ePayment API requests payment from the customer and adds order details.
  3. Customer clicks pay.
  4. Webhooks API sends the merchant a webhook with the payment authorization status.
  5. Merchant displays order confirmation to the customer.
  6. Merchant prepares the order (packs goods, makes ready to dispatch).
  7. Merchant captures the payment via the ePayment API.
  8. ePayment API returns a response with the captured amount.
  9. Merchant verifies the captured amount matches expected before shipping.
  10. 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