refactor: remove address fields from customer entity and related services

- Removed address-related fields from Customer entity, DTOs, and services to streamline KYC process.
- Updated KYC initiation and customer update logic to default to Saudi Arabia for country and use fixed address values.
- Added migration to drop address columns from the database.

src/auth/dtos/request/verify-user.request.dto.ts

@@ -1,7 +1,5 @@
 import { ApiProperty } from '@nestjs/swagger';
 import {
-  IsDateString,
-  IsEmail,
   IsEnum,
   IsNotEmpty,
   IsNumberString,
@@ -15,7 +13,7 @@ import { i18nValidationMessage as i18n } from 'nestjs-i18n';
 import { COUNTRY_CODE_REGEX, PASSWORD_REGEX } from '~/auth/constants';
 import { CountryIso } from '~/common/enums';
 import { DEFAULT_OTP_LENGTH } from '~/common/modules/otp/constants';
-import { IsAbove18, IsValidPhoneNumber } from '~/core/decorators/validations';
+import { IsValidPhoneNumber } from '~/core/decorators/validations';
 
 export class VerifyUserRequestDto {
   @ApiProperty({ example: '+962' })
@@ -39,11 +37,6 @@ export class VerifyUserRequestDto {
   @IsNotEmpty({ message: i18n('validation.IsNotEmpty', { path: 'general', property: 'customer.lastName' }) })
   lastName!: string;
 
-  @ApiProperty({ example: '2001-01-01' })
-  @IsDateString({}, { message: i18n('validation.IsDateString', { path: 'general', property: 'customer.dateOfBirth' }) })
-  @IsAbove18({ message: i18n('validation.IsAbove18', { path: 'general', property: 'customer.dateOfBirth' }) })
-  dateOfBirth!: Date;
-
   @ApiProperty({ example: 'JO' })
   @IsEnum(CountryIso, {
     message: i18n('validation.IsEnum', { path: 'general', property: 'customer.countryOfResidence' }),
@@ -51,10 +44,38 @@ export class VerifyUserRequestDto {
   @IsOptional()
   countryOfResidence: CountryIso = CountryIso.SAUDI_ARABIA;
 
-  @ApiProperty({ example: 'test@test.com' })
-  @IsEmail({}, { message: i18n('validation.IsEmail', { path: 'general', property: 'auth.email' }) })
+  // Address fields (optional during registration, required for card creation)
+  @ApiProperty({ example: 'SA', description: 'Country code', required: false })
+  @IsEnum(CountryIso, {
+    message: i18n('validation.IsEnum', { path: 'general', property: 'customer.country' }),
+  })
   @IsOptional()
-  email!: string;
+  country?: CountryIso;
+
+  @ApiProperty({ example: 'Riyadh', description: 'Region/Province', required: false })
+  @IsString({ message: i18n('validation.IsString', { path: 'general', property: 'customer.region' }) })
+  @IsOptional()
+  region?: string;
+
+  @ApiProperty({ example: 'Riyadh', description: 'City', required: false })
+  @IsString({ message: i18n('validation.IsString', { path: 'general', property: 'customer.city' }) })
+  @IsOptional()
+  city?: string;
+
+  @ApiProperty({ example: 'Al Olaya', description: 'Neighborhood/District', required: false })
+  @IsString({ message: i18n('validation.IsString', { path: 'general', property: 'customer.neighborhood' }) })
+  @IsOptional()
+  neighborhood?: string;
+
+  @ApiProperty({ example: 'King Fahd Road', description: 'Street name', required: false })
+  @IsString({ message: i18n('validation.IsString', { path: 'general', property: 'customer.street' }) })
+  @IsOptional()
+  street?: string;
+
+  @ApiProperty({ example: '123', description: 'Building number', required: false })
+  @IsString({ message: i18n('validation.IsString', { path: 'general', property: 'customer.building' }) })
+  @IsOptional()
+  building?: string;
 
   @ApiProperty({ example: 'Abcd1234@' })
   @Matches(PASSWORD_REGEX, {

src/auth/dtos/response/user.response.dto.ts

@@ -1,4 +1,5 @@
 import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
+import { Gender } from '~/customer/enums';
 import { DocumentMetaResponseDto } from '~/document/dtos/response';
 import { User } from '~/user/entities';
 
@@ -33,6 +34,10 @@ export class UserResponseDto {
   @ApiProperty()
   isEmailVerified!: boolean;
 
+  @ApiPropertyOptional({ enum: Gender, nullable: true })
+  gender!: Gender | null;
+
+
   constructor(user: User) {
     this.id = user.id;
     this.countryCode = user.countryCode;
@@ -44,5 +49,6 @@ export class UserResponseDto {
     this.profilePicture = user.profilePicture ? new DocumentMetaResponseDto(user.profilePicture) : null;
     this.isEmailVerified = user.isEmailVerified;
     this.isPhoneVerified = user.isPhoneVerified;
+    this.gender = (user.customer?.gender as Gender) || null;
   }
 }

src/auth/services/auth.service.ts

@@ -41,14 +41,6 @@ export class AuthService {
   ) {}
 
   async sendRegisterOtp(body: CreateUnverifiedUserRequestDto) {
-    if (body.email) {
-      const isEmailUsed = await this.userService.findUser({ email: body.email, isEmailVerified: true });
-      if (isEmailUsed) {
-        this.logger.error(`Email ${body.email} is already used`);
-        throw new BadRequestException('USER.EMAIL_ALREADY_TAKEN');
-      }
-    }
-
     if (body.password !== body.confirmPassword) {
       this.logger.error('Password and confirm password do not match');
       throw new BadRequestException('AUTH.PASSWORD_MISMATCH');

src/card/controllers/cards.controller.ts

@@ -34,6 +34,15 @@ export class CardsController {
     return ResponseFactory.data(cards.map((card) => new ChildCardResponseDto(card)));
   }
 
+  @Get('child-cards/:childid')
+  @UseGuards(RolesGuard)
+  @AllowedRoles(Roles.GUARDIAN)
+  @ApiDataResponse(ChildCardResponseDto)
+  async getChildCardById(@Param('childid') childId: string, @AuthenticatedUser() { sub }: IJwtPayload) {
+    const card = await this.cardService.getCardByChildId(sub, childId);
+    return ResponseFactory.data(new ChildCardResponseDto(card));
+  }
+
   @Get('child-cards/:cardid/embossing-details')
   @UseGuards(RolesGuard)
   @AllowedRoles(Roles.GUARDIAN)

src/card/dtos/responses/card.response.dto.ts

@@ -58,7 +58,9 @@ export class CardResponseDto {
     this.status = card.status;
     this.statusDescription = CardStatusDescriptionMapper[card.statusDescription][UserLocale.ENGLISH].description;
     this.balance =
-      card.customerType === CustomerType.CHILD ? Math.min(card.limit, card.account.balance) : card.account.balance;
+      card.customerType === CustomerType.CHILD
+        ? Math.min(card.limit, card.account.balance)
+        : card.account.balance - card.account.reservedBalance;
     this.reservedBalance = card.customerType === CustomerType.PARENT ? card.account.reservedBalance : null;
   }
 }

src/card/dtos/responses/child-transfer-item.response.dto.ts

@@ -0,0 +1,16 @@
+import { ApiProperty } from '@nestjs/swagger';
+
+export class ChildTransferItemDto {
+  @ApiProperty({ example: '2025-10-14T09:53:40.000Z' })
+  date!: Date;
+
+  @ApiProperty({ example: 50.0 })
+  amount!: number;
+
+  @ApiProperty({ example: 'SAR' })
+  currency!: string;
+
+  @ApiProperty({ example: 'You received {{amount}} {{currency}} from your parent.' })
+  message!: string;
+}
+

src/card/dtos/responses/guardian-home.response.dto.ts

@@ -0,0 +1,17 @@
+import { ApiProperty } from '@nestjs/swagger';
+import { TransactionItemResponseDto } from './transaction-item.response.dto';
+
+export class GuardianHomeResponseDto {
+  @ApiProperty({ example: 2000.0 })
+  availableBalance!: number;
+
+  @ApiProperty({ type: [TransactionItemResponseDto] })
+  recentTransactions!: TransactionItemResponseDto[];
+
+  constructor(availableBalance: number, recentTransactions: TransactionItemResponseDto[]) {
+    this.availableBalance = availableBalance;
+    this.recentTransactions = recentTransactions;
+  }
+}
+
+

src/card/dtos/responses/index.ts

@@ -1,3 +1,15 @@
 export * from './account-iban.response.dto';
 export * from './card.response.dto';
 export * from './child-card.response.dto';
+export * from './transaction-item.response.dto';
+export * from './guardian-home.response.dto';
+export * from './paged-transactions.response.dto';
+export * from './parent-transfer-item.response.dto';
+export * from './parent-home.response.dto';
+export * from './paged-parent-transfers.response.dto';
+export * from './child-transfer-item.response.dto';
+export * from './junior-home.response.dto';
+export * from './paged-child-transfers.response.dto';
+export * from './spending-history-item.response.dto';
+export * from './spending-history.response.dto';
+export * from './transaction-detail.response.dto';

src/card/dtos/responses/junior-home.response.dto.ts

@@ -0,0 +1,16 @@
+import { ApiProperty } from '@nestjs/swagger';
+import { ChildTransferItemDto } from './child-transfer-item.response.dto';
+
+export class JuniorHomeResponseDto {
+  @ApiProperty({ example: 500.0 })
+  availableBalance!: number;
+
+  @ApiProperty({ type: [ChildTransferItemDto] })
+  recentTransfers!: ChildTransferItemDto[];
+
+  constructor(availableBalance: number, recentTransfers: ChildTransferItemDto[]) {
+    this.availableBalance = availableBalance;
+    this.recentTransfers = recentTransfers;
+  }
+}
+

src/card/dtos/responses/paged-child-transfers.response.dto.ts

@@ -0,0 +1,33 @@
+import { ApiProperty } from '@nestjs/swagger';
+import { ChildTransferItemDto } from './child-transfer-item.response.dto';
+
+export class PagedChildTransfersResponseDto {
+  @ApiProperty({ type: [ChildTransferItemDto] })
+  items!: ChildTransferItemDto[];
+
+  @ApiProperty({ example: 1 })
+  page!: number;
+
+  @ApiProperty({ example: 10 })
+  size!: number;
+
+  @ApiProperty({ example: 20 })
+  total!: number;
+
+  @ApiProperty({ example: true })
+  hasMore!: boolean;
+
+  constructor(
+    items: ChildTransferItemDto[],
+    page: number,
+    size: number,
+    total: number,
+  ) {
+    this.items = items;
+    this.page = page;
+    this.size = size;
+    this.total = total;
+    this.hasMore = page * size < total;
+  }
+}
+

src/card/dtos/responses/paged-parent-transfers.response.dto.ts

@@ -0,0 +1,33 @@
+import { ApiProperty } from '@nestjs/swagger';
+import { ParentTransferItemDto } from './parent-transfer-item.response.dto';
+
+export class PagedParentTransfersResponseDto {
+  @ApiProperty({ type: [ParentTransferItemDto] })
+  items!: ParentTransferItemDto[];
+
+  @ApiProperty({ example: 1 })
+  page!: number;
+
+  @ApiProperty({ example: 10 })
+  size!: number;
+
+  @ApiProperty({ example: 45 })
+  total!: number;
+
+  @ApiProperty({ example: true })
+  hasMore!: boolean;
+
+  constructor(
+    items: ParentTransferItemDto[],
+    page: number,
+    size: number,
+    total: number,
+  ) {
+    this.items = items;
+    this.page = page;
+    this.size = size;
+    this.total = total;
+    this.hasMore = page * size < total;
+  }
+}
+

src/card/dtos/responses/paged-transactions.response.dto.ts

@@ -0,0 +1,33 @@
+import { ApiProperty } from '@nestjs/swagger';
+import { TransactionItemResponseDto } from './transaction-item.response.dto';
+
+export class PagedTransactionsResponseDto {
+  @ApiProperty({ type: [TransactionItemResponseDto] })
+  items!: TransactionItemResponseDto[];
+
+  @ApiProperty({ example: 1 })
+  page!: number;
+
+  @ApiProperty({ example: 10 })
+  size!: number;
+
+  @ApiProperty({ example: 45 })
+  total!: number;
+
+  @ApiProperty({ example: true })
+  hasMore!: boolean;
+
+  constructor(
+    items: TransactionItemResponseDto[],
+    page: number,
+    size: number,
+    total: number,
+  ) {
+    this.items = items;
+    this.page = page;
+    this.size = size;
+    this.total = total;
+    this.hasMore = page * size < total;
+  }
+}
+

src/card/dtos/responses/parent-home.response.dto.ts

@@ -0,0 +1,16 @@
+import { ApiProperty } from '@nestjs/swagger';
+import { ParentTransferItemDto } from './parent-transfer-item.response.dto';
+
+export class ParentHomeResponseDto {
+  @ApiProperty({ example: 2000.0 })
+  availableBalance!: number;
+
+  @ApiProperty({ type: [ParentTransferItemDto] })
+  recentTransfers!: ParentTransferItemDto[];
+
+  constructor(availableBalance: number, recentTransfers: ParentTransferItemDto[]) {
+    this.availableBalance = availableBalance;
+    this.recentTransfers = recentTransfers;
+  }
+}
+

src/card/dtos/responses/parent-transfer-item.response.dto.ts

@@ -0,0 +1,16 @@
+import { ApiProperty } from '@nestjs/swagger';
+
+export class ParentTransferItemDto {
+  @ApiProperty({ example: '2025-10-14T09:53:40.000Z' })
+  date!: Date;
+
+  @ApiProperty({ example: 50.0 })
+  amount!: number;
+
+  @ApiProperty({ example: 'SAR' })
+  currency!: string;
+
+  @ApiProperty({ example: 'Ahmed Ali' })
+  childName!: string;
+}
+

src/card/dtos/responses/spending-history-item.response.dto.ts

@@ -0,0 +1,58 @@
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
+import { Transaction } from '~/card/entities/transaction.entity';
+
+export class SpendingHistoryItemDto {
+  @ApiProperty({ example: '2025-10-14T09:53:40.000Z' })
+  date!: Date;
+
+  @ApiProperty({ example: 50.5 })
+  amount!: number;
+
+  @ApiProperty({ example: 'SAR' })
+  currency!: string;
+
+  @ApiPropertyOptional({ example: 'Shopping' })
+  category!: string | null;
+
+  @ApiPropertyOptional({ example: 'Target Store' })
+  merchantName!: string | null;
+
+  @ApiPropertyOptional({ example: 'Riyadh' })
+  merchantCity!: string | null;
+
+  @ApiProperty({ example: '277012*****3456' })
+  cardMasked!: string;
+
+  @ApiProperty()
+  transactionId!: string;
+
+  constructor(transaction: Transaction) {
+    this.date = transaction.transactionDate;
+    this.amount = transaction.transactionAmount;
+    this.currency = transaction.transactionCurrency === '682' ? 'SAR' : transaction.transactionCurrency;
+    this.category = this.mapMccToCategory(transaction.merchantCategoryCode);
+    this.merchantName = transaction.merchantName;
+    this.merchantCity = transaction.merchantCity;
+    this.cardMasked = transaction.cardMaskedNumber;
+    this.transactionId = transaction.id;
+  }
+
+  private mapMccToCategory(mcc: string | null): string {
+    if (!mcc) return 'Other';
+    
+    const mccCode = mcc;
+    
+    // Map MCC codes to categories
+    if (mccCode >= '5200' && mccCode <= '5599') return 'Shopping';
+    if (mccCode >= '5800' && mccCode <= '5899') return 'Food & Dining';
+    if (mccCode >= '3000' && mccCode <= '3999') return 'Travel';
+    if (mccCode >= '4000' && mccCode <= '4799') return 'Transportation';
+    if (mccCode >= '7200' && mccCode <= '7999') return 'Entertainment';
+    if (mccCode >= '5900' && mccCode <= '5999') return 'Services';
+    if (mccCode >= '4800' && mccCode <= '4899') return 'Utilities';
+    if (mccCode >= '8000' && mccCode <= '8999') return 'Health & Wellness';
+    
+    return 'Other';
+  }
+}
+

src/card/dtos/responses/spending-history.response.dto.ts

@@ -0,0 +1,24 @@
+import { ApiProperty } from '@nestjs/swagger';
+import { SpendingHistoryItemDto } from './spending-history-item.response.dto';
+
+export class SpendingHistoryResponseDto {
+  @ApiProperty({ type: [SpendingHistoryItemDto] })
+  transactions!: SpendingHistoryItemDto[];
+
+  @ApiProperty({ example: 150.75 })
+  totalSpent!: number;
+
+  @ApiProperty({ example: 'SAR' })
+  currency!: string;
+
+  @ApiProperty({ example: 10 })
+  count!: number;
+
+  constructor(transactions: SpendingHistoryItemDto[], currency: string = 'SAR') {
+    this.transactions = transactions;
+    this.totalSpent = transactions.reduce((sum, tx) => sum + tx.amount, 0);
+    this.currency = currency;
+    this.count = transactions.length;
+  }
+}
+

src/card/dtos/responses/transaction-detail.response.dto.ts

@@ -0,0 +1,74 @@
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
+import { Transaction } from '~/card/entities/transaction.entity';
+
+export class TransactionDetailResponseDto {
+  @ApiProperty()
+  id!: string;
+
+  @ApiProperty({ example: '2025-10-14T09:53:40.000Z' })
+  date!: Date;
+
+  @ApiProperty({ example: 50.5 })
+  amount!: number;
+
+  @ApiProperty({ example: 'SAR' })
+  currency!: string;
+
+  @ApiProperty({ example: 2.5 })
+  fees!: number;
+
+  @ApiProperty({ example: 0.5 })
+  vatOnFees!: number;
+
+  @ApiPropertyOptional({ example: 'Target Store' })
+  merchantName!: string | null;
+
+  @ApiPropertyOptional({ example: 'Shopping' })
+  category!: string | null;
+
+  @ApiPropertyOptional({ example: 'Riyadh' })
+  merchantCity!: string | null;
+
+  @ApiProperty({ example: '277012*****3456' })
+  cardMasked!: string;
+
+  @ApiProperty()
+  rrn!: string;
+
+  @ApiProperty()
+  transactionId!: string;
+
+  constructor(transaction: Transaction) {
+    this.id = transaction.id;
+    this.date = transaction.transactionDate;
+    this.amount = transaction.transactionAmount;
+    this.currency = transaction.transactionCurrency === '682' ? 'SAR' : transaction.transactionCurrency;
+    this.fees = transaction.fees;
+    this.vatOnFees = transaction.vatOnFees;
+    this.merchantName = transaction.merchantName;
+    this.category = this.mapMccToCategory(transaction.merchantCategoryCode);
+    this.merchantCity = transaction.merchantCity;
+    this.cardMasked = transaction.cardMaskedNumber;
+    this.rrn = transaction.rrn;
+    this.transactionId = transaction.transactionId;
+  }
+
+  private mapMccToCategory(mcc: string | null): string {
+    if (!mcc) return 'Other';
+    
+    const mccCode = mcc;
+    
+    // Map MCC codes to categories
+    if (mccCode >= '5200' && mccCode <= '5599') return 'Shopping';
+    if (mccCode >= '5800' && mccCode <= '5899') return 'Food & Dining';
+    if (mccCode >= '3000' && mccCode <= '3999') return 'Travel';
+    if (mccCode >= '4000' && mccCode <= '4799') return 'Transportation';
+    if (mccCode >= '7200' && mccCode <= '7999') return 'Entertainment';
+    if (mccCode >= '5900' && mccCode <= '5999') return 'Services';
+    if (mccCode >= '4800' && mccCode <= '4899') return 'Utilities';
+    if (mccCode >= '8000' && mccCode <= '8999') return 'Health & Wellness';
+    
+    return 'Other';
+  }
+}
+

src/card/dtos/responses/transaction-item.response.dto.ts

@@ -0,0 +1,24 @@
+import { ApiProperty } from '@nestjs/swagger';
+import { ParentTransactionType } from '~/card/enums';
+
+export class TransactionItemResponseDto {
+  @ApiProperty()
+  date!: Date;
+
+  @ApiProperty({ example: -50.0 })
+  amountSigned!: number;
+
+  @ApiProperty({ enum: ParentTransactionType })
+  type!: ParentTransactionType;
+
+  @ApiProperty({ description: 'Counterparty display name (child for transfer, source label for top-up)' })
+  counterpartyName!: string;
+
+  @ApiProperty({ nullable: true })
+  counterpartyAccountMasked!: string | null;
+
+  @ApiProperty({ required: false })
+  childName?: string;
+}
+
+

src/card/entities/account.entity.ts

@@ -22,10 +22,28 @@ export class Account {
   @Column('varchar', { length: 255, nullable: false, name: 'currency' })
   currency!: string;
 
-  @Column('decimal', { precision: 10, scale: 2, default: 0.0, name: 'balance' })
+  @Column('decimal', {
+    precision: 10,
+    scale: 2,
+    default: 0.0,
+    name: 'balance',
+    transformer: {
+      to: (value: number) => value,
+      from: (value: string) => parseFloat(value),
+    },
+  })
   balance!: number;
 
-  @Column('decimal', { precision: 10, scale: 2, default: 0.0, name: 'reserved_balance' })
+  @Column('decimal', {
+    precision: 10,
+    scale: 2,
+    default: 0.0,
+    name: 'reserved_balance',
+    transformer: {
+      to: (value: number) => value,
+      from: (value: string) => parseFloat(value),
+    },
+  })
   reservedBalance!: number;
 
   @OneToMany(() => Card, (card) => card.account, { cascade: true })

src/card/entities/transaction.entity.ts

@@ -32,7 +32,16 @@ export class Transaction {
   @Column({ name: 'rrn', nullable: true, type: 'varchar' })
   rrn!: string;
 
-  @Column({ type: 'decimal', precision: 12, scale: 2, name: 'transaction_amount' })
+  @Column({
+    type: 'decimal',
+    precision: 12,
+    scale: 2,
+    name: 'transaction_amount',
+    transformer: {
+      to: (value: number) => value,
+      from: (value: string) => parseFloat(value),
+    },
+  })
   transactionAmount!: number;
 
   @Column({ type: 'varchar', name: 'transaction_currency' })
@@ -50,6 +59,15 @@ export class Transaction {
   @Column({ type: 'decimal', name: 'vat_on_fees', precision: 12, scale: 2, default: 0.0 })
   vatOnFees!: number;
 
+  @Column({ name: 'merchant_name', type: 'varchar', nullable: true })
+  merchantName!: string | null;
+
+  @Column({ name: 'merchant_category_code', type: 'varchar', nullable: true })
+  merchantCategoryCode!: string | null;
+
+  @Column({ name: 'merchant_city', type: 'varchar', nullable: true })
+  merchantCity!: string | null;
+
   @Column({ name: 'card_id', type: 'uuid', nullable: true })
   cardId!: string;
 

src/card/enums/index.ts

@@ -6,3 +6,4 @@ export * from './card-status.enum';
 export * from './customer-type.enum';
 export * from './transaction-scope.enum';
 export * from './transaction-type.enum';
+export * from './parent-transaction-type.enum';

src/card/enums/parent-transaction-type.enum.ts

@@ -0,0 +1,6 @@
+export enum ParentTransactionType {
+  PARENT_TRANSFER = 'PARENT_TRANSFER',
+  PARENT_TOPUP = 'PARENT_TOPUP',
+}
+
+

src/card/repositories/card.repository.ts

@@ -45,6 +45,13 @@ export class CardRepository {
     return this.cardRepository.findOne({ where: { id }, relations: ['account'] });
   }
 
+  findCardByChildId(guardianId: string, childId: string): Promise<Card | null> {
+    return this.cardRepository.findOne({
+      where: { parentId: guardianId, customerId: childId, customerType: CustomerType.CHILD },
+      relations: ['account', 'customer', 'customer.user', 'customer.user.profilePicture', 'customer.junior'],
+    });
+  }
+
   getCardByReferenceNumber(referenceNumber: string): Promise<Card | null> {
     return this.cardRepository.findOne({ where: { cardReference: referenceNumber }, relations: ['account'] });
   }

src/card/repositories/index.ts

@@ -1 +1,3 @@
 export * from './card.repository';
+export * from './transaction.repository';
+export * from './account.repository';

src/card/repositories/transaction.repository.ts

@@ -34,6 +34,9 @@ export class TransactionRepository {
         accountReference: card.account!.accountReference,
         transactionScope: TransactionScope.CARD,
         vatOnFees: transactionData.vatOnFees,
+        merchantName: transactionData.cardAcceptorLocation?.merchantName || null,
+        merchantCategoryCode: transactionData.cardAcceptorLocation?.mcc || null,
+        merchantCity: transactionData.cardAcceptorLocation?.merchantCity || null,
       }),
     );
   }
@@ -84,4 +87,97 @@ export class TransactionRepository {
       where: { transactionId, accountReference },
     });
   }
+
+  getTransactionsForCardWithinDateRange(juniorId: string, startDate: Date, endDate: Date): Promise<Transaction[]> {
+    return this.transactionRepository
+      .createQueryBuilder('transaction')
+      .innerJoinAndSelect('transaction.card', 'card')
+      .where('card.customerId = :juniorId', { juniorId })
+      .andWhere('transaction.transactionScope = :scope', { scope: TransactionScope.CARD })
+      .andWhere('transaction.transactionType = :type', { type: TransactionType.EXTERNAL })
+      .andWhere('transaction.transactionDate BETWEEN :startDate AND :endDate', { startDate, endDate })
+      .orderBy('transaction.transactionDate', 'DESC')
+      .getMany();
+  }
+
+  findParentTransfers(guardianCustomerId: string, skip: number, take: number): Promise<Transaction[]> {
+    return this.transactionRepository
+      .createQueryBuilder('tx')
+      .innerJoinAndSelect('tx.card', 'card')
+      .innerJoinAndSelect('card.customer', 'childCustomer')
+      .innerJoinAndSelect('card.account', 'account')
+      .where('card.parentId = :guardianCustomerId', { guardianCustomerId })
+      .andWhere('tx.transactionScope = :scope', { scope: TransactionScope.CARD })
+      .andWhere('tx.transactionType = :type', { type: TransactionType.INTERNAL })
+      .orderBy('tx.transactionDate', 'DESC')
+      .skip(skip)
+      .take(take)
+      .getMany();
+  }
+
+  findParentTopups(guardianCustomerId: string, skip: number, take: number): Promise<Transaction[]> {
+    return this.transactionRepository
+      .createQueryBuilder('tx')
+      .innerJoinAndSelect('tx.account', 'account')
+      .leftJoinAndSelect('account.cards', 'parentCards')
+      .where('tx.transactionScope = :scope', { scope: TransactionScope.ACCOUNT })
+      .andWhere('parentCards.customerId = :guardianCustomerId', { guardianCustomerId })
+      .orderBy('tx.transactionDate', 'DESC')
+      .skip(skip)
+      .take(take)
+      .getMany();
+  }
+
+  countParentTransfers(guardianCustomerId: string): Promise<number> {
+    return this.transactionRepository
+      .createQueryBuilder('tx')
+      .innerJoin('tx.card', 'card')
+      .where('card.parentId = :guardianCustomerId', { guardianCustomerId })
+      .andWhere('tx.transactionScope = :scope', { scope: TransactionScope.CARD })
+      .andWhere('tx.transactionType = :type', { type: TransactionType.INTERNAL })
+      .getCount();
+  }
+
+  countParentTopups(guardianCustomerId: string): Promise<number> {
+    return this.transactionRepository
+      .createQueryBuilder('tx')
+      .innerJoin('tx.account', 'account')
+      .leftJoin('account.cards', 'parentCards')
+      .where('tx.transactionScope = :scope', { scope: TransactionScope.ACCOUNT })
+      .andWhere('parentCards.customerId = :guardianCustomerId', { guardianCustomerId })
+      .getCount();
+  }
+
+  findTransfersToJunior(juniorId: string, skip: number, take: number): Promise<Transaction[]> {
+    return this.transactionRepository
+      .createQueryBuilder('tx')
+      .innerJoinAndSelect('tx.card', 'card')
+      .innerJoinAndSelect('card.account', 'account')
+      .where('card.customerId = :juniorId', { juniorId })
+      .andWhere('tx.transactionScope = :scope', { scope: TransactionScope.CARD })
+      .andWhere('tx.transactionType = :type', { type: TransactionType.INTERNAL })
+      .orderBy('tx.transactionDate', 'DESC')
+      .skip(skip)
+      .take(take)
+      .getMany();
+  }
+
+  countTransfersToJunior(juniorId: string): Promise<number> {
+    return this.transactionRepository
+      .createQueryBuilder('tx')
+      .innerJoin('tx.card', 'card')
+      .where('card.customerId = :juniorId', { juniorId })
+      .andWhere('tx.transactionScope = :scope', { scope: TransactionScope.CARD })
+      .andWhere('tx.transactionType = :type', { type: TransactionType.INTERNAL })
+      .getCount();
+  }
+
+  findTransactionById(transactionId: string, juniorId: string): Promise<Transaction | null> {
+    return this.transactionRepository
+      .createQueryBuilder('tx')
+      .innerJoinAndSelect('tx.card', 'card')
+      .where('tx.id = :transactionId', { transactionId })
+      .andWhere('card.customerId = :juniorId', { juniorId })
+      .getOne();
+  }
 }

src/card/services/account.service.ts

@@ -64,9 +64,8 @@ export class AccountService {
   }
 
   increaseReservedBalance(account: Account, amount: number) {
-    if (account.balance < account.reservedBalance + amount) {
-      throw new UnprocessableEntityException('ACCOUNT.INSUFFICIENT_BALANCE');
-    }
+    // Balance check is performed by the caller (e.g., transferToChild)
+    // to ensure correct account (guardian vs child) is validated
     return this.accountRepository.increaseReservedBalance(account.id, amount);
   }
 

src/card/services/card.service.ts

@@ -34,10 +34,26 @@ export class CardService {
       throw new BadRequestException('CUSTOMER.KYC_NOT_APPROVED');
     }
 
+    if (!customer.neoleapExternalCustomerId) {
+      throw new BadRequestException('CUSTOMER.KYC_NOT_COMPLETED');
+    }
+
     if (customer.cards.length > 0) {
       throw new BadRequestException('CUSTOMER.ALREADY_HAS_CARD');
     }
 
+    // Validate required fields for card creation
+    const missingFields = [];
+    if (!customer.nationalId) missingFields.push('nationalId');
+    if (!customer.dateOfBirth) missingFields.push('dateOfBirth');
+    if (!customer.nationalIdExpiry) missingFields.push('nationalIdExpiry');
+
+    if (missingFields.length > 0) {
+      throw new BadRequestException(
+        `CUSTOMER.MISSING_REQUIRED_FIELDS: ${missingFields.join(', ')}. Please complete your profile.`
+      );
+    }
+
     const data = await this.neoleapService.createApplication(customer);
     const account = await this.accountService.createAccount(data);
     const createdCard = await this.cardRepository.createCard(customerId, account.id, data);
@@ -63,6 +79,15 @@ export class CardService {
 
     return this.getCardById(createdCard.id);
   }
+
+  async getCardByChildId(guardianId: string, childId: string): Promise<Card> {
+    const card = await this.cardRepository.findCardByChildId(guardianId, childId);
+    if (!card) {
+      throw new BadRequestException('CARD.NOT_FOUND');
+    }
+    await this.prepareJuniorImages([card]);
+    return card;
+  }
   async getCardById(id: string): Promise<Card> {
     const card = await this.cardRepository.getCardById(id);
 
@@ -139,7 +164,18 @@ export class CardService {
   async transferToChild(juniorId: string, amount: number) {
     const card = await this.getCardByCustomerId(juniorId);
 
-    if (amount > card.account.balance - card.account.reservedBalance) {
+    this.logger.debug(`Transfer to child - juniorId: ${juniorId}, parentId: ${card.parentId}, cardId: ${card.id}`);
+    this.logger.debug(`Card account - balance: ${card.account.balance}, reserved: ${card.account.reservedBalance}`);
+
+    const fundingAccount = card.parentId
+      ? await this.accountService.getAccountByCustomerId(card.parentId)
+      : card.account;
+
+    this.logger.debug(`Funding account - balance: ${fundingAccount.balance}, reserved: ${fundingAccount.reservedBalance}, available: ${fundingAccount.balance - fundingAccount.reservedBalance}`);
+    this.logger.debug(`Amount requested: ${amount}`);
+
+    if (amount > fundingAccount.balance - fundingAccount.reservedBalance) {
+      this.logger.error(`Insufficient balance - requested: ${amount}, available: ${fundingAccount.balance - fundingAccount.reservedBalance}`);
       throw new BadRequestException('CARD.INSUFFICIENT_BALANCE');
     }
 
@@ -147,13 +183,17 @@ export class CardService {
     await Promise.all([
       this.neoleapService.updateCardControl(card.cardReference, finalAmount.toNumber()),
       this.updateCardLimit(card.id, finalAmount.toNumber()),
-      this.accountService.increaseReservedBalance(card.account, amount),
+      this.accountService.increaseReservedBalance(fundingAccount, amount),
       this.transactionService.createInternalChildTransaction(card.id, amount),
     ]);
 
     return finalAmount.toNumber();
   }
 
+  getWeeklySummary(juniorId: string, startDate?: Date, endDate?: Date) {
+    return this.transactionService.getWeeklySummary(juniorId, startDate, endDate);
+  }
+
   fundIban(iban: string, amount: number) {
     return this.accountService.fundIban(iban, amount);
   }

src/card/services/index.ts

@@ -1 +1,3 @@
 export * from './card.service';
+export * from './transaction.service';
+export * from './account.service';

src/card/services/transaction.service.ts

@@ -1,15 +1,25 @@
 import { forwardRef, Inject, Injectable, UnprocessableEntityException } from '@nestjs/common';
 import Decimal from 'decimal.js';
+import moment from 'moment';
 import { Transactional } from 'typeorm-transactional';
 import {
   AccountTransactionWebhookRequest,
   CardTransactionWebhookRequest,
 } from '~/common/modules/neoleap/dtos/requests';
 import { Transaction } from '../entities/transaction.entity';
-import { CustomerType } from '../enums';
+import { CustomerType, TransactionType } from '../enums';
 import { TransactionRepository } from '../repositories/transaction.repository';
 import { AccountService } from './account.service';
 import { CardService } from './card.service';
+import {
+  TransactionItemResponseDto,
+  PagedTransactionsResponseDto,
+  ParentTransferItemDto,
+  PagedParentTransfersResponseDto,
+  ChildTransferItemDto,
+  PagedChildTransfersResponseDto,
+} from '../dtos/responses';
+import { ParentTransactionType } from '../enums';
 
 @Injectable()
 export class TransactionService {
@@ -32,10 +42,18 @@ export class TransactionService {
     const total = new Decimal(body.transactionAmount).plus(body.billingAmount).plus(body.fees).plus(body.vatOnFees);
 
     if (card.customerType === CustomerType.CHILD) {
-      await Promise.all([
-        this.accountService.decreaseAccountBalance(card.account.accountReference, total.toNumber()),
-        this.accountService.decrementReservedBalance(card.account, total.toNumber()),
-      ]);
+      if (card.parentId) {
+        const parentAccount = await this.accountService.getAccountByCustomerId(card.parentId);
+        await Promise.all([
+          this.accountService.decreaseAccountBalance(parentAccount.accountReference, total.toNumber()),
+          this.accountService.decrementReservedBalance(parentAccount, total.toNumber()),
+        ]);
+      } else {
+        await Promise.all([
+          this.accountService.decreaseAccountBalance(card.account.accountReference, total.toNumber()),
+          this.accountService.decrementReservedBalance(card.account, total.toNumber()),
+        ]);
+      }
     } else {
       await this.accountService.decreaseAccountBalance(card.account.accountReference, total.toNumber());
     }
@@ -73,4 +91,233 @@ export class TransactionService {
 
     return existingTransaction;
   }
+
+  async getWeeklySummary(juniorId: string, startDate?: Date, endDate?: Date) {
+    let startOfWeek: Date;
+    let endOfWeek: Date;
+
+    if (startDate && endDate) {
+      startOfWeek = startDate;
+      endOfWeek = endDate;
+    } else {
+      const now = moment();
+      const dayOfWeek = now.day();
+      
+      startOfWeek = moment().subtract(dayOfWeek, 'days').startOf('day').toDate();
+      
+      endOfWeek = moment().add(6 - dayOfWeek, 'days').endOf('day').toDate();
+    }
+
+    const transactions = await this.transactionRepository.getTransactionsForCardWithinDateRange(
+      juniorId,
+      startOfWeek,
+      endOfWeek,
+    );
+    
+    const summary = {
+      startOfWeek: startOfWeek,
+      endOfWeek: endOfWeek,
+      total: 0,
+      monday: 0,
+      tuesday: 0,
+      wednesday: 0,
+      thursday: 0,
+      friday: 0,
+      saturday: 0,
+      sunday: 0,
+    };
+
+    transactions.forEach((transaction) => {
+      const day = moment(transaction.transactionDate).format('dddd').toLowerCase() as
+        | 'monday'
+        | 'tuesday'
+        | 'wednesday'
+        | 'thursday'
+        | 'friday'
+        | 'saturday'
+        | 'sunday';
+      summary[day] += transaction.transactionAmount;
+    });
+
+    summary.total = transactions.reduce((acc, curr) => acc + curr.transactionAmount, 0);
+
+    return summary;
+  }
+
+  async getParentConsolidated(
+    guardianCustomerId: string,
+    page: number,
+    size: number,
+  ): Promise<TransactionItemResponseDto[]> {
+    const skip = (page - 1) * size;
+
+    const [transfers, topups] = await Promise.all([
+      this.transactionRepository.findParentTransfers(guardianCustomerId, skip, size),
+      this.transactionRepository.findParentTopups(guardianCustomerId, skip, size),
+    ]);
+
+    const merged = [...transfers, ...topups].sort(
+      (a, b) => new Date(b.transactionDate).getTime() - new Date(a.transactionDate).getTime(),
+    );
+
+    const trimmed = merged.slice(0, size);
+
+    return trimmed.map((t) => this.mapParentItem(t));
+  }
+
+  async getParentTransactionsPaginated(
+    guardianCustomerId: string,
+    page: number,
+    size: number,
+    type?: ParentTransactionType,
+  ): Promise<PagedTransactionsResponseDto> {
+    const skip = (page - 1) * size;
+
+    let transfers: Transaction[] = [];
+    let topups: Transaction[] = [];
+    let transferCount = 0;
+    let topupCount = 0;
+
+    if (!type || type === ParentTransactionType.PARENT_TRANSFER) {
+      [transfers, transferCount] = await Promise.all([
+        this.transactionRepository.findParentTransfers(guardianCustomerId, skip, size),
+        this.transactionRepository.countParentTransfers(guardianCustomerId),
+      ]);
+    }
+
+    if (!type || type === ParentTransactionType.PARENT_TOPUP) {
+      [topups, topupCount] = await Promise.all([
+        this.transactionRepository.findParentTopups(guardianCustomerId, skip, size),
+        this.transactionRepository.countParentTopups(guardianCustomerId),
+      ]);
+    }
+
+    const total = transferCount + topupCount;
+
+    if (type) {
+      const items = type === ParentTransactionType.PARENT_TRANSFER ? transfers : topups;
+      const mapped = items.map((t) => this.mapParentItem(t));
+      return new PagedTransactionsResponseDto(mapped, page, size, total);
+    }
+
+    const merged = [...transfers, ...topups].sort(
+      (a, b) => new Date(b.transactionDate).getTime() - new Date(a.transactionDate).getTime(),
+    );
+
+    const paginated = merged.slice(0, size);
+    const mapped = paginated.map((t) => this.mapParentItem(t));
+
+    return new PagedTransactionsResponseDto(mapped, page, size, total);
+  }
+
+  async getParentTransfersOnly(guardianCustomerId: string, page: number, size: number): Promise<ParentTransferItemDto[]> {
+    const skip = (page - 1) * size;
+    const transfers = await this.transactionRepository.findParentTransfers(guardianCustomerId, skip, size);
+    return transfers.map((t) => this.mapToParentTransferItem(t));
+  }
+
+  async getParentTransfersPaginated(
+    guardianCustomerId: string,
+    page: number,
+    size: number,
+  ): Promise<PagedParentTransfersResponseDto> {
+    const skip = (page - 1) * size;
+    const [transfers, total] = await Promise.all([
+      this.transactionRepository.findParentTransfers(guardianCustomerId, skip, size),
+      this.transactionRepository.countParentTransfers(guardianCustomerId),
+    ]);
+    const items = transfers.map((t) => this.mapToParentTransferItem(t));
+    return new PagedParentTransfersResponseDto(items, page, size, total);
+  }
+
+  async getChildTransfers(juniorId: string, page: number, size: number): Promise<ChildTransferItemDto[]> {
+    const skip = (page - 1) * size;
+    const transfers = await this.transactionRepository.findTransfersToJunior(juniorId, skip, size);
+    return transfers.map((t) => this.mapToChildTransferItem(t));
+  }
+
+  async getChildTransfersPaginated(
+    juniorId: string,
+    page: number,
+    size: number,
+  ): Promise<PagedChildTransfersResponseDto> {
+    const skip = (page - 1) * size;
+    const [transfers, total] = await Promise.all([
+      this.transactionRepository.findTransfersToJunior(juniorId, skip, size),
+      this.transactionRepository.countTransfersToJunior(juniorId),
+    ]);
+    const items = transfers.map((t) => this.mapToChildTransferItem(t));
+    return new PagedChildTransfersResponseDto(items, page, size, total);
+  }
+
+  private mapToParentTransferItem(t: Transaction): ParentTransferItemDto {
+    const child = t.card?.customer;
+    const currency = t.transactionCurrency === '682' ? 'SAR' : t.transactionCurrency;
+    return {
+      date: t.transactionDate,
+      amount: Math.abs(t.transactionAmount),
+      currency,
+      childName: child ? `${child.firstName} ${child.lastName}` : 'Child',
+    };
+  }
+
+  private mapToChildTransferItem(t: Transaction): ChildTransferItemDto {
+    const amount = Math.abs(t.transactionAmount);
+    const currency = t.transactionCurrency === '682' ? 'SAR' : t.transactionCurrency;
+    return {
+      date: t.transactionDate,
+      amount,
+      currency,
+      message: `You received {{amount}} {{currency}} from your parent.`,
+    };
+  }
+
+  async getChildSpendingHistory(juniorId: string, startUtc: Date, endUtc: Date) {
+    const transactions = await this.transactionRepository.getTransactionsForCardWithinDateRange(
+      juniorId,
+      startUtc,
+      endUtc,
+    );
+
+    const { SpendingHistoryItemDto, SpendingHistoryResponseDto } = await import('../dtos/responses');
+    const items = transactions.map((t) => new SpendingHistoryItemDto(t));
+    return new SpendingHistoryResponseDto(items);
+  }
+
+  async getTransactionDetail(transactionId: string, juniorId: string) {
+    const transaction = await this.transactionRepository.findTransactionById(transactionId, juniorId);
+
+    if (!transaction) {
+      throw new UnprocessableEntityException('TRANSACTION.NOT_FOUND');
+    }
+
+    const { TransactionDetailResponseDto } = await import('../dtos/responses');
+    return new TransactionDetailResponseDto(transaction);
+  }
+
+  private mapParentItem(t: Transaction): TransactionItemResponseDto {
+    const dto = new TransactionItemResponseDto();
+    dto.date = t.transactionDate;
+
+    if (t.transactionType === TransactionType.INTERNAL) {
+      dto.type = ParentTransactionType.PARENT_TRANSFER;
+      dto.amountSigned = -Math.abs(t.transactionAmount);
+      const child = t.card?.customer;
+      dto.counterpartyName = child ? `${child.firstName} ${child.lastName}` : 'Child';
+      dto.childName = dto.counterpartyName;
+      dto.counterpartyAccountMasked = t.card?.account?.accountReference
+        ? `****${t.card.account.accountReference.slice(-4)}`
+        : null;
+      return dto;
+    }
+
+    dto.type = ParentTransactionType.PARENT_TOPUP;
+    const settlement = Number(t.settlementAmount ?? 0);
+    const txn = Number(t.transactionAmount ?? 0);
+    const creditAmount = settlement > 0 ? settlement : txn;
+    dto.amountSigned = Math.abs(Number.isFinite(creditAmount) ? creditAmount : 0);
+    dto.counterpartyName = 'Top-up';
+    dto.counterpartyAccountMasked = t.accountReference ? `****${t.accountReference.slice(-4)}` : null;
+    return dto;
+  }
 }

src/common/modules/neoleap/__mocks__/kyc-callback.mock.ts

@@ -17,7 +17,6 @@ export const getKycCallbackMock = (nationalId: string) => {
     salaryMax: '1000',
     incomeSource: 'Salary',
     professionTitle: 'Software Engineer',
-    professionType: 'Full-Time',
     isPep: 'N',
     country: '682',
     region: 'Mecca',

src/common/modules/neoleap/dtos/requests/account-transaction-webhook.request.dto.ts

@@ -56,12 +56,12 @@ export class AccountTransactionWebhookRequest {
   @ApiProperty({ example: '682' })
   currency!: string;
 
-  @Expose()
+  @Expose({ name: 'Date' })
   @IsString()
   @ApiProperty({ name: 'Date', example: '20241112' })
   date!: string;
 
-  @Expose()
+  @Expose({ name: 'Time' })
   @IsString()
   @ApiProperty({ name: 'Time', example: '125340' })
   time!: string;

src/common/modules/neoleap/dtos/requests/kyc-webhook.request.dto.ts

@@ -1,129 +1,50 @@
 import { ApiProperty } from '@nestjs/swagger';
-import { Expose } from 'class-transformer';
-import { IsString } from 'class-validator';
-export class KycWebhookRequest {
-  @Expose({ name: 'InstId' })
-  @IsString()
-  @ApiProperty({ name: 'InstId', example: '1100' })
-  instId!: string;
+import { IsEnum, IsObject, IsString } from 'class-validator';
 
-  @Expose()
-  @IsString()
-  @ApiProperty({ example: '3136fd60-3f89-4d24-a92f-b9c63a53807f' })
-  transId!: string;
-
-  @Expose()
-  @IsString()
-  @ApiProperty({ example: '20250807' })
-  date!: string;
-
-  @Expose()
-  @IsString()
-  @ApiProperty({ example: '150000' })
-  time!: string;
-
-  @Expose()
-  @IsString()
-  @ApiProperty({ example: 'SUCCESS' })
-  status!: string;
-
-  @Expose()
-  @IsString()
-  @ApiProperty({ example: 'John' })
-  firstName!: string;
-
-  @Expose()
-  @IsString()
-  @ApiProperty({ example: 'Doe' })
-  lastName!: string;
-
-  @Expose()
-  @IsString()
-  @ApiProperty({ example: '19990107' })
-  dob!: string;
-
-  @Expose()
-  @IsString()
-  @ApiProperty({ example: '682' })
-  nationality!: string;
-
-  @Expose()
-  @IsString()
-  @ApiProperty({ example: 'M' })
-  gender!: string;
-
-  @Expose()
-  @IsString()
-  @ApiProperty({ example: '20310917' })
-  nationalIdExpiry!: string;
-
-  @Expose()
-  @IsString()
-  @ApiProperty({ example: '1250820840' })
-  nationalId!: string;
-
-  @Expose()
-  @IsString()
-  @ApiProperty({ example: '+962798765432' })
-  mobile!: string;
-
-  @Expose()
-  @IsString()
-  @ApiProperty({ example: '500' })
-  salaryMin!: string;
-
-  @Expose()
-  @IsString()
-  @ApiProperty({ example: '1000' })
-  salaryMax!: string;
-
-  @Expose()
-  @IsString()
-  @ApiProperty({ example: 'Salary' })
-  incomeSource!: string;
-
-  @Expose()
-  @IsString()
-  @ApiProperty({ example: 'Software Engineer' })
-  professionTitle!: string;
-
-  @Expose()
-  @IsString()
-  @ApiProperty({ example: 'Full-Time' })
-  professionType!: string;
-
-  @Expose()
-  @IsString()
-  @ApiProperty({ example: 'N' })
-  isPep!: string;
-
-  @Expose()
-  @IsString()
-  @ApiProperty({ example: '682' })
-  country!: string;
-
-  @Expose()
-  @IsString()
-  @ApiProperty({ example: 'Mecca' })
-  region!: string;
-
-  @Expose()
-  @IsString()
-  @ApiProperty({ example: 'At-Taif' })
-  city!: string;
-
-  @Expose()
-  @IsString()
-  @ApiProperty({ example: 'Al-Hamra' })
-  neighborhood!: string;
-
-  @Expose()
-  @IsString()
-  @ApiProperty({ example: 'Al-Masjid Al-Haram' })
-  street!: string;
-
-  @Expose()
-  @IsString()
-  @ApiProperty({ example: '123' })
-  building!: string;
+export enum NeoleapKycWebhookStatus {
+  ONBOARDING_SUCCESS = 'ONBOARDING_SUCCESS',
+  ONBOARDING_FAILURE = 'ONBOARDING_FAILURE',
+  IN_PROGRESS = 'IN_PROGRESS',
+}
+
+class KycEntityDto {
+  @ApiProperty({ example: 'INDIVIDUAL', description: 'Entity type - INDIVIDUAL for KYC' })
+  @IsString()
+  type!: string;
+
+  @ApiProperty({ example: 'FIN-TECK-CUSTOMER-20393', description: 'Customer external ID from Neoleap' })
+  @IsString()
+  externalId!: string;
+}
+
+export class KycWebhookRequest {
+  @ApiProperty({ 
+    example: '8a745b1b-1252-4921-a569-b3d4406c25fd', 
+    description: 'Transaction ID, the same as returned from onboard API response' 
+  })
+  @IsString()
+  stateId!: string;
+
+  @ApiProperty({ 
+    example: '8a745b1b-1252-4921-a569-b3d4406c25fd', 
+    description: 'Unique callback ID used as reference and for tracking' 
+  })
+  @IsString()
+  callbackId!: string;
+
+  @ApiProperty({ example: '1100', description: 'Fintech ID (1100 for ZOD)' })
+  @IsString()
+  externalFintechId!: string;
+
+  @ApiProperty({ type: KycEntityDto })
+  @IsObject()
+  entity!: KycEntityDto;
+
+  @ApiProperty({ 
+    enum: NeoleapKycWebhookStatus, 
+    example: NeoleapKycWebhookStatus.ONBOARDING_SUCCESS,
+    description: 'Status of onboarding: ONBOARDING_SUCCESS or ONBOARDING_FAILURE'
+  })
+  @IsEnum(NeoleapKycWebhookStatus)
+  status!: NeoleapKycWebhookStatus;
 }

src/common/modules/neoleap/services/neoleap.service.ts

@@ -48,47 +48,109 @@ export class NeoLeapService {
     this.useKycMock = [true, 'true'].includes(this.configService.get<boolean>('USE_KYC_MOCK', true));
   }
 
-  initiateKyc(customerId: string, body: InitiateKycRequestDto) {
-    const responseKey = 'InitiateKycResponseDetails';
-
+  async initiateKycOnboarding(dto: InitiateKycRequestDto) {
+    // Mock mode for development
     if (this.useKycMock) {
-      const responseDto = plainToInstance(InitiateKycResponseDto, INITIATE_KYC_MOCK[responseKey], {
-        excludeExtraneousValues: true,
-      });
+      const mockResponse = {
+        externalCustomerId: `FIN-TECK-CUSTOMER-${Date.now()}`,
+        externalFintechId: '1100',
+        nafathRandomCode: '38',
+        stateId: uuid(),
+        status: 'IN_PROGRESS',
+      };
 
+      // Trigger mock webhook after 7 seconds
       setTimeout(() => {
         this.httpService
-          .post(`${this.zodApiUrl}/neoleap-webhooks/kyc`, getKycCallbackMock(body.nationalId), {
-            headers: {
-              'Content-Type': 'application/json',
+          .post(`${this.zodApiUrl}/neoleap-webhooks/kyc`, {
+            stateId: mockResponse.stateId,
+            callbackId: uuid(),
+            externalFintechId: '1100',
+            entity: {
+              type: 'INDIVIDUAL',
+              externalId: mockResponse.externalCustomerId,
             },
+            status: 'ONBOARDING_SUCCESS',
           })
           .subscribe({
-            next: () => this.logger.log('Mock KYC webhook sent'),
-            error: (err) => console.error(err),
+            next: () => this.logger.log('Mock KYC webhook sent successfully'),
+            error: (err) => this.logger.error('Mock KYC webhook failed:', err.message),
           });
       }, 7000);
 
-      return responseDto;
+      return mockResponse;
     }
 
+    // Real API call to Neoleap
     const payload = {
-      InitiateKycRequestDetails: {
-        CustomerIdentifier: {
-          InstitutionCode: this.institutionCode,
-          Id: customerId,
-          NationalId: body.nationalId,
+      poiNumber: dto.poiNumber,
+      poiType: dto.poiType,
+      mobileNumber: dto.mobileNumber,
+      email: dto.email,
+      dateOfBirth: dto.dateOfBirth,
+      jobSector: dto.jobSector,
+      employer: dto.employer,
+      incomeSource: dto.incomeSource,
+      jobCategory: dto.jobCategory,
+      incomeRange: dto.incomeRange,
+      // Use default address values for Neoleap KYC
+      address: {
+        national: {
+          buildingNumber: '1',
+          additionalNumber: '',
+          street: 'King Fahd Road',
+          streetEn: 'King Fahd Road',
+          city: 'Riyadh',
+          cityEn: 'Riyadh',
+          zipcode: '',
+          unitNumber: '',
+          district: 'Al Olaya',
+          districtEn: 'Al Olaya',
+        },
+        general: {
+          address: '1, King Fahd Road, Al Olaya, Riyadh, Riyadh',
+          website: '',
+          email: dto.email || '',
+          telephone1: dto.mobileNumber || '',
+          telephone2: '',
+          fax1: '',
+          fax2: '',
+          postalBox1: '',
+          postalBox2: '',
+          zipcode: '',
         },
       },
-      RequestHeader: this.prepareHeaders('InitiateKyc'),
     };
 
-    return this.sendRequestToNeoLeap<typeof payload, InitiateKycResponseDto>(
-      'kyc/InitiateKyc',
-      payload,
-      responseKey,
-      InitiateKycResponseDto,
-    );
+    try {
+      const { data } = await this.httpService.axiosRef.post(
+        `${this.gatewayBaseUrl}/kyc/onboardCustomer`,
+        payload,
+        {
+          headers: {
+            'Content-Type': 'application/json',
+            Authorization: this.apiKey,
+            'X-Request-id': uuid(),
+            'X-Session-Language': 'ar',
+          },
+        },
+      );
+
+      return data.data;
+    } catch (error: any) {
+      this.logger.error('Error initiating KYC:', error.response?.data || error.message);
+
+      // Handle specific Neoleap errors
+      if (error.response?.data?.errorCode === 'E810109') {
+        throw new BadRequestException('National ID is already registered with Neoleap');
+      }
+
+      if (error.response?.data?.error === 'schema validation failed') {
+        throw new BadRequestException('Invalid data format for KYC verification');
+      }
+
+      throw new InternalServerErrorException('Failed to initiate KYC verification');
+    }
   }
 
   createApplication(customer: Customer) {
@@ -124,7 +186,9 @@ export class NeoLeapService {
           },
           BillingCycle: 'C1',
         },
-        ApplicationOtherInfo: {},
+        ApplicationOtherInfo: {
+          ExternalCorporateId: customer.neoleapExternalCustomerId,
+        },
         ApplicationCustomerDetails: {
           FirstName: customer.firstName,
           LastName: customer.lastName,
@@ -137,14 +201,14 @@ export class NeoLeapService {
           Title: customer.gender === Gender.MALE ? 'Mr' : 'Ms',
           Gender: customer.gender === Gender.MALE ? 'M' : 'F',
           LocalizedDateOfBirth: moment(customer.dateOfBirth).format('YYYY-MM-DD'),
-          Nationality: CountriesNumericISO[customer.countryOfResidence],
+          Nationality: CountriesNumericISO[customer.countryOfResidence || 'SA'],
         },
         ApplicationAddress: {
-          City: customer.city,
-          Country: CountriesNumericISO[customer.country],
-          Region: customer.region,
-          AddressLine1: `${customer.street} ${customer.building}`,
-          AddressLine2: customer.neighborhood,
+          City: 'Riyadh',
+          Country: CountriesNumericISO['SA'],
+          Region: 'Riyadh',
+          AddressLine1: 'King Fahd Road 1',
+          AddressLine2: 'Al Olaya',
           AddressRole: 0,
           Email: customer.user.email,
           Phone1: customer.user.phoneNumber,
@@ -213,14 +277,14 @@ export class NeoLeapService {
           Title: parent.gender === Gender.MALE ? 'Mr' : 'Ms',
           Gender: parent.gender === Gender.MALE ? 'M' : 'F',
           LocalizedDateOfBirth: moment(parent.dateOfBirth).format('YYYY-MM-DD'),
-          Nationality: CountriesNumericISO[parent.countryOfResidence],
+          Nationality: CountriesNumericISO[parent.countryOfResidence || 'SA'],
         },
         ApplicationAddress: {
-          City: parent.city,
-          Country: CountriesNumericISO[parent.country],
-          Region: parent.region,
-          AddressLine1: `${parent.street} ${parent.building}`,
-          AddressLine2: parent.neighborhood,
+          City: 'Riyadh',
+          Country: CountriesNumericISO['SA'],
+          Region: 'Riyadh',
+          AddressLine1: 'King Fahd Road 1',
+          AddressLine2: 'Al Olaya',
           AddressRole: 0,
           Email: child.user.email,
           Phone1: child.user.phoneNumber,

src/customer/controllers/customer.controller.ts

@@ -1,12 +1,12 @@
 import { Body, Controller, Get, Post, UseGuards } from '@nestjs/common';
-import { ApiBearerAuth, ApiTags } from '@nestjs/swagger';
+import { ApiBearerAuth, ApiOperation, ApiTags } from '@nestjs/swagger';
 import { IJwtPayload } from '~/auth/interfaces';
 import { AuthenticatedUser } from '~/common/decorators';
 import { AccessTokenGuard } from '~/common/guards';
 import { ApiDataResponse, ApiLangRequestHeader } from '~/core/decorators';
 import { ResponseFactory } from '~/core/utils';
 import { InitiateKycRequestDto } from '../dtos/request';
-import { CustomerResponseDto, InitiateKycResponseDto } from '../dtos/response';
+import { CustomerResponseDto, InitiateKycResponseDto, KycMetadataResponseDto } from '../dtos/response';
 import { CustomerService } from '../services';
 
 @Controller('customers')
@@ -30,6 +30,16 @@ export class CustomerController {
   async initiateKyc(@AuthenticatedUser() { sub }: IJwtPayload, @Body() body: InitiateKycRequestDto) {
     const res = await this.customerService.initiateKycRequest(sub, body);
 
-    return ResponseFactory.data(new InitiateKycResponseDto(res.randomNumber));
+    return ResponseFactory.data(new InitiateKycResponseDto(res));
+  }
+
+  @Get('/kyc/onboard-metadata')
+  @UseGuards(AccessTokenGuard)
+  @ApiOperation({ summary: 'Get KYC onboarding form metadata' })
+  @ApiDataResponse(KycMetadataResponseDto)
+  async getKycMetadata() {
+    const metadata = await this.customerService.getKycOnboardMetadata();
+
+    return ResponseFactory.data(metadata);
   }
 }

src/customer/customer.module.ts

@@ -4,14 +4,14 @@ import { NeoLeapModule } from '~/common/modules/neoleap/neoleap.module';
 import { GuardianModule } from '~/guardian/guardian.module';
 import { UserModule } from '~/user/user.module';
 import { CustomerController } from './controllers';
-import { Customer } from './entities';
-import { CustomerRepository } from './repositories/customer.repository';
-import { CustomerService } from './services';
+import { Customer, KycTransaction } from './entities';
+import { CustomerRepository, KycTransactionRepository } from './repositories';
+import { CustomerService, MetadataService } from './services';
 
 @Module({
-  imports: [TypeOrmModule.forFeature([Customer]), GuardianModule, forwardRef(() => UserModule), NeoLeapModule],
+  imports: [TypeOrmModule.forFeature([Customer, KycTransaction]), GuardianModule, forwardRef(() => UserModule), NeoLeapModule],
   controllers: [CustomerController],
-  providers: [CustomerService, CustomerRepository],
+  providers: [CustomerService, CustomerRepository, KycTransactionRepository, MetadataService],
   exports: [CustomerService],
 })
 export class CustomerModule {}

src/customer/dtos/request/initiate-kyc.request.dto.ts

@@ -1,8 +1,55 @@
 import { ApiProperty } from '@nestjs/swagger';
+import { IsDateString, IsEmail, IsEnum, IsOptional, IsString, Matches } from 'class-validator';
 import { i18nValidationMessage as i18n } from 'nestjs-i18n';
-import { isValidSaudiId } from '~/core/decorators/validations';
+import { Gender, IncomeRange, IncomeSource, JobCategory, JobSector, PoiType } from '~/customer/enums';
+
 export class InitiateKycRequestDto {
-  @ApiProperty({ example: '999300024' })
-  @isValidSaudiId({ message: i18n('validation.isValidSaudiId', { path: 'general', property: 'customer.nationalId' }) })
-  nationalId!: string;
+  @ApiProperty({ example: '2586234623', description: 'Saudi National ID or Iqama number' })
+  @IsString({ message: i18n('validation.IsString', { path: 'general', property: 'customer.poiNumber' }) })
+  poiNumber!: string;
+
+  @ApiProperty({ enum: PoiType, example: PoiType.NAT, default: PoiType.NAT })
+  @IsEnum(PoiType, { message: i18n('validation.IsEnum', { path: 'general', property: 'customer.poiType' }) })
+  poiType!: PoiType;
+
+  @ApiProperty({ example: '0512345678', pattern: '^05\\d{8}$' })
+  @Matches(/^05\d{8}$/, { message: i18n('validation.Matches', { path: 'general', property: 'customer.mobileNumber' }) })
+  mobileNumber!: string;
+
+  @ApiProperty({ example: 'user@zodwallet.com', required: false })
+  @IsEmail({}, { message: i18n('validation.IsEmail', { path: 'general', property: 'customer.email' }) })
+  @IsOptional()
+  email?: string;
+
+  @ApiProperty({ example: '1990-01-01', format: 'date' })
+  @IsDateString({}, { message: i18n('validation.IsDateString', { path: 'general', property: 'customer.dateOfBirth' }) })
+  dateOfBirth!: string;
+
+  @ApiProperty({ example: '2030-12-31', format: 'date', description: 'National ID expiry date' })
+  @IsDateString({}, { message: i18n('validation.IsDateString', { path: 'general', property: 'customer.nationalIdExpiry' }) })
+  nationalIdExpiry!: string;
+
+  @ApiProperty({ enum: Gender, example: Gender.MALE })
+  @IsEnum(Gender, { message: i18n('validation.IsEnum', { path: 'general', property: 'customer.gender' }) })
+  gender!: Gender;
+
+  @ApiProperty({ enum: JobSector, example: JobSector.PRIVATE_SECTOR })
+  @IsEnum(JobSector, { message: i18n('validation.IsEnum', { path: 'general', property: 'customer.jobSector' }) })
+  jobSector!: JobSector;
+
+  @ApiProperty({ example: 'Test Company Ltd' })
+  @IsString({ message: i18n('validation.IsString', { path: 'general', property: 'customer.employer' }) })
+  employer!: string;
+
+  @ApiProperty({ enum: IncomeSource, example: IncomeSource.SALARY })
+  @IsEnum(IncomeSource, { message: i18n('validation.IsEnum', { path: 'general', property: 'customer.incomeSource' }) })
+  incomeSource!: IncomeSource;
+
+  @ApiProperty({ enum: JobCategory, example: JobCategory.ENGINEER })
+  @IsEnum(JobCategory, { message: i18n('validation.IsEnum', { path: 'general', property: 'customer.jobCategory' }) })
+  jobCategory!: JobCategory;
+
+  @ApiProperty({ enum: IncomeRange, example: IncomeRange.RANGE_10000_20000 })
+  @IsEnum(IncomeRange, { message: i18n('validation.IsEnum', { path: 'general', property: 'customer.incomeRange' }) })
+  incomeRange!: IncomeRange;
 }

src/customer/dtos/response/customer.response.dto.ts

@@ -34,15 +34,6 @@ export class CustomerResponseDto {
   @ApiProperty({ example: 'JO' })
   countryOfResidence!: string;
 
-  @ApiProperty({ example: 'Employee' })
-  sourceOfIncome!: string;
-
-  @ApiProperty({ example: 'Software Development' })
-  profession!: string;
-
-  @ApiProperty({ example: 'Full-time' })
-  professionType!: string;
-
   @ApiProperty({ example: false })
   isPep!: boolean;
 
@@ -58,24 +49,6 @@ export class CustomerResponseDto {
   @ApiProperty({ example: 12345 })
   waitingNumber!: number;
 
-  @ApiProperty({ example: 'SA' })
-  country!: string | null;
-
-  @ApiProperty({ example: 'Riyadh' })
-  region!: string | null;
-
-  @ApiProperty({ example: 'Riyadh City' })
-  city!: string | null;
-
-  @ApiProperty({ example: 'Al-Masif' })
-  neighborhood!: string | null;
-
-  @ApiProperty({ example: 'King Fahd Road' })
-  street!: string | null;
-
-  @ApiProperty({ example: '123' })
-  building!: string | null;
-
   @ApiPropertyOptional({ type: DocumentMetaResponseDto })
   profilePicture!: DocumentMetaResponseDto | null;
 
@@ -90,19 +63,10 @@ export class CustomerResponseDto {
     this.nationalId = customer.nationalId;
     this.nationalIdExpiry = customer.nationalIdExpiry;
     this.countryOfResidence = customer.countryOfResidence;
-    this.sourceOfIncome = customer.sourceOfIncome;
-    this.profession = customer.profession;
-    this.professionType = customer.professionType;
     this.isPep = customer.isPep;
     this.gender = customer.gender;
     this.isJunior = customer.isJunior;
     this.isGuardian = customer.isGuardian;
     this.waitingNumber = customer.applicationNumber;
-    this.country = customer.country;
-    this.region = customer.region;
-    this.city = customer.city;
-    this.neighborhood = customer.neighborhood;
-    this.street = customer.street;
-    this.building = customer.building;
   }
 }

src/customer/dtos/response/index.ts

@@ -1,2 +1,3 @@
 export * from './customer.response.dto';
 export * from './initiate-kyc.response.dto';
+export * from './kyc-metadata.response.dto';

src/customer/dtos/response/initiate-kyc.response.dto.ts

@@ -1,10 +1,28 @@
 import { ApiProperty } from '@nestjs/swagger';
+import { Expose } from 'class-transformer';
 
 export class InitiateKycResponseDto {
-  @ApiProperty()
-  randomNumber!: string;
+  @ApiProperty({ description: 'Internal transaction ID to track this KYC attempt' })
+  @Expose()
+  transactionId!: string;
 
-  constructor(randomNumber: string) {
-    this.randomNumber = randomNumber;
+  @ApiProperty({ description: 'Neoleap state ID for tracking' })
+  @Expose()
+  stateId!: string;
+
+  @ApiProperty({ description: 'Nafath random code to show to the user', example: '38' })
+  @Expose()
+  nafathRandomCode!: string;
+
+  @ApiProperty({ description: 'Current status', example: 'IN_PROGRESS' })
+  @Expose()
+  status!: string;
+
+  @ApiProperty({ description: 'External customer ID from Neoleap' })
+  @Expose()
+  externalCustomerId!: string;
+
+  constructor(data: Partial<InitiateKycResponseDto>) {
+    Object.assign(this, data);
   }
 }

src/customer/dtos/response/kyc-metadata.response.dto.ts

@@ -0,0 +1,12 @@
+export class MetadataOptionDto {
+  value!: string;
+  label!: string;
+}
+
+export class KycMetadataResponseDto {
+  poiTypes!: MetadataOptionDto[];
+  jobSectors!: MetadataOptionDto[];
+  incomeSources!: MetadataOptionDto[];
+  jobCategories!: MetadataOptionDto[];
+  incomeRanges!: MetadataOptionDto[];
+}

src/customer/entities/customer.entity.ts

@@ -49,15 +49,6 @@ export class Customer extends BaseEntity {
   @Column('varchar', { length: 255, nullable: true, name: 'country_of_residence' })
   countryOfResidence!: CountryIso;
 
-  @Column('varchar', { length: 255, nullable: true, name: 'source_of_income' })
-  sourceOfIncome!: string;
-
-  @Column('varchar', { length: 255, nullable: true, name: 'profession' })
-  profession!: string;
-
-  @Column('varchar', { length: 255, nullable: true, name: 'profession_type' })
-  professionType!: string;
-
   @Column('boolean', { default: false, name: 'is_pep' })
   isPep!: boolean;
 
@@ -77,23 +68,27 @@ export class Customer extends BaseEntity {
   @Column('varchar', { name: 'user_id' })
   userId!: string;
 
-  @Column('varchar', { name: 'country', length: 255, nullable: true })
-  country!: CountryIso;
+  // KYC-specific fields
+  @Column('varchar', { length: 255, nullable: true, name: 'neoleap_external_customer_id' })
+  neoleapExternalCustomerId!: string | null;
 
-  @Column('varchar', { name: 'region', length: 255, nullable: true })
-  region!: string;
+  @Column('varchar', { length: 100, nullable: true, name: 'job_sector' })
+  jobSector!: string | null;
 
-  @Column('varchar', { name: 'city', length: 255, nullable: true })
-  city!: string;
+  @Column('varchar', { length: 255, nullable: true, name: 'employer' })
+  employer!: string | null;
 
-  @Column('varchar', { name: 'neighborhood', length: 255, nullable: true })
-  neighborhood!: string;
+  @Column('varchar', { length: 100, nullable: true, name: 'income_source' })
+  incomeSource!: string | null;
 
-  @Column('varchar', { name: 'street', length: 255, nullable: true })
-  street!: string;
+  @Column('varchar', { length: 100, nullable: true, name: 'job_category' })
+  jobCategory!: string | null;
 
-  @Column('varchar', { name: 'building', length: 255, nullable: true })
-  building!: string;
+  @Column('varchar', { length: 100, nullable: true, name: 'income_range' })
+  incomeRange!: string | null;
+
+  @Column('varchar', { length: 20, nullable: true, name: 'mobile_number' })
+  mobileNumber!: string | null;
 
   @OneToOne(() => User, (user) => user.customer, { onDelete: 'CASCADE' })
   @JoinColumn({ name: 'user_id' })

src/customer/entities/index.ts

@@ -1 +1,2 @@
 export * from './customer.entity';
+export * from './kyc-transaction.entity';

src/customer/entities/kyc-transaction.entity.ts

@@ -0,0 +1,76 @@
+import {
+  BaseEntity,
+  Column,
+  CreateDateColumn,
+  Entity,
+  JoinColumn,
+  ManyToOne,
+  PrimaryGeneratedColumn,
+  UpdateDateColumn,
+} from 'typeorm';
+import { Customer } from './customer.entity';
+import { User } from '~/user/entities';
+
+@Entity('kyc_transactions')
+export class KycTransaction extends BaseEntity {
+  @PrimaryGeneratedColumn('uuid')
+  id!: string;
+
+  @Column('uuid', { name: 'customer_id' })
+  customerId!: string;
+
+  @Column('uuid', { name: 'user_id' })
+  userId!: string;
+
+  // National ID from form
+  @Column('varchar', { length: 50, name: 'national_id', nullable: false })
+  nationalId!: string;
+
+  // Neoleap IDs
+  @Column('varchar', { length: 255, unique: true, name: 'state_id' })
+  stateId!: string;
+
+  @Column('varchar', { length: 255, nullable: true, name: 'external_customer_id' })
+  externalCustomerId!: string | null;
+
+  // Nafath details
+  @Column('varchar', { length: 10, nullable: true, name: 'nafath_random_code' })
+  nafathRandomCode!: string | null;
+
+  // Status tracking
+  @Column('varchar', { length: 50, default: 'INITIATED', name: 'status' })
+  status!: string;
+
+  // Audit trail
+  @Column('jsonb', { name: 'form_data' })
+  formData!: any;
+
+  @Column('varchar', { length: 255, nullable: true, name: 'callback_id' })
+  callbackId!: string | null;
+
+  // Timestamps
+  @Column('timestamp', { default: () => 'CURRENT_TIMESTAMP', name: 'initiated_at' })
+  initiatedAt!: Date;
+
+  @Column('timestamp', { nullable: true, name: 'completed_at' })
+  completedAt!: Date | null;
+
+  @Column('timestamp', { nullable: true, name: 'expires_at' })
+  expiresAt!: Date | null;
+
+  @CreateDateColumn({ type: 'timestamp with time zone', default: () => 'CURRENT_TIMESTAMP', name: 'created_at' })
+  createdAt!: Date;
+
+  @UpdateDateColumn({ type: 'timestamp with time zone', default: () => 'CURRENT_TIMESTAMP', name: 'updated_at' })
+  updatedAt!: Date;
+
+  // Relationships
+  @ManyToOne(() => Customer, { onDelete: 'CASCADE' })
+  @JoinColumn({ name: 'customer_id' })
+  customer!: Customer;
+
+  @ManyToOne(() => User, { onDelete: 'CASCADE' })
+  @JoinColumn({ name: 'user_id' })
+  user!: User;
+}
+

src/customer/enums/income-range.enum.ts

@@ -0,0 +1,8 @@
+export enum IncomeRange {
+  BELOW_2000 = 'SAR 2,000 and below',
+  RANGE_2000_5000 = 'SAR 2,000 to 5,000',
+  RANGE_5000_10000 = 'SAR 5,000 to 10,000',
+  RANGE_10000_20000 = 'SAR 10,000 to 20,000',
+  ABOVE_20000 = 'SAR 20,000 and above',
+}
+

src/customer/enums/income-source.enum.ts

@@ -0,0 +1,9 @@
+export enum IncomeSource {
+  SALARY = 'SALARY',
+  ANCESTRAL = 'ANCESTRAL',
+  REAL_ESTATE = 'REAL_ESTATE',
+  INVESTMENT_RETURNS = 'INVESTMENT_RETURNS',
+  RENTAL_INCOME = 'RENTAL_INCOME',
+  OTHER = 'OTHER',
+}
+

src/customer/enums/index.ts

@@ -1,3 +1,8 @@
 export * from './customer-status.enum';
 export * from './gender.enum';
 export * from './kyc-status.enum';
+export * from './poi-type.enum';
+export * from './job-sector.enum';
+export * from './income-source.enum';
+export * from './job-category.enum';
+export * from './income-range.enum';

src/customer/enums/job-category.enum.ts

@@ -0,0 +1,57 @@
+export enum JobCategory {
+  ASSISTANT_MINISTER = 'ASSISTANT_MINISTER',
+  DEPUTY_MINISTER = 'DEPUTY_MINISTER',
+  UNDER_SECRETARY = 'UNDER_SECRETARY',
+  GENERAL_MANAGER = 'GENERAL_MANAGER',
+  CHAIRMAN = 'CHAIRMAN',
+  MANAGER = 'MANAGER',
+  PROFESSOR = 'PROFESSOR',
+  HEAD_OF_COURT = 'HEAD_OF_COURT',
+  JUDGE = 'JUDGE',
+  LAWYER = 'LAWYER',
+  SCIENTIST = 'SCIENTIST',
+  NOTARY = 'NOTARY',
+  BUSINESSMAN = 'BUSINESSMAN',
+  MERCHANT = 'MERCHANT',
+  PHARMACIST = 'PHARMACIST',
+  DOCTOR = 'DOCTOR',
+  MEDICAL_TECHNICIAN = 'MEDICAL_TECHNICIAN',
+  NURSE = 'NURSE',
+  ENGINEER = 'ENGINEER',
+  CHEMIST = 'CHEMIST',
+  CONTRACTOR = 'CONTRACTOR',
+  AUDITOR_ACCOUNTANT = 'AUDITOR_ACCOUNTANT',
+  RESEARCHER = 'RESEARCHER',
+  ACCOUNTANT = 'ACCOUNTANT',
+  JOURNALIST = 'JOURNALIST',
+  DESIGNER = 'DESIGNER',
+  COMPUTER_SPECIALIST = 'COMPUTER_SPECIALIST',
+  TRANSLATOR = 'TRANSLATOR',
+  TEACHER = 'TEACHER',
+  PILOT = 'PILOT',
+  HOST = 'HOST',
+  OFFICER = 'OFFICER',
+  SOLDIER = 'SOLDIER',
+  RETIRED = 'RETIRED',
+  SALESMAN = 'SALESMAN',
+  AUTHOR = 'AUTHOR',
+  CRAFTSMAN = 'CRAFTSMAN',
+  SECURITY = 'SECURITY',
+  LABORER = 'LABORER',
+  DRIVER = 'DRIVER',
+  FARMER = 'FARMER',
+  HOUSEWIFE = 'HOUSEWIFE',
+  DIPLOMAT = 'DIPLOMAT',
+  STUDENT = 'STUDENT',
+  FREELANCER = 'FREELANCER',
+  SHEPHERD = 'SHEPHERD',
+  HOUSEMAID_OR_BABYSITTER = 'HOUSEMAID_OR_BABYSITTER',
+  CAPTAIN = 'CAPTAIN',
+  AMBASSADOR = 'AMBASSADOR',
+  MARKETING = 'MARKETING',
+  CONSULTING = 'CONSULTING',
+  SUPERVISOR = 'SUPERVISOR',
+  BANKER = 'BANKER',
+  BODYGUARD_OR_PERSONAL_ASSISTANT = 'BODYGUARD_OR_PERSONAL_ASSISTANT',
+}
+

src/customer/enums/job-sector.enum.ts

@@ -0,0 +1,12 @@
+export enum JobSector {
+  GOVERNMENT_SECTOR = 'GOVERNMENT_SECTOR',
+  HOME_MAKER = 'HOME_MAKER',
+  MILITARY = 'MILITARY',
+  PRIVATE_SECTOR = 'PRIVATE_SECTOR',
+  RETIRED = 'RETIRED',
+  SELF_EMPLOYED = 'SELF_EMPLOYED',
+  STUDENT = 'STUDENT',
+  HOUSEHOLD_LABOR = 'HOUSEHOLD_LABOR',
+  UNEMPLOYED = 'UNEMPLOYED',
+}
+

src/customer/enums/poi-type.enum.ts

@@ -0,0 +1,5 @@
+export enum PoiType {
+  IQA = 'IQA', // Iqama (Resident ID)
+  NAT = 'NAT', // National ID
+}
+

src/customer/repositories/index.ts

@@ -0,0 +1,3 @@
+export * from './customer.repository';
+export * from './kyc-transaction.repository';
+

src/customer/repositories/kyc-transaction.repository.ts

@@ -0,0 +1,46 @@
+import { Injectable } from '@nestjs/common';
+import { InjectRepository } from '@nestjs/typeorm';
+import { Repository } from 'typeorm';
+import { KycTransaction } from '../entities';
+
+@Injectable()
+export class KycTransactionRepository {
+  constructor(
+    @InjectRepository(KycTransaction)
+    private readonly kycTransactionRepository: Repository<KycTransaction>,
+  ) {}
+
+  async create(data: Partial<KycTransaction>): Promise<KycTransaction> {
+    const transaction = this.kycTransactionRepository.create(data);
+    return this.kycTransactionRepository.save(transaction);
+  }
+
+  async findByStateId(stateId: string): Promise<KycTransaction | null> {
+    return this.kycTransactionRepository.findOne({
+      where: { stateId },
+      relations: ['customer', 'user'],
+    });
+  }
+
+  async findActiveByNationalId(nationalId: string): Promise<KycTransaction | null> {
+    return this.kycTransactionRepository.findOne({
+      where: {
+        nationalId,
+        status: 'IN_PROGRESS',
+      },
+      order: { initiatedAt: 'DESC' },
+    });
+  }
+
+  async updateByStateId(stateId: string, data: Partial<KycTransaction>): Promise<void> {
+    await this.kycTransactionRepository.update({ stateId }, data);
+  }
+
+  async findAllByCustomerId(customerId: string): Promise<KycTransaction[]> {
+    return this.kycTransactionRepository.find({
+      where: { customerId },
+      order: { initiatedAt: 'DESC' },
+    });
+  }
+}
+

src/customer/services/customer.service.ts

@@ -1,4 +1,4 @@
-import { BadRequestException, forwardRef, Inject, Injectable, Logger } from '@nestjs/common';
+import { BadRequestException, ConflictException, forwardRef, Inject, Injectable, Logger } from '@nestjs/common';
 import moment from 'moment';
 import { Transactional } from 'typeorm-transactional';
 import { CountryIso } from '~/common/enums';
@@ -11,15 +11,18 @@ import { User } from '~/user/entities';
 import { InitiateKycRequestDto } from '../dtos/request';
 import { Customer } from '../entities';
 import { Gender, KycStatus } from '../enums';
-import { CustomerRepository } from '../repositories/customer.repository';
+import { CustomerRepository, KycTransactionRepository } from '../repositories';
+import { MetadataService } from './metadata.service';
 
 @Injectable()
 export class CustomerService {
   private readonly logger = new Logger(CustomerService.name);
   constructor(
     private readonly customerRepository: CustomerRepository,
+    private readonly kycTransactionRepo: KycTransactionRepository,
     private readonly guardianService: GuardianService,
     @Inject(forwardRef(() => NeoLeapService)) private readonly neoleapService: NeoLeapService,
+    private readonly metadataService: MetadataService,
   ) {}
 
   async updateCustomer(userId: string, data: Partial<Customer>): Promise<Customer> {
@@ -53,23 +56,68 @@ export class CustomerService {
   }
 
   async initiateKycRequest(customerId: string, body: InitiateKycRequestDto) {
-    this.logger.log(`Initiating KYC request for user ${customerId}`);
+    this.logger.log(`Initiating KYC request for customer ${customerId}`);
 
     const customer = await this.findCustomerById(customerId);
 
+    // Validate customer is not already verified
     if (customer.kycStatus === KycStatus.APPROVED) {
       this.logger.error(`KYC for customer ${customerId} is already approved`);
       throw new BadRequestException('CUSTOMER.KYC_ALREADY_APPROVED');
     }
 
-    // I will assume the api for initiating KYC is not allowing me to send customerId as correlationId so I will store the nationalId in the customer entity
+    // Check for active KYC transaction by National ID
+    const activeTransaction = await this.kycTransactionRepo.findActiveByNationalId(body.poiNumber);
+    if (activeTransaction) {
+      this.logger.error(`KYC verification already in progress for National ID ${body.poiNumber}`);
+      throw new ConflictException('KYC verification already in progress for this National ID');
+    }
 
+    // Update customer with KYC data
     await this.customerRepository.updateCustomer(customerId, {
-      nationalId: body.nationalId,
+      nationalId: body.poiNumber,
+      dateOfBirth: new Date(body.dateOfBirth),
+      nationalIdExpiry: new Date(body.nationalIdExpiry),
+      gender: body.gender,
+      countryOfResidence: CountryIso.SAUDI_ARABIA, // Always default to Saudi Arabia
+      mobileNumber: body.mobileNumber,
+      jobSector: body.jobSector,
+      employer: body.employer,
+      incomeSource: body.incomeSource,
+      jobCategory: body.jobCategory,
+      incomeRange: body.incomeRange,
       kycStatus: KycStatus.PENDING,
     });
 
-    return this.neoleapService.initiateKyc(customerId, body);
+    // Call Neoleap KYC API
+    const neoleapResponse = await this.neoleapService.initiateKycOnboarding(body);
+
+    // Create transaction record
+    const transaction = await this.kycTransactionRepo.create({
+      customerId,
+      userId: customer.userId,
+      nationalId: body.poiNumber,
+      stateId: neoleapResponse.stateId,
+      externalCustomerId: neoleapResponse.externalCustomerId,
+      nafathRandomCode: neoleapResponse.nafathRandomCode,
+      status: neoleapResponse.status,
+      formData: body,
+      initiatedAt: new Date(),
+    });
+
+    // Update customer with external ID
+    await this.customerRepository.updateCustomer(customerId, {
+      neoleapExternalCustomerId: neoleapResponse.externalCustomerId,
+    });
+
+    // Return formatted response
+    return {
+      transactionId: transaction.id,
+      stateId: neoleapResponse.stateId,
+      nafathRandomCode: neoleapResponse.nafathRandomCode,
+      status: neoleapResponse.status,
+      externalCustomerId: neoleapResponse.externalCustomerId,
+    };
   }
 
   @Transactional()
@@ -92,34 +140,34 @@ export class CustomerService {
   }
 
   async updateCustomerKyc(body: KycWebhookRequest) {
-    this.logger.log(`Updating KYC for customer with national ID ${body.nationalId}`);
+    this.logger.log(`Updating KYC for stateId ${body.stateId}`);
 
-    const customer = await this.customerRepository.findOne({ nationalId: body.nationalId });
-
-    if (!customer) {
-      throw new BadRequestException('CUSTOMER.NOT_FOUND');
+    // Find transaction by stateId
+    const transaction = await this.kycTransactionRepo.findByStateId(body.stateId);
+    
+    if (!transaction) {
+      this.logger.error(`KYC transaction not found for stateId ${body.stateId}`);
+      throw new BadRequestException('KYC transaction not found');
     }
 
-    await this.customerRepository.updateCustomer(customer.id, {
-      kycStatus: body.status === 'SUCCESS' ? KycStatus.APPROVED : KycStatus.REJECTED,
-      firstName: body.firstName,
-      lastName: body.lastName,
-      dateOfBirth: moment(body.dob, 'YYYYMMDD').toDate(),
-      nationalId: body.nationalId,
-      nationalIdExpiry: moment(body.nationalIdExpiry, 'YYYYMMDD').toDate(),
-      countryOfResidence: NumericToCountryIso[body.country],
-      country: NumericToCountryIso[body.country],
-      gender: body.gender === 'M' ? Gender.MALE : Gender.FEMALE,
-      sourceOfIncome: body.incomeSource,
-      profession: body.professionTitle,
-      professionType: body.professionType,
-      isPep: body.isPep === 'Y',
-      city: body.city,
-      region: body.region,
-      neighborhood: body.neighborhood,
-      street: body.street,
-      building: body.building,
+    const customer = await this.findCustomerById(transaction.customerId);
+
+    // Update transaction record
+    await this.kycTransactionRepo.updateByStateId(body.stateId, {
+      status: body.status,
+      callbackId: body.callbackId,
+      completedAt: new Date(),
     });
+
+    // Update customer KYC status and external customer ID
+    const kycStatus = body.status === 'ONBOARDING_SUCCESS' ? KycStatus.APPROVED : KycStatus.REJECTED;
+
+    await this.customerRepository.updateCustomer(customer.id, {
+      kycStatus,
+      neoleapExternalCustomerId: body.entity.externalId,
+    });
+
+    this.logger.log(`KYC updated successfully for customer ${customer.id}, status: ${body.status}, externalId: ${body.entity.externalId}`);
   }
 
   // TO BE REMOVED: This function is for testing only and will be removed
@@ -132,12 +180,6 @@ export class CustomerService {
       nationalId: '1089055972',
       nationalIdExpiry: moment('2031-09-17').toDate(),
       countryOfResidence: CountryIso.SAUDI_ARABIA,
-      country: CountryIso.SAUDI_ARABIA,
-      region: 'Mecca',
-      city: 'AT Taif',
-      neighborhood: 'Al Faisaliah',
-      street: 'Al Faisaliah Street',
-      building: '4',
     });
 
     await User.update(userId, {
@@ -149,6 +191,11 @@ export class CustomerService {
     return this.findCustomerById(userId);
   }
 
+  getKycOnboardMetadata() {
+    this.logger.log('Getting KYC onboard metadata');
+    return this.metadataService.getKycOnboardMetadata();
+  }
+
   // TO BE REMOVED: This function is for testing only and will be removed
   private generateSaudiPhoneNumber(): string {
     // Saudi mobile numbers are 9 digits, always starting with '5'

src/customer/services/index.ts

@@ -1 +1,2 @@
 export * from './customer.service';
+export * from './metadata.service';

src/customer/services/metadata.service.ts

@@ -0,0 +1,105 @@
+import { Injectable } from '@nestjs/common';
+import { IncomeRange, IncomeSource, JobCategory, JobSector, PoiType } from '../enums';
+import { KycMetadataResponseDto, MetadataOptionDto } from '../dtos/response';
+
+@Injectable()
+export class MetadataService {
+  getKycOnboardMetadata(): KycMetadataResponseDto {
+    return {
+      poiTypes: this.enumToOptions(PoiType, {
+        [PoiType.IQA]: 'Iqama (Resident ID)',
+        [PoiType.NAT]: 'National ID',
+      }),
+      jobSectors: this.enumToOptions(JobSector, {
+        [JobSector.GOVERNMENT_SECTOR]: 'Government Sector',
+        [JobSector.HOME_MAKER]: 'Home Maker',
+        [JobSector.MILITARY]: 'Military',
+        [JobSector.PRIVATE_SECTOR]: 'Private Sector',
+        [JobSector.RETIRED]: 'Retired',
+        [JobSector.SELF_EMPLOYED]: 'Self Employed',
+        [JobSector.STUDENT]: 'Student',
+        [JobSector.HOUSEHOLD_LABOR]: 'Household Labor',
+        [JobSector.UNEMPLOYED]: 'Unemployed',
+      }),
+      incomeSources: this.enumToOptions(IncomeSource, {
+        [IncomeSource.SALARY]: 'Salary',
+        [IncomeSource.ANCESTRAL]: 'Ancestral/Inheritance',
+        [IncomeSource.REAL_ESTATE]: 'Real Estate',
+        [IncomeSource.INVESTMENT_RETURNS]: 'Investment Returns',
+        [IncomeSource.RENTAL_INCOME]: 'Rental Income',
+        [IncomeSource.OTHER]: 'Other',
+      }),
+      jobCategories: this.enumToOptions(JobCategory, {
+        [JobCategory.ASSISTANT_MINISTER]: 'Assistant Minister',
+        [JobCategory.DEPUTY_MINISTER]: 'Deputy Minister',
+        [JobCategory.UNDER_SECRETARY]: 'Under Secretary',
+        [JobCategory.GENERAL_MANAGER]: 'General Manager',
+        [JobCategory.CHAIRMAN]: 'Chairman',
+        [JobCategory.MANAGER]: 'Manager',
+        [JobCategory.PROFESSOR]: 'Professor',
+        [JobCategory.HEAD_OF_COURT]: 'Head of Court',
+        [JobCategory.JUDGE]: 'Judge',
+        [JobCategory.LAWYER]: 'Lawyer',
+        [JobCategory.SCIENTIST]: 'Scientist',
+        [JobCategory.NOTARY]: 'Notary',
+        [JobCategory.BUSINESSMAN]: 'Businessman',
+        [JobCategory.MERCHANT]: 'Merchant',
+        [JobCategory.PHARMACIST]: 'Pharmacist',
+        [JobCategory.DOCTOR]: 'Doctor',
+        [JobCategory.MEDICAL_TECHNICIAN]: 'Medical Technician',
+        [JobCategory.NURSE]: 'Nurse',
+        [JobCategory.ENGINEER]: 'Engineer',
+        [JobCategory.CHEMIST]: 'Chemist',
+        [JobCategory.CONTRACTOR]: 'Contractor',
+        [JobCategory.AUDITOR_ACCOUNTANT]: 'Auditor/Accountant',
+        [JobCategory.RESEARCHER]: 'Researcher',
+        [JobCategory.ACCOUNTANT]: 'Accountant',
+        [JobCategory.JOURNALIST]: 'Journalist',
+        [JobCategory.DESIGNER]: 'Designer',
+        [JobCategory.COMPUTER_SPECIALIST]: 'Computer Specialist',
+        [JobCategory.TRANSLATOR]: 'Translator',
+        [JobCategory.TEACHER]: 'Teacher',
+        [JobCategory.PILOT]: 'Pilot',
+        [JobCategory.HOST]: 'Host',
+        [JobCategory.OFFICER]: 'Officer',
+        [JobCategory.SOLDIER]: 'Soldier',
+        [JobCategory.RETIRED]: 'Retired',
+        [JobCategory.SALESMAN]: 'Salesman',
+        [JobCategory.AUTHOR]: 'Author',
+        [JobCategory.CRAFTSMAN]: 'Craftsman',
+        [JobCategory.SECURITY]: 'Security',
+        [JobCategory.LABORER]: 'Laborer',
+        [JobCategory.DRIVER]: 'Driver',
+        [JobCategory.FARMER]: 'Farmer',
+        [JobCategory.HOUSEWIFE]: 'Housewife',
+        [JobCategory.DIPLOMAT]: 'Diplomat',
+        [JobCategory.STUDENT]: 'Student',
+        [JobCategory.FREELANCER]: 'Freelancer',
+        [JobCategory.SHEPHERD]: 'Shepherd',
+        [JobCategory.HOUSEMAID_OR_BABYSITTER]: 'Housemaid/Babysitter',
+        [JobCategory.CAPTAIN]: 'Captain',
+        [JobCategory.AMBASSADOR]: 'Ambassador',
+        [JobCategory.MARKETING]: 'Marketing',
+        [JobCategory.CONSULTING]: 'Consulting',
+        [JobCategory.SUPERVISOR]: 'Supervisor',
+        [JobCategory.BANKER]: 'Banker',
+        [JobCategory.BODYGUARD_OR_PERSONAL_ASSISTANT]: 'Bodyguard/Personal Assistant',
+      }),
+      incomeRanges: this.enumToOptions(IncomeRange, {
+        [IncomeRange.BELOW_2000]: 'SAR 2,000 and below',
+        [IncomeRange.RANGE_2000_5000]: 'SAR 2,000 to 5,000',
+        [IncomeRange.RANGE_5000_10000]: 'SAR 5,000 to 10,000',
+        [IncomeRange.RANGE_10000_20000]: 'SAR 10,000 to 20,000',
+        [IncomeRange.ABOVE_20000]: 'SAR 20,000 and above',
+      }),
+    };
+  }
+
+  private enumToOptions(enumObj: any, labels: Record<string, string>): MetadataOptionDto[] {
+    return Object.keys(enumObj).map((key) => ({
+      value: enumObj[key],
+      label: labels[enumObj[key]] || enumObj[key],
+    }));
+  }
+}
+

src/customer/validators/poi-number.validator.ts

@@ -0,0 +1,65 @@
+import {
+  registerDecorator,
+  ValidationOptions,
+  ValidatorConstraint,
+  ValidatorConstraintInterface,
+  ValidationArguments,
+} from 'class-validator';
+import { PoiType } from '../enums';
+
+@ValidatorConstraint({ name: 'IsValidPoiNumber', async: false })
+export class IsValidPoiNumberConstraint implements ValidatorConstraintInterface {
+  validate(poiNumber: string, args: ValidationArguments) {
+    const object = args.object as any;
+    const poiType = object.poiType;
+
+    if (!poiNumber || !poiType) {
+      return false;
+    }
+
+    // Saudi National ID: 10 digits, typically starts with 1 or 2
+    const nationalIdPattern = /^[12]\d{9}$/;
+
+    // Iqama (Resident ID): 10 digits, typically starts with other numbers (not 1 or 2)
+    const iqamaPattern = /^[3-9]\d{9}$/;
+
+    if (poiType === PoiType.NAT) {
+      return nationalIdPattern.test(poiNumber);
+    }
+
+    if (poiType === PoiType.IQA) {
+      return iqamaPattern.test(poiNumber);
+    }
+
+    return false;
+  }
+
+  defaultMessage(args: ValidationArguments) {
+    const object = args.object as any;
+    const poiType = object.poiType;
+
+    if (poiType === PoiType.NAT) {
+      return 'National ID must be 10 digits and start with 1 or 2';
+    }
+
+    if (poiType === PoiType.IQA) {
+      return 'Iqama number must be 10 digits and start with 3-9';
+    }
+
+    return 'Invalid POI number format';
+  }
+}
+
+export function IsValidPoiNumber(validationOptions?: ValidationOptions) {
+  return function (object: Object, propertyName: string) {
+    registerDecorator({
+      target: object.constructor,
+      propertyName: propertyName,
+      options: validationOptions,
+      constraints: [],
+      validator: IsValidPoiNumberConstraint,
+    });
+  };
+}
+
+

src/db/migrations/1757915357218-add-deleted-at-column-to-junior.ts

@@ -0,0 +1,13 @@
+import { MigrationInterface, QueryRunner } from 'typeorm';
+
+export class AddDeletedAtColumnToJunior1757915357218 implements MigrationInterface {
+  name = 'AddDeletedAtColumnToJunior1757915357218';
+
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`ALTER TABLE "juniors" ADD "deleted_at" TIMESTAMP WITH TIME ZONE`);
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`ALTER TABLE "juniors" DROP COLUMN "deleted_at"`);
+  }
+}

src/db/migrations/1760869651296-AddMerchantInfoToTransactions.ts

@@ -0,0 +1,18 @@
+import { MigrationInterface, QueryRunner } from "typeorm";
+
+export class AddMerchantInfoToTransactions1760869651296 implements MigrationInterface {
+    name = 'AddMerchantInfoToTransactions1760869651296'
+
+    public async up(queryRunner: QueryRunner): Promise<void> {
+        await queryRunner.query(`ALTER TABLE "transactions" ADD COLUMN IF NOT EXISTS "merchant_name" character varying`);
+        await queryRunner.query(`ALTER TABLE "transactions" ADD COLUMN IF NOT EXISTS "merchant_category_code" character varying`);
+        await queryRunner.query(`ALTER TABLE "transactions" ADD COLUMN IF NOT EXISTS "merchant_city" character varying`);
+    }
+
+    public async down(queryRunner: QueryRunner): Promise<void> {
+        await queryRunner.query(`ALTER TABLE "transactions" DROP COLUMN "merchant_city"`);
+        await queryRunner.query(`ALTER TABLE "transactions" DROP COLUMN "merchant_category_code"`);
+        await queryRunner.query(`ALTER TABLE "transactions" DROP COLUMN "merchant_name"`);
+    }
+
+}

src/db/migrations/1761032305682-AddUniqueConstraintToUserEmail.ts

@@ -0,0 +1,15 @@
+import { MigrationInterface, QueryRunner } from "typeorm";
+
+export class AddUniqueConstraintToUserEmail1761032305682 implements MigrationInterface {
+    name = 'AddUniqueConstraintToUserEmail1761032305682'
+
+    public async up(queryRunner: QueryRunner): Promise<void> {
+
+        await queryRunner.query(`ALTER TABLE "users" ADD CONSTRAINT "UQ_97672ac88f789774dd47f7c8be3" UNIQUE ("email")`);
+    }
+
+    public async down(queryRunner: QueryRunner): Promise<void> {
+        await queryRunner.query(`ALTER TABLE "users" DROP CONSTRAINT "UQ_97672ac88f789774dd47f7c8be3"`);
+    }
+
+}

src/db/migrations/1765804942393-AddKycFieldsAndTransactions.ts

@@ -0,0 +1,32 @@
+import { MigrationInterface, QueryRunner } from "typeorm";
+
+export class AddKycFieldsAndTransactions1765804942393 implements MigrationInterface {
+    name = 'AddKycFieldsAndTransactions1765804942393'
+
+    public async up(queryRunner: QueryRunner): Promise<void> {
+        await queryRunner.query(`CREATE TABLE "kyc_transactions" ("id" uuid NOT NULL DEFAULT uuid_generate_v4(), "customer_id" uuid NOT NULL, "user_id" uuid NOT NULL, "state_id" character varying(255) NOT NULL, "external_customer_id" character varying(255), "nafath_random_code" character varying(10), "status" character varying(50) NOT NULL DEFAULT 'INITIATED', "form_data" jsonb NOT NULL, "callback_id" character varying(255), "initiated_at" TIMESTAMP NOT NULL DEFAULT now(), "completed_at" TIMESTAMP, "expires_at" TIMESTAMP, "created_at" TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT now(), "updated_at" TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT now(), CONSTRAINT "UQ_231ce1d974b00919a8202e9ca3f" UNIQUE ("state_id"), CONSTRAINT "PK_aa56e3feebd4323c684ca146418" PRIMARY KEY ("id"))`);
+        await queryRunner.query(`ALTER TABLE "customers" ADD "neoleap_external_customer_id" character varying(255)`);
+        await queryRunner.query(`ALTER TABLE "customers" ADD "job_sector" character varying(100)`);
+        await queryRunner.query(`ALTER TABLE "customers" ADD "employer" character varying(255)`);
+        await queryRunner.query(`ALTER TABLE "customers" ADD "income_source" character varying(100)`);
+        await queryRunner.query(`ALTER TABLE "customers" ADD "job_category" character varying(100)`);
+        await queryRunner.query(`ALTER TABLE "customers" ADD "income_range" character varying(100)`);
+        await queryRunner.query(`ALTER TABLE "customers" ADD "mobile_number" character varying(20)`);
+        await queryRunner.query(`ALTER TABLE "kyc_transactions" ADD CONSTRAINT "FK_7651cf2e3ae6381377d8b9ed963" FOREIGN KEY ("customer_id") REFERENCES "customers"("id") ON DELETE CASCADE ON UPDATE NO ACTION`);
+        await queryRunner.query(`ALTER TABLE "kyc_transactions" ADD CONSTRAINT "FK_336a3791fd94d386e5c428850db" FOREIGN KEY ("user_id") REFERENCES "users"("id") ON DELETE CASCADE ON UPDATE NO ACTION`);
+    }
+
+    public async down(queryRunner: QueryRunner): Promise<void> {
+        await queryRunner.query(`ALTER TABLE "kyc_transactions" DROP CONSTRAINT "FK_336a3791fd94d386e5c428850db"`);
+        await queryRunner.query(`ALTER TABLE "kyc_transactions" DROP CONSTRAINT "FK_7651cf2e3ae6381377d8b9ed963"`);
+        await queryRunner.query(`ALTER TABLE "customers" DROP COLUMN "mobile_number"`);
+        await queryRunner.query(`ALTER TABLE "customers" DROP COLUMN "income_range"`);
+        await queryRunner.query(`ALTER TABLE "customers" DROP COLUMN "job_category"`);
+        await queryRunner.query(`ALTER TABLE "customers" DROP COLUMN "income_source"`);
+        await queryRunner.query(`ALTER TABLE "customers" DROP COLUMN "employer"`);
+        await queryRunner.query(`ALTER TABLE "customers" DROP COLUMN "job_sector"`);
+        await queryRunner.query(`ALTER TABLE "customers" DROP COLUMN "neoleap_external_customer_id"`);
+        await queryRunner.query(`DROP TABLE "kyc_transactions"`);
+    }
+
+}

src/db/migrations/1765877128065-AddNationalIdToKycTransactions.ts

@@ -0,0 +1,26 @@
+import { MigrationInterface, QueryRunner } from "typeorm";
+
+export class AddNationalIdToKycTransactions1765877128065 implements MigrationInterface {
+    name = 'AddNationalIdToKycTransactions1765877128065'
+
+    public async up(queryRunner: QueryRunner): Promise<void> {
+        // Add column as nullable first (to handle existing records)
+        await queryRunner.query(`ALTER TABLE "kyc_transactions" ADD "national_id" character varying(50)`);
+        
+        // Backfill existing records from form_data->poiNumber
+        await queryRunner.query(`
+            UPDATE "kyc_transactions" 
+            SET "national_id" = form_data->>'poiNumber' 
+            WHERE "national_id" IS NULL AND form_data->>'poiNumber' IS NOT NULL
+        `);
+        
+        // Now make it NOT NULL with a default empty string for safety
+        await queryRunner.query(`ALTER TABLE "kyc_transactions" ALTER COLUMN "national_id" SET DEFAULT ''`);
+        await queryRunner.query(`ALTER TABLE "kyc_transactions" ALTER COLUMN "national_id" SET NOT NULL`);
+    }
+
+    public async down(queryRunner: QueryRunner): Promise<void> {
+        await queryRunner.query(`ALTER TABLE "kyc_transactions" DROP COLUMN "national_id"`);
+    }
+
+}

src/db/migrations/1765891028260-RemoveOldCustomerColumns.ts

@@ -0,0 +1,23 @@
+import { MigrationInterface, QueryRunner } from 'typeorm';
+
+export class RemoveOldCustomerColumns1765891028260 implements MigrationInterface {
+  name = 'RemoveOldCustomerColumns1765891028260';
+
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    // Remove duplicate/unused columns that were replaced by KYC-specific fields
+    // source_of_income -> replaced by income_source
+    // profession -> replaced by job_sector
+    // profession_type -> replaced by job_category
+    await queryRunner.query(`ALTER TABLE "customers" DROP COLUMN IF EXISTS "source_of_income"`);
+    await queryRunner.query(`ALTER TABLE "customers" DROP COLUMN IF EXISTS "profession"`);
+    await queryRunner.query(`ALTER TABLE "customers" DROP COLUMN IF EXISTS "profession_type"`);
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    // Restore columns if migration is rolled back
+    await queryRunner.query(`ALTER TABLE "customers" ADD "source_of_income" character varying(255)`);
+    await queryRunner.query(`ALTER TABLE "customers" ADD "profession" character varying(255)`);
+    await queryRunner.query(`ALTER TABLE "customers" ADD "profession_type" character varying(255)`);
+  }
+}
+

src/db/migrations/1765975126402-RemoveAddressColumns.ts

@@ -0,0 +1,26 @@
+import { MigrationInterface, QueryRunner } from 'typeorm';
+
+export class RemoveAddressColumns1765975126402 implements MigrationInterface {
+  name = 'RemoveAddressColumns1765975126402';
+
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    // Drop address columns from customers table
+    await queryRunner.query(`ALTER TABLE "customers" DROP COLUMN IF EXISTS "country"`);
+    await queryRunner.query(`ALTER TABLE "customers" DROP COLUMN IF EXISTS "region"`);
+    await queryRunner.query(`ALTER TABLE "customers" DROP COLUMN IF EXISTS "city"`);
+    await queryRunner.query(`ALTER TABLE "customers" DROP COLUMN IF EXISTS "neighborhood"`);
+    await queryRunner.query(`ALTER TABLE "customers" DROP COLUMN IF EXISTS "street"`);
+    await queryRunner.query(`ALTER TABLE "customers" DROP COLUMN IF EXISTS "building"`);
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    // Re-add address columns in case of rollback
+    await queryRunner.query(`ALTER TABLE "customers" ADD "country" varchar(255)`);
+    await queryRunner.query(`ALTER TABLE "customers" ADD "region" varchar(255)`);
+    await queryRunner.query(`ALTER TABLE "customers" ADD "city" varchar(255)`);
+    await queryRunner.query(`ALTER TABLE "customers" ADD "neighborhood" varchar(255)`);
+    await queryRunner.query(`ALTER TABLE "customers" ADD "street" varchar(255)`);
+    await queryRunner.query(`ALTER TABLE "customers" ADD "building" varchar(255)`);
+  }
+}
+

src/db/migrations/index.ts

@@ -3,3 +3,10 @@ export * from './1754915164809-create-neoleap-related-entities';
 export * from './1754915164810-seed-default-avatar';
 export * from './1757349525708-create-money-requests-table';
 export * from './1757433339849-add-reservation-amount-to-account-entity';
+export * from './1757915357218-add-deleted-at-column-to-junior';
+export * from './1760869651296-AddMerchantInfoToTransactions';
+export * from './1761032305682-AddUniqueConstraintToUserEmail';
+export * from './1765804942393-AddKycFieldsAndTransactions';
+export * from './1765877128065-AddNationalIdToKycTransactions';
+export * from './1765891028260-RemoveOldCustomerColumns';
+export * from './1765975126402-RemoveAddressColumns';

src/guardian/controllers/guardian-transactions.controller.ts

@@ -0,0 +1,50 @@
+import { Controller, Get, Query, UseGuards } from '@nestjs/common';
+import { ApiBearerAuth, ApiTags, ApiQuery } from '@nestjs/swagger';
+import { Roles } from '~/auth/enums';
+import { IJwtPayload } from '~/auth/interfaces';
+import { AllowedRoles, AuthenticatedUser } from '~/common/decorators';
+import { AccessTokenGuard, RolesGuard } from '~/common/guards';
+import { ApiDataResponse, ApiLangRequestHeader } from '~/core/decorators';
+import { ResponseFactory } from '~/core/utils';
+import { ParentHomeResponseDto, PagedParentTransfersResponseDto } from '~/card/dtos/responses';
+import { GuardianTransactionsService } from '../services';
+
+
+@Controller('guardians/me')
+@ApiTags('Guardians')
+@ApiBearerAuth()
+@ApiLangRequestHeader()
+@UseGuards(AccessTokenGuard, RolesGuard)
+@AllowedRoles(Roles.GUARDIAN)
+export class GuardianTransactionsController {
+  constructor(private readonly guardianTxService: GuardianTransactionsService) {}
+
+  @Get('home')
+  @ApiQuery({ name: 'size', required: false, type: Number, example: 5 })
+  @ApiDataResponse(ParentHomeResponseDto)
+  async getHome(
+    @AuthenticatedUser() user: IJwtPayload,
+    @Query('size') size?: number,
+  ) {
+    const limit = Math.max(1, Math.min(Number(size) || 5, 20));
+    const res = await this.guardianTxService.getHome(user.sub, limit);
+    return ResponseFactory.data(res);
+  }
+
+  @Get('transfers')
+  @ApiQuery({ name: 'page', required: false, type: Number, example: 1 })
+  @ApiQuery({ name: 'size', required: false, type: Number, example: 10 })
+  @ApiDataResponse(PagedParentTransfersResponseDto)
+  async getTransfers(
+    @AuthenticatedUser() user: IJwtPayload,
+    @Query('page') page?: number,
+    @Query('size') size?: number,
+  ) {
+    const pageNum = Math.max(1, Number(page) || 1);
+    const pageSize = Math.max(1, Math.min(Number(size) || 10, 50));
+    const res = await this.guardianTxService.getTransfers(user.sub, pageNum, pageSize);
+    return ResponseFactory.data(res);
+  }
+}
+
+

src/guardian/controllers/index.ts

@@ -0,0 +1,3 @@
+export * from './guardian-transactions.controller';
+
+

src/guardian/guardian.module.ts

@@ -1,12 +1,18 @@
 import { Module } from '@nestjs/common';
+import { forwardRef } from '@nestjs/common';
+import { CustomerModule } from '~/customer/customer.module';
+import { CardModule } from '~/card/card.module';
+import { GuardianTransactionsController } from './controllers/guardian-transactions.controller';
+import { GuardianTransactionsService } from './services/guardian-transactions.service';
 import { TypeOrmModule } from '@nestjs/typeorm';
 import { Guardian } from './entities/guradian.entity';
 import { GuardianRepository } from './repositories';
 import { GuardianService } from './services';
 
 @Module({
-  providers: [GuardianService, GuardianRepository],
-  imports: [TypeOrmModule.forFeature([Guardian])],
+  providers: [GuardianService, GuardianRepository, GuardianTransactionsService],
+  controllers: [GuardianTransactionsController],
+  imports: [TypeOrmModule.forFeature([Guardian]), forwardRef(() => CustomerModule), forwardRef(() => CardModule)],
   exports: [GuardianService],
 })
 export class GuardianModule {}

src/guardian/services/guardian-transactions.service.ts

@@ -0,0 +1,42 @@
+import { Injectable } from '@nestjs/common';
+import { CustomerService } from '~/customer/services';
+import { ParentHomeResponseDto, PagedParentTransfersResponseDto } from '~/card/dtos/responses';
+import { TransactionService } from '~/card/services/transaction.service';
+
+@Injectable()
+export class GuardianTransactionsService {
+  constructor(
+    private readonly customerService: CustomerService,
+    private readonly transactionService: TransactionService,
+  ) {}
+
+  async getHome(guardianId: string, size: number): Promise<ParentHomeResponseDto> {
+    const parent = await this.customerService.findCustomerById(guardianId);
+    const primaryCard = parent.cards?.[0];
+
+    let availableBalance = 0;
+    if (primaryCard) {
+      const hasLimit = typeof primaryCard.limit === 'number' && !Number.isNaN(primaryCard.limit);
+      const hasBalance = primaryCard.account && typeof primaryCard.account.balance === 'number';
+      if (hasLimit && hasBalance && primaryCard.limit > 0) {
+        availableBalance = Math.min(primaryCard.limit, primaryCard.account.balance);
+      } else if (hasBalance) {
+        availableBalance = primaryCard.account.balance;
+      }
+    }
+
+    const recentTransfers = await this.transactionService.getParentTransfersOnly(guardianId, 1, size);
+
+    return new ParentHomeResponseDto(availableBalance, recentTransfers);
+  }
+
+  async getTransfers(
+    guardianId: string,
+    page: number,
+    size: number,
+  ): Promise<PagedParentTransfersResponseDto> {
+    return this.transactionService.getParentTransfersPaginated(guardianId, page, size);
+  }
+}
+
+

src/guardian/services/index.ts

@@ -1 +1,2 @@
-export * from './guardian.service';
+export * from './guardian.service'
+export * from './guardian-transactions.service'

src/i18n/ar/app.json

@@ -19,6 +19,10 @@
     "TOKEN_EXPIRED": "رمز المستخدم منتهي الصلاحية."
   },
 
+  "QR": {
+    "CODE_USED_OR_EXPIRED": "تم استخدام رمز QR مسبقًا أو انتهت صلاحيته."
+  },
+
   "USER": {
     "PHONE_ALREADY_VERIFIED": "تم التحقق من رقم الهاتف بالفعل.",
     "EMAIL_ALREADY_VERIFIED": "تم التحقق من عنوان البريد الإلكتروني بالفعل.",
@@ -68,7 +72,8 @@
     "CIVIL_ID_REQUIRED": "مطلوب بطاقة الهوية المدنية.",
     "CIVIL_ID_NOT_CREATED_BY_GUARDIAN": "تم تحميل بطاقة الهوية المدنية من قبل شخص آخر غير ولي الأمر.",
     "CIVIL_ID_ALREADY_EXISTS": "بطاقة الهوية المدنية مستخدمة بالفعل من قبل طفل آخر.",
-    "CANNOT_UPDATE_REGISTERED_USER": "الطفل قد سجل بالفعل. لا يُسمح بتحديث البيانات."
+    "CANNOT_UPDATE_REGISTERED_USER": "الطفل قد سجل بالفعل. لا يُسمح بتحديث البيانات.",
+    "CANNOT_DELETE_REGISTERED_USER": "الطفل قد سجل بالفعل. لا يُسمح بحذف الطفل."
   },
 
   "MONEY_REQUEST": {
@@ -103,6 +108,7 @@
   },
   "CARD": {
     "INSUFFICIENT_BALANCE": "البطاقة لا تحتوي على رصيد كافٍ لإكمال هذا التحويل.",
-    "DOES_NOT_BELONG_TO_GUARDIAN": "البطاقة لا تنتمي إلى ولي الأمر."
+    "DOES_NOT_BELONG_TO_GUARDIAN": "البطاقة لا تنتمي إلى ولي الأمر.",
+    "NOT_FOUND": "لم يتم العثور على البطاقة."
   }
 }

src/i18n/en/app.json

@@ -19,6 +19,10 @@
     "TOKEN_EXPIRED": "The user token has expired."
   },
 
+  "QR": {
+    "CODE_USED_OR_EXPIRED": "The QR code has already been used or expired."
+  },
+
   "USER": {
     "PHONE_ALREADY_VERIFIED": "The phone number has already been verified.",
     "EMAIL_ALREADY_VERIFIED": "The email address has already been verified.",
@@ -67,7 +71,8 @@
     "CIVIL_ID_REQUIRED": "Civil ID is required.",
     "CIVIL_ID_NOT_CREATED_BY_GUARDIAN": "The civil ID document was not uploaded by the guardian.",
     "CIVIL_ID_ALREADY_EXISTS": "The civil ID is already used by another junior.",
-    "CANNOT_UPDATE_REGISTERED_USER": "The junior has already registered. Updating details is not allowed."
+    "CANNOT_UPDATE_REGISTERED_USER": "The junior has already registered. Updating details is not allowed.",
+    "CANNOT_DELETE_REGISTERED_USER": "The junior has already registered. Deleting the junior is not allowed."
   },
 
   "MONEY_REQUEST": {
@@ -102,6 +107,7 @@
   },
   "CARD": {
     "INSUFFICIENT_BALANCE": "The card does not have sufficient balance to complete this transfer.",
-    "DOES_NOT_BELONG_TO_GUARDIAN": "The card does not belong to the guardian."
+    "DOES_NOT_BELONG_TO_GUARDIAN": "The card does not belong to the guardian.",
+    "NOT_FOUND": "The card was not found."
   }
 }

src/junior/controllers/junior.controller.ts

@@ -1,5 +1,17 @@
-import { Body, Controller, Get, Param, Patch, Post, Query, UseGuards } from '@nestjs/common';
-import { ApiBearerAuth, ApiTags } from '@nestjs/swagger';
+import {
+  Body,
+  Controller,
+  Delete,
+  Get,
+  HttpCode,
+  HttpStatus,
+  Param,
+  Patch,
+  Post,
+  Query,
+  UseGuards,
+} from '@nestjs/common';
+import { ApiBearerAuth, ApiTags, ApiQuery } from '@nestjs/swagger';
 import { Roles } from '~/auth/enums';
 import { IJwtPayload } from '~/auth/interfaces';
 import { AllowedRoles, AuthenticatedUser, Public } from '~/common/decorators';
@@ -20,6 +32,8 @@ import {
   ThemeResponseDto,
   TransferToJuniorResponseDto,
 } from '../dtos/response';
+import { WeeklySummaryResponseDto } from '../dtos/response/weekly-summary.response.dto';
+import { JuniorHomeResponseDto, PagedChildTransfersResponseDto } from '~/card/dtos/responses';
 import { JuniorService } from '../services';
 
 @Controller('juniors')
@@ -83,6 +97,14 @@ export class JuniorController {
     return ResponseFactory.data(new JuniorResponseDto(junior));
   }
 
+  @Delete(':juniorId')
+  @UseGuards(RolesGuard)
+  @AllowedRoles(Roles.GUARDIAN)
+  @HttpCode(HttpStatus.NO_CONTENT)
+  async deleteJunior(@AuthenticatedUser() user: IJwtPayload, @Param('juniorId', CustomParseUUIDPipe) juniorId: string) {
+    await this.juniorService.deleteJunior(juniorId, user.sub);
+  }
+
   @Post('set-theme')
   @UseGuards(RolesGuard)
   @AllowedRoles(Roles.JUNIOR)
@@ -124,4 +146,82 @@ export class JuniorController {
 
     return ResponseFactory.data(new TransferToJuniorResponseDto(newAmount));
   }
+
+  @Get(':juniorId/weekly-summary')
+  @UseGuards(RolesGuard)
+  @AllowedRoles(Roles.GUARDIAN)
+  @ApiDataResponse(WeeklySummaryResponseDto)
+  @ApiQuery({ name: 'startUtc', required: false, type: String, example: '2025-10-20T00:00:00.000Z', description: 'Start date (defaults to start of current week)' })
+  @ApiQuery({ name: 'endUtc', required: false, type: String, example: '2025-10-26T23:59:59.999Z', description: 'End date (defaults to end of current week)' })
+  async getWeeklySummary(
+    @Param('juniorId', CustomParseUUIDPipe) juniorId: string,
+    @AuthenticatedUser() user: IJwtPayload,
+    @Query('startUtc') startUtc?: string,
+    @Query('endUtc') endUtc?: string,
+  ) {
+    const startDate = startUtc ? new Date(startUtc) : undefined;
+    const endDate = endUtc ? new Date(endUtc) : undefined;
+    const summary = await this.juniorService.getWeeklySummary(juniorId, user.sub, startDate, endDate);
+    return ResponseFactory.data(summary);
+  }
+
+  @Get(':juniorId/home')
+  @UseGuards(RolesGuard)
+  @AllowedRoles(Roles.JUNIOR, Roles.GUARDIAN)
+  @ApiQuery({ name: 'size', required: false, type: Number, example: 5 })
+  @ApiDataResponse(JuniorHomeResponseDto)
+  async getJuniorHome(
+    @Param('juniorId', CustomParseUUIDPipe) juniorId: string,
+    @AuthenticatedUser() user: IJwtPayload,
+    @Query('size') size?: number,
+  ) {
+    const limit = Math.max(1, Math.min(Number(size) || 5, 20));
+    const res = await this.juniorService.getJuniorHome(juniorId, user.sub, limit);
+    return ResponseFactory.data(res);
+  }
+
+  @Get(':juniorId/transfers')
+  @UseGuards(RolesGuard)
+  @AllowedRoles(Roles.JUNIOR, Roles.GUARDIAN)
+  @ApiQuery({ name: 'page', required: false, type: Number, example: 1 })
+  @ApiQuery({ name: 'size', required: false, type: Number, example: 10 })
+  @ApiDataResponse(PagedChildTransfersResponseDto)
+  async getJuniorTransfers(
+    @Param('juniorId', CustomParseUUIDPipe) juniorId: string,
+    @AuthenticatedUser() user: IJwtPayload,
+    @Query('page') page?: number,
+    @Query('size') size?: number,
+  ) {
+    const pageNum = Math.max(1, Number(page) || 1);
+    const pageSize = Math.max(1, Math.min(Number(size) || 10, 50));
+    const res = await this.juniorService.getJuniorTransfers(juniorId, user.sub, pageNum, pageSize);
+    return ResponseFactory.data(res);
+  }
+
+  @Get(':juniorId/spending-history')
+  @UseGuards(RolesGuard)
+  @AllowedRoles(Roles.JUNIOR, Roles.GUARDIAN)
+  @ApiQuery({ name: 'startUtc', required: true, type: String, example: '2025-01-01T00:00:00.000Z' })
+  @ApiQuery({ name: 'endUtc', required: true, type: String, example: '2025-01-31T23:59:59.999Z' })
+  async getSpendingHistory(
+    @Param('juniorId', CustomParseUUIDPipe) juniorId: string,
+    @AuthenticatedUser() user: IJwtPayload,
+    @Query('startUtc') startUtc: string,
+    @Query('endUtc') endUtc: string,
+  ) {
+    const res = await this.juniorService.getSpendingHistory(juniorId, user.sub, new Date(startUtc), new Date(endUtc));
+    return ResponseFactory.data(res);
+  }
+
+  @Get(':juniorId/transactions/:transactionId')
+  @UseGuards(RolesGuard)
+  @AllowedRoles(Roles.JUNIOR, Roles.GUARDIAN)
+  async getTransactionDetail(
+    @Param('juniorId', CustomParseUUIDPipe) juniorId: string,
+    @Param('transactionId', CustomParseUUIDPipe) transactionId: string,
+    @AuthenticatedUser() user: IJwtPayload,
+  ) {
+    const res = await this.juniorService.getTransactionDetail(juniorId, user.sub, transactionId);
+    return ResponseFactory.data(res);
+  }
 }

src/junior/dtos/response/qr-code-validation-details.response.dto.ts

@@ -1,7 +1,8 @@
 import { ApiProperty } from '@nestjs/swagger';
+import { Gender } from '~/customer/enums';
 import { Guardian } from '~/guardian/entities/guradian.entity';
 import { Junior } from '~/junior/entities';
-import { GuardianRelationship } from '~/junior/enums';
+import { ChildRelationshipLabel, GuardianRelationship, Relationship } from '~/junior/enums';
 
 export class QrCodeValidationDetailsResponse {
   @ApiProperty()
@@ -26,6 +27,17 @@ export class QrCodeValidationDetailsResponse {
     this.phoneNumber = person.customer.user.phoneNumber;
     this.email = person.customer.user.email;
     this.dateOfBirth = person.customer.dateOfBirth;
-    this.relationship = guardian ? junior.relationship : GuardianRelationship[junior.relationship];
+    
+    if (guardian) {
+      this.relationship = junior.relationship;
+    } else {
+      if (junior.relationship === Relationship.PARENT) {
+        this.relationship = junior.customer.gender === Gender.MALE 
+          ? ChildRelationshipLabel.SON 
+          : ChildRelationshipLabel.DAUGHTER;
+      } else {
+        this.relationship = GuardianRelationship[junior.relationship];
+      }
+    }
   }
 }

src/junior/dtos/response/weekly-summary.response.dto.ts

@@ -0,0 +1,31 @@
+import { ApiProperty } from '@nestjs/swagger';
+
+export class WeeklySummaryResponseDto {
+  @ApiProperty({ description: 'Start date of the week', example: '2023-10-01' })
+  startOfWeek!: Date;
+  @ApiProperty({ description: 'End date of the week', example: '2023-10-07' })
+  endOfWeek!: Date;
+  @ApiProperty({ description: 'Total amount spent in the week', example: 350 })
+  total!: number;
+
+  @ApiProperty({ description: 'Amount spent on Sunday', example: 50 })
+  sunday!: number;
+
+  @ApiProperty({ description: 'Amount spent on Monday', example: 30 })
+  monday!: number;
+
+  @ApiProperty({ description: 'Amount spent on Tuesday', example: 20 })
+  tuesday!: number;
+
+  @ApiProperty({ description: 'Amount spent on Wednesday', example: 40 })
+  wednesday!: number;
+
+  @ApiProperty({ description: 'Amount spent on Thursday', example: 60 })
+  thursday!: number;
+
+  @ApiProperty({ description: 'Amount spent on Friday', example: 70 })
+  friday!: number;
+
+  @ApiProperty({ description: 'Amount spent on Saturday', example: 80 })
+  saturday!: number;
+}

src/junior/entities/junior.entity.ts

@@ -2,6 +2,7 @@ import {
   BaseEntity,
   Column,
   CreateDateColumn,
+  DeleteDateColumn,
   Entity,
   JoinColumn,
   ManyToOne,
@@ -49,4 +50,7 @@ export class Junior extends BaseEntity {
 
   @UpdateDateColumn({ name: 'updated_at', type: 'timestamp with time zone', default: () => 'CURRENT_TIMESTAMP' })
   updatedAt!: Date;
+
+  @DeleteDateColumn({ name: 'deleted_at', type: 'timestamp with time zone', nullable: true })
+  deletedAt!: Date | null;
 }

src/junior/enums/child-relationship-label.enum.ts

@@ -0,0 +1,5 @@
+export enum ChildRelationshipLabel {
+  SON = 'SON',
+  DAUGHTER = 'DAUGHTER',
+}
+

src/junior/enums/index.ts

@@ -1,3 +1,4 @@
+export * from './child-relationship-label.enum';
 export * from './guardian-relationship.enum';
 export * from './relationship.enum';
 export * from './theme-color.enum';

src/junior/repositories/junior.repository.ts

@@ -65,4 +65,8 @@ export class JuniorRepository {
       }),
     );
   }
+
+  softDelete(juniorId: string) {
+    return this.juniorRepository.softDelete({ id: juniorId });
+  }
 }

src/junior/services/junior.service.ts

@@ -1,9 +1,11 @@
 import { BadRequestException, Injectable, Logger } from '@nestjs/common';
+import { IsNull, Not } from 'typeorm';
 import { Transactional } from 'typeorm-transactional';
 import { Roles } from '~/auth/enums';
-import { CardService } from '~/card/services';
+import { CardService, TransactionService } from '~/card/services';
 import { NeoLeapService } from '~/common/modules/neoleap/services';
 import { PageOptionsRequestDto } from '~/core/dtos';
+import { ErrorCategory } from '~/core/enums';
 import { setIf } from '~/core/utils';
 import { CustomerService } from '~/customer/services';
 import { DocumentService, OciService } from '~/document/services';
@@ -19,6 +21,7 @@ import {
 import { Junior } from '../entities';
 import { JuniorRepository } from '../repositories';
 import { QrcodeService } from './qrcode.service';
+import { JuniorHomeResponseDto, PagedChildTransfersResponseDto } from '~/card/dtos/responses';
 
 @Injectable()
 export class JuniorService {
@@ -33,6 +36,7 @@ export class JuniorService {
     private readonly qrCodeService: QrcodeService,
     private readonly neoleapService: NeoLeapService,
     private readonly cardService: CardService,
+    private readonly transactionService: TransactionService,
   ) {}
 
   @Transactional()
@@ -110,18 +114,40 @@ export class JuniorService {
       }
       junior.customer.user.email = body.email;
     }
-    setIf(user, 'profilePictureId', body.profilePictureId);
+    // Update profile picture: ensure FK and relation are consistent to avoid TypeORM overriding the FK
+    if (typeof body.profilePictureId !== 'undefined') {
+      if (body.profilePictureId) {
+        const document = await this.documentService.findDocumentById(body.profilePictureId);
+        if (!document) {
+          this.logger.error(`Document with id ${body.profilePictureId} not found`);
+          throw new BadRequestException('DOCUMENT.NOT_FOUND');
+        }
+        if (document.createdById !== juniorId) {
+          this.logger.error(
+            `Document with id ${body.profilePictureId} does not belong to user ${juniorId}`,
+          );
+        }
+        user.profilePictureId = body.profilePictureId;
+        // assign relation to keep it consistent with FK during save
+        user.profilePicture = document as any;
+      } else {
+        // if empty string provided (unlikely), clear relation and FK
+        user.profilePicture = null as any;
+        user.profilePictureId = null as any;
+      }
+    }
     setIf(user, 'firstName', body.firstName);
     setIf(user, 'lastName', body.lastName);
 
     setIf(customer, 'firstName', body.firstName);
     setIf(customer, 'lastName', body.lastName);
     setIf(customer, 'dateOfBirth', body.dateOfBirth as unknown as Date);
+    setIf(customer, 'gender', body.gender);
 
     setIf(junior, 'relationship', body.relationship);
     await Promise.all([junior.save(), customer.save(), user.save()]);
     this.logger.log(`Junior ${juniorId} updated successfully`);
-    return junior;
+    return this.findJuniorById(juniorId, false, guardianId);
   }
 
   @Transactional()
@@ -154,7 +180,14 @@ export class JuniorService {
   async validateToken(token: string) {
     this.logger.log(`Validating token ${token}`);
     const juniorId = await this.userTokenService.validateToken(token, UserType.JUNIOR);
-    return this.findJuniorById(juniorId!, true);
+    const junior = await this.findJuniorById(juniorId!, true);
+
+    if (junior.customer?.user?.password) {
+      this.logger.error(`Token ${token} already used for junior ${juniorId}`);
+      throw new BadRequestException({ message: 'QR.CODE_USED_OR_EXPIRED', category: ErrorCategory.BUSINESS_ERROR });
+    }
+
+    return junior;
   }
 
   async generateToken(juniorId: string) {
@@ -183,6 +216,129 @@ export class JuniorService {
     return this.cardService.transferToChild(juniorId, body.amount);
   }
 
+  async deleteJunior(juniorId: string, guardianId: string) {
+    const doesBelong = await this.doesJuniorBelongToGuardian(guardianId, juniorId);
+
+    if (!doesBelong) {
+      this.logger.error(`Junior ${juniorId} does not belong to guardian ${guardianId}`);
+      throw new BadRequestException('JUNIOR.NOT_BELONG_TO_GUARDIAN');
+    }
+
+    const hasPassword = await this.userService.findUser({ id: juniorId, password: Not(IsNull()) });
+
+    if (hasPassword) {
+      this.logger.error(`Cannot delete junior ${juniorId} with registered user`);
+      throw new BadRequestException('JUNIOR.CANNOT_DELETE_REGISTERED_USER');
+    }
+
+    const { affected } = await this.juniorRepository.softDelete(juniorId);
+
+    if (affected === 0) {
+      this.logger.error(`Junior ${juniorId} not found`);
+      throw new BadRequestException('JUNIOR.NOT_FOUND');
+    }
+
+    this.logger.log(`Junior ${juniorId} deleted successfully`);
+  }
+
+  async getWeeklySummary(juniorId: string, guardianId: string, startDate?: Date, endDate?: Date) {
+    const doesBelong = await this.doesJuniorBelongToGuardian(guardianId, juniorId);
+
+    if (!doesBelong) {
+      this.logger.error(`Junior ${juniorId} does not belong to guardian ${guardianId}`);
+      throw new BadRequestException('JUNIOR.NOT_BELONG_TO_GUARDIAN');
+    }
+
+    this.logger.log(`Getting weekly summary for junior ${juniorId}`);
+    return this.cardService.getWeeklySummary(juniorId, startDate, endDate);
+  }
+
+  async getJuniorHome(juniorId: string, userId: string, size: number): Promise<JuniorHomeResponseDto> {
+    this.logger.log(`Getting home for junior ${juniorId}`);
+    
+    // Check if user is the junior themselves or their guardian
+    let junior: Junior | null;
+    if (juniorId === userId) {
+      // User is the junior accessing their own home
+      junior = await this.findJuniorById(juniorId, false);
+    } else {
+      // User might be the guardian accessing junior's home
+      junior = await this.findJuniorById(juniorId, false, userId);
+    }
+
+    if (!junior) {
+      throw new BadRequestException('JUNIOR.NOT_FOUND');
+    }
+
+    const card = junior.customer?.cards?.[0];
+    const availableBalance = card ? Math.min(card.limit, card.account.balance) : 0;
+
+    const recentTransfers = await this.transactionService.getChildTransfers(juniorId, 1, size);
+
+    return new JuniorHomeResponseDto(availableBalance, recentTransfers);
+  }
+
+  async getJuniorTransfers(
+    juniorId: string,
+    userId: string,
+    page: number,
+    size: number,
+  ): Promise<PagedChildTransfersResponseDto> {
+    this.logger.log(`Getting transfers for junior ${juniorId}`);
+    
+    // Check if user is the junior themselves or their guardian
+    let junior: Junior | null;
+    if (juniorId === userId) {
+      // User is the junior accessing their own transfers
+      junior = await this.findJuniorById(juniorId, false);
+    } else {
+      // User might be the guardian accessing junior's transfers
+      junior = await this.findJuniorById(juniorId, false, userId);
+    }
+
+    if (!junior) {
+      throw new BadRequestException('JUNIOR.NOT_FOUND');
+    }
+
+    return this.transactionService.getChildTransfersPaginated(juniorId, page, size);
+  }
+
+  async getSpendingHistory(juniorId: string, userId: string, startUtc: Date, endUtc: Date) {
+    this.logger.log(`Getting spending history for junior ${juniorId}`);
+    
+    // Check if user is the junior themselves or their guardian
+    let junior: Junior | null;
+    if (juniorId === userId) {
+      junior = await this.findJuniorById(juniorId, false);
+    } else {
+      junior = await this.findJuniorById(juniorId, false, userId);
+    }
+
+    if (!junior) {
+      throw new BadRequestException('JUNIOR.NOT_FOUND');
+    }
+
+    return this.transactionService.getChildSpendingHistory(juniorId, startUtc, endUtc);
+  }
+
+  async getTransactionDetail(juniorId: string, userId: string, transactionId: string) {
+    this.logger.log(`Getting transaction detail ${transactionId} for junior ${juniorId}`);
+    
+    // Check if user is the junior themselves or their guardian
+    let junior: Junior | null;
+    if (juniorId === userId) {
+      junior = await this.findJuniorById(juniorId, false);
+    } else {
+      junior = await this.findJuniorById(juniorId, false, userId);
+    }
+
+    if (!junior) {
+      throw new BadRequestException('JUNIOR.NOT_FOUND');
+    }
+
+    return this.transactionService.getTransactionDetail(transactionId, juniorId);
+  }
+
   private async prepareJuniorImages(juniors: Junior[]) {
     this.logger.log(`Preparing junior images`);
     await Promise.all(

src/user/dtos/request/update-user.request.dto.ts

@@ -1,6 +1,7 @@
-import { ApiProperty } from '@nestjs/swagger';
-import { IsNotEmpty, IsOptional, IsString, IsUUID } from 'class-validator';
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
+import { IsDateString, IsEmail, IsEnum, IsNotEmpty, IsOptional, IsString, IsUUID } from 'class-validator';
 import { i18nValidationMessage as i18n } from 'nestjs-i18n';
+import { Gender } from '~/customer/enums';
 export class UpdateUserRequestDto {
   @ApiProperty({ example: 'John' })
   @IsString({ message: i18n('validation.IsString', { path: 'general', property: 'user.firstName' }) })
@@ -14,8 +15,23 @@ export class UpdateUserRequestDto {
   @IsOptional()
   lastName!: string;
 
+  @ApiPropertyOptional({ example: 'child@example.com' })
+  @IsEmail({}, { message: i18n('validation.IsEmail', { path: 'general', property: 'user.email' }) })
+  @IsOptional()
+  email!: string;
+
   @ApiProperty({ example: '123e4567-e89b-12d3-a456-426614174000' })
   @IsUUID('4', { message: i18n('validation.IsUUID', { path: 'general', property: 'user.profilePictureId' }) })
   @IsOptional()
   profilePictureId!: string;
+
+  @ApiPropertyOptional({ enum: Gender })
+  @IsEnum(Gender, { message: i18n('validation.IsEnum', { path: 'general', property: 'customer.gender' }) })
+  @IsOptional()
+  gender!: Gender;
+
+  @ApiPropertyOptional({ example: '2020-01-01' })
+  @IsDateString({}, { message: i18n('validation.IsDateString', { path: 'general', property: 'customer.dateOfBirth' }) })
+  @IsOptional()
+  dateOfBirth!: Date;
 }

src/user/entities/user.entity.ts

@@ -28,7 +28,7 @@ export class User extends BaseEntity {
   @Column('varchar', { length: 255, name: 'last_name', nullable: false })
   lastName!: string;
 
-  @Column('varchar', { length: 255, name: 'email', nullable: true })
+  @Column('varchar', { length: 255, name: 'email', nullable: true, unique: true })
   email!: string;
 
   @Column('varchar', { length: 255, name: 'phone_number', nullable: true })

src/user/services/user.service.ts

@@ -64,14 +64,12 @@ export class UserService {
       this.customerService.createGuardianCustomer(userId, {
         firstName: body.firstName,
         lastName: body.lastName,
-        dateOfBirth: body.dateOfBirth,
         countryOfResidence: body.countryOfResidence,
       }),
       this.userRepository.update(userId, {
         isPhoneVerified: true,
         password: hashedPassword,
         salt,
-        ...(body.email && { email: body.email }),
       }),
     ]);
   }
@@ -102,7 +100,6 @@ export class UserService {
       return this.userRepository.createUnverifiedUser({
         phoneNumber: body.phoneNumber,
         countryCode: body.countryCode,
-        email: body.email,
         firstName: body.firstName,
         lastName: body.lastName,
         roles: [Roles.GUARDIAN],
@@ -191,20 +188,50 @@ export class UserService {
   async updateUser(userId: string, data: UpdateUserRequestDto) {
     await this.validateProfilePictureId(data.profilePictureId, userId);
 
+    if (data.email) {
+      const userWithEmail = await this.findUser({ email: data.email });
+      if (userWithEmail && userWithEmail.id !== userId) {
+        this.logger.error(`Email ${data.email} is already taken by another user`);
+        throw new BadRequestException('USER.EMAIL_ALREADY_TAKEN');
+      }
+    }
+
     this.logger.log(`Updating user ${userId} with data ${JSON.stringify(data)}`);
-    const { affected } = await this.userRepository.update(userId, data);
+    
+    const { gender, dateOfBirth, ...userData } = data;
+    
+    const { affected } = await this.userRepository.update(userId, userData);
     if (affected === 0) {
       this.logger.error(`User with id ${userId} not found`);
       throw new BadRequestException('USER.NOT_FOUND');
     }
+
+    if (gender !== undefined || dateOfBirth !== undefined) {
+      const customerData: Partial<{ gender: typeof gender; dateOfBirth: Date }> = {};
+      if (gender !== undefined) {
+        customerData.gender = gender;
+      }
+      if (dateOfBirth !== undefined) {
+        customerData.dateOfBirth = dateOfBirth;
+      }
+      await this.customerService.updateCustomer(userId, customerData);
+    }
   }
 
   async updateUserEmail(userId: string, email: string) {
-    const userWithEmail = await this.findUser({ email, isEmailVerified: true });
+    const userWithEmail = await this.findUser({ email });
 
     if (userWithEmail) {
       if (userWithEmail.id === userId) {
-        return;
+        this.logger.log(`Generating OTP for current email ${email} for user ${userId}`);
+        await this.userRepository.update(userId, { isEmailVerified: false });
+        
+        return this.otpService.generateAndSendOtp({
+          userId,
+          recipient: email,
+          otpType: OtpType.EMAIL,
+          scope: OtpScope.VERIFY_EMAIL,
+        });
       }
 
       this.logger.error(`Email ${email} is already taken by another user`);

test/app.e2e-spec.ts

@@ -1,5 +1,5 @@
-import { Test, TestingModule } from '@nestjs/testing';
 import { INestApplication } from '@nestjs/common';
+import { Test, TestingModule } from '@nestjs/testing';
 import request from 'supertest';
 import { AppModule } from './../src/app.module';
 
@@ -18,4 +18,6 @@ describe('AppController (e2e)', () => {
   it('/ (GET)', () => {
     return request(app.getHttpServer()).get('/').expect(200).expect('Hello World!');
   });
+
+
 });