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.

For steps in Cloudflare, GoDaddy, Namecheap or cPanel, see Add the TXT record at your DNS provider.

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.

For steps on WordPress, Nginx, Apache or behind Cloudflare, see Serve the file from your site.

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.

Add the TXT record at your DNS provider

Add the record where your domain's DNS is hosted, which may not be where you bought the domain. In every panel, paste the value as it is, without adding quotes. The steps below are for the domain itself (example.com).

Cloudflare

  1. Log in, then select your account and your domain.
  2. Go to DNS > Records and click Add record.
  3. Set Type to TXT, Name to @ and Content to your value. Leave TTL on Auto.
  4. Click Save.

TXT records are never proxied, so there is no proxy setting to change. For a subdomain, set Name to just the subdomain part, such as shop.

GoDaddy

  1. Sign in and open your Domain Portfolio.
  2. Select your domain, then open the DNS tab.
  3. Click Add New Record and choose TXT as the Type.
  4. Set Name to @ and Value to your value. Leave TTL as it is.
  5. Click Save.

If your domain has Domain Protection, GoDaddy asks for a code before it saves. For a subdomain, set Name to just the subdomain part, such as shop.

Namecheap

These steps work when your domain uses Namecheap's BasicDNS, PremiumDNS or FreeDNS. If it points to Namecheap hosting, use the cPanel steps below instead.

  1. Sign in and go to Domain List.
  2. Click Manage next to your domain, then open the Advanced DNS tab.
  3. Under Host Records, click Add New Record and choose TXT Record.
  4. Set Host to @ and Value to your value. Leave TTL on Automatic.
  5. Click the green check mark on the row to save it. If a Save all changes button shows, click it too.

For a subdomain, set Host to just the subdomain part, such as shop. Don't add your domain to it.

cPanel

  1. Log in to cPanel. In the Domains section, open Zone Editor.
  2. Click Manage next to your domain.
  3. Click the arrow next to Add Record and choose the TXT record.
  4. Set Name to your domain with a dot at the end, example.com., and Record to your value. Leave TTL as it is.
  5. Click Save Record.

For a subdomain, use its full name with a dot at the end, such as shop.example.com.. If you don't see Zone Editor, your host manages DNS for you: ask them to add the record.

Check the record

Once you've saved it, you can check that the record is live before you click Verify:

Bash
dig +short TXT example.com

The answer should include your value. Without dig, any online DNS lookup tool shows the same. If the value isn't there yet, wait a few minutes and try again.

Serve the file from your site

Whatever runs your site, the file goes in a folder named .well-known at the top of your site, so that it answers at https://example.com/.well-known/cryptapi-verification.txt. Check it in your browser before you click Verify: the page should show only your value.

WordPress or other shared hosting with cPanel

  1. In cPanel, open Files > File Manager.
  2. Folders whose names start with a dot are hidden at first. Click Settings at the top right, tick Show Hidden Files (dotfiles) and click Save.
  3. Open your site's folder: the one that holds wp-includes, which is public_html for your main domain.
  4. If there is no .well-known folder, click + Folder, name it .well-known and create it.
  5. Open .well-known, click + File, name it cryptapi-verification.txt and create it.
  6. Select the file, click Edit, paste your value and save.

WordPress needs no changes: its own rules let the server send any file that exists. If verification still fails because of compression or a redirect, add the Apache lines below.

Nginx

Add this to the server block that answers https://example.com, with your own value. You don't need to create a file:

nginx
location = /.well-known/cryptapi-verification.txt {
    gzip off;
    return 200 "cryptapi-verification=3f9c0a1b2c3d4e5f60718293a4b5c6d7";
}

If you use the Brotli module, add brotli off; to the block as well. Then reload Nginx.

A return 301 written directly in the server block, for example to send visitors to www., runs before any location and breaks the check. Move it into location / { … } so the block above can answer.

Apache

Create the file in your site's folder, at .well-known/cryptapi-verification.txt. Then add these lines to the .htaccess file in the same folder. Put them at the top, above # BEGIN WordPress and any redirect rules:

apache
<IfModule mod_setenvif.c>
  SetEnvIf Request_URI "^/\.well-known/cryptapi-verification\.txt$" no-gzip no-brotli
</IfModule>
<IfModule mod_rewrite.c>
  RewriteEngine On
  RewriteRule ^\.well-known/cryptapi-verification\.txt$ - [L]
</IfModule>

The first part turns off compression for this file. The second stops the rewrite rules below it, such as redirects to https:// or www., from touching it. A redirect written as Redirect or RedirectMatch isn't covered, so make sure it doesn't match this path.

Behind Cloudflare

If Cloudflare runs your domain's DNS, the TXT record is the easier method. If you use the file and your site is proxied through Cloudflare (orange cloud):

  • Compression: Cloudflare compresses text files. Go to Rules > Overview, click Create rule > Compression Rule, choose Custom filter expression and enter (http.request.uri.path eq "/.well-known/cryptapi-verification.txt"). Then choose Disable compression and click Deploy. Turn off compression on your server too, as above.
  • Bot protection: CryptAPI's check is not a browser, so it can't pass a challenge. Bot Fight Mode, on the Free plan, can't be skipped for one path, so turn it off while you verify. On paid plans, create a custom rule for the same path with the action Skip, and skip All Super Bot Fight Mode rules and Browser Integrity Check.

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.