Skip to main content

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

The standard payment flow. The customer checks out in your web shop or app and approves the payment in the Vipps or MobilePay app.

Tip

For a visual walkthrough of the customer's experience with online payments, see How ePayment works online.

Three-screen app-switch payment flow: (1) WebShop checkout with the app selected as payment method. (2) Payment app screen. (3) WebShop order confirmation page.

Scenario​

In your user interface, offer Vipps and/or MobilePay as a payment option. When the user selects their preferred method, send the payment request to us. We'll then prompt the user in their Vipps or MobilePay app to complete the payment.

The basic online flow is:

  1. Customer selects to pay with Vipps or MobilePay
  2. The merchant creates a payment request
  3. The Vipps or MobilePay app will open with the request for payment.
    • If the customer is on a phone with the app installed, they get an automatic switch over to the Vipps/MobilePay app.
    • Otherwise, the Vipps/MobilePay landing page will open and they enter their phone number.
  4. Customer confirms the payment in the app
  5. The merchant's shop confirms the order
  6. The merchant completes the order and shipping
  7. The merchant captures the payment

In a physical store, you need the customer's phone number before creating the payment request. See Personal QR and One-time payment QR for the in-person alternatives.

Authorization​

All ePayment API requests must include a valid Bearer token in the Authorization header. See Authorization for how to obtain one.

Request​

Create the payment with POST:/epayment/v1/payments. Specify "userFlow": "WEB_REDIRECT" and a returnUrl.

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 "Idempotency-Key: YOUR-IDEMPOTENCY-KEY" \
-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": 49900
  },
  "paymentMethod": {
    "type": "WALLET"
  },
  "reference": "acme-shop-123-order123abc",
  "returnUrl": "https://example.com/redirect?reference=acme-shop-123-order123abc",
  "userFlow": "WEB_REDIRECT",
  "paymentDescription": "One pair of socks"
}'

WEB_REDIRECT handles the app switch for you, with the landing page as fallback when the app is not installed. The response contains a redirectUrl. Send the customer to that URL to start the payment. When the payment session ends, the customer is returned to your returnUrl.

See userFlow for the other options, such as PUSH_MESSAGE, which sends the request straight to a phone number you already have.

To determine that the user has authorized the payment, get notifications via the Webhooks API and/or poll for the status, according to the polling guidelines.

Once the order is ready to ship, capture the payment.

Sequence diagram​

Standard online payment flow

  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).
Last updated on