Worldpay.HPP (Worldpay v1.0.0)

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

Summary

Functions

create_session(body, config)

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

customization(opts \\ [])

Build HPP customization options for hostedCustomization field.

get_session(session_id, config)

Retrieve an HPP session.

pay_by_link(body, config, opts \\ [])

Create a pay-by-link URL.

properties(opts \\ [])

Build HPP properties flags for hostedProperties field.

Functions

create_session(body, config)

@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(opts \\ [])

@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(session_id, config)

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

Retrieve an HPP session.

pay_by_link(body, config, opts \\ [])

@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(opts \\ [])

@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