Skip to main content

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.

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.

App switch flow in Vipps

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

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