Skip to main content

Leveraging Pass Barcodes

ethpass gives you the option of using some extra features to get the best use out of your pass barcodes.

Using a Barcode Message​

Passes have an optional message parameter, which can be used to securely include relevant information, such as internal IDs. The message will be AES-256 bit encrypted and signed using our own set of private keys. The decrypted value will only be returned in a successful GET /v0/scan response.

For example, if you want to issue a pass that allows users to redeem their NFT for a specific item, the item's ID can be encoded in the pass message. This ID will only be revealed when the pass is scanned by ethpass.

// create a pass
const payload = {
  barcode: {
    message:
      "ITEM-ID:207 (the contents of this will be decoded with the scan API)",
  },
  signature:
    "0x71147d2b97a397061e6dbd82351867a7057bdb4d9566a8ac2d618e1a3e62d43c722245fb4e6a8e9ee814348bdd5c433224c8c10f9fadf7fd154b44c17056109f1c",
  signatureMessage: "Sign this message to generate a pass with ethpass.xyz",
  platform: "apple",
  chain: {
    name: "evm",
    network: 1,
  },
};

// use the scan API to verify the pass through its QR code
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",
    }),
  }
);

const decodedMessage = response.json().message;
// decodedMessage === payload.message === "ITEM-ID:207 (the contents of this will be decoded with the scan API)"

If you choose, you can delegate the scanning of a pass to a different server with a redirect argument.

If the barcode does not contain a redirect argument, scanning the QR code on the pass will simply yield the barcode information which you can pass to the scan API.

If you choose to include a redirect URL, scanning the QR code on the pass will automatically route to https://your-redirect-url.io?barcodeSignature=${barcode}.

Your redirect endpoint will need to process this request, and make the GET /v0/scan request with the barcodeSignature included in the URL parameters.

With this, you can implement your own custom processing, and even skip using the scan API altogether.

NOTE: A scan is only registered if you hit our GET /v0/scan endpoint. If you choose to implement your own scan endpoint, you will lose the ability to track scan history through ethpass, and you will need to support this in your own server (not recommended for best use).