Skip to main content
Version: 1.0.143

Push Notification Channel Service API Specification

This page describes how to integrate with the Push Notification Channel Service on a technical level.

This service is a specialized downstream service, typically called by the central Notification Service. Its sole responsibility is to handle the formatting and dispatching of push notifications to mobile and web clients (e.g., via FCM).

REST Resources​

The Push Notification Channel Service provides a single resource for sending a push notification.

The Push Notification Resource​

A push notification request defines the content to be "pushed" to a user's device. It consists of:

  • reference: A unique ID for tracking this specific send request.
  • token: The device-specific push token (e.g., an FCM registration token).
  • title: The title of the notification.
  • body: The main message content of the notification.
  • appName: The target application (e.g., "Banqup").
  • data: An optional key-value map for sending custom data payloads.

An example of a push notification request in JSON format:

{
  "reference": "push_ref_778899_def",
  "token": "eEd-LqO...8d1sF-j",
  "title": "New Invoice Received",
  "body": "You have received a new invoice (INV-2025-0043) from Acme Corp.",
  "appName": "Banqup",
  "deviceType": "PHONE",
  "data": {
    "documentId": "b1a4c2a0-4f5c-4b3d-811c-9e2b6a4a1f2c",
    "action": "view_invoice"
  }
}

When this push notification is successfully queued for sending, the service returns a unique notificationId:

{
  "notificationId": "f4b3c2a1-9e8d-4f6c-8a7b-1d2e3c4b5a6d"
}

Sending a Push Notification​

To send a new push notification, you'll perform a POST request to the **/core/pushnotification/v1/pushnotifications ** endpoint, providing the full push notification object in the request body.

POST /v1/pushnotifications
Content-Type: application/json

{
  "reference": "push_ref_778899_def",
  "token": "eEd-LqO...8d1sF-j",
  "title": "New Invoice Received",
  "body": "You have received a new invoice (INV-2025-0043) from Acme Corp.",
  "appName": "Banqup",
  "deviceType": "PHONE"
}

A successful response (HTTP 202 Accepted) will return the notificationId confirming the push notification has been accepted for delivery.

Security​

Access to send push notifications is controlled by the push_notification_send security scope. All requests to the Push Notification Channel API must be authenticated using an OAuth security scheme and include a token with the required scope.

Authentication​

Security Scheme Type:

oauth2

OAuth Flow (clientCredentials):

Scopes:

  • info: Scopes are endpoint-specific, see each endpoint for required scope.

OAuth Flow (authorizationCode):

Scopes:

  • info: Scopes are endpoint-specific, see each endpoint for required scope.