Notification Inbox

Flow Summary

The current notification inbox flow is:

Step 1. Load the notification list
GET /api/v1/mobile_user/notifications

Step 2. Mark one notification as read
PATCH /api/v1/mobile_user/notifications/{id}/read

Step 3. Mark all notifications as read
PATCH /api/v1/mobile_user/notifications/read-all

Step 4. Refresh the unread badge count
GET /api/v1/mobile_user/notifications/unread-count

All routes below should be treated as protected routes and sent with:

Authorization: Bearer <access_token>

Notification Data Model

These inbox APIs return records from mobile_user_notifications.

Important current fields:

• notification_type uses the same transaction-style enum values used elsewhere in the backend, commonly:
  • CARD_REQUEST
  • TOP_UP
  • WITHDRAW
  • PURCHASE
  • FEE
  • REFUND
  • TRANSFER
  • RECEIVE
• status commonly uses:
  • PENDING
  • SUCCESS
  • FAILED
• title and content are translated at response time from the internal notification_key

Localization behavior

• Send Accept-Language: zh to get Chinese notification title/content when a translation exists
• If a translation key is missing, the handler falls back to the raw notification_key string for both title and content

1. List Notifications

GET /api/v1/mobile_user/notifications

Returns a paginated list of notifications for the authenticated mobile user.

Query parameters

Important backend behavior

• The list is scoped to the authenticated mobile user
• Results are always ordered by created_at DESC
• The handler applies localization after loading the rows

Success response shape

{
  "status_code": 200,
  "message": "Success",
  "data": [
    {
      "id": 81,
      "uuid": "0d65f58d-47f6-43d7-84b2-4bdc8d44e391",
      "card_id": 508,
      "notification_type": "TOP_UP",
      "status": "SUCCESS",
      "title": "Top up successful",
      "content": "Your card top up has completed successfully.",
      "source_id": 42,
      "is_read": false,
      "created_at": "2026-02-28T10:00:00Z",
      "updated_at": "2026-02-28T10:00:00Z"
    }
  ],
  "metadata": {
    "current_page": 1,
    "limit": 20,
    "total": 1
  }
}

2. Mark One Notification As Read

PATCH /api/v1/mobile_user/notifications/{id}/read

Marks one notification as read for the current mobile user.

Notes

• id is the local numeric notification row ID
• The lookup is scoped to the current mobile user, so another user's notification returns not found
• This is effectively idempotent: if the notification is already read, the handler still returns success and leaves the existing read_at unchanged

Success response shape

{
  "status_code": 200,
  "message": "Success",
  "data": {
    "id": 81,
    "is_read": true,
    "read_at": "2026-02-28T10:05:00Z"
  }
}

3. Mark All Notifications As Read

PATCH /api/v1/mobile_user/notifications/read-all

Marks every unread notification as read for the current mobile user.

Success response shape

{
  "status_code": 200,
  "message": "Success",
  "data": {
    "updated_count": 3
  }
}

Notes

• Only rows with read_at IS NULL are updated
• If everything is already read, the call still succeeds and returns updated_count: 0

4. Get Unread Count

GET /api/v1/mobile_user/notifications/unread-count

Returns the current unread notification badge count.

Success response shape

{
  "status_code": 200,
  "message": "Success",
  "data": {
    "unread_count": 5
  }
}

Integration Notes

1. Use the list endpoint for the inbox screen and pass is_read=false for an unread-only tab if needed.
2. Use read-all after a bulk “mark all read” action in the app.
3. Refresh unread-count after read actions to keep the badge in sync.