Custom Hosted Handoff Domains

Custom hosted handoff domains let you show Proxy payment handoff links on a subdomain you control, such as pay.example.com, instead of pay.proxycheckout.com.

Production only

Custom hosted handoff domains are production-only in V1. Sandbox and test-mode handoff links continue to use pay.proxycheckout.com.

How It Works

Proxy gives you a dedicated CNAME target for each custom handoff domain.

pay.example.com CNAME hdom-q8f3k2m9.customers.pay.proxycheckout.com

Use DNS-only CNAME records

Proxy verifies the public DNS CNAME chain for your hostname. It does not read your DNS provider’s dashboard or API configuration.

If you use Cloudflare, the CNAME must be DNS-only / gray-clouded before you click Check status. Proxied / orange-cloud CNAME records may fail status checks because Cloudflare flattens or hides the origin target from public DNS. The same requirement applies to any DNS or CDN provider that proxies, flattens, or hides CNAME targets.

Keep the record DNS-only after activation unless Proxy documents support for a different validation or proxying path.

After your DNS-only record is visible in public DNS, use Check status in the dashboard. Proxy verifies that your CNAME chain reaches the assigned target, asks CloudFront to issue and manage the TLS certificate, activates the hostname when CloudFront reports it active, and then starts returning that host in new hosted handoff URLs.

Existing handoff sessions are merchant-bound, not host-bound. A valid session can still be opened through pay.proxycheckout.com or through any active verified custom handoff domain for the same merchant.

Set Up a Domain

1. Open Custom domains in the Proxy dashboard.
2. Add the production subdomain you want payers to see, such as pay.example.com. Do not use an apex domain such as example.com; V1 uses CNAME-based subdomains.
3. Copy the CNAME target shown by Proxy.
4. Create a DNS-only, unproxied CNAME record in your DNS provider. In Cloudflare, this means the record must be gray-clouded, not orange-clouded.
5. Click Check status after the DNS-only CNAME has propagated publicly.
6. Set the verified domain as the default hosted handoff domain.

When a verified custom domain is default, sessions.createHandoff returns a handoffUrl on that domain:

const handoff = await proxy.sessions.createHandoff({
  amountMinor: 5000,
  buyerReference: "buyer_123",
  cartSnapshot,
  currency: "usd",
});

console.log(handoff.handoffUrl);
// https://pay.example.com/s/psess_...?pk=pk_live_...

Roll Back

Click Use Proxy host for the current default custom domain in the dashboard to make new hosted handoff sessions use https://pay.proxycheckout.com again.

Previously created sessions remain valid until their normal expiration. If the custom domain is still active, those links may still open on the custom host.

Security Boundaries

Custom domains only change the payer-visible host for the hosted handoff page. They do not:

• authorize payment operations;
• change the merchant for a session;
• change cart contents, amount, currency, or PSP routing;
• broaden allowed forwarding destinations;
• hide the public publishable key in V1 hosted handoff URLs.

Proxy still authorizes hosted handoff reads with the publishable key, session ID, session TTL, merchant ownership, and verified host ownership.