Brand website NFC verification API
The tag opens your website. Your server sends the exact URL from the tap to BrandGuard, reads the decision, and displays the result on your website.
From website registration to a phone tap
- Verify the website. Choose the environment, publish the ownership file on the website and confirm approval.
- Configure the connection. Select or create the connection, confirm the chip and exact tag entry URL, issue the token, store it on the server and enable the connection.
- Connect the website. Use the selected connection’s server settings and run a test request. Display results by SKU, registered page path or a verified chip UID associated later by your business system.
- Prepare a test tag. The administrator selects an Item using this encoding. The tag operator writes it and checks the readback. This can run alongside website setup.
- Verify a fresh phone tap. Match the page on the phone, the physical Item and the receipt for that tap.
Run the offline example
Download the full SDK 1.3.3, extract it, and open START_HERE.html. The SDK includes website adapters, a simulator, test cases, and deployment instructions. Use Node.js 22.12 or later with npm for the full workflow.
English SDK 1.3.3中文 SDK 1.3.3SHA-256 checksums
From the extracted folder run node reference/node-server.mjs. Open the loopback URL printed by the server and try a synthetic tap. The simulator uses local sample data and requires no token or tag.
HTTP API v1 contract (OpenAPI) · Node request and retry helper
Configure this connection
- Ask the administrator for the connection’s environment, API address, approved website origin, tag opening address and
encodingVersionId. Keep these values together. The administrator supplies the server token separately. Store its full value in your server’s secret manager. - Serve the configured tag opening address over HTTPS. Capture the complete incoming URL, preserving the path, query order, case and percent encoding. Disable raw URL logging for this route.
- Before sending a request, durably save the original request body, API origin and a fresh idempotency key for this tap in protected server storage. POST to
/api/customer/v1/verificationsat the assigned API origin withContent-Type: application/json,Authorization: Bearerplus your server token, andIdempotency-Key. The body containsencodingVersionIdand the exacttapUrl.
POST needs verifications:execute. To look up a receipt, GET /api/customer/v1/verifications/{verificationId} with verifications:read for the same tenant, connection and environment.
Display the result on your website
Read receipt.result and currentEligibility.eligible. For a fresh eligible valid decision, open the matching product page if its mapping is confirmed. Otherwise keep the decision visible on the verification result page. Use the receipt’s original time and count on refresh. A replay asks for a fresh tap. For invalid_signature, unknown_tag and policy_rejected show the recorded decision. Show electronic seal information only when the tag supports it.
Troubleshoot a request
| Response or symptom | First check |
|---|---|
| No response | Check DNS, TLS, outbound network, the exact API host and timeout. Keep the same API address, request body and idempotency key for recovery. |
400 · invalid_encoding_version / invalid_tap_url | Compare the encoding ID, exact tag opening address and complete captured query with the connection settings. |
401 · not_authorized | Check the server secret and Bearer header. Check whether the token expired or was revoked. An anonymous POST returning this response confirms the request reached authentication. |
403 · not_authorized / integration_not_authorized | Check the token’s tenant, execute scope, connection and environment, and that the connection is enabled. |
409 · idempotency_conflict | Retrieve the original request associated with the key and compare the encoding ID and tap URL. End the conflicting submission and reconcile the earlier operation. |
| 202 / 429 / 503, or a lost response | Keep the original key, API origin and request body. Resume the same operation after the specified Retry-After delay when supplied. |
For support record the UTC time, HTTP status, recognized error code and request ID. Keep raw tap URLs and tokens out of logs and support messages.
Test your server in Staging
- Open the engineer handoff for a dedicated, enabled Staging verification connection. Choose its encoding and the Bash or PowerShell example for your server.
- Run the anonymous request first. HTTP 401 confirms that the endpoint requires authentication. For the second request, supply the execute token for this connection through the server environment. The synthetic tag must be unregistered. This request records a diagnostic decision on the connection.
- Expect HTTP 200. Compare this field in the response:
{"receipt":{"result":"unknown_tag"}}This excerpt shows the result field. The full response also contains the verification ID. A new test or a changed tap URL needs a new idempotency key. To recover a lost response, reuse the original key, encoding and exact request body at the same API endpoint. Changing the request under an existing key can return HTTP 409.
Check a real tap on a phone
Tap a written test Item with its registered tag. Compare the receipt’s verificationId and itemId with the Item and the page the phone actually opens. Confirm the expected product or variant. Open the page directly and refresh the previous visit to check how each is displayed.