Set up a custom QR domain

A QR domain is a hostname you control, such as qr.example.com, that your QR stickers encode. Once it is ready, Ivora answers every scan on it and sends the driver to the charger's current checkout: your previous platform until the charger moves, Ivora checkout once it has moved. See QR sticker redirects for the settings, the sticker import and how scans follow each charger's move.

Before you start

• Save your QR settings and import your stickers. A ready QR domain answers scans as soon as it is active, settings or not.
• Choose a hostname that serves nothing else. Ivora serves only sticker scans on it: GET and HEAD requests for the bare hostname (the find-your-charger page) or a path a sticker can encode.
• A hostname serves one purpose: OCPP, payment, QR or return. Registering it for a second purpose is refused (409) until you disable the first.
• Changes need stations:write (a tenant administrator); reads need stations:read.

Other methods, and paths no sticker encodes (/.well-known/…, /favicon.ico, /robots.txt, paths over 300 characters), answer 404.

1. Register the hostname

POST /v1/tenants/{tenant_id}/qr-domains
Content-Type: application/json

{"hostname": "qr.example.com"}

The request is idempotent by tenant and hostname. The response (201 Created) lists the two DNS records the domain needs and the URL your stickers encode:

{
  "id": "dom_3f0c...",
  "purpose": "qr",
  "hostname": "qr.example.com",
  "status": "pending_dns",
  "ready": false,
  "scan_url_template": "https://qr.example.com/{code}",
  "dns_records": [
    {"type": "CNAME", "name": "qr.example.com", "value": "ocpp-edge.ivoracharge.com", "ttl": 300, "proxied": false},
    {"type": "TXT", "name": "_ivora-qr.qr.example.com", "value": "ivora-qr-verification=<generated token>", "ttl": 300}
  ]
}

Show both records to whoever manages your DNS exactly as returned. Always take them from the response, never from this page.

2. Add the two records

ocpp-edge.ivoracharge.com is Ivora's DNS-only name for the production edge, the same target as custom OCPP domains. Point the CNAME at it directly, not through another name of yours. An A record to the address it resolves to does not verify: if the edge address changes, Ivora updates that one name and your CNAME keeps working.

• Editors that append your zone automatically use qr and _ivora-qr.qr as the names.
• Keep the address record DNS only: a record proxied by a CDN does not verify, because Ivora issues the hostname's certificate itself.
• Keep both records for as long as you use the domain. Ivora rechecks them every 15 minutes; a domain whose records stop checking out stops answering scans until they do.
• Certificate issuance needs public port 80 to reach Ivora (only the certificate challenge is served over HTTP) and any CAA records on your zone to allow Let's Encrypt.

3. Check DNS

POST /v1/tenants/{tenant_id}/qr-domains/{domain_id}/verify

checks reports each record: {"address": true, "ownership": true} once both are published, and the status moves to dns_verified. Check again at most every 15 seconds (429 otherwise); DNS changes can take longer than that to appear.

dns_verified does not mean scans work yet. Ivora then issues the hostname's certificate, normally within 15 minutes, and the domain becomes active with ready: true. Read it with GET /v1/tenants/{tenant_id}/qr-domains/{domain_id}.

activation_error explains an activation that needs attention; contact Ivora support if it stays set.

4. Test a sticker

Before you rely on the domain, check a sticker without counting a scan:

GET /v1/tenants/{tenant_id}/qr/resolve?code=C-1042

Then scan a real sticker, or open https://qr.example.com/C-1042. A charger that has moved to Ivora answers 302 to its Ivora checkout page; one that has not answers 302 to your previous platform. A code Ivora does not know shows the find-your-charger page in your brand. Redirects are never permanent, so phones never keep an old destination after a move.

Print new stickers on it

Make the domain your project's qr_domain (PATCH /v1/tenants/{tenant_id} with {"qr_domain": "qr.example.com"}, see Project default domains). The project's sticker_url_template is then https://qr.example.com/{station_name}: new stickers keep working when you later change payment domains, and each scan follows the charger's move as above.

Disable a domain

DELETE /v1/tenants/{tenant_id}/qr-domains/{domain_id} stops scans at once. Your imported stickers and DNS records stay in place. While the domain is the project's qr_domain, the request needs ?confirm=true (Removing a default domain). Registering the hostname again starts over with a new ownership token.

In production, a QR domain that is disabled or not ready (DNS not rechecked within 24 hours, an expired certificate) answers every scan 404.

Troubleshooting