Offer a Qevik identifier on your items

In short

1. 1

   Declare

   You declare your domain, your return address and your public keys. No account is needed.

2. 2

   Prove the domain

   You publish a verification file, and Qevik gives you a production client and a test client.

3. 3

   Integrate

   Your server calls the API, the buyer confirms, and you receive the QR code or System ID of each item.

What you need

• A domain reachable over https, where you can publish a file under /.well-known/.
• An https return address on that domain, declared exactly as used.
• One or two public ES256 keys (P-256, JWK format) for production, and up to two test keys, all distinct. The private keys stay with you.
• The operator's name and country of establishment.
• A contact address.
• Outside the European Union and countries recognised as adequate: acceptance of the standard contractual clauses.

Get your access

1. 1

   Fill in the declaration form and accept the merchant API terms.

2. 2

   Publish the file https://your-domain/.well-known/qevik-verification.txt: the value you received alone on a line, then one qevik-key= line per key.

3. 3

   Run the verification within 72 hours. The value is shown only once.

4. 4

   Keep your two identifiers: mrc_… for production and mrc_test_… for test. They do not work on the platform API.

A declaration carries the whole set of keys: adding or removing a key needs a new declaration. Codes to activate are requested in the same form and open after the domain is verified, sometimes with a short delay when many merchants sign up on the same day. Keep the verification file published: Qevik reads it regularly, and activation codes are withdrawn if it can no longer be read.

Authentication

Server-to-server authentication with private_key_jwt (ES256): you declare your public keys, Qevik stores no secret.

Each server-to-server call is signed with a JWT assertion: ES256 only, kid equal to the thumbprint of an active key of that environment, iss and sub equal to your client, aud equal to the exact URL called, exp at most 300 seconds ahead, jti unique.

// Header
{ "alg": "ES256", "kid": "<RFC 7638 thumbprint of an active key>" }

// Claims
{
  "iss": "mrc_YOUR_CLIENT_ID",
  "sub": "mrc_YOUR_CLIENT_ID",
  "aud": "https://qevik.com/api/v1/public/merchant/oauth/par",
  "exp": 1893456000,
  "jti": "a-unique-value"
}

Test environment

The mrc_test_… client uses its own keys and reaches only accounts Qevik marked as test accounts. Its items are never counted and cannot be found publicly. The System ID it receives is a fictitious alias starting with UTST, never a real identifier.

Limits and cases to handle

• You receive the item's QR code or System ID and nothing else: no name, no e-mail address, no internal identifier.
• An exchange code presented twice revokes the items it activated.
• Plan for refusal: error=access_denied on return from path A, subscription_required on path B when the holder is past the free item count without Qevik Plus.
• Durations: 90 seconds for a pushed request, 30 minutes for the confirmation, 60 seconds for the exchange code. On path B, the e-mailed code lasts 10 minutes, for 5 attempts.
• Default ceilings: 1,000 pushes per hour, 5,000 items per day per merchant, 50 items per day per buyer. Beyond them the API answers 429 with Retry-After.

Terms