Skip to main content

Distributing Passes

After creating an Apple or Google Wallet pass with POST /v0/passes, you will want to prompt the user to add the pass to their device.

Please Note: Platform Differences in Distribution​

Apple Wallet and Google Wallet distribute their passes using different solutions.

Google Wallet API returns a claim link for a pass, while the Apple Wallet API returns a file that needs to be downloaded.

While we offer some assistance with this, we are a non-custodial solution, and we defer long-term file hosting to the developer. For Apple Wallet passes, your use case may require some additional handling.

Google Pass Distribution​

The Google Pass API returns a claim link that remains live until the pass gets installed. The link will only expire after the pass is installed successfully.

Example Distribution Payload​

{
  "fileURL": "https://api.ethpass.xyz/api/download/T3EPFmwiA9K2dy17swY6FbHnWBn7N83D"
}

Apple Pass Distribution​

The Apple Wallet API returns a file. To make it easier to work with Apple passes, we provide a download link which remains live until the pass gets installed.

Example Distribution Payload​

{
  // temporary link
  "fileURL": "https://api.ethpass.xyz/api/download/T3EPFmwiA9K2dy17swY6FbHnWBn7N83D",
  "buffer": {
    "type": "Buffer",
    "data": [80, 75, 3, 4, 10, 0, 0, 0, 0, 0, ...]
  }
}

Working With the File Buffer​

Your language of choice should have a library or built-in method for working with file buffers. In Javascript, you can use the built-in method like so: For more on this, you can reference our email example below.

const buffer = {
    "type": "Buffer",
    "data": [80, 75, 3, 4, 10, 0, 0, 0, 0, 0, ...]
};
const file = Buffer.from(buffer.data).toString("base64");

Obtaining Distribution Data​

You can obtain distribution data in two ways:

1. Upon creation, from the POST /v0/passes response:​

const body = {...};

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

// Extract distribution info from result
const { id, fileURL, buffer } = await response.json();

2. Querying with GET /v0/passes/{passId}/distribute​

const passId = "5450c91b-9929-46a5-a2cc-3bbe7e728a45";

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

const { fileURL, buffer } = await response.json();

Distribution Examples​

Once you have the distribution data, you can expose it to a user in a number of ways:

  • Download upon scanning a QR code
  • Direct download
  • Email
  • Text

Download Pass via QR Code​

An easy and mobile-friendly way to prompt users to download their pass is with a QR code.

You can use an open source tool like qrcode to generate a barcode from the distribution URL. If the user scans the QR code with their device, they will be routed to the distribution URL and prompted to install the pass into their wallet.

Please note: this example relies solely on the URL, and should only be used when a pass is first created. After the initial creation period, you may need to work with the file buffer.

// EXAMPLE IN REACT

import QRCode from "qrcode";
import { useEffect, useState } from "react";

const DownloadQRCode = () => {
  const fileURL =
    "https://api.ethpass.xyz/api/download/T3EPFmwiA9K2dy17swY6FbHnWBn7N83D;
  const [qrCode, setQrCode] = useState();

  // Generate QR code from URL
  useEffect(() => {
    QRCode.toDataURL(fileURL, (err, url) => {
      if (!err) setQrCode(url);
    });
  }, []);

  // Render QR code
  return <img src={qrCode} alt="QR Code" width={250} height={250} />;
};

Direct Download​

To prompt a direct download of a pass, you can expose a button which will route to the distribution URL.

Please note: this example relies solely on the URL, and should only be used when a pass is first created. After the initial creation period, you may need to work with the file buffer.

// EXAMPLE IN REACT

const DirectDownload = () => {
  const fileURL =
    "https://api.ethpass.xyz/api/download/T3EPFmwiA9K2dy17swY6FbHnWBn7N83D";

  return (
    <a target="_blank" href={fileURL} rel="noreferrer">
      Click Here to Add to Your Wallet
    </a>
  );
};

Email​

If you would like to send email confirmations to pass holders, you can prompt users to download passes via email.

As an important note, Google Wallet and Apple Wallet passes are implemented differently, so the below example takes this into account.

Our example uses sendgrid to send emails (requires an API key).

// EXAMPLE IN JAVASCRIPT

import sgMail from "@sendgrid/mail"

const sendEmail = () => {
    // Obtained from POST v0/passes or GET /v0/passes/{passId}/distribute
    const fileURL = "https://api.ethpass.xyz/api/download/T3EPFmwiA9K2dy17swY6FbHnWBn7N83D";
    const buffer = {
        type: "Buffer",
        data: [80, 75, 3, 4, 10, 0, 0, 0, 0, 0, ...]
    };

    // Your Information
    const recipient = "recipient@their-email.com";
    const sender = "me@my-project.com"; // Use a verified sender
    const eventName = "Your Event";

    // Email Details
    let html = ""; // Google passes are URLs, can be included in HTML
    let attachments = [];   // Apple passes are files, and must be attached

    if (platform === "apple") {
        attachments = [
          {
            content: Buffer.from(buffer.data).toString("base64"),
            filename: `${eventName}.pkpass`,
            type: "application/vnd.apple.pkpass",
            disposition: "attachment",
          },
        ];
    } else if (platform === "google") {
        html = `<a href="${fileURL}">Add Pass To Your Wallet</a>`;
    }

    const msg = {
      to: recipient,
      from: sender,
      subject: `${eventName}: Download Your Tickets`,
      html,
      attachments
    }

    return sgMail.send(msg);
}

Assets​

We are happy to supply these assets for your Add to Wallet buttons: