Delegate your domain
Delegate a subdomain to Ginger, so your merchants reach the portals, the hosted payment page and the API on your domain.
Host your Ginger platform under a domain you control, such as gateway.example.com. You delegate a subdomain to Ginger, and Ginger runs the portals, the hosted payment page and the API on subdomains of it.
Recommended for every platform
Ginger is a white-label platform, built to stay in the background so your brand comes first. A custom domain keeps your merchants and their customers on your domain from the API to the checkout.
Once the domain is set up:
- Ginger creates the subdomains it needs under your domain, such as
api.gateway.example.comandtokens.gateway.example.com. - Your merchants reach every API and portal on these subdomains.
- Ginger issues the TLS certificates for the subdomains and renews them automatically.
Before you begin
- Access to the DNS of the parent domain, to add NS records.
- Check whether the parent domain has a CAA record. See CAA records.
Delegate the subdomain
Choose the subdomain
Pick the subdomain for your payment platform, typically something like online.example.com or gateway.example.com. Ginger creates its own subdomains under it, so choose one you don't use for anything else.
Send it to Ginger
Send the subdomain to your Ginger contact. Say whether you also want a CAA record and DNSSEC on it.
Add the NS records
When Ginger has set up the DNS zone for your subdomain, you receive the hostnames of four name servers. In the DNS of your parent domain, add an NS record for each of them, so these name servers become authoritative for the subdomain.
Check the delegation with dig. With the subdomain gateway.example.com, the answer lists the four name servers:
$ dig NS gateway.example.com +short
ns-101.awsdns-12.com.
ns-1202.awsdns-22.org.
ns-1803.awsdns-33.co.uk.
ns-704.awsdns-44.net.The values above are examples: use the hostnames Ginger sends you.
Tell Ginger
Tell your Ginger contact that the NS records are in place. Ginger completes the configuration of your platform and sends you the endpoints on your domain.
CAA records
A Certification Authority Authorization (CAA) record names the certificate authorities that may issue TLS certificates for a domain.
Your platform runs on AWS, and its certificates are issued by Amazon. Ginger can add a CAA record to the zone of your subdomain that only allows certificates issued by Amazon.
Off by default
Ask your Ginger contact to add the CAA record when you delegate the subdomain.
DNSSEC
DNSSEC (Domain Name System Security Extensions) signs the DNS records of your subdomain, which protects against forged responses and cache poisoning.
To enable it, Ginger sets up signing on the zone of your subdomain, and you complete the chain of trust in the DNS of your parent domain.
Off by default
DNSSEC is disabled by default. Ask your Ginger contact to enable it.
Troubleshooting
The certificate isn't issued
A CAA record on your parent domain can block the TLS certificates for your subdomain. Ginger tells you when this happens.
To fix it, choose one of these options:
- Recommended: add these certificate authorities to your CAA record, so Amazon can issue certificates for your domain:
amazon.com,amazontrust.com,awstrust.com,amazonaws.com. - Not recommended: remove the CAA record from your domain. Then any certificate authority can issue certificates for it.
More about CAA records
The AWS Certificate Manager documentation explains how CAA records work with Amazon certificates. A public CAA lookup tool shows which records your domain has.
Next steps
- Back to Set up your platform: connect your processor.
- Board your first merchant.