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, and x402_setup (how to set up x402
payments, worth passing on to the user) when x402_ready=False.
Pricing: a call is one create or one update. Free for 30 calls a day per caller IP (20 from
2026-11-18), while a shared pool of 500 free calls a day lasts; failed calls count too, and counts reset at 00:00 UTC.
Past either limit, a call costs $0.01 in USDC on Base, paid with x402; the refusal carries the
payment requirements, and 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 past the free limit.
Only logged: it changes neither price nor limits.