Skip to main content

How the ePayment PSP API works with Express

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

Express extends the Online flow with built-in shipping selection directly in the Vipps MobilePay app, using CARD_PASSTHROUGH with the ePayment API.

Details​

1. Customer clicks the Express button​

On a merchant's website or app, the customer sees an Express button on the product page or in the shopping cart.

Screenshot: Online merchant product page showing an Express button (Vipps or MobilePay) alongside the standard checkout options.

Tip

Use the Widget SDK to render the button. The SDK serves its appearance, so it always reflects the current design guidelines and the correct brand for your market.

2. The PSP creates an Express payment request​

When the customer clicks the Express button, the PSP creates an Express payment request with POST:/epayment/v1/payments.

The request includes:

  • paymentMethod.type set to CARD_PASSTHROUGH
  • cardPassthrough object with the PSP's server URL specified in the cardCallbackUrl field
  • profile.scope must include address
  • shipping.fixedOptions or shipping.dynamicOptions with available shipping methods

See API guide: Create an Express payment for the full request example and required parameters.

3. Customer opens the Vipps/MobilePay app​

The Widget SDK handles the transition from the website to the Vipps or MobilePay app automatically.

If the payment was started on 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.

4. Customer consents to share profile information​

Before seeing the payment amount, the customer consents to sharing their name, address, phone number, and email with the merchant.

Two-screen profile-sharing flow in the app (Vipps or MobilePay): Left — "Information you share" consent screen with a Share information button. Right — payment screen with a Pay button.

5. Customer selects their shipping option​

The customer sees the available shipping options and can view or change their delivery address, and select from the available shipping methods.

Four-screen Express flow (Vipps or MobilePay): (1) Product page with Express button. (2) Information sharing consent screen. (3) Delivery options with pick-up point and home delivery choices. (4) Payment summary with card and delivery selection.

For shipping option configuration, including fixed vs. dynamic options, see Shipping options.

6. Customer confirms the total payment amount​

Once the customer has selected their shipping option, the total amount (product price + shipping cost) is displayed. The customer reviews the final amount and confirms the payment.

7. Vipps MobilePay sends the card token to the PSP​

When the customer confirms the payment and selects their card, Vipps MobilePay sends a card token to the PSP's cardCallbackUrl. The PSP must respond within 20 seconds. See Card callback for the request format, HMAC authentication, and expected response.

8. The PSP processes the payment and receives the shipping details​

The PSP processes the payment through its own acquiring infrastructure using the card token, then retrieves the shipping details and profile information by calling GET:/epayment/v1/payments/{reference} with the Psp-Id header, or from the ePayment webhook payload.

9. The merchant completes the order and shipping​

The merchant uses the provided address and shipping preferences to fulfill and ship the order.

10. The PSP updates the payment status​

The PSP captures, refunds, or cancels the payment via the ePayment API, keeping the Vipps MobilePay app status in sync. See Update payment status.

Limitations​

Express has country and currency restrictions that apply the same way for PSPs as for direct merchants. See Limitations.

More information​

See API guide: Create an Express payment for more details.

Last updated on