Send a wallet push
Sends a marketing wallet push to a specific enrolment. The
customer must have push-marketing consent enabled, otherwise
the endpoint returns 403 with
push_marketing_consent_required.
Merge fields ({firstName}, {balance}, {installLink},
{shareLink}, {cardName}, {orgName}) are resolved against
the targeted customer + enrolment + card.
Throttle: 3-minute per-card cooldown. Hit → 429 with
Retry-After. The cooldown is shared with the operator’s
dashboard push paths so a rapid dashboard + API sequence is
also caught.
Test mode (pk_test_… or OAuth mode=TEST): the endpoint
returns 200 with test_mode: true but does NOT push. Lets
partners verify wire integration without spamming real
customer lock screens.
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Headers
Replay-safe request key. Repeated requests with the same value within 24h return the original response unchanged.
255Body
The enrolment to target. The push fans out across every
wallet pass on the customer's physical device (siblings
with the same deviceFingerprint), so multiple cards on
one phone share the message.
Plain-text push body. Merge fields are resolved:
{firstName}, {lastName}, {balance}, {cardName},
{installLink}, {shareLink}, {orgName}.
1 - 180Free-form key/value bag for partner-side context. Not persisted beyond the audit row.
Response
Test-mode push (no actual delivery)
Broadcast audit row id. Null on test-mode calls (no row written).
True when every attempted platform succeeded. False if any APNs / Google send failed — the message still landed on the pass copy + audit row.
Enrolment ids touched, including sibling-device-fingerprint
fan-out beyond the supplied enrollment_id.
Count of (pass × platform) deliveries attempted. Zero in test mode.
True when the caller used a pk_test_… key or an OAuth
mode=TEST token. No wallet push is actually fired and
no Broadcast row is written.
Related topics
Perkstar developer platformSend push notificationsAuthentication and scopesTypeScript SDKTest mode
