Hostnames & DNS conventions

Use this page as the canonical list of first-party hostnames and how they relate to deploy environment variables. Generic examples elsewhere (yourcompany.com, example.com) illustrate the same roles under your own DNS zone.

---

Reference: *.payment-gateway.app (hosted stack)

The hosted platform uses a fixed subdomain layout. Each hostname maps to the payment-gateway-reverseproxy/Caddyfile site block driven by the corresponding variable in Docker Compose / Podman deploy:

[!IMPORTANT] Do not point provider webhook URLs or browser checkout runtime traffic at api.payment-gateway.app. Webhooks and public checkout APIs for the hosted stack belong on webhook.payment-gateway.app (MAIN_BACKEND_DOMAIN).

Sandbox / test tiers often use parallel names (for example test-api.payment-gateway.app for the Admin API). Use the hostnames your operator gives you for that environment.

Merchant custom domains (buyer-facing checkout on the merchant’s own DNS) are additional hostnames, verified in the Admin Panel and typically served via on-demand TLS when the merchant hostname reaches the gateway origin directly — see Caddy reverse proxy.

[!IMPORTANT] Custom domains are frequently part of payment-provider compliance, not just branding. Providers may require your checkout pages, callback URLs, and webhook endpoints to remain on domains you own and control.

Cloudflare proxy caveat for merchant custom domains

If MAIN_FRONTEND_DOMAIN or MAIN_BACKEND_DOMAIN is itself routed through Cloudflare with Proxy status = Proxied, a customer hostname that CNAMEs to that proxied target may fail TLS at Cloudflare before the request ever reaches your reverse proxy.

This usually shows up as browser TLS failures such as ERR_SSL_VERSION_OR_CIPHER_MISMATCH while the origin logs show little or no traffic for that hostname. The reason is architectural: Cloudflare is the TLS edge for the proxied hostname, so it needs a certificate for the customer hostname before it can forward anything to origin.

For environments that onboard arbitrary merchant domains, use one of these models:

• Direct-to-origin model: keep the merchant-facing target hostname DNS only so the request reaches the reverse proxy and origin-managed certificate flow can complete.
• Cloudflare edge-managed model: enable Cloudflare for SaaS / Custom Hostnames and provision each merchant hostname in Cloudflare before sending traffic through the proxy.

Cloudflare reference: Create custom hostnames.

---

Self-hosted naming pattern

On your own infrastructure you assign DNS under your zone. Typical choices mirror the hosted layout:

Variable names and a worked example.com table: Self-Hosted Installation. Routing and /v1 rewrites: Caddy reverse proxy. Integration order (webhooks → API key → checkout → IPN): Server integration checklist.

---

Licensing, registry, and operator portal

These endpoints are for operators, image pulls, and license activation — not for merchant Admin API or checkout traffic:

Self-hosted stacks need outbound HTTPS to these services (and the license portal) to pull images and complete activation — see Self-Hosted Installation.