Scanning Passes

To verify a pass, you will need to do the following:

1. Obtain the barcode on the pass with a QR scanner.
2. Use the barcode to call the GET /v0/scan endpoint.

Obtaining a Barcode

You will need to use a QR scanner to scan the barcode included on the pass.

There are many libraries to scan QR codes for both web browsers and mobile, but ethpass’s example using qr-scanner is a good sample to reference.

The result of the QR scan should yield a barcodeSignature which you can use to verify the pass via the GET /v0/scan API.

Scanning a Pass

Once you have obtained the barcode on the pass, you simply need to call the GET /v0/scan endpoint with the barcode signature.

const barcode = "0xe49383c69c2f0426877a5086b8113c6d9db200abc";

const response = await fetch(
  `https://api.ethpass.xyz/api/v0/scan?data=${barcode}`,
  {
    headers: new Headers({
      "content-type": "application/json",
      "X-API-KEY": "YOUR_SECRET_API_KEY",
    }),
  }
);

A successful scan will return pass details, a decoded barcode message (if included), and information about the nfts linked to the pass.

Please note: a successful scan DOES NOT mean a pass is valid. Instead, the scan result will return information to be handled by the client.

Performing a Dry Run

The dryRun parameter in the API allows you to perform a simulation of a scan without actually recording the results in the database. This is a useful feature for testing and validation purposes, as it enables you to preview the data contained in a scan before marking it as valid. With this parameter set to true, the API will scan a pass and return the extracted information, but it will not be recorded as a valid scan in the database.

This allows you to verify the contents of the data and make any necessary adjustments before committing to a full scan. The dryRun parameter is especially useful for complex scanning systems where accuracy and reliability are critical, as it provides a way to test the scan process and ensure that the results are accurate before they are recorded in the database.

const barcode = "0xe49383c69c2f0426877a5086b8113c6d9db200abc";

const response = await fetch(
  `https://api.ethpass.xyz/api/v0/scan?data=${barcode}&dryRun=true`,
  {
    headers: new Headers({
      "content-type": "application/json",
      "X-API-KEY": "YOUR_SECRET_API_KEY",
    }),
  }
);

Interpreting the Scan Result

To properly verify the scan result, we suggest checking two attributes:

1. expiredAt / expiredAction on the pass
2. valid on the linked NFT (if applicable)

Checking Pass Expiration

To confirm a pass has not expired, you can check the expiredAt value in the result.

If this value exists, the pass has been expired, and the expiredAction on the result can provide more details on the reason.

Possible values for expiredAction include:

Value	Description
TRANSFER_EVENT	NFT transferred to another wallet
APPLE_CALLBACK	User removed pass from Apple device
GOOGLE_CALLBACK	User removed pass from Google device
USER_REVOKE	Manually revoked by admin/user

Checking Validity of NFT

The ethpass API considers a pass invalid if the signer transfers the related NFT out of their wallet.

This value is determined real-time by reading the owner of the NFT on the network.

The scan result returns a list of nfts linked to the pass, and the validity can be parsed like below:

const invalid = scanResult.nfts.some((nft) => {
  return !nft.valid;
});

NOTE: The scan result includes an array of nfts to support multiple NFTs in the near future. For the time being, we only support creating a pass with one nft, so you can expect only 1 item in the nfts array.

Realtime vs. Async Verification of NFT Ownership

Change in NFT ownership will reflect in both the expiredAt and valid status of the pass.

Passes are marked expired via an asynchronous event listener, while valid affirms the owner of the NFT in realtime at the time of scanning.

Depending on your desired level of security, you can protect against any latency in transfer events by checking the valid status on the pass. We recommend always checking both conditions.

Tip: Skipping QR Scanning in Development

If you are testing and developing against passes you created with ethpass APIs, you can avoid the QR scanning step by using GET /v0/passes/{passId} to fetch the pass, obtaining the barcodeSignature from the response, and supplying this to the GET /v0/scan API.

const passId = "f664196b-035a-454d-90c4-ab0adc107981";

const response = await fetch(
  `https://api.ethpass.xyz/api/v0/passes/${passId}`,
  {
    method: "POST",
    body: JSON.stringify(payload),
    headers: new Headers({
      "content-type": "application/json",
      "X-API-KEY": "YOUR_SECRET_API_KEY",
    }),
  }
);

const pass = response.json();
const barcodeSignature = pass.barcodeSignature;

const response = await fetch(
  `https://api.ethpass.xyz/api/v0/scan?data=${barcodeSignature}`,
  {
    headers: new Headers({
      "content-type": "application/json",
      "X-API-KEY": "YOUR_SECRET_API_KEY",
    }),
  }
);