# `Worldpay.HPP`
[🔗](https://github.com/iamkanishka/worldpay/blob/v1.0.0/lib/worldpay/access/partner.ex#L272)

Worldpay **Hosted Payment Page (HPP)** API — hosted checkout and pay-by-link.

Generates HPP session URLs and pay-by-link URLs. The customer is redirected
to a Worldpay-hosted page to complete payment, keeping merchants fully
out of PCI scope (SAQ A).

## Integration modes

- **Redirect** — customer redirected from your site to HPP
- **Lightbox / iFrame** — HPP embedded in your checkout page
- **Pay-by-link** — shareable URL sent by email/SMS

## Example

    {:ok, session} = Worldpay.HPP.create_session(%{
      "merchant" => %{"entity" => "default"},
      "instruction" => %{
        "value" => %{"amount" => 1999, "currency" => "GBP"},
        "narrative" => %{"line1" => "My Store"}
      },
      "resultUrls" => %{
        "successUrl" => "https://example.com/success",
        "failureUrl" => "https://example.com/failure",
        "cancelUrl" => "https://example.com/cancel"
      },
      "expiry" => "PT1H"
    }, config)

    redirect_url = session["_links"]["hpp:js"]["href"]
    # Redirect customer to redirect_url

# `create_session`

```elixir
@spec create_session(map(), Worldpay.Config.t()) ::
  {:ok, map()} | {:error, Worldpay.Error.t()}
```

Create an HPP session (redirect / lightbox / pay-by-link).

## Key body fields

- `instruction.value` — amount + currency (required)
- `instruction.narrative` — statement descriptor
- `resultUrls` — successUrl, failureUrl, cancelUrl
- `expiry` — ISO 8601 duration e.g. `"PT1H"` (1 hour); for pay-by-link
- `locale` — language/locale e.g. `"en-GB"`, `"fr-FR"`
- `hostedCustomization` — CSS property overrides
- `hostedProperties` — HPP feature flags
- `cancelOn.cvcNotMatched` — boolean (auto-cancel if CVC fails)
- `orderReference` — merchant order reference

# `customization`

```elixir
@spec customization(keyword()) :: %{required(String.t()) => term()}
```

Build HPP customization options for `hostedCustomization` field.

## Options

- `:background_color` — CSS color value
- `:button_color` — primary button color
- `:font_family` — CSS font family
- `:logo_url` — URL to merchant logo
- `:header_text` — checkout page header text

# `get_session`

```elixir
@spec get_session(String.t(), Worldpay.Config.t()) ::
  {:ok, map()} | {:error, Worldpay.Error.t()}
```

Retrieve an HPP session.

# `pay_by_link`

```elixir
@spec pay_by_link(map(), Worldpay.Config.t(), keyword()) ::
  {:ok, String.t()} | {:error, Worldpay.Error.t()}
```

Create a pay-by-link URL.

Sets a long expiry duration so the link can be shared via email/SMS.
Returns the shareable URL from the response's `_links.hpp:payByLink.href`.

## Options

- `:expiry` — ISO 8601 duration (default `"P7D"` — 7 days)
- `:locale` — language e.g. `"en-GB"`

# `properties`

```elixir
@spec properties(keyword()) :: %{required(String.t()) => term()}
```

Build HPP properties flags for `hostedProperties` field.

## Options (all boolean)

- `:save_card` — show save card option (default false)
- `:billing_address` — collect billing address
- `:shipping_address` — collect shipping address
- `:customer_email` — collect customer email
- `:show_order_summary` — show order line items

---

*Consult [api-reference.md](api-reference.md) for complete listing*