# Hosted integrations

Hosted integrations hand the payment over to GoPay's hosted gateway, which offers the customer every payment method the eshop has enabled. The gateway is a destination the customer is sent to — it cannot be embedded in the merchant's own checkout. A merchant who needs the payment step inside their own UI can use the checkout integration, which today covers card, Google Pay, Apple Pay and QR payments and is being extended to further methods; every method the eshop has enabled is already available here on the gateway. In a hosted integration, the customer is sent to the GoPay-hosted payment UX to choose a payment method and complete the payment. The merchant's code never collects card data, never handles a wallet payload, and never calls the charge endpoint.

## Flow

1. The merchant's server obtains a merchant access token with the `payment:write` scope. See the security page.
2. The merchant's server creates the payment with `POST /eshops/{goid}/payments`. The body is a `Payment Create Request`; `Payment Callback.return_url` must be supplied; `Payment Callback.notification_url` may be left out. See the payment lifecycle page.
3. The merchant's server reads `Payment Details.gw_url` from the response and uses it to send the customer to the gateway, as described below.
4. The customer is taken to the gateway, picks a payment method, and completes the payment. At the end, the customer's browser is redirected to `return_url` with the payment `id` (and `parent_id` for recurring children) as query parameters.
5. The merchant's server reacts to the `payments.*` event delivered as a webhook and re-fetches the payment with `GET /payments/{payment_id}` to learn the new state. The webhook is the authoritative trigger; the return-URL handling is for the customer-facing page. See the events and webhooks page.

The merchant should not call `POST /payments/{payment_id}/charge` for hosted payments. The hosted gateway charges the payment itself.

## Redirect

The customer's browser is sent to `Payment Details.gw_url` with a normal full-page navigation. The customer leaves the merchant's site for the duration of the payment and returns through `return_url`.

Three techniques are equivalent at the API level. The choice is a matter of how the merchant's server hands the URL to the browser.

- HTML link. The merchant's server renders a page containing `<a href="<gw_url>">…</a>`.
- HTTP redirection. The merchant's server returns a `302 Found` with `Location: <gw_url>`.
- Client-side JavaScript. The merchant's client receives `gw_url` from its server (for example through an AJAX call) and assigns it to `window.location`.

```html
<!-- HTML link -->
<a href="https://gate.gopay.com/gw/300000001">Pay</a>
```

```http
HTTP/1.1 302 Found
Location: https://gate.gopay.com/gw/300000001
```

## Hosted gateway in a mobile application

A merchant whose checkout runs inside a native mobile application should open `gw_url` in a system browser component — Chrome Custom Tabs on Android and `SFSafariViewController` on iOS. In-app web views (Android `WebView`, iOS `WKWebView`) do not run a full browser environment, so online banking redirects may not behave correctly. A merchant with a native checkout UI on mobile can use the checkout integration instead as far as it reaches — card, Google Pay, Apple Pay and QR today; anything beyond that still goes through `gw_url` in a system browser component.

## Sequence

```mermaid
sequenceDiagram
    autonumber
    participant MS as Merchant's server
    participant MC as Merchant's client
    participant GW as GoPay hosted gateway
    participant API as GoPay API

    MS->>API: POST /eshops/{goid}/payments
    API-->>MS: Payment Details (id, gw_url)
    MS->>MC: gw_url
    MC->>GW: open gw_url
    Note over MC,GW: customer picks a method and completes the payment
    GW-->>MC: return_url with id
    API-->>MS: webhook with payments.* event
    MS->>API: GET /payments/{id}
    API-->>MS: Payment Details (terminal state)
```
