Custom Domains - SSL and DNS for Brand Checkouts

​

Domain pipeline

Request -> DomainMiddleware -> Resolve HTTP_HOST against op_domains -> Inject merchant_id
       -> DomainUrlService -> Build checkout/callback URLs under brand's custom domain
       -> BrandThemeService -> Load per-brand visual identity

​

How it works

​

DomainMiddleware

1. Resolves HTTP_HOST against op_domains table
2. Injects merchant_id, custom_domain, domain_type into request attributes
3. Blocks /admin/* on custom domains (returns 404)
4. Uses APP_DOMAIN env var to identify the master domain

​

DomainUrlService

• buildCheckoutUrl() - Checkout page URL
• buildCallbackUrl() - Gateway callback URL
• buildLegacyCallbackUrl() - Legacy callback URL

​

BrandThemeService

​

Configuration

​

Adding a custom domain

1. Go to System > Domains
2. Click Add Domain
3. Enter the domain (e.g., pay.yourdomain.com)
4. Configure DNS to point to your OwnPay server
5. Click Verify DNS
6. Set domain type to checkout

​

DNS requirements

​

Domain types

• checkout - Serves checkout, invoice, and payment pages
• api - Serves API endpoints only

​

Security rules

• Admin panel is only accessible on the master APP_DOMAIN
• /admin/* paths return 404 on custom domains
• Custom domains require dns_verified = 1 before serving content
• DNS verification failure returns 503

​

Important rules

• Never hardcode APP_URL or domain names for checkout/callback URLs
• Always use DomainUrlService methods for URL construction
• APP_DOMAIN must be a bare hostname (e.g., ownpay.test), not a full URL

​

Further reading

• Custom domain setup - Step-by-step guide to mapping and verifying a domain
• Brands - Understand how brands isolate data and configuration
• Troubleshooting domains - Fix common DNS and verification issues