​
Overview

The platform delivers escrow events through two parallel channels:
ChannelMechanismUse case
In-app (realtime)Supabase Realtime subscriptionsUser has the app open
Push notificationsAPNs / FCM via ExpoUser has the app in the background or closed
Both channels fire for the same events — your client should handle deduplication (e.g. suppress the push banner if the app is foregrounded).

​
Registering a device token

Call this after obtaining an Expo push token on the device: 
POST /push-token-register
Authorization: Bearer <token>

{
  "token": "ExponentPushToken[xxxxxxxxxxxxxxxxxxxxxx]",
  "platform": "ios"
}
FieldValues
tokenExpo push token string
platformios, android, or web
A user can have multiple active tokens (multiple devices). Each token is stored independently. Registering the same token again is a no-op.

​
Unregistering a token

Call this on logout or when the user disables notifications on a device: 
POST /push-token-unregister
Authorization: Bearer <token>

{
  "token": "ExponentPushToken[xxxxxxxxxxxxxxxxxxxxxx]"
}
The token is deactivated immediately — no further push notifications will be sent to it.
Always call /push-token-unregister on logout. Stale tokens remain active until explicitly removed and will continue receiving push notifications for the previous session’s user.

​
What triggers a push notification

Push notifications are sent for every event that produces a notifications row — the same events you see in the in-app feed:
EventExample push body
Escrow funded”Your escrow ‘iPhone 15’ has been funded. Tap to accept.”
Escrow accepted”Chidi accepted your escrow ‘iPhone 15’.”
Dispute raised”A dispute has been raised on ‘iPhone 15’.”
Milestone completed”UI Design mockups has been marked complete. Release funds when ready.”
Payout succeeded”₦150,000 has been sent to your Access Bank account.”
Push payloads include entity_type, entity_id, escrow_id, and action_label — use these for deep-link routing to the correct screen.

​
Push delivery

Pushes are processed asynchronously via a queue worker (worker-push-notifications). There is a small delay (typically under 5 seconds) between the triggering event and push delivery. If the device is offline, APNs/FCM handles re-delivery according to their standard TTL policies.