Search documentation

Find pages, endpoints, parameters, and guides.

How to verify your callback domain

View as Markdown

CryptAPI only creates new payment addresses for callback URLs on a verified domain. You verify each domain once, on our Verify Domain page, by proving you control it with a DNS TXT record or an HTTPS file. There is no account to create.

If the domain of your callback isn't verified, the create endpoint answers HTTP 400:

JSON
{
  "status": "error",
  "error": "Please verify your domain before using our service: https://cryptapi.io/verify_domain/"
}

Payment addresses you already created keep working. Any new payment address, for example one per order or one for another cryptocurrency, needs a callback URL on a verified domain.

Which domain to verify

Verify the host of your callback URL. For https://shop.example.com/webhook?order_id=123, that is shop.example.com. The port and the path don't matter, and if you paste a whole URL into the page, it keeps only the host.

  • Verifying example.com by DNS also covers its subdomains, such as shop.example.com and api.example.com.
  • Verifying by HTTPS file covers that exact host only.
  • example.com and www.example.com are different hosts. If your callback URLs use www.example.com, verify example.com by DNS, which covers both, or verify www.example.com itself.
  • On a shared hosting domain, such as up.railway.app or herokuapp.com, verify your app's own host (myapp.up.railway.app), usually with the HTTPS file.
  • IP addresses can't be verified on the page. Contact support instead.
  • If you use one of our plugins, your callbacks go to your store, so verify your store's domain.

Step 1: Get your verification value

  1. Go to the Verify Domain page.
  2. Enter your domain, for example example.com.
  3. Complete the captcha and click Get instructions.

The page shows a value like cryptapi-verification=3f9c0a1b2c3d4e5f60718293a4b5c6d7. It never changes for a domain, so you can come back later and get the same one. If the domain is already verified, the page says so and you can skip the next steps. The page checks only the name you enter: a subdomain of a domain you verified by DNS shows as not verified, but its callback URLs already work.

Step 2: Publish the value

Choose one of the two methods.

DNS TXT record (covers subdomains)

Add a TXT record to your domain's DNS:

  • Name: the domain itself, for example example.com. Many DNS panels write the domain itself as @, and a subdomain such as shop.example.com as just shop.
  • Value: the whole value from Step 1, cryptapi-verification=… included.

The record must be on the domain itself. A subdomain that is a CNAME can't hold a TXT record, so verify its parent domain by DNS instead, or verify the subdomain with the HTTPS file. DNS changes can take a while to reach everyone.

HTTPS file (this host only)

Use this when you can't edit the domain's DNS, for example on a hosting platform's subdomain. Serve the value as the whole content of this file on your site:

text
https://example.com/.well-known/cryptapi-verification.txt

The file must:

  • answer over HTTPS on the standard port (443), with a valid certificate, with status 200, within 5 seconds;
  • answer without a redirect, for example to www. or to another path;
  • be served uncompressed, so turn off gzip or Brotli for this file;
  • hold only the value (a trailing new line is fine), at most 1 KB.

Step 3: Verify

Back on the page, open the tab of the method you used (DNS TXT record or HTTPS file), complete the captcha and click Verify. Once the domain is verified, you can create payment addresses with callback URLs on it.

To extend a domain you verified by file to its subdomains, add the TXT record from Step 2. Then, with the domain shown on the page (enter it and click Get instructions again if needed), complete the captcha and click Verify by DNS.

If verification fails

The page says what went wrong:

  • TXT record … not found on example.com: the record isn't visible yet, it's on another name, or the name is a CNAME. Check the name and the value, wait for the DNS change to spread, then try again.
  • DNS lookup failed for example.com: the lookup itself failed. Try again later.
  • … must answer 200 with … as its content, without a redirect: the file is missing, holds something else, redirects or is served compressed, or a firewall or bot protection (such as Cloudflare's) answers instead of your site.
  • Could not fetch …: CryptAPI couldn't fetch the file, for example because your site is offline, too slow, or its certificate isn't valid.
  • Many sites share …, so it can't be verified: you entered a name many sites share, such as co.uk or the shared hosting domain up.railway.app. Enter your own domain or host under it instead.
  • Enter the punycode (xn--) form of this domain: for some international domain names, enter the xn-- form of the name, and use that same xn-- form in your callback URLs.

If you're still stuck, contact support.