# FCM Push Notifications — Frontend API Docs

Base URL: `https://borrowerapi.nextpayday.ng/api/v1`

---

## Overview

Push notifications use **Firebase Cloud Messaging (FCM)**. The mobile app registers a device token with the API; the server sends push on loan events, repayments, withdrawals, etc.

Channels per notification:
- **FCM push** (device banner / lock screen)
- **In-app inbox** (`GET /profile/notifications`)
- SMS + email (existing)

---

## 1. Register FCM token

### On login (recommended)

```
POST /auth/user/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "your_password",
  "fcm_token": "firebase_device_token_here"
}
```

`fcm_token` is optional. If sent, it is saved on the user record.

### Dedicated endpoint (token refresh)

Call after login and whenever Firebase rotates the token.

```
PUT /profile/fcm-token
Authorization: Bearer {token}
Content-Type: application/json

{
  "fcm_token": "firebase_device_token_here"
}
```

**Success `200`:**
```json
{
  "message": "FCM token updated successfully."
}
```

**Errors:** `401` unauthenticated, `422` missing/invalid token

### On signup

Already supported:

```
POST /auth/create-password
{ "signupToken": "...", "password": "...", "fcm_token": "..." }

POST /auth/user/register
{ ..., "fcm_token": "..." }
```

---

## 2. Logout — clear token

```
POST /auth/logout
Authorization: Bearer {token}
```

Server clears `fcm_token` so the device stops receiving pushes for that account.

---

## 3. Read in-app notification history

```
GET /profile/notifications?page=1
Authorization: Bearer {token}
```

**Response:**
```json
{
  "data": [
    {
      "id": "uuid",
      "title": "Loan Settled Successfully",
      "description": "Your loan LN-ABC has been settled...",
      "data": {
        "type": "loan_settlement",
        "loan_reference": "LN-ABC"
      },
      "read": false,
      "date": "2026-06-13 10:00:00"
    }
  ],
  "current_page": 1,
  "last_page": 1
}
```

Use `data.type` and `data.loan_reference` (etc.) for deep linking when user taps a notification.

---

## 4. FCM push payload (what mobile receives)

When the server sends push, the data map includes:

| Field | Example | Use |
|-------|---------|-----|
| `type` | `loan_settlement` | Route to screen |
| `loan_reference` | `LN-LIFVZBSIWR` | Open loan detail |
| `loan_id` | `2` | API calls |
| `installment_number` | `3` | Repayment context |

### `type` values

| `type` | Screen |
|--------|--------|
| `loan_settlement` | Loan detail (paid) |
| `loan_repayment` | Loan detail / schedule |
| `system` | Notifications inbox |

---

## 5. Flutter integration checklist

1. Add `firebase_core` + `firebase_messaging`
2. Request notification permission (iOS)
3. Get token: `FirebaseMessaging.instance.getToken()`
4. On login success → `POST /auth/user/login` with `fcm_token`
5. Listen `onTokenRefresh` → `PUT /profile/fcm-token`
6. On logout → `POST /auth/logout`
7. Handle `onMessage` (foreground) and `onMessageOpenedApp` (background tap)
8. Read `message.data['type']` for navigation

---

## 6. Server setup (ops)

Add to production `.env`:

```env
FIREBASE_ENABLED=true
FIREBASE_PROJECT_ID=your-firebase-project-id
FIREBASE_CREDENTIALS=storage/app/firebase/service-account.json
```

**Credentials file path (default):**

```
api/storage/app/firebase/service-account.json
```

1. Copy the template: `storage/app/firebase/service-account.json.example` → `service-account.json`
2. Replace placeholders with values from Firebase Console → Project settings → Service accounts → **Generate new private key**
3. `service-account.json` is gitignored — never commit real keys

If `FIREBASE_CREDENTIALS` is omitted, the API uses `storage/app/firebase/service-account.json` automatically.

If `FIREBASE_ENABLED=false`, SMS/email/in-app still work; push is skipped.

---

## Quick reference

```
POST /auth/user/login              optional fcm_token in body
PUT  /profile/fcm-token            save/refresh token (auth)
POST /auth/logout                  clears token (auth)
GET  /profile/notifications        in-app history (auth)
```