Docs

Setting up a Custom Domain 

When your customer hits cancel, we'll redirect them to a cancel page hosted on Chargebee Retention. Make it look and feel like they are never leaving your site by setting up a custom domain with a CNAME. When the Chargebee Retention cancel page loads, the URL that appears in the browser will contain the custom domain you specify, instead of retention.chargebee.com.

Steps to set up your custom domain 

  1. Go to Settings > Custom Domain
  2. Enter the custom domain you'd like to use for your cancel page, like cancel.example.com.
  3. Create a CNAME record. See the section Setting up your CNAME below for more details.
  4. After creating a CNAME, click "Submit for verification." Chargebee Retention will be performing various checks to ensure your custom domain is ready to use. You will receive an email confirmation when the custom domain is ready to use.
  5. Go back to Settings > Custom Domain. Update the toggle to Active to start using the custom domain.

You may receive an error at step 4 after clicking "Submit for verification." Please refer to the Custom Domain Verification Errors section below to understand the possible errors and resolution.

Setting up your CNAME 

We'll need to work together to make sure your Cancel Page is secure by setting up SSL. As for your part, you'll need to create a new CNAME record with your DNS provider. A CNAME record tells computers that when someone types in your custom domain (e.g. cancel.example.com) that you want it to actually reach out to the Brightback page site address custom.prod.brightback.com.

When you create the CNAME in your DNS, you'll be prompted to insert a host name or subdomain. Continuing with the example above, cancel would be the subdomain.

You'll also be asked to add a destination. For this value, that's where you enter custom.prod.brightback.com.

In other words, we're simply setting up a rule that says: If a customer visits cancel.example.com, they should see the page located at custom.prod.brightback.com.

Here are some links to some popular DNS help pages on adding a CNAME to point you in the right direction. If you're using a different DNS, let us know and we'll be happy to help you find the right instructions to make sure you're in the right place!

Note

Once you save the CNAME, it can take up to 24 hours to propagate and properly point to Brightback, but changes may take effect in as little as an hour. If you see any TTL settings when setting up your CNAME, set those as 300s.

Frequently Asked Questions 

What is a CAA record?

"CAA records allow domain owners to declare which certificate authorities are allowed to issue a certificate for a domain. They also provide a means of indicating notification rules in case someone requests a certificate from an unauthorized certificate authority. If no CAA record is present, any CA is allowed to issue a certificate for the domain. If a CAA record is present, only the CAs listed in the record(s) are allowed to issue certificates for that hostname.

CAA records can set policy for the entire domain or for specific hostnames. CAA records are also inherited by subdomains. For example, a CAA record set on example.com also applies to any subdomain, like subdomain.example.com (unless overridden). CAA records can control the issuance of single-name certificates, wildcard certificates, or both."[1]

1 https://support.dnsimple.com/articles/caa-record/

How do I tell if my domain is configured to use a CAA record?

You can use any number of DNS lookup tools to search for the CAA record of your domain (if one exists). Below is an example using the CLI tool dig:

$ dig +noall +answer example.com caa 
example.com.        1800    IN  CAA 0 issue "digicert.com"

If the response is empty, stop here! You're good to go. If the results of the domain lookup include issue along with the name of a certificate authority, then your domain is configured with CAA protection. If the issuer is a certificate authority other than letsencrypt.org, you'll need to take additional action in order to use a vanity domain with Chargebee Retention.

What do I need to do if my domain is configured with a CAA record?

If you have created a Certificate Authority Authorization (CAA) record for your domain, you'll need to perform one of the following steps in order to use a vanity domain with Brightback:

  1. Amend the CAA record in domain root to include LetsEncrypt.

  2. Google Domains: Create or edit a resource record with Google Domains

  3. GoDaddy: Change a CAA record

example.com.        1800    IN  CAA 0 issue "letsencrypt.org"

The vanity domain would then be an equivalent to cancel.example.com.

OR

  1. Create a new subzone containing the CAA record, which will contain the CNAME record that points to custom.prod.brightback.com.
subzone.example.com.        1800    IN  CAA 0 issue "letsencrypt.org"

In this example, your vanity domain would end up being configured as . . . , i.e. cancel.subzone.example.com.

Additional reading

https://letsencrypt.org/docs/caa/

Custom Domain Verification Errors 

Within the Chargebee Retention settings page, you may encounter an error after submitting a CNAME for verification. The following table outlines the types of errors that may arise.

More details on errors can also be found in the Activity Log and in the email sent when an error occurs.

Error

Description

CNAME/CAA step incomplete

Error occurred when verifying the CNAME/CAA step. Please ensure this step is completed before submitting for verification.

Healthcheck failed

For the first 2 errors, you will need to take action to resolve the error. For the other errors, please reach out to retention-support@chargebee.com for assistance.

  • certificate_expired : Custom domain was set up properly and working. After few months, the certificate expired and is no longer valid. You will need to renew the certificate.
  • uri_syntax_exception : Wrong custom domain URL format such as entering the URL with only "http://" or the sample URL "http://cancel.example.com." Enter a valid URL and try again.
  • connect_timeout : Connection timed out when performing healthcheck
  • io_exception : Error occurred with SSL handshake during the connection process
  • non_200_status : Server responded with a non 200 status
  • expected_certificate_authority_not_found : Certificates do not have LetsEncrypt as issuer
Was this article helpful?
Loading…