walletmcppass: Apple Wallet passes

Create a signed Apple Wallet pass (.pkpass) and return a link to download it. Builds one pass in one of the five Wallet styles -- boardingPass, eventTicket, coupon, storeCard or generic -- from the text fields, colors, barcode and optional PNG images given below, signs it with this service's Apple Pass Type ID certificate, and returns an https download_url valid for 1 hour. Opening the link on an iPhone shows "Add to Apple Wallet". Passes install on any iOS version; the iOS 26/27 layouts fall back to the classic style on older iPhones. Barcodes: QR, PDF417, Aztec and Code128 on every iOS version; Code39, Codabar, EAN13 and ITF on iOS 27+. The barcode encodes exactly barcode_message. Gate and till scanners read that data, so a copy of an existing boarding pass, ticket or loyalty card only scans if barcode_message is the original barcode's content (airline boarding passes are usually PDF417 or Aztec, holding an IATA BCBP string such as "M1DOE/JANE ..."). This tool does not issue tickets, check anyone in, or contact airlines or venues. The link must be opened in Safari on the iPhone: Wallet adds a pass from Safari, but not from a .pkpass file handed over by another app. Google Wallet on Android also imports these files. Not supported: NFC passes. With updatable=True the pass can be changed later with update_wallet_pass, and copies already in Wallet refresh themselves. Its contents are then stored on this server for updatable_hours (1 hour by default, at most 30 days), then deleted. Returns {download_url, expires_in_seconds, serial_number, pass_type_identifier}, plus edit_token and updatable_until when updatable=True. With x402_ready=False and 3 or fewer free passes left today, also free_passes_left_today and x402_setup (how to set up x402 payments): pass that on to the user. Pricing: a call is one create or one update. The first 10 successful calls each day per caller (IP address or contact_email) are free (while a shared pool of 500 free calls a day lasts); failed calls don't count (up to 20 failures a day per caller), and counts reset at 00:00 UTC. Every call after them costs $0.01 in USDC on Base, paid with x402: the refusal carries the payment requirements; have the user's wallet tool sign them and retry the same call with the result as x402_payment. A paid result includes the payment receipt. Payment is settled only after the pass is built, so a failed build is never charged. Args: style: one of "boardingPass", "eventTicket", "coupon", "generic", "storeCard". organization_name: shown as the pass issuer. description: accessibility description (required by Wallet, not usually shown). logo_text: text shown next to the logo image. transit_type: only for style="boardingPass" -- "Air", "Boat", "Bus", "Generic", or "Train" (default "Air"). barcode_message: raw text/data encoded into the barcode. Omit for no barcode. barcode_format: a format name or an ordered list of them; each becomes a barcode with the same message, and Wallet shows the first one the device supports. Nothing is added that you don't list. Formats: "QR" (default), "PDF417", "Aztec", "Code128" (all iOS versions), and iOS 27+ only: "Code39", "Codabar", "EAN13", "ITF" -- older iPhones skip these, so e.g. ["EAN13", "Code128"] shows EAN13 on iOS 27 and Code128 before it. EAN13 needs 12-13 digits, ITF an even number of digits, Code39 uppercase letters/digits. barcode_alt_text: human-readable text shown under the barcode (e.g. the card number). background_color / foreground_color / label_color: hex colors, e.g. "#1a1a19". relevant_date / expiration_date: ISO 8601 timestamps. locations: up to 10 places where the pass appears on the lock screen when the iPhone is nearby, each {"latitude": float, "longitude": float, "altitude": optional float, "relevantText": optional str shown on the lock screen, e.g. "Your gym card"}. Look up the coordinates of the actual branch, not just the brand. For boardingPass and eventTicket the pass is relevant near a location around relevant_date if one is set; the other styles use location alone. Wallet only shows a pass within its own default radius of a location, which is small for store cards and coupons. max_distance: meters; shrinks the default radius around every location (Wallet uses the smaller of the two, so it cannot enlarge it). Requires locations. voided: mark the pass voided/used (shows a "VOID" stamp). primary_fields / secondary_fields / auxiliary_fields / header_fields / back_fields: lists of {"key": optional str, "label": optional str, "value": str, "changeMessage": optional str} shown on the pass. changeMessage only matters on updatable passes: when an update changes that field's value, the iPhone shows it as a lock-screen notification, with %@ replaced by the new value (e.g. "You now have %@ points"); without %@ Wallet shows a generic message. Updates match fields by key, so give fields that will change an explicit key (auto keys are by position). serial_number: unique id for this pass; auto-generated if omitted. icon_color / icon_text: control the auto-generated icon (a colored square with initials) when icon_png_b64 is not supplied. logo_color: color of the auto-generated logo image, a wordmark of logo_text (or organization_name) drawn on a transparent background over background_color. Defaults to icon_color. Wallet also renders logo_text as text beside the logo image, so the generated wordmark repeats it -- set generate_logo=False to show only the text. icon_png_b64 / logo_png_b64: PNG to use instead of auto-generated art. Every *_png_b64 parameter takes either base64 PNG data or an https:// URL of an image (PNG, JPEG, WebP or GIF, up to 5 MB; non-PNG is converted to PNG). The URL is fetched once, when the pass is built. generate_logo: set False to include no auto-generated logo or primary logo at all (both are optional in Wallet; a supplied logo_png_b64/primary_logo_png_b64 is still used). poster: (iOS 27+) render as Apple's new full-bleed "Poster Generic" layout -- large background image, header field, up to 4 primary fields, up to 2 footer_fields, and a square QR code. Only for style "generic", "storeCard" or "coupon"; that style is kept as the fallback older iPhones display (secondary/auxiliary fields only show on the fallback). Good for memberships, loyalty cards and gift cards. footer_fields: up to 2 fields along the bottom of a poster pass (requires poster=True). background_png_b64: base64 PNG poster background, ideally 1035x1515 px (345x505pt @3x); a gradient in background_color is generated if omitted. Only used when poster=True. featured_actions: (iOS 27+) up to 2 tappable shortcut cards shown under the pass, each {"type": ..., "url": "https://..."}. type is one of: viewSchedule, watchTrailer, listenToMusic, call (url must be "tel:+..."), addToBalance, order, shop, membershipBenefits, bookAppointment, bookCar, bookFlight, bookStay, viewOffersRewards. Works on every style; ignored by older iPhones. semantics: machine-readable tags (Apple's SemanticTags) that Wallet uses for Siri/Maps/ Calendar suggestions on every style, and to lay out the semantic designs below. Values are emitted as given; unknown keys and wrong types are rejected. Dates are ISO 8601 with an offset. Common shapes: passengerName {"givenName", "familyName"}; flightNumber is a number (123, not "AI123"); seats [{"seatNumber", "seatRow", "seatSection", ...}]; venueLocation {"latitude", "longitude"}; totalPrice {"amount": "12.50", "currencyCode": "INR"}; eventType one of generic, livePerformance, movie, sports, conference, convention, workshop, socialGathering. semantic_layout: use Wallet's semantic design, with the classic style kept for older iPhones -- which only show primary/secondary/auxiliary fields, so still fill those. - boardingPass (iOS 26+, airline only, transit_type "Air"): live flight status, gate changes, badges. Requires semantics airlineCode, flightNumber, departureAirportCode, departureCityName, destinationAirportCode, destinationCityName, originalBoardingDate, originalDepartureDate, originalArrivalDate, passengerName, plus departure and destination time zones (IANA, e.g. "Asia/Kolkata"). Apple's docs call these departureLocationTimeZone/destinationLocationTimeZone but Apple's pass-builder code uses departureAirportTimeZone/destinationAirportTimeZone; either is accepted, and giving both is safest. - eventTicket (iOS 26+ "poster event ticket"): requires eventName, venueName, venueRegionName, venueRoom; sports also needs awayTeamAbbreviation and homeTeamAbbreviation, livePerformance needs performerNames. Apple says this design is meant for NFC entry, not barcodes, and NFC passes need an Apple entitlement this server doesn't have -- Wallet may show the classic event ticket instead. info_links: top-level links that fill the event guide (event tickets) or the airline and services page (boarding passes). URL keys (http/https): accessibilityURL, addOnURL, bagPolicyURL, merchandiseURL, orderFoodURL, parkingInformationURL, purchaseParkingURL, sellURL, transferURL, transitInformationURL, contactVenueWebsite, directionsInformationURL, changeSeatURL, entertainmentURL, purchaseAdditionalBaggageURL, purchaseLoungeAccessURL, purchaseWifiURL, upgradeURL, managementURL, registerServiceAnimalURL, reportLostBagURL, requestWheelchairURL, transitProviderWebsiteURL. Text keys: contactVenueEmail, contactVenuePhoneNumber, transitProviderEmail, transitProviderPhoneNumber. Extra images (base64 PNG or https URL). Which image shows where depends on style and iOS version (from Apple's Pass Designer docs); Wallet ignores an image a layout has no slot for: primary_logo_png_b64: max 126x30pt. Boarding pass and coupon on iOS 27+, event ticket on iOS 18+, poster. On those, the plain logo is only shown by older iOS. A wordmark is auto-generated for poster and semantic_layout passes unless generate_logo=False. secondary_logo_png_b64: max 135x12pt. Event tickets, iOS 18+. strip_png_b64: 375x144pt banner behind the primary fields. Coupon, store card and event ticket; not shown on iOS 26+ coupon/store card. thumbnail_png_b64: 90x90pt. Generic and event ticket. artwork_png_b64: 358x448pt poster event ticket artwork (eventTicket with semantic_layout, iOS 27+); if neither this nor background_png_b64 is given, a gradient in background_color is generated, since Wallet needs one of them. background_png_b64 is also used on eventTicket (blurred behind the classic ticket). updatable: keep this pass on the server so update_wallet_pass can change it later. The response then includes an edit_token: the only way to update the pass, and it can't be recovered, so give it to the user. Wallet registers each iPhone that adds the pass, and an update reaches them within seconds. The pass contents are stored (other passes only log the style and organization_name). Use for passes that change: loyalty points, gate or seat changes, memberships that can be cancelled. updatable_hours: how long an updatable pass can be updated, 1 (default) to 720 (30 days), counted from creation; updates don't extend it. Afterwards the stored pass is deleted and can't be changed again, while copies in Wallet stay as they last were. Pick it to cover the pass's useful life, e.g. until a flight lands or an event ends. Only with updatable=True. contact_email: required. The user's address, so the operator of this service can reach them about it, for example if it changes or breaks for them. Ask the user for it; never take it from the pass details or make one up. It isn't added to the pass, and it's kept in the request log. x402_ready: required. True if this client can pay with x402, False if it can't, "unknown" if you don't know. It shows the operator how many clients could pay after their free passes. Only logged: it changes neither price nor limits. x402_payment: only after a refusal that asked for payment. The signed x402 payment for the requirements in that refusal (the PaymentPayload JSON object, or its base64), e.g. from a wallet connector's sign/pay tool. Same as sending it in _meta["x402/payment"].

Change a pass made with create_wallet_pass(updatable=True); every iPhone that added it refreshes. Takes the serial_number and edit_token returned when the pass was created, the required contact_email and x402_ready, plus any of create_wallet_pass's parameters (x402_payment included), with the same meanings. Each parameter given replaces the stored value completely (a fields list replaces the whole list, so resend unchanged fields too); parameters left out keep their current values. Clear a text value with "" and a list with []. To cancel a pass, set voided=True: Wallet marks it void on every iPhone. Wallet asks the server for the new version as soon as Apple delivers the push, usually within seconds. A field's changeMessage is shown on the lock screen when that field's value changes. Only works until the pass's updatable_until time (set by updatable_hours at creation). Returns {download_url, expires_in_seconds, serial_number, pass_type_identifier, notified_devices, updatable_until}. notified_devices counts the iPhones the push was sent to, not ones that have already refreshed. The download_url (valid 1 hour) is only needed to add the pass to a new device. With x402_ready=False the result also has x402_setup, as for create_wallet_pass.