Card Favorites

Flow Summary

The current favorites flow is:

Step 1. Add a favorite destination card
POST /api/v1/mobile_user/favorites

Step 2. Load the saved favorites list
GET /api/v1/mobile_user/favorites

Step 3. Read, update, or delete one favorite
Use GET, PUT, or DELETE /api/v1/mobile_user/favorites/{uuid}

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

Authorization: Bearer <access_token>

1. Create Favorite

POST /api/v1/mobile_user/favorites

Saves one destination card as a favorite for the authenticated mobile user.

Request

{
  "card_number": "4111111111111111",
  "nickname": "Alice"
}

Request rules

• card_number is required
• card_number must be exactly 16 digits
• nickname is optional
• nickname can be up to 100 characters

Important backend behavior

• The route resolves the target card by card number
• The card number must belong to an active card that can be resolved by the backend lookup flow
• The current user cannot add their own card as a favorite
• The same destination card cannot be saved twice for the same user
• The stored card number is encrypted before persistence
• If a previously deleted favorite exists for the same user/card pair, the repo restores and updates that row instead of creating a separate duplicate

Success response

{
  "status_code": 200,
  "message": "Success",
  "data": {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "display_name": "Alice",
    "nickname": "Alice",
    "card_holder_name": "ALICE SOK",
    "card_number": "41111111****1111",
    "avatar_url": ""
  }
}

Common failures

• 401: missing or invalid mobile-user auth context
• 403: the user tries to add their own card as a favorite
• 404: incorrect card number or target card not found
• 409: the same favorite card already exists for the user

2. List Favorites

GET /api/v1/mobile_user/favorites

Returns the authenticated user's saved favorite cards with pagination.

Query parameters

Success response

{
  "status_code": 200,
  "message": "Success",
  "data": [
    {
      "uuid": "550e8400-e29b-41d4-a716-446655440000",
      "display_name": "Alice",
      "nickname": "Alice",
      "card_holder_name": "ALICE SOK",
      "card_number": "41111111****1111",
      "avatar_url": ""
    }
  ],
  "metadata": {
    "current_page": 1,
    "limit": 20,
    "total": 1
  }
}

Important backend behavior

• The list is scoped to the authenticated mobile user
• Results are ordered by created_at DESC
• The list response always returns masked card numbers, not the full plaintext card number
• display_name prefers nickname when present; otherwise it falls back to card_holder_name

3. Get Favorite Detail

GET /api/v1/mobile_user/favorites/{uuid}

Returns one favorite card entry for the authenticated mobile user.

Important backend behavior

• uuid must be a valid UUID
• The favorite must belong to the current mobile user
• Unlike the list endpoint, the detail response returns the full card number after backend decryption

Success response

{
  "status_code": 200,
  "message": "Success",
  "data": {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "display_name": "Alice",
    "card_holder_name": "ALICE SOK",
    "card_number": "4111111111111111",
    "nickname": "Alice",
    "avatar_url": ""
  }
}

Common failures

• 400: invalid favorite UUID
• 404: favorite not found for this user

4. Update Favorite

PUT /api/v1/mobile_user/favorites/{uuid}

Updates the target card number and/or nickname for one saved favorite.

Request

{
  "card_number": "4222222222222222",
  "nickname": "Alice New"
}

Important backend behavior

• uuid must be a valid UUID owned by the current user
• The replacement card must resolve to an active target card
• The current user still cannot point the favorite to their own card
• The update is rejected if another favorite row already uses the same destination card for the same user
• The updated detail response returns the full card number, not the masked form

Success response

The response shape matches GET /api/v1/mobile_user/favorites/{uuid}.

Common failures

• 400: invalid request body or invalid UUID
• 403: the user tries to favorite their own card
• 404: favorite not found or target card not found
• 409: another favorite already uses that card number

5. Delete Favorite

DELETE /api/v1/mobile_user/favorites/{uuid}

Deletes one saved favorite card for the authenticated mobile user.

Success response

{
  "status_code": 200,
  "message": "Success",
  "data": {
    "deleted": true
  }
}

Important backend behavior

• uuid must be a valid UUID
• The delete is scoped to the authenticated mobile user
• If the row is deleted successfully, the API returns deleted: true

Common failures

• 400: invalid favorite UUID
• 404: favorite not found for this user

Integration Notes

1. Use the create and update routes with a full 16-digit destination card number.
2. Treat the list response as a masked summary view only.
3. Use the detail route when the client needs the full stored card number for edit flows.
4. The same routes are also mirrored under /api/v2/mobile_user/favorites.