# Update Primary Bank Account — Mobile API

Supports the **"Update Primary Bank Account"** screen: user picks a salary bank and enters an account number. The server resolves the account name via Paystack, saves to `bank_details`, and marks it as primary.

## Base URL

```
{API_HOST}/api/v1
```

```http
Authorization: Bearer {accessToken}
Content-Type: application/json
Accept: application/json
```

---

## 1. Bank picker — `GET /profile/banks/list`

Populates **"Select Salary Bank"**.

**Auth:** required

**Response `200`:** Array of Paystack banks (sorted A–Z).

```json
[
  {
    "id": 9,
    "name": "Guaranty Trust Bank",
    "slug": "guaranty-trust-bank",
    "code": "058",
    "active": true,
    "country": "Nigeria",
    "currency": "NGN",
    "type": "nuban"
  }
]
```

**Mobile mapping:**

| UI | API field |
|----|-----------|
| Dropdown label | `name` |
| Submit payload | `code` → send as `bank_code` |

---

## 2. Update primary — `PUT /profile/banks/primary`

**Auth:** required

### Request (salary bank form)

```json
{
  "bank_code": "058",
  "account_number": "0123456789",
  "bank_name": "Guaranty Trust Bank"
}
```

| Field | Required | Rules |
|-------|----------|-------|
| `bank_code` | yes | Paystack bank `code` from `/banks/list` |
| `account_number` | yes | Exactly 10 digits (NUBAN) |
| `bank_name` | no | Display name from dropdown; inferred from bank list if omitted |

### Success `200`

```json
{
  "message": "Primary salary bank account updated successfully.",
  "bank": {
    "id": 25,
    "bank_code": "058",
    "bank_name": "Guaranty Trust Bank",
    "account_number": "0123456789",
    "account_name": "JOHN DOE",
    "is_primary": 1,
    "is_active": 1
  }
}
```

Show `account_name` to confirm Paystack resolved the account.

### Errors

| Status | When |
|--------|------|
| `422` | Invalid account number length, or Paystack could not resolve account |
| `404` | Only when using legacy `bank_id` mode and id not found |

**Example `422`:**

```json
{
  "message": "Could not verify this bank account. Please check the account number and bank."
}
```

---

## 3. Read saved accounts — `GET /profile/banks`

**Auth:** required

```json
{
  "banks": [
    {
      "id": 25,
      "bank_code": "058",
      "bank_name": "Guaranty Trust Bank",
      "account_number": "0123456789",
      "account_name": "JOHN DOE",
      "is_primary": 1,
      "is_active": 1
    }
  ]
}
```

Primary salary account = row where `is_primary === 1`.

---

## Legacy mode — existing saved account

If the account is already in `bank_details`, you can set primary by id only:

```json
{
  "bank_id": 25
}
```

**Response `200`:**

```json
{
  "message": "Primary bank account updated to receive money",
  "bank_id": 25
}
```

---

## Mobile screen flow

```
1. GET /profile/banks/list
2. User selects bank + enters account number
3. PUT /profile/banks/primary  { bank_code, account_number, bank_name }
4. On 200 → show success + account_name from response
5. On 422 → show Paystack error message
```

---

## Server behaviour

1. Calls Paystack **Resolve Account Number** (`GET /bank/resolve`)
2. **Upserts** `bank_details` (same `bank_code` + `account_number` → update; else insert)
3. Sets `is_primary = 1` on that row; clears primary on all other user banks

---

## Dev / test notes (Paystack `sk_test_`)

- Use Paystack test bank code **`001`** with account **`0000000000`** when testing resolve in sandbox.
- Live bank codes hit a daily resolve limit on test keys.
- Production uses live keys and real bank codes from `/banks/list`.

---

## Quick reference

| Action | Method | Endpoint |
|--------|--------|----------|
| Bank dropdown | `GET` | `/profile/banks/list` |
| Update primary (form) | `PUT` | `/profile/banks/primary` |
| List accounts | `GET` | `/profile/banks` |
| Set primary by id | `PUT` | `/profile/banks/primary` + `{ "bank_id" }` |