Send app notifications

United States
Canada
Europe
Latin America

The Clover app notification infrastructure allows you to send a message to a single instance of an app running on a merchant device or to all of them. You can also implement your own app notification system or use an external message delivery service.

Prerequisites

You must have the following unique identifiers to make REST API calls:

  • App ID and App Secret—Locate the App Secret and App ID on the Developer Dashboard > Your Apps > App name > App Settings.
  • Merchant identifier—Locate the merchantId on the Developer Dashboard > Businesses > Merchant Name. For the selected merchant, click Account & Setup > About Your Business > Merchants. MerchantId is the 13-alphanumeric identifier below the merchant name in the Merchant column.

Send a notification

Clover supports both app-level and device-level notifications. Device-level notifications are directed specifically to a single device.

The two POST endpoints are:

OperationDescription
/v3/apps/{aId}/merchants/{mId}/notificationsCreate a notification for an app
/v3/apps/{aId}/devices/{deviceId}/notificationsCreate a notification for a device. This endpoint requires the device ID.

🚧

IMPORTANT

During most Clover REST API calls, the authorization: Bearer header is set with auth_token. For /v3/apps/ endpoints, you must replace the auth_token with your app secret. You also use the mId when making REST API calls.

curl --request POST \
  --url https://apisandbox.dev.clover.com/v3/apps/{aId}/merchants/{mId}/notifications \
  --header 'accept: application/json' \  
  --header 'authorization: Bearer {app_secret}'
  --data '{"event":"test_notification","data":"New order created"}'

The fields in the JSON object in the payload are:

ParameterFormatDescription
event ()String, requiredNotification name specific to the app. This name uniquely identifies the notification.
timeToLiveLong, optionalTime in seconds for which the notification is available. The notification disappears after the time expires.
Default: 5 days (432000 seconds)
dataString, optionalPayload for the notification.
Length: Maximum 4000 characters

See the Notifications section of the REST API reference for more information. Sample of the basic body of the notification is as follows:

{
  "event": "test_notification",
  "data": "New order created"
}

📘

NOTE

An empty JSON response ({}) indicates that the message is queued for delivery.

Android example

protected Boolean doInBackground(Void... params) {
    try {
        // Your Notification model
        final NotificationData notificationData = new NotificationData();

        final CloverAuth.AuthResult authorization = CloverAuth.authenticate(context, CloverAccount.getAccount(context));
        final GenericUrl uri = new GenericUrl(authorization.baseUrl +
                "/v3/apps/" + authorization.appId +
                "/merchants/" + authorization.merchantId +
                "/notifications");

        final String jsonString = JSON_FACTORY.toString(notificationData);

        GenericJson json = new GenericJson();
        json.set("data", jsonString);
        json.set("event", NOTIFICATION_EVENT_NAME);
        final HttpContent httpContent = new JsonHttpContent(JSON_FACTORY, json);

        HttpHeaders headers = new HttpHeaders().setAuthorization("Bearer " + authorization.authToken);
        HttpResponse httpResponse = HTTP_TRANSPORT.createRequestFactory()
                .buildPostRequest(uri, httpContent)
                .setHeaders(headers)
                .execute();
        return httpResponse.isSuccessStatusCode();
    } catch (Exception e) {
        Log.e(this.getClass().getSimpleName(), e.getMessage(), e.fillInStackTrace());
    }
    return null;
}

See the Push Notification Example Code for more information.

Receive a notification

The Clover service handles the POST and pushes the message to the Clover Android Service running on each device that's currently online. The Clover Android Service processes the message and sends the following Intent to the app:

com.clover.sdk.app.intent.action.APP_NOTIFICATION

The app can handle the Intent with either: