Apple Wallet passes

Apple Wallet (previously known as 'Apple Passbook') is a digital wallet service that can be used to store digital artifacts (known as 'passes'), such as movie tickets.

OCAPI supports generation of Apple Wallet passes for completed orders that contain tickets.

Prerequisites

Ensure that the Digital Platform has been configured to enable Apple Wallet. See the "Lumos configuration" section in our help centre article for details or talk to your local Vista representative for assistance.

Add to Apple Wallet flow

Render an 'Add to Apple Wallet' button

Apple provides brand guidelines that outline the requirements for rendering an 'Add to Apple Wallet' button on various platforms. The 'Add to Apple Wallet' button should generate a pass when pressed and open the pass.

Generate an Apple Wallet pass

Use the GetAppleWalletPassForOrder endpoint to generate an Apple Wallet pass for a completed order.

Points to Note

An Apple Wallet pass can only be generated for standard orders that contain tickets and have not expired .
For orders that contain tickets to multiple showtimes, an Apple Wallet pass will be generated for each showtime.
Regardless of the number of showtimes, the endpoint will return a single .pkpasses bundle containing an Apple Wallet pass for each showtime.

Open the Apple Wallet pass

The GetAppleWalletPassForOrder endpoint returns a byte array with a MIME type of application/vnd.apple.pkpasses, representing the Apple Wallet pass bundle for the completed order.

Opening the Apple Wallet pass bundle on supported devices will prompt the patron to add the passes to their Apple Wallet.

For web, use the response Blob to open the Apple Wallet pass bundle, for example:

Copy

Copied

/**
 * Loads an Apple Wallet pass for a completed order and opens the 'add pass to wallet' prompt UI on supported devices.
 */
async function onAddToAppleWalletButtonClick(apiUrl, gasToken, orderId) {
  // Load the Apple Wallet pass.
  const response = await fetch(
    `https://${apiUrl}/ocapi/v1/orders/completed/${orderId}/assets/apple-wallet-pass`,
    {
      method: 'GET',
      headers: {
        Authorization: `Bearer ${gasToken}`,
      },
    },
  );

  // Parse the Apple Wallet pass blob.
  const appleWalletPassBlob = await response.blob();

  // Open the blob via a hidden link.
  const url = window.URL.createObjectURL(appleWalletPassBlob);
  const link = document.createElement('a');
  link.href = url;

  // Append the link to the body and open it in the current window.
  document.body.appendChild(link);
  link.click();

  // Clean up.
  document.body.removeChild(link);
  window.URL.revokeObjectURL(url);
}