Wallet
Apple Wallet passes: a card's holder downloads their earned card through a short-lived link, and anyone can download a pass for a fundraiser that can be opened by its link. Passes keep themselves current through the PassKit web service under /passkit/v1, which Wallet itself calls, with the pass's own token (Authorization: ApplePass <token>) where Apple's protocol asks for one. Passes come in English, Russian, Ukrainian or Spanish. Until the platform's Pass Type ID certificate is configured, every endpoint but GET /wallet/status answers 503 (code: wallet_unavailable).
Whether Apple Wallet passes are available
available is true once the platform's Pass Type ID certificate is configured. Until then every other Wallet endpoint answers 503 with code: wallet_unavailable, so a client shows no "Add to Apple Wallet" button. Public, the same answer for everyone, cached for five minutes.
Responses
Availability
Get a download link for your card's Apple Wallet pass
For the holder of the card only (the signed-in person, or an organization they administer). Answers a link to GET /wallet/passes/{token} that works for ten minutes, for one download of this card's pass, in the request's language (?lang=, the language cookie, then Accept-Language). The pass is a generic Wallet pass in the colours of the card's tier: the series number, the species, the tier, when the current tier was reached, the holder's public name, the series, the rarity and, for a card earned by a verified donation, the proof, with the card's verify QR code. It shows only what the public card page shows. Writes nothing.
Authorizations
In the browser, authentication rides on the httpOnly session cookies set by /cognito/signin or the Google / Apple sign-in at /cognito/oauth/{provider}. For scripts and for Swagger UI testing, paste an API key (fh_live_…, created with POST /api-keys); a Cognito JWT is accepted too. Sign-in does not return a token in its body.
Parameters
Path Parameters
The card's code, e.g. WH-2318.
Query Parameters
The pass's language.
"en""ru""uk""es"Responses
The download link
Download your card's Apple Wallet pass
The link POST /wallet/cards/{code}/link answers, opened within ten minutes. The card is checked again; a card revoked or no longer the requester's in the meantime answers 404. Every download is a new pass with its own serial number. The pass stays current through the PassKit web service: when the card reaches a new tier, Wallet is told and fetches it. private, no-store: the file carries the pass's own authentication token.
Parameters
Path Parameters
The signed download token from the link.
Responses
The signed pass, sent as an attachment named FundlyHub-<code>.pkpass
Download a fundraiser's Apple Wallet pass
A store card for any fundraiser that can be opened by its link (live, ended or paused, not private, not deleted): the amount raised, the percent of the goal, the title and the donor count, the same figures and money formatting as the fundraiser's page, over its cover photo. The QR code opens the fundraiser's page (?utm_source=wallet), or, when ref is a referral code for this fundraiser, that sharer's /r/<code> link, so their link keeps counting what it brings. Any other ref is ignored. Each download is a new pass that updates as gifts come in. Language: ?lang=, the language cookie, then Accept-Language; without one the labels are English and the title is the fundraiser's own.
Parameters
Path Parameters
"uuid"Query Parameters
A referral code for this fundraiser.
"en""ru""uk""es"Responses
The signed pass, sent as an attachment named FundlyHub-<slug>.pkpass
Register a device for a pass's updates (PassKit web service)
Apple's PassKit web service, called by Wallet itself under the pass's webServiceURL. Authenticated by the pass's own token. 201 for a new registration, 200 when the device was already registered (its push token is updated).
Authorizations
Apple's PassKit web service scheme: Authorization: ApplePass <authenticationToken>, the token inside the pass itself. Sent by Wallet, never by a person.
Parameters
Request Body
Responses
Already registered: the device's push token is updated. The body is the plain-text status line OK.
Unregister a device from a pass's updates (PassKit web service)
Called by Wallet when the pass is removed from the device. Authenticated by the pass's own token.
Authorizations
Apple's PassKit web service scheme: Authorization: ApplePass <authenticationToken>, the token inside the pass itself. Sent by Wallet, never by a person.
Parameters
Responses
Unregistered, also when the device was not registered for this pass. The body is the plain-text status line OK.
List a device's passes that changed (PassKit web service)
The serial numbers of the passes this device registered for that changed after passesUpdatedSince (a lastUpdated value this endpoint answered before; all of them without it), and the lastUpdated value to send next time. A pass can be listed again; fetching it then answers 304. No authentication, as Apple specifies.
Parameters
Query Parameters
Responses
Changed passes
Get the current version of a pass (PassKit web service)
The pass as it is now, rebuilt from the card or the fundraiser, with Last-Modified. 304 when it has not changed since If-Modified-Since. A card that was revoked or withdrawn, or is no longer its holder's, and a fundraiser that can no longer be opened, come back as a voided pass. Authenticated by the pass's own token.
Authorizations
Apple's PassKit web service scheme: Authorization: ApplePass <authenticationToken>, the token inside the pass itself. Sent by Wallet, never by a person.
Parameters
Header Parameters
Responses
The signed pass