Using Pass Barcodes

This section provides crucial insights into the use of Pass Barcodes. It encompasses integral topics like "Using a Barcode Message", a guide to encoding and decoding barcode-based information. "Using a Pass Redirect" section describes the process of redirecting a barcode scan to a designated function or application. In the "Barcode Formats" section, we assist you in selecting the barcode format most fitting for your specific needs. Finally, we illuminate the concept of "Disable Encoding", where we explain how to pause the barcode encoding process, if necessary. Our objective is to equip you with the knowledge and tools to harness the full potential of barcode technology in your operations.

Using a Barcode Message

Passes feature an optional message parameter, enabling the secure inclusion of pertinent information such as internal IDs. The message is encrypted and signed using AES-256 bit encryption and our proprietary set of private keys. The decrypted value will only be returned in a successful GET /v0/scan response.

Take, for instance, if you aim to issue a pass that enables users to redeem their NFT for a specific item. You can encode the item's ID within the pass message. This ID will only be unveiled when the pass is scanned by ethpass.

📘

Tip

For use cases such as the one mentioned above, employing External IDs may prove to be a more suitable solution. This approach is particularly beneficial because it provides an efficient method to cross-reference a pass with a resource in your system, such as a specific item. Using External IDs streamlines the process of tracking and managing these associations within your operational environment. Using External ID

Defining a Message

// create a pass
const payload = {
  barcode: {
    message: "ITEM-ID:207",
  },
  ...
};

Message Retrieval

// 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)"

Using a Pass Redirect

You have the flexibility to delegate the scanning of a pass to a different server by leveraging a redirect argument.

In the absence of a redirect argument, scanning the QR code will yield the barcode information. This data can then be passed to the scan API for subsequent processing.

However, should you opt to incorporate a redirect URL, the QR code scanning will automatically redirect to your specified address, formatted as https://your-redirect-url.io?barcodeSignature=${barcode}.

To manage this redirection effectively, your redirect endpoint should be configured to process the incoming request and issue a GET /v0/scan request. The barcodeSignature should be included as a parameter within the URL.

Let's consider an example. Suppose you want to process scan data within your system and integrate it with your user management system. By including a redirect URL like https://your-user-management.io?barcodeSignature=${barcode}, the scan data can be sent directly to your system. This allows you to implement custom processing logic within your existing infrastructure, providing the option to bypass the scan API completely if you choose.

🚧

Warning

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).

Barcode Formats

Our system accommodates a range of barcode formats to suit various needs. This includes the QR code (QR), the Code 128 format (CODE_128), the Aztec code (AZTEC), and the PDF417 format (PDF417). Furthermore, we provide an option for NONE, which is applicable in instances where a barcode is not required or has been deactivated for a specific pass. By supporting these diverse formats, our system allows you to personalize your barcode strategy to align with your specific operational needs.

Defining Barcode Format

const payload = {
  barcode: {
    message: "ITEM-ID:207",
    format: 'PDF417',
  },
  ...
};

📘

Note

By default, the system will use the QR code format if no specific format is chosen.

Barcode Encoding

Our system provides a versatile approach to barcode encoding, designed to effortlessly blend into your existing operational setup. By default, the barcode value is an encoded hash that requires communication with our API to process a scan accurately. However, we've introduced an option to disable this encoding, allowing the barcode value to be a direct representation of the message parameter you input. This creates barcodes that are instantly compatible with your current scanning hardware or Point of Sale (POS) system.

For example, should your business aim to distribute coupon codes already registered in your POS system, you can utilize this disabled encoding feature. This way, the barcodes you create directly represent these coupon codes. When customers present these barcodes at the point of sale, your existing system can interpret and apply the coupon codes without any need for interaction with our API. This feature not only simplifies the process of distributing and redeeming coupon codes but also enhances the customer experience by reducing technical complexities.

Disable Encoding

const payload = {
  barcode: {
    message: "ITEM-ID:207",
    format: 'PDF417',
    encoded: false,
  },
  ...
};

NFC Support

Our system also supports NFC technology for Apple and Google Wallet passes. This feature can add a significant layer of convenience and efficiency to your operations. However, please note that obtaining NFC certificates for your company is a necessary requirement from both Apple and Google to enable this functionality. If you're interested in this capability, we invite you to reach out to us. Our team will be happy to guide you through the process and connect you with the appropriate parties to help you obtain your NFC certificates.