Hosted Handoff

Hosted handoff is the Proxy-hosted page a payer opens before Proxy sends them to your checkout. Configure it before creating handoff links so payers see your product name, a trusted destination, and a correct link preview in messages and social surfaces.

Required Settings

Open Hosted handoff in the dashboard and save:

Display name: the merchant, product, or app name shown to payers.
Default checkout URL: the default destination in your app where payers complete checkout.
Allowed destination hosts: the destination hostnames Proxy may forward payers to.

The default checkout URL hostname must be present in Allowed destination hosts. Proxy appends proxy_session_id to the URL when it forwards the payer.

Per-session checkout destinations

Most integrations should omit payerDestinationUrl when calling sessions.createHandoff. Proxy then forwards the payer to the default checkout URL configured in the dashboard.

An integration can provide payerDestinationUrl when the destination must vary for an individual payment, such as a preview deployment or multi-origin environment:

const handoff = await proxy.sessions.createHandoff({
  // ...
  payerDestinationUrl: "https://preview.example.com/checkout",
});

Proxy uses the override only for that session and accepts it only when its hostname matches Allowed destination hosts. Add every exact hostname your integration may provide, or use a supported wildcard such as *.example.com.

Link Preview

Hosted handoff links include preview metadata for apps such as iMessage, Slack, Discord, and social feeds.

Use these fields for the preview:

Field	Used for
Logo	The large image shown in message and social link previews.
Title	The preview title.
Description	The preview description.
Site name	The site or source label where supported.

Icon URL is separate. Proxy uses it for the browser tab icon, Apple touch icon, and the merchant mark on the hosted handoff page. It is not the link preview logo.

For broad preview compatibility, use a 1200 x 630 image when possible. Square images can work well for compact message previews, but social feeds usually expect the wide ratio.

Template Variables

Title and Description support these variables:

Variable	Example output
`{{merchant}}`	`Example Store`
`{{amount}}`	`$49.00`

Whitespace inside the braces is allowed, so {{ merchant }} and {{merchant}} are equivalent.

Complete your purchase with {{ merchant }}

{{ merchant }} requested {{ amount }}.

Unknown variables are left unchanged so mistakes are visible in the generated metadata.

Custom Domains

Hosted handoff links use https://pay.proxycheckout.com by default. For live merchants, you can add a production custom handoff domain such as pay.example.com.

See Custom Hosted Handoff Domains for DNS setup and activation.

Custom domains change only the payer-visible host. They do not change session authorization, checkout destination allowlists, PSP routing, or payment behavior.