> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dintero.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Hosted payment sessions

> Skip the Dintero Checkout and complete payment via the Vipps or MobilePay hosted payment page

If a payment session contains only Vipps or MobilePay, you can skip opening the Dintero Checkout and instead open the payment method's hosted payment page directly.

<Info>
  Testing hosted payments in the sandbox environment is only possible with the direct `vipps` integration or `dintero_psp.vipps`, so some testing will have to be done with real payments.
</Info>

## Creating a hosted payment session

Set `configuration.channel=hosted` for payment sessions that contain a single payment method.

**Request**

```json highlight={11-18} theme={null}
{
  "url": {
    "return_url": "http://merchant.com/handle_payment/ORDER123/return",
    "callback_url": "http://merchant.com/handle_payment/ORDER123/callback"
  },
  "order": {
    "amount": "500",
    "currency": "NOK",
    "merchant_reference": "ORDER123"
  },
  "configuration": {
    "channel": "hosted",
    "dintero_psp": {
      "vipps": {
        "enabled": true
      }
    }
  }
}
```

**Response**

```json theme={null}
{
  "id": "P12345678.55Q4CC1WuVJdgCssZfrf5a",
  "url": "https://pay.vipps.no/dwo-api-application/v1/deeplink/vippsgateway?v=2&token={vipps_token}"
}
```

Open the `url` in the end users devices to complete the payment.

<Warning>
  Do not embed the hosted `url` when opening it, so that the hosted page can act as a universal link and launch the Vipps or MobilePay app. Hosted payments are not compatible with embedding via the frontend `Dintero.Checkout.Web.SDK`.
</Warning>

### Payment finished or cancelled

After the user finishes or cancels the payment, they are returned to the `return_url`. Dintero appends the following query parameters:

| Name                | Description                        | Always present |
| ------------------- | ---------------------------------- | -------------- |
| transaction\_id     | The transaction ID for the payment | No             |
| session\_id         | The payment session ID             | No             |
| error               | Error code identifying the cause   | No             |
| merchant\_reference | The merchant reference             | Yes            |

## Fallback to the Dintero Checkout

If a session specifies `configuration.channel=hosted` but its payment method does not support hosted payments, or the session contains more than one payment method, the `url` returned on session creation opens the Dintero Checkout instead, where the user can complete their payment.

The url will also fall back to Dintero Checkout for [Checkout Express](/docs/checkout/express#what-is-checkout-express) sessions, so the end user can submit their shipping and billing information and select a shipping option before payment.

## Handling dangling browser tabs on mobile

On mobile devices, the hosted payment acts as a universal link and tries to open the payment directly in the payment method's native app (e.g. Vipps or MobilePay). If the app is not installed, the browser navigates to the hosted payment page instead.

When a payment app is opened via a universal link, the page the user was visiting remains open in the browser. After the payment completes, the `return_url` opens in a *new* browser tab, leaving the original page open as a dangling pending-payment page.

To handle this, we recommend one or both of the following:

* **Update the UI before redirecting.** Before opening the hosted payment link, change the payment page to show messaging that the user is being redirected to complete payment.
* **Re-check status on focus.** Add code that runs when the tab regains focus to check the payment session status. If the user returns to the dangling page, you can then update it to show that the payment completed, or prompt them to try again.