> **Description:** Visual walkthrough of the Express flow for PSPs using card passthrough with the ePayment API. > **AI agent:** Read [https://developer.vippsmobilepay.com/docs/knowledge-base/ai-tools.md](https://developer.vippsmobilepay.com/docs/knowledge-base/ai-tools.md) first. It covers keeping API keys and secrets out of generated code. > **Full site overview:** For an overview of the entire site, read [https://developer.vippsmobilepay.com/llms.txt](https://developer.vippsmobilepay.com/llms.txt). # How the ePayment PSP API works with Express Express extends the [Online flow](https://developer.vippsmobilepay.com/docs/APIs/psp-epayment-api/how-it-works/online-psp.md) with built-in shipping selection directly in the Vipps MobilePay app, using `CARD_PASSTHROUGH` with the ePayment API. The customer goes from the Express button to a finished payment without leaving the app: 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. The steps below describe each of these in turn. ## 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](https://developer.vippsmobilepay.com/docs/knowledge-base/widget.md) 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`](https://developer.vippsmobilepay.com/redocusaurus/epayment-swagger-id.yaml). The request includes: * `paymentMethod.type` set to `CARD_PASSTHROUGH` * [`psp`](https://developer.vippsmobilepay.com/docs/APIs/psp-epayment-api/epayment-psp-api-guide.md#psp) object with the PSP's server URL specified in the `callbackUrl` field * `profile.scope` must include `address`. Also include every other scope you need to deliver the order, usually `name email phoneNumber address`. * `shipping.fixedOptions` or `shipping.dynamicOptions` with available shipping methods See [API guide: Create an Express payment](https://developer.vippsmobilepay.com/docs/APIs/psp-epayment-api/epayment-psp-api-guide.md#create-an-express-payment) for the full request example and required parameters. ### 3. Customer opens the Vipps/MobilePay app The [Widget SDK](https://developer.vippsmobilepay.com/docs/knowledge-base/widget.md) 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 address with the merchant. ### 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. For shipping option configuration, including fixed vs. dynamic options, see [Shipping options](https://developer.vippsmobilepay.com/docs/APIs/epayment-api/api-guide/features/express.md#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. The merchant learns the outcome from webhooks and polling The merchant's system has no visibility into what happens in the app, so a webhook is how it learns that the payment will not be completed: * `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. On either event, the merchant's system discards the pending order, including the shipping selection made in the app. No card callback follows, and the flow ends here. Register the webhook before creating the payment, so no event is missed while the customer is paying. See [Webhooks](https://developer.vippsmobilepay.com/docs/APIs/psp-epayment-api/epayment-psp-api-guide.md#webhooks) for what to register as a PSP and how to handle the events. ### 8. 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 `psp.callbackUrl`. ### 9. The PSP processes the payment and responds to the card callback The PSP processes the payment through its own acquiring infrastructure using the card token, then responds to the callback within 20 seconds. See [Card callback](https://developer.vippsmobilepay.com/docs/APIs/psp-epayment-api/epayment-psp-api-guide.md#card-callback) for the request format, HMAC authentication, and expected response. A `RESERVE` response reserves the amount for a later capture; it does not move the money. The payment is now authorized, and the merchant's system can confirm this through the `epayments.payment.authorized.v1` webhook. ### 10. The PSP receives the shipping details The PSP retrieves the shipping details and profile information by calling [`GET:/epayment/v1/payments/{reference}`](https://developer.vippsmobilepay.com/redocusaurus/epayment-swagger-id.yaml) with the `Psp-Id` header, or from the [ePayment webhook payload](https://developer.vippsmobilepay.com/docs/APIs/epayment-api/api-guide/webhooks.md#webhook-payload). ### 11. The merchant completes the order and shipping The merchant uses the provided address and shipping preferences to fulfill and ship the order. ### 12. The PSP captures the payment The PSP captures the payment in its own systems. It then sends a capture request to the ePayment API, which does not move any money; it only tells Vipps MobilePay to update the status so the customer sees the payment as captured in their app. Refunds and cancellations use the same endpoints, but happen later and only if something goes wrong. See [Update payment status](https://developer.vippsmobilepay.com/docs/APIs/psp-epayment-api/epayment-psp-api-guide.md#update-payment-status). ## Sequence diagram Express flow for PSPs ```mermaid sequenceDiagram autonumber actor C as Customer participant PSP as Merchant/PSP participant ePayment as ePayment API participant Webhooks as Webhooks API C->>PSP: Click the Express button PSP->>ePayment: Create an Express payment with CARD_PASSTHROUGH and shipping options ePayment-->>PSP: redirectUrl and payment reference PSP->>C: Handle app switch with redirectUrl (tip: use Widget SDK) ePayment->>C: Request the payment in the Vipps/MobilePay app C->>ePayment: Share the address, select a shipping option, and confirm the total amount Webhooks-->>PSP: Webhook: the payment was aborted or expired PSP->>ePayment: Poll for payment info, as a backup if the webhook is delayed or missed ePayment-->>PSP: Current state of the payment, with shippingDetails and userDetails alt The payment was aborted or expired PSP->>C: Return the customer to the page they started from else The customer accepted the payment ePayment->>PSP: Card callback with the card token Note over PSP: Process the payment in its own acquiring systems PSP-->>ePayment: Respond to the callback with RESERVE within 20 seconds PSP->>ePayment: Get the shipping details and profile information PSP->>C: Fulfill and ship the order PSP->>ePayment: Send the capture status so the app shows it as captured end ``` Customer clicks the Express button. PSP creates an Express payment via the ePayment API with card passthrough and shipping options. ePayment API returns a redirectUrl and payment reference to the PSP. PSP handles the app switch with the redirectUrl. We recommend using the Widget SDK for this. ePayment API requests the payment in the customer's Vipps or MobilePay app. Customer shares their address, selects a shipping option, and confirms the total amount. Webhooks API sends the merchant's system an aborted or expired event if the customer does not accept the payment. Merchant's system gets the payment from the ePayment API, as a backup if the webhook is delayed or missed. ePayment API returns the current state of the payment, including the shipping details and the user details. If the payment was aborted or expired, the merchant returns the customer to the page they started from, and the flow ends. If the customer accepts the payment, the ePayment API sends the card token to the PSP's card callback URL. PSP processes the payment in its own acquiring systems and responds to the callback with a reserve status within 20 seconds. PSP gets the shipping details and profile information from the ePayment API. PSP fulfills and ships the order. PSP sends the capture status to the ePayment API, so the customer sees it as captured in the app. For a more detailed sequence diagram that includes dynamic shipping methods, see [Express API guide: Sequence diagram](https://developer.vippsmobilepay.com/docs/APIs/epayment-api/api-guide/features/express.md#sequence-diagram). ## Limitations Express has country and currency restrictions that apply the same way for PSPs as for direct merchants. See [Limitations](https://developer.vippsmobilepay.com/docs/APIs/epayment-api/api-guide/features/express.md#limitations). ## More information See [API guide: Create an Express payment](https://developer.vippsmobilepay.com/docs/APIs/psp-epayment-api/epayment-psp-api-guide.md#create-an-express-payment) for more details.