refactor: remove unused PoiValidationRule class from KycMetadataResponseDto

Enhance profile picture handling in JuniorService to ensure foreign

src/app.module.ts

@@ -9,6 +9,7 @@ import { LoggerModule } from 'nestjs-pino';
 import { DataSource } from 'typeorm';
 import { addTransactionalDataSource } from 'typeorm-transactional';
 import { AuthModule } from './auth/auth.module';
+import { CardModule } from './card/card.module';
 import { CacheModule } from './common/modules/cache/cache.module';
 import { LookupModule } from './common/modules/lookup/lookup.module';
 import { NeoLeapModule } from './common/modules/neoleap/neoleap.module';
@@ -26,7 +27,8 @@ import { GuardianModule } from './guardian/guardian.module';
 import { HealthModule } from './health/health.module';
 import { JuniorModule } from './junior/junior.module';
 import { UserModule } from './user/user.module';
-import { CardModule } from './card/card.module';
+import { WebhookModule } from './webhook/webhook.module';
+import { MoneyRequestModule } from './money-request/money-request.module';
 
 @Module({
   controllers: [],
@@ -61,6 +63,7 @@ import { CardModule } from './card/card.module';
     CustomerModule,
     JuniorModule,
     GuardianModule,
+    CardModule,
 
     NotificationModule,
     OtpModule,
@@ -71,7 +74,8 @@ import { CardModule } from './card/card.module';
 
     CronModule,
     NeoLeapModule,
-    CardModule,
+    WebhookModule,
+    MoneyRequestModule,
   ],
   providers: [
     // Global Pipes

src/auth/controllers/auth.controller.ts

@@ -9,9 +9,11 @@ import {
   ChangePasswordRequestDto,
   CreateUnverifiedUserRequestDto,
   ForgetPasswordRequestDto,
+  JuniorLoginRequestDto,
   LoginRequestDto,
   RefreshTokenRequestDto,
   SendForgetPasswordOtpRequestDto,
+  setJuniorPasswordRequestDto,
   VerifyForgetPasswordOtpRequestDto,
   VerifyUserRequestDto,
 } from '../dtos/request';
@@ -69,10 +71,26 @@ export class AuthController {
   @Post('change-password')
   @HttpCode(HttpStatus.NO_CONTENT)
   @UseGuards(AccessTokenGuard)
-  async changePassword(@AuthenticatedUser() { sub }: IJwtPayload, @Body() forgetPasswordDto: ChangePasswordRequestDto) {
+  changePassword(@AuthenticatedUser() { sub }: IJwtPayload, @Body() forgetPasswordDto: ChangePasswordRequestDto) {
     return this.authService.changePassword(sub, forgetPasswordDto);
   }
 
+  @Post('junior/set-password')
+  @HttpCode(HttpStatus.NO_CONTENT)
+  @Public()
+  setJuniorPasscode(@Body() setPassworddto: setJuniorPasswordRequestDto) {
+    return this.authService.setJuniorPassword(setPassworddto);
+  }
+
+  @Post('junior/login')
+  @HttpCode(HttpStatus.OK)
+  @ApiDataResponse(LoginResponseDto)
+  async juniorLogin(@Body() juniorLoginDto: JuniorLoginRequestDto) {
+    const [res, user] = await this.authService.juniorLogin(juniorLoginDto);
+
+    return ResponseFactory.data(new LoginResponseDto(res, user));
+  }
+
   @Post('refresh-token')
   @Public()
   async refreshToken(@Body() { refreshToken }: RefreshTokenRequestDto) {

src/auth/dtos/request/index.ts

@@ -1,11 +1,11 @@
 export * from './change-password.request.dto';
 export * from './create-unverified-user.request.dto';
 export * from './forget-password.request.dto';
+export * from './junior-login.request.dto';
 export * from './login.request.dto';
 export * from './refresh-token.request.dto';
 export * from './send-forget-password-otp.request.dto';
 export * from './set-junior-password.request.dto';
-export * from './set-passcode.request.dto';
 export * from './verify-forget-password-otp.request.dto';
 export * from './verify-otp.request.dto';
 export * from './verify-user.request.dto';

src/auth/dtos/request/junior-login.request.dto.ts

@@ -0,0 +1,12 @@
+import { ApiProperty } from '@nestjs/swagger';
+import { IsEmail, IsString } from 'class-validator';
+import { i18nValidationMessage as i18n } from 'nestjs-i18n';
+export class JuniorLoginRequestDto {
+  @ApiProperty({ example: 'test@junior.com' })
+  @IsEmail({}, { message: i18n('validation.IsEmail', { path: 'general', property: 'auth.email' }) })
+  email!: string;
+
+  @ApiProperty({ example: 'Abcd1234@' })
+  @IsString({ message: i18n('validation.IsString', { path: 'general', property: 'auth.password' }) })
+  password!: string;
+}

src/auth/dtos/request/set-junior-password.request.dto.ts

@@ -1,8 +1,11 @@
-import { ApiProperty } from '@nestjs/swagger';
+import { ApiProperty, PickType } from '@nestjs/swagger';
 import { IsNotEmpty, IsString } from 'class-validator';
 import { i18nValidationMessage as i18n } from 'nestjs-i18n';
-import { SetPasscodeRequestDto } from './set-passcode.request.dto';
-export class setJuniorPasswordRequestDto extends SetPasscodeRequestDto {
+import { ChangePasswordRequestDto } from './change-password.request.dto';
+export class setJuniorPasswordRequestDto extends PickType(ChangePasswordRequestDto, [
+  'newPassword',
+  'confirmNewPassword',
+]) {
   @ApiProperty()
   @IsString({ message: i18n('validation.IsNumberString', { path: 'general', property: 'auth.qrToken' }) })
   @IsNotEmpty({ message: i18n('validation.IsNotEmpty', { path: 'general', property: 'auth.qrToken' }) })

src/auth/dtos/request/set-passcode.request.dto.ts

@@ -1,15 +0,0 @@
-import { ApiProperty } from '@nestjs/swagger';
-import { IsNumberString, MaxLength, MinLength } from 'class-validator';
-import { i18nValidationMessage as i18n } from 'nestjs-i18n';
-const PASSCODE_LENGTH = 6;
-
-export class SetPasscodeRequestDto {
-  @ApiProperty({ example: '123456' })
-  @IsNumberString(
-    { no_symbols: true },
-    { message: i18n('validation.IsNumberString', { path: 'general', property: 'auth.passcode' }) },
-  )
-  @MinLength(PASSCODE_LENGTH, { message: i18n('validation.MinLength', { path: 'general', property: 'auth.passcode' }) })
-  @MaxLength(PASSCODE_LENGTH, { message: i18n('validation.MaxLength', { path: 'general', property: 'auth.passcode' }) })
-  passcode!: string;
-}

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

@@ -14,6 +14,7 @@ import {
   ChangePasswordRequestDto,
   CreateUnverifiedUserRequestDto,
   ForgetPasswordRequestDto,
+  JuniorLoginRequestDto,
   LoginRequestDto,
   SendForgetPasswordOtpRequestDto,
   setJuniorPasswordRequestDto,
@@ -196,11 +197,14 @@ export class AuthService {
     this.logger.log(`Password changed successfully for user with id ${userId}`);
   }
 
-  async setJuniorPasscode(body: setJuniorPasswordRequestDto) {
+  async setJuniorPassword(body: setJuniorPasswordRequestDto) {
     this.logger.log(`Setting passcode for junior with qrToken ${body.qrToken}`);
+    if (body.newPassword != body.confirmNewPassword) {
+      throw new BadRequestException('AUTH.PASSWORD_MISMATCH');
+    }
     const juniorId = await this.userTokenService.validateToken(body.qrToken, UserType.JUNIOR);
     const salt = bcrypt.genSaltSync(SALT_ROUNDS);
-    const hashedPasscode = bcrypt.hashSync(body.passcode, salt);
+    const hashedPasscode = bcrypt.hashSync(body.newPassword, salt);
     await this.userService.setPassword(juniorId!, hashedPasscode, salt);
     await this.userTokenService.invalidateToken(body.qrToken);
     this.logger.log(`Passcode set successfully for junior with id ${juniorId}`);
@@ -278,6 +282,26 @@ export class AuthService {
     return [tokens, user];
   }
 
+  async juniorLogin(juniorLoginDto: JuniorLoginRequestDto): Promise<[ILoginResponse, User]> {
+    const user = await this.userService.findUser({ email: juniorLoginDto.email });
+
+    if (!user || !user.roles.includes(Roles.JUNIOR)) {
+      throw new UnauthorizedException('AUTH.INVALID_CREDENTIALS');
+    }
+
+    this.logger.log(`validating password for user with email ${juniorLoginDto.email}`);
+    const isPasswordValid = bcrypt.compareSync(juniorLoginDto.password, user.password);
+
+    if (!isPasswordValid) {
+      this.logger.error(`Invalid password for user with email ${juniorLoginDto.email}`);
+      throw new UnauthorizedException('AUTH.INVALID_CREDENTIALS');
+    }
+
+    const tokens = await this.generateAuthToken(user);
+    this.logger.log(`Password validated successfully for user`);
+    return [tokens, user];
+  }
+
   private async generateAuthToken(user: User) {
     this.logger.log(`Generating auth token for user with id ${user.id}`);
     const [accessToken, refreshToken] = await Promise.all([

src/card/card.module.ts

@@ -1,5 +1,8 @@
-import { Module } from '@nestjs/common';
+import { forwardRef, Module } from '@nestjs/common';
 import { TypeOrmModule } from '@nestjs/typeorm';
+import { NeoLeapModule } from '~/common/modules/neoleap/neoleap.module';
+import { CustomerModule } from '~/customer/customer.module';
+import { CardsController } from './controllers';
 import { Card } from './entities';
 import { Account } from './entities/account.entity';
 import { Transaction } from './entities/transaction.entity';
@@ -11,7 +14,11 @@ import { AccountService } from './services/account.service';
 import { TransactionService } from './services/transaction.service';
 
 @Module({
-  imports: [TypeOrmModule.forFeature([Card, Account, Transaction])],
+  imports: [
+    TypeOrmModule.forFeature([Card, Account, Transaction]),
+    forwardRef(() => NeoLeapModule),
+    forwardRef(() => CustomerModule), // <-- add forwardRef here
+  ],
   providers: [
     CardService,
     CardRepository,
@@ -21,5 +28,6 @@ import { TransactionService } from './services/transaction.service';
     AccountRepository,
   ],
   exports: [CardService, TransactionService],
+  controllers: [CardsController],
 })
 export class CardModule {}

src/card/controllers/cards.controller.ts

@@ -0,0 +1,86 @@
+import { Body, Controller, Get, HttpCode, HttpStatus, Param, Post, UseGuards } from '@nestjs/common';
+import { ApiBearerAuth, ApiOperation, ApiTags } 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 { CardEmbossingDetailsResponseDto } from '~/common/modules/neoleap/dtos/response';
+import { ApiDataResponse } from '~/core/decorators';
+import { ResponseFactory } from '~/core/utils';
+import { FundIbanRequestDto } from '../dtos/requests';
+import { AccountIbanResponseDto, CardResponseDto, ChildCardResponseDto } from '../dtos/responses';
+import { CardService } from '../services';
+
+@Controller('cards')
+@ApiBearerAuth()
+@ApiTags('Cards')
+@UseGuards(AccessTokenGuard)
+export class CardsController {
+  constructor(private readonly cardService: CardService) {}
+
+  @Post()
+  @ApiDataResponse(CardResponseDto)
+  async createCard(@AuthenticatedUser() { sub }: IJwtPayload) {
+    const card = await this.cardService.createCard(sub);
+    return ResponseFactory.data(new CardResponseDto(card));
+  }
+
+  @Get('child-cards')
+  @UseGuards(RolesGuard)
+  @AllowedRoles(Roles.GUARDIAN)
+  @ApiDataResponse(ChildCardResponseDto)
+  async getChildCards(@AuthenticatedUser() { sub }: IJwtPayload) {
+    const cards = await this.cardService.getChildCards(sub);
+    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)
+  @ApiDataResponse(CardEmbossingDetailsResponseDto)
+  async getChildCardEmbossingDetails(@Param('cardid') cardId: string, @AuthenticatedUser() { sub }: IJwtPayload) {
+    const res = await this.cardService.getChildCardEmbossingInformation(cardId, sub);
+    return ResponseFactory.data(res);
+  }
+
+  @Get('current')
+  @ApiDataResponse(CardResponseDto)
+  async getCurrentCard(@AuthenticatedUser() { sub }: IJwtPayload) {
+    const card = await this.cardService.getCardByCustomerId(sub);
+    return ResponseFactory.data(new CardResponseDto(card));
+  }
+
+  @Get('embossing-details')
+  @ApiDataResponse(CardEmbossingDetailsResponseDto)
+  async getCardById(@AuthenticatedUser() { sub }: IJwtPayload) {
+    const res = await this.cardService.getEmbossingInformation(sub);
+    return ResponseFactory.data(res);
+  }
+
+  @Get('iban')
+  @UseGuards(RolesGuard)
+  @AllowedRoles(Roles.GUARDIAN)
+  @ApiDataResponse(AccountIbanResponseDto)
+  async getCardIban(@AuthenticatedUser() { sub }: IJwtPayload) {
+    const iban = await this.cardService.getIbanInformation(sub);
+    return ResponseFactory.data(new AccountIbanResponseDto(iban));
+  }
+
+  @Post('mock/fund-iban')
+  @ApiOperation({ summary: 'Mock endpoint to fund the IBAN - For testing purposes only' })
+  @UseGuards(RolesGuard)
+  @AllowedRoles(Roles.GUARDIAN)
+  @HttpCode(HttpStatus.NO_CONTENT)
+  fundIban(@Body() { amount, iban }: FundIbanRequestDto) {
+    return this.cardService.fundIban(iban, amount);
+  }
+}

src/card/controllers/index.ts

@@ -0,0 +1 @@
+export * from './cards.controller';

src/card/dtos/requests/fund-iban.request.dto.ts

@@ -0,0 +1,9 @@
+import { ApiProperty } from '@nestjs/swagger';
+import { IsString } from 'class-validator';
+import { TransferToJuniorRequestDto } from '~/junior/dtos/request';
+
+export class FundIbanRequestDto extends TransferToJuniorRequestDto {
+  @ApiProperty({ example: 'DE89370400440532013000' })
+  @IsString()
+  iban!: string;
+}

src/card/dtos/requests/index.ts

@@ -0,0 +1 @@
+export * from './fund-iban.request.dto';

src/card/dtos/responses/account-iban.response.dto.ts

@@ -0,0 +1,10 @@
+import { ApiProperty } from '@nestjs/swagger';
+
+export class AccountIbanResponseDto {
+  @ApiProperty({ example: 'DE89370400440532013000' })
+  iban!: string;
+
+  constructor(iban: string) {
+    this.iban = iban;
+  }
+}

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

@@ -0,0 +1,66 @@
+import { ApiProperty } from '@nestjs/swagger';
+import { Card } from '~/card/entities';
+import { CardScheme, CardStatus, CustomerType } from '~/card/enums';
+import { CardStatusDescriptionMapper } from '~/card/mappers/card-status-description.mapper';
+import { UserLocale } from '~/core/enums';
+
+export class CardResponseDto {
+  @ApiProperty({
+    example: 'b34df8c2-5d3e-4b1a-9c2f-7e3b1a2d3f4e',
+  })
+  id!: string;
+
+  @ApiProperty({
+    example: '123456',
+    description: 'The first six digits of the card number.',
+  })
+  firstSixDigits!: string;
+
+  @ApiProperty({ example: '7890', description: 'The last four digits of the card number.' })
+  lastFourDigits!: string;
+
+  @ApiProperty({
+    enum: CardScheme,
+    description: 'The card scheme (e.g., VISA, MASTERCARD).',
+  })
+  scheme!: CardScheme;
+
+  @ApiProperty({
+    enum: CardStatus,
+    description: 'The current status of the card (e.g., ACTIVE, PENDING).',
+  })
+  status!: CardStatus;
+
+  @ApiProperty({
+    example: 'The card is active',
+    description: 'A description of the card status.',
+  })
+  statusDescription!: string;
+
+  @ApiProperty({
+    example: 2000.0,
+    description: 'The credit limit of the card.',
+  })
+  balance!: number;
+
+  @ApiProperty({
+    example: 100.0,
+    nullable: true,
+    description: 'The reserved balance of the card (applicable for child accounts).',
+  })
+  reservedBalance!: number | null;
+
+  constructor(card: Card) {
+    this.id = card.id;
+    this.firstSixDigits = card.firstSixDigits;
+    this.lastFourDigits = card.lastFourDigits;
+    this.scheme = card.scheme;
+    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.account.reservedBalance;
+    this.reservedBalance = card.customerType === CustomerType.PARENT ? card.account.reservedBalance : null;
+  }
+}

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

@@ -0,0 +1,48 @@
+import { ApiProperty } from '@nestjs/swagger';
+import { Card } from '~/card/entities';
+import { Gender } from '~/customer/enums';
+import { DocumentMetaResponseDto } from '~/document/dtos/response';
+import { CardResponseDto } from './card.response.dto';
+
+class JuniorInfo {
+  @ApiProperty({ example: 'id' })
+  id!: string;
+
+  @ApiProperty({ example: 'FirstName' })
+  firstName!: string;
+
+  @ApiProperty({ example: 'LastName' })
+  lastName!: string;
+
+  @ApiProperty({ example: 'test@example.com' })
+  email!: string;
+
+  @ApiProperty({ enum: Gender, example: Gender.MALE })
+  gender!: Gender;
+
+  @ApiProperty({ example: '2000-01-01' })
+  dateOfBirth!: Date;
+
+  @ApiProperty({ example: DocumentMetaResponseDto, nullable: true })
+  profilePicture!: DocumentMetaResponseDto | null;
+
+  constructor(card: Card) {
+    this.id = card.customer?.junior?.id;
+    this.firstName = card.customer?.firstName;
+    this.lastName = card.customer?.lastName;
+    this.email = card.customer?.user?.email;
+    this.gender = card.customer.gender;
+    this.profilePicture = card.customer?.user?.profilePicture
+      ? new DocumentMetaResponseDto(card.customer.user.profilePicture)
+      : null;
+  }
+}
+export class ChildCardResponseDto extends CardResponseDto {
+  @ApiProperty({ type: JuniorInfo })
+  junior!: JuniorInfo | null;
+
+  constructor(card: Card) {
+    super(card);
+    this.junior = card.customer?.junior ? new JuniorInfo(card) : 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

@@ -0,0 +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,9 +22,30 @@ 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',
+    transformer: {
+      to: (value: number) => value,
+      from: (value: string) => parseFloat(value),
+    },
+  })
+  reservedBalance!: number;
+
   @OneToMany(() => Card, (card) => card.account, { cascade: true })
   cards!: Card[];
 

src/card/entities/card.entity.ts

@@ -39,7 +39,7 @@ export class Card {
   @Column({ type: 'varchar', nullable: false, name: 'customer_type' })
   customerType!: CustomerType;
 
-  @Column({ type: 'varchar', nullable: false, default: CardColors.BLUE })
+  @Column({ type: 'varchar', nullable: false, default: CardColors.DEEP_MAGENTA })
   color!: CardColors;
 
   @Column({ type: 'varchar', nullable: false, default: CardStatus.PENDING })

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/card-colors.enum.ts

@@ -1,4 +1,13 @@
 export enum CardColors {
-  RED = 'RED',
-  BLUE = 'BLUE',
+  RAINBOW_PASTEL = 'RAINBOW_PASTEL',
+  DEEP_MAGENTA = 'DEEP_MAGENTA',
+  GREEN_TEAL = 'GREEN_TEAL',
+
+  BLUE_GREEN = 'BLUE_GREEN',
+  TEAL_NAVY = 'TEAL_NAVY',
+  PURPLE_PINK = 'PURPLE_PINK',
+
+  GOLD_BLUE = 'GOLD_BLUE',
+  OCEAN_BLUE = 'OCEAN_BLUE',
+  BROWN_RUST = 'BROWN_RUST',
 }

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/mappers/card-status-description.mapper.ts

@@ -1,7 +1,10 @@
 import { UserLocale } from '~/core/enums';
 import { CardStatusDescription } from '../enums';
 
-export const CardStatusMapper: Record<CardStatusDescription, { [key in UserLocale]: { description: string } }> = {
+export const CardStatusDescriptionMapper: Record<
+  CardStatusDescription,
+  { [key in UserLocale]: { description: string } }
+> = {
   [CardStatusDescription.NORMAL]: {
     [UserLocale.ENGLISH]: { description: 'The card is active' },
     [UserLocale.ARABIC]: { description: 'البطاقة نشطة' },

src/card/repositories/account.repository.ts

@@ -27,6 +27,13 @@ export class AccountRepository {
     });
   }
 
+  getAccountByIban(iban: string): Promise<Account | null> {
+    return this.accountRepository.findOne({
+      where: { iban },
+      relations: ['cards'],
+    });
+  }
+
   getAccountByAccountNumber(accountNumber: string): Promise<Account | null> {
     return this.accountRepository.findOne({
       where: { accountNumber },
@@ -34,6 +41,13 @@ export class AccountRepository {
     });
   }
 
+  getAccountByCustomerId(customerId: string): Promise<Account | null> {
+    return this.accountRepository.findOne({
+      where: { cards: { customerId } },
+      relations: ['cards'],
+    });
+  }
+
   topUpAccountBalance(accountReference: string, amount: number) {
     return this.accountRepository.increment({ accountReference }, 'balance', amount);
   }
@@ -41,4 +55,12 @@ export class AccountRepository {
   decreaseAccountBalance(accountReference: string, amount: number) {
     return this.accountRepository.decrement({ accountReference }, 'balance', amount);
   }
+
+  increaseReservedBalance(accountId: string, amount: number) {
+    return this.accountRepository.increment({ id: accountId }, 'reservedBalance', amount);
+  }
+
+  decreaseReservedBalance(accountId: string, amount: number) {
+    return this.accountRepository.decrement({ id: accountId }, 'reservedBalance', amount);
+  }
 }

src/card/repositories/card.repository.ts

@@ -9,26 +9,47 @@ import { CardColors, CardIssuers, CardScheme, CardStatus, CardStatusDescription,
 export class CardRepository {
   constructor(@InjectRepository(Card) private readonly cardRepository: Repository<Card>) {}
 
-  createCard(customerId: string, accountId: string, card: CreateApplicationResponse): Promise<Card> {
+  createCard(
+    customerId: string,
+    accountId: string,
+    card: CreateApplicationResponse,
+    cardColor?: CardColors,
+    parentId?: string,
+  ): Promise<Card> {
     return this.cardRepository.save(
       this.cardRepository.create({
         customerId: customerId,
         expiry: card.expiryDate,
         cardReference: card.cardId,
-        customerType: CustomerType.PARENT,
+        customerType: parentId ? CustomerType.CHILD : CustomerType.PARENT,
         firstSixDigits: card.firstSixDigits,
         lastFourDigits: card.lastFourDigits,
-        color: CardColors.BLUE,
+        color: cardColor ? cardColor : CardColors.DEEP_MAGENTA,
         scheme: CardScheme.VISA,
         issuer: CardIssuers.NEOLEAP,
         accountId: accountId,
         vpan: card.vpan,
+        parentId,
       }),
     );
   }
 
+  findChildCardsForGuardian(guardianId: string): Promise<Card[]> {
+    return this.cardRepository.find({
+      where: { parentId: guardianId, customerType: CustomerType.CHILD },
+      relations: ['account', 'customer', 'customer.user', 'customer.user.profilePicture', 'customer.junior'],
+    });
+  }
+
   getCardById(id: string): Promise<Card | null> {
-    return this.cardRepository.findOne({ where: { id } });
+    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> {
@@ -42,9 +63,10 @@ export class CardRepository {
     });
   }
 
-  getActiveCardForCustomer(customerId: string): Promise<Card | null> {
+  getCardByCustomerId(customerId: string): Promise<Card | null> {
     return this.cardRepository.findOne({
-      where: { customerId, status: CardStatus.ACTIVE },
+      where: { customerId },
+      relations: ['account'],
     });
   }
 
@@ -54,4 +76,10 @@ export class CardRepository {
       statusDescription: statusDescription,
     });
   }
+
+  updateCardLimit(cardId: string, newLimit: number) {
+    return this.cardRepository.update(cardId, {
+      limit: newLimit,
+    });
+  }
 }

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,
       }),
     );
   }
@@ -57,9 +60,124 @@ export class TransactionRepository {
     );
   }
 
+  createInternalChildTransaction(card: Card, amount: number): Promise<Transaction> {
+    return this.transactionRepository.save(
+      this.transactionRepository.create({
+        transactionId: `CHILD-${card.id}-${Date.now()}`,
+        transactionAmount: amount,
+        transactionCurrency: '682',
+        billingAmount: 0,
+        settlementAmount: 0,
+        transactionDate: new Date(),
+        fees: 0,
+        cardId: card.id,
+        cardReference: card.cardReference,
+        cardMaskedNumber: card.firstSixDigits + '******' + card.lastFourDigits,
+        accountId: card.account!.id,
+        transactionType: TransactionType.INTERNAL,
+        accountReference: card.account!.accountReference,
+        transactionScope: TransactionScope.CARD,
+        vatOnFees: 0,
+      }),
+    );
+  }
+
   findTransactionByReference(transactionId: string, accountReference: string): Promise<Transaction | null> {
     return this.transactionRepository.findOne({
       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

@@ -27,15 +27,33 @@ export class AccountService {
     return account;
   }
 
-  async creditAccountBalance(accountReference: string, amount: number) {
+  async getAccountByIban(iban: string): Promise<Account> {
+    const account = await this.accountRepository.getAccountByIban(iban);
+    if (!account) {
+      throw new UnprocessableEntityException('ACCOUNT.NOT_FOUND');
+    }
+    return account;
+  }
+
+  creditAccountBalance(accountReference: string, amount: number) {
     return this.accountRepository.topUpAccountBalance(accountReference, amount);
   }
 
+  async getAccountByCustomerId(customerId: string): Promise<Account> {
+    const account = await this.accountRepository.getAccountByCustomerId(customerId);
+    if (!account) {
+      throw new UnprocessableEntityException('ACCOUNT.NOT_FOUND');
+    }
+    return account;
+  }
+
   async decreaseAccountBalance(accountReference: string, amount: number) {
     const account = await this.getAccountByReferenceNumber(accountReference);
+
     /**
+     *
      * While there is no need to check for insufficient balance  because this is a webhook handler,
-     * I just added this check to ensure we don't have corruption in our data especially if this service is used elsewhere.
+     * I just added this check to ensure we don't have corruption in our data.
      */
 
     if (account.balance < amount) {
@@ -44,4 +62,20 @@ export class AccountService {
 
     return this.accountRepository.decreaseAccountBalance(accountReference, amount);
   }
+
+  increaseReservedBalance(account: Account, amount: number) {
+    // 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);
+  }
+
+  decrementReservedBalance(account: Account, amount: number) {
+    return this.accountRepository.decreaseReservedBalance(account.id, amount);
+  }
+
+  //THIS IS A MOCK FUNCTION FOR TESTING PURPOSES ONLY
+  async fundIban(iban: string, amount: number) {
+    const account = await this.getAccountByIban(iban);
+    return this.accountRepository.topUpAccountBalance(account.accountReference, amount);
+  }
 }

src/card/services/card.service.ts

@@ -1,22 +1,77 @@
-import { BadRequestException, Injectable } from '@nestjs/common';
+import { BadRequestException, forwardRef, Inject, Injectable, Logger } from '@nestjs/common';
+import Decimal from 'decimal.js';
 import { Transactional } from 'typeorm-transactional';
 import { AccountCardStatusChangedWebhookRequest } from '~/common/modules/neoleap/dtos/requests';
-import { CreateApplicationResponse } from '~/common/modules/neoleap/dtos/response';
+import { NeoLeapService } from '~/common/modules/neoleap/services';
+import { Customer } from '~/customer/entities';
+import { KycStatus } from '~/customer/enums';
+import { CustomerService } from '~/customer/services';
+import { OciService } from '~/document/services';
 import { Card } from '../entities';
+import { CardColors } from '../enums';
 import { CardStatusMapper } from '../mappers/card-status.mapper';
 import { CardRepository } from '../repositories';
 import { AccountService } from './account.service';
+import { TransactionService } from './transaction.service';
 
 @Injectable()
 export class CardService {
-  constructor(private readonly cardRepository: CardRepository, private readonly accountService: AccountService) {}
+  private readonly logger = new Logger(CardService.name);
+  constructor(
+    private readonly cardRepository: CardRepository,
+    private readonly accountService: AccountService,
+    private readonly ociService: OciService,
+    @Inject(forwardRef(() => TransactionService)) private readonly transactionService: TransactionService,
+    @Inject(forwardRef(() => NeoLeapService)) private readonly neoleapService: NeoLeapService,
+    @Inject(forwardRef(() => CustomerService)) private readonly customerService: CustomerService,
+  ) {}
 
   @Transactional()
-  async createCard(customerId: string, cardData: CreateApplicationResponse): Promise<Card> {
-    const account = await this.accountService.createAccount(cardData);
-    return this.cardRepository.createCard(customerId, account.id, cardData);
+  async createCard(customerId: string): Promise<Card> {
+    const customer = await this.customerService.findCustomerById(customerId);
+
+    if (customer.kycStatus !== KycStatus.APPROVED) {
+      throw new BadRequestException('CUSTOMER.KYC_NOT_APPROVED');
+    }
+
+    if (customer.cards.length > 0) {
+      throw new BadRequestException('CUSTOMER.ALREADY_HAS_CARD');
+    }
+
+    const data = await this.neoleapService.createApplication(customer);
+    const account = await this.accountService.createAccount(data);
+    const createdCard = await this.cardRepository.createCard(customerId, account.id, data);
+
+    return this.getCardById(createdCard.id);
   }
 
+  async getChildCards(guardianId: string): Promise<Card[]> {
+    const cards = await this.cardRepository.findChildCardsForGuardian(guardianId);
+    await this.prepareJuniorImages(cards);
+    return cards;
+  }
+
+  async createCardForChild(parentCustomer: Customer, childCustomer: Customer, cardColor: CardColors, cardPin: string) {
+    const data = await this.neoleapService.createChildCard(parentCustomer, childCustomer, cardPin);
+    const createdCard = await this.cardRepository.createCard(
+      childCustomer.id,
+      parentCustomer.cards[0].account.id,
+      data,
+      cardColor,
+      parentCustomer.id,
+    );
+
+    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);
 
@@ -46,11 +101,12 @@ export class CardService {
     return card;
   }
 
-  async getActiveCardForCustomer(customerId: string): Promise<Card> {
-    const card = await this.cardRepository.getActiveCardForCustomer(customerId);
+  async getCardByCustomerId(customerId: string): Promise<Card> {
+    const card = await this.cardRepository.getCardByCustomerId(customerId);
     if (!card) {
       throw new BadRequestException('CARD.NOT_FOUND');
     }
+
     return card;
   }
 
@@ -60,4 +116,82 @@ export class CardService {
 
     return this.cardRepository.updateCardStatus(card.id, status, description);
   }
+
+  async getEmbossingInformation(customerId: string) {
+    const card = await this.getCardByCustomerId(customerId);
+
+    return this.neoleapService.getEmbossingInformation(card);
+  }
+
+  async getChildCardEmbossingInformation(cardId: string, guardianId: string) {
+    const card = await this.getCardById(cardId);
+    if (card.parentId !== guardianId) {
+      throw new BadRequestException('CARD.DOES_NOT_BELONG_TO_GUARDIAN');
+    }
+    return this.neoleapService.getEmbossingInformation(card);
+  }
+
+  async updateCardLimit(cardId: string, newLimit: number) {
+    const { affected } = await this.cardRepository.updateCardLimit(cardId, newLimit);
+
+    if (affected === 0) {
+      throw new BadRequestException('CARD.NOT_FOUND');
+    }
+  }
+
+  async getIbanInformation(customerId: string) {
+    const account = await this.accountService.getAccountByCustomerId(customerId);
+    return account.iban;
+  }
+
+  @Transactional()
+  async transferToChild(juniorId: string, amount: number) {
+    const card = await this.getCardByCustomerId(juniorId);
+
+    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');
+    }
+
+    const finalAmount = Decimal(amount).plus(card.limit);
+    await Promise.all([
+      this.neoleapService.updateCardControl(card.cardReference, finalAmount.toNumber()),
+      this.updateCardLimit(card.id, finalAmount.toNumber()),
+      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);
+  }
+
+  private async prepareJuniorImages(cards: Card[]) {
+    this.logger.log(`Preparing junior images`);
+    await Promise.all(
+      cards.map(async (card) => {
+        const profilePicture = card.customer?.user?.profilePicture;
+
+        if (profilePicture) {
+          profilePicture.url = await this.ociService.generatePreSignedUrl(profilePicture);
+        }
+      }),
+    );
+  }
 }

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,21 +1,32 @@
-import { Injectable, UnprocessableEntityException } from '@nestjs/common';
+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, 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 {
   constructor(
     private readonly transactionRepository: TransactionRepository,
-    private readonly cardService: CardService,
     private readonly accountService: AccountService,
+    @Inject(forwardRef(() => CardService)) private readonly cardService: CardService,
   ) {}
 
   @Transactional()
@@ -30,7 +41,22 @@ export class TransactionService {
     const transaction = await this.transactionRepository.createCardTransaction(card, body);
     const total = new Decimal(body.transactionAmount).plus(body.billingAmount).plus(body.fees).plus(body.vatOnFees);
 
-    await this.accountService.decreaseAccountBalance(card.account.accountReference, total.toNumber());
+    if (card.customerType === CustomerType.CHILD) {
+      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());
+    }
 
     return transaction;
   }
@@ -51,6 +77,12 @@ export class TransactionService {
     return transaction;
   }
 
+  async createInternalChildTransaction(cardId: string, amount: number) {
+    const card = await this.cardService.getCardById(cardId);
+    const transaction = await this.transactionRepository.createInternalChildTransaction(card, amount);
+    return transaction;
+  }
+
   private async findExistingTransaction(transactionId: string, accountReference: string): Promise<Transaction | null> {
     const existingTransaction = await this.transactionRepository.findTransactionByReference(
       transactionId,
@@ -59,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__/card-embossing-details.mock.ts

@@ -0,0 +1,38 @@
+export const CARD_EMBOSSING_DETAILS_MOCK = {
+  ResponseHeader: {
+    Version: '1.0.0',
+    MsgUid: 'adaa1893-9f95-48a8-b7a1-0422bcf629b5',
+    Source: 'ZOD',
+    ServiceId: 'GetEmbossingInformation',
+    ReqDateTime: '2025-06-11T07:32:16.304Z',
+    RspDateTime: '2025-08-14T10:01:14.205',
+    ResponseCode: '000',
+    ResponseType: 'Success',
+    ProcessingTime: 67,
+    EncryptionKey: null,
+    ResponseDescription: 'Operation Successful',
+    LocalizedResponseDescription: null,
+    CustomerSpecificResponseDescriptionList: null,
+    HeaderUserDataList: null,
+  },
+  GetEmbossingInformationResponseDetails: {
+    icvv: '259',
+    Track1: '%B4017786818471184^AMMAR/QAFFAF^31102261029800997000000?',
+    Track2: ';4017786818471184=31102261029899700?',
+    Track3: null,
+    EmvTrack1: '1029800259000000',
+    EmvTrack2: '4017786818471184D31102261029825900',
+    ClearPan: '4017786818471184',
+    PinBlock: '663B1A71D8112D97',
+    Cvv: '997',
+    Cvv2: '834',
+    iCvv: '259',
+    Pvv: '0298',
+    EmbossingName: 'AMMAR QAFFAF',
+    ExpiryDate: '20311031',
+    OldPlasticExpiryDate: null,
+    CardStatus: '30',
+    OldPlasticCardStatus: '  ',
+    EmbossingRecord: null,
+  },
+};

src/common/modules/neoleap/__mocks__/create-application.mock.ts

@@ -1,750 +1,198 @@
-export const CREATE_APPLICATION_MOCK = {
-  ResponseHeader: {
-    Version: '1.0.0',
-    MsgUid: 'adaa1893-9f95-48a8-b7a1-0422bcf629b5',
-    Source: 'ZOD',
-    ServiceId: 'CreateNewApplication',
-    ReqDateTime: '2025-06-03T07:32:16.304Z',
-    RspDateTime: '2025-06-03T08:21:15.662',
-    ResponseCode: '000',
-    ResponseType: 'Success',
-    ProcessingTime: 1665,
-    EncryptionKey: null,
-    ResponseDescription: 'Operation Successful',
-    LocalizedResponseDescription: null,
-    CustomerSpecificResponseDescriptionList: null,
-    HeaderUserDataList: null,
-  },
+import { randomInt, randomUUID } from 'crypto';
 
-  CreateNewApplicationResponseDetails: {
-    InstitutionCode: '1100',
-    ApplicationTypeDetails: {
-      TypeCode: '01',
-      Description: 'Normal Primary',
-      Additional: false,
-      Corporate: false,
-      UserData: null,
+/** Generate a string of `n` random digits (first digit never 0). */
+function randomDigits(n: number): string {
+  if (n <= 0) return '0';
+  let s = String(randomInt(1, 10)); // first digit 1–9
+  for (let i = 1; i < n; i++) s += String(randomInt(0, 10));
+  return s;
+}
+
+/** Build a fresh mock object every time it's called */
+export function buildCreateApplicationMock() {
+  const now = new Date().toISOString();
+
+  return {
+    ResponseHeader: {
+      Version: '1.0.0',
+      MsgUid: randomUUID(),
+      Source: 'ZOD',
+      ServiceId: 'CreateNewApplication',
+      ReqDateTime: now,
+      RspDateTime: now,
+      ResponseCode: '000',
+      ResponseType: 'Success',
+      ProcessingTime: 1665,
+      EncryptionKey: null,
+      ResponseDescription: 'Operation Successful',
+      LocalizedResponseDescription: null,
+      CustomerSpecificResponseDescriptionList: null,
+      HeaderUserDataList: null,
     },
-    ApplicationDetails: {
-      cif: null,
-      ApplicationNumber: '3300000000073',
-      ExternalApplicationNumber: '3',
-      ApplicationStatus: '04',
-      Organization: 0,
-      Product: '1101',
-      ApplicatonDate: '2025-05-29',
-      ApplicationSource: 'O',
-      SalesSource: null,
-      DeliveryMethod: 'V',
-      ProgramCode: null,
-      Campaign: null,
-      Plastic: null,
-      Design: null,
-      ProcessStage: '99',
-      ProcessStageStatus: 'S',
-      Score: null,
-      ExternalScore: null,
-      RequestedLimit: 0,
-      SuggestedLimit: null,
-      AssignedLimit: 0,
-      AllowedLimitList: null,
-      EligibilityCheckResult: '00',
-      EligibilityCheckDescription: null,
-      Title: 'Mr.',
-      FirstName: 'Abdalhamid',
-      SecondName: null,
-      ThirdName: null,
-      LastName: ' Ahmad',
-      FullName: 'Abdalhamid Ahmad',
-      EmbossName: 'ABDALHAMID AHMAD',
-      PlaceOfBirth: null,
-      DateOfBirth: '1999-01-07',
-      LocalizedDateOfBirth: '1999-01-07',
-      Age: 26,
-      Gender: 'M',
-      Married: 'U',
-      Nationality: '682',
-      IdType: '01',
-      IdNumber: '1089055972',
-      IdExpiryDate: '2031-09-17',
-      EducationLevel: null,
-      ProfessionCode: 0,
-      NumberOfDependents: 0,
-      EmployerName: 'N/A',
-      EmploymentYears: 0,
-      EmploymentMonths: 0,
-      EmployerPhoneArea: null,
-      EmployerPhoneNumber: null,
-      EmployerPhoneExtension: null,
-      EmployerMobile: null,
-      EmployerFaxArea: null,
-      EmployerFax: null,
-      EmployerCity: null,
-      EmployerAddress: null,
-      EmploymentActivity: null,
-      EmploymentStatus: null,
-      CIF: null,
-      BankAccountNumber: ' ',
-      Currency: {
-        CurrCode: '682',
-        AlphaCode: 'SAR',
+
+    CreateNewApplicationResponseDetails: {
+      InstitutionCode: '1100',
+      ApplicationTypeDetails: {
+        TypeCode: '01',
+        Description: 'Normal Primary',
+        Additional: false,
+        Corporate: false,
+        UserData: null,
       },
-      RequestedCurrencyList: null,
-      CreditAccountNumber: '6000000000000000',
-      AccountType: '30',
-      OpenDate: null,
-      Income: 0,
-      AdditionalIncome: 0,
-      TotalIncome: 0,
-      CurrentBalance: 0,
-      AverageBalance: 0,
-      AssetsBalance: 0,
-      InsuranceBalance: 0,
-      DepositAmount: 0,
-      GuarenteeAccountNumber: null,
-      GuarenteeAmount: 0,
-      InstalmentAmount: 0,
-      AutoDebit: 'N',
-      PaymentMethod: '2',
-      BillingCycle: 'C1',
-      OldIssueDate: null,
-      OtherPaymentsDate: null,
-      MaximumDelinquency: null,
-      CreditBureauDecision: null,
-      CreditBureauUserData: null,
-      ECommerce: 'N',
-      NumberOfCards: 0,
-      OtherBank: null,
-      OtherBankDescription: null,
-      InsuranceProduct: null,
-      SocialCode: '000',
-      JobGrade: 0,
-      Flags: [
-        {
-          Position: 1,
-          Value: '0',
-        },
-        {
-          Position: 2,
-          Value: '0',
-        },
-        {
-          Position: 3,
-          Value: '0',
-        },
-        {
-          Position: 4,
-          Value: '0',
-        },
-        {
-          Position: 5,
-          Value: '0',
-        },
-        {
-          Position: 6,
-          Value: '0',
-        },
-        {
-          Position: 7,
-          Value: '0',
-        },
-        {
-          Position: 8,
-          Value: '0',
-        },
-        {
-          Position: 9,
-          Value: '0',
-        },
-        {
-          Position: 10,
-          Value: '0',
-        },
-        {
-          Position: 11,
-          Value: '0',
-        },
-        {
-          Position: 12,
-          Value: '0',
-        },
-        {
-          Position: 13,
-          Value: '0',
-        },
-        {
-          Position: 14,
-          Value: '0',
-        },
-        {
-          Position: 15,
-          Value: '0',
-        },
-        {
-          Position: 16,
-          Value: '0',
-        },
-        {
-          Position: 17,
-          Value: '0',
-        },
-        {
-          Position: 18,
-          Value: '0',
-        },
-        {
-          Position: 19,
-          Value: '0',
-        },
-        {
-          Position: 20,
-          Value: '0',
-        },
-        {
-          Position: 21,
-          Value: '0',
-        },
-        {
-          Position: 22,
-          Value: '0',
-        },
-        {
-          Position: 23,
-          Value: '0',
-        },
-        {
-          Position: 24,
-          Value: '0',
-        },
-        {
-          Position: 25,
-          Value: '0',
-        },
-        {
-          Position: 26,
-          Value: '0',
-        },
-        {
-          Position: 27,
-          Value: '0',
-        },
-        {
-          Position: 28,
-          Value: '0',
-        },
-        {
-          Position: 29,
-          Value: '0',
-        },
-        {
-          Position: 30,
-          Value: '0',
-        },
-        {
-          Position: 31,
-          Value: '0',
-        },
-        {
-          Position: 32,
-          Value: '0',
-        },
-        {
-          Position: 33,
-          Value: '0',
-        },
-        {
-          Position: 34,
-          Value: '0',
-        },
-        {
-          Position: 35,
-          Value: '0',
-        },
-        {
-          Position: 36,
-          Value: '0',
-        },
-        {
-          Position: 37,
-          Value: '0',
-        },
-        {
-          Position: 38,
-          Value: '0',
-        },
-        {
-          Position: 39,
-          Value: '0',
-        },
-        {
-          Position: 40,
-          Value: '0',
-        },
-        {
-          Position: 41,
-          Value: '0',
-        },
-        {
-          Position: 42,
-          Value: '0',
-        },
-        {
-          Position: 43,
-          Value: '0',
-        },
-        {
-          Position: 44,
-          Value: '0',
-        },
-        {
-          Position: 45,
-          Value: '0',
-        },
-        {
-          Position: 46,
-          Value: '0',
-        },
-        {
-          Position: 47,
-          Value: '0',
-        },
-        {
-          Position: 48,
-          Value: '0',
-        },
-        {
-          Position: 49,
-          Value: '0',
-        },
-        {
-          Position: 50,
-          Value: '0',
-        },
-        {
-          Position: 51,
-          Value: '0',
-        },
-        {
-          Position: 52,
-          Value: '0',
-        },
-        {
-          Position: 53,
-          Value: '0',
-        },
-        {
-          Position: 54,
-          Value: '0',
-        },
-        {
-          Position: 55,
-          Value: '0',
-        },
-        {
-          Position: 56,
-          Value: '0',
-        },
-        {
-          Position: 57,
-          Value: '0',
-        },
-        {
-          Position: 58,
-          Value: '0',
-        },
-        {
-          Position: 59,
-          Value: '0',
-        },
-        {
-          Position: 60,
-          Value: '0',
-        },
-        {
-          Position: 61,
-          Value: '0',
-        },
-        {
-          Position: 62,
-          Value: '0',
-        },
-        {
-          Position: 63,
-          Value: '0',
-        },
-        {
-          Position: 64,
-          Value: '0',
-        },
-      ],
-      CheckFlags: [
-        {
-          Position: 1,
-          Value: '0',
-        },
-        {
-          Position: 2,
-          Value: '0',
-        },
-        {
-          Position: 3,
-          Value: '0',
-        },
-        {
-          Position: 4,
-          Value: '0',
-        },
-        {
-          Position: 5,
-          Value: '0',
-        },
-        {
-          Position: 6,
-          Value: '0',
-        },
-        {
-          Position: 7,
-          Value: '0',
-        },
-        {
-          Position: 8,
-          Value: '0',
-        },
-        {
-          Position: 9,
-          Value: '0',
-        },
-        {
-          Position: 10,
-          Value: '0',
-        },
-        {
-          Position: 11,
-          Value: '0',
-        },
-        {
-          Position: 12,
-          Value: '0',
-        },
-        {
-          Position: 13,
-          Value: '0',
-        },
-        {
-          Position: 14,
-          Value: '0',
-        },
-        {
-          Position: 15,
-          Value: '0',
-        },
-        {
-          Position: 16,
-          Value: '0',
-        },
-        {
-          Position: 17,
-          Value: '0',
-        },
-        {
-          Position: 18,
-          Value: '0',
-        },
-        {
-          Position: 19,
-          Value: '0',
-        },
-        {
-          Position: 20,
-          Value: '0',
-        },
-        {
-          Position: 21,
-          Value: '0',
-        },
-        {
-          Position: 22,
-          Value: '0',
-        },
-        {
-          Position: 23,
-          Value: '0',
-        },
-        {
-          Position: 24,
-          Value: '0',
-        },
-        {
-          Position: 25,
-          Value: '0',
-        },
-        {
-          Position: 26,
-          Value: '0',
-        },
-        {
-          Position: 27,
-          Value: '0',
-        },
-        {
-          Position: 28,
-          Value: '0',
-        },
-        {
-          Position: 29,
-          Value: '0',
-        },
-        {
-          Position: 30,
-          Value: '0',
-        },
-        {
-          Position: 31,
-          Value: '0',
-        },
-        {
-          Position: 32,
-          Value: '0',
-        },
-        {
-          Position: 33,
-          Value: '0',
-        },
-        {
-          Position: 34,
-          Value: '0',
-        },
-        {
-          Position: 35,
-          Value: '0',
-        },
-        {
-          Position: 36,
-          Value: '0',
-        },
-        {
-          Position: 37,
-          Value: '0',
-        },
-        {
-          Position: 38,
-          Value: '0',
-        },
-        {
-          Position: 39,
-          Value: '0',
-        },
-        {
-          Position: 40,
-          Value: '0',
-        },
-        {
-          Position: 41,
-          Value: '0',
-        },
-        {
-          Position: 42,
-          Value: '0',
-        },
-        {
-          Position: 43,
-          Value: '0',
-        },
-        {
-          Position: 44,
-          Value: '0',
-        },
-        {
-          Position: 45,
-          Value: '0',
-        },
-        {
-          Position: 46,
-          Value: '0',
-        },
-        {
-          Position: 47,
-          Value: '0',
-        },
-        {
-          Position: 48,
-          Value: '0',
-        },
-        {
-          Position: 49,
-          Value: '0',
-        },
-        {
-          Position: 50,
-          Value: '0',
-        },
-        {
-          Position: 51,
-          Value: '0',
-        },
-        {
-          Position: 52,
-          Value: '0',
-        },
-        {
-          Position: 53,
-          Value: '0',
-        },
-        {
-          Position: 54,
-          Value: '0',
-        },
-        {
-          Position: 55,
-          Value: '0',
-        },
-        {
-          Position: 56,
-          Value: '0',
-        },
-        {
-          Position: 57,
-          Value: '0',
-        },
-        {
-          Position: 58,
-          Value: '0',
-        },
-        {
-          Position: 59,
-          Value: '0',
-        },
-        {
-          Position: 60,
-          Value: '0',
-        },
-        {
-          Position: 61,
-          Value: '0',
-        },
-        {
-          Position: 62,
-          Value: '0',
-        },
-        {
-          Position: 63,
-          Value: '0',
-        },
-        {
-          Position: 64,
-          Value: '0',
-        },
-      ],
-      Maker: null,
-      Checker: null,
-      ReferredTo: null,
-      ReferralReason: null,
-      UserData1: null,
-      UserData2: null,
-      UserData3: null,
-      UserData4: null,
-      UserData5: null,
-      AdditionalFields: [],
-    },
-    ApplicationStatusDetails: {
-      StatusCode: '04',
-      Description: 'Approved',
-      Canceled: false,
-    },
-    CorporateDetails: null,
-    CustomerDetails: {
-      Id: 115158,
-      CustomerCode: '100000024619',
-      IdNumber: ' ',
-      TypeId: 0,
-      PreferredLanguage: 'EN',
-      ExternalCustomerCode: null,
-      Title: ' ',
-      FirstName: ' ',
-      LastName: ' ',
-      DateOfBirth: null,
-      UserData1: '2031-09-17',
-      UserData2: '01',
-      UserData3: null,
-      UserData4: '682',
-      CustomerSegment: null,
-      Gender: 'U',
-      Married: 'U',
-    },
-    AccountDetailsList: [
-      {
-        Id: 21017,
-        InstitutionCode: '1100',
-        AccountNumber: '6899999999999999',
-        Currency: {
-          CurrCode: '682',
-          AlphaCode: 'SAR',
-        },
-        AccountTypeCode: '30',
-        ClassId: '2',
-        AccountStatus: '00',
-        VipFlag: '0',
-        BlockedAmount: 0,
-        EquivalentBlockedAmount: null,
-        UnclearCredit: 0,
-        EquivalentUnclearCredit: null,
-        AvailableBalance: 0,
-        EquivalentAvailableBalance: null,
-        AvailableBalanceToSpend: 0,
-        CreditLimit: 0,
-        RemainingCashLimit: null,
-        UserData1: 'D36407C9AE4C28D2185',
-        UserData2: null,
-        UserData3: 'D36407C9AE4C28D2185',
-        UserData4: null,
-        UserData5: 'SA2380900000752991120011',
-      },
-    ],
-    CardDetailsList: [
-      {
-        pvv: null,
-        ResponseCardIdentifier: {
-          Id: 28595,
-          Pan: 'DDDDDDDDDDDDDDDDDDD',
-          MaskedPan: '999999_9999',
-          VPan: '1100000000000000',
-          Seqno: 0,
-        },
-        ExpiryDate: '2031-09-30',
-        EffectiveDate: '2025-06-02',
-        CardStatus: '30',
-        OldPlasticExpiryDate: null,
-        OldPlasticCardStatus: null,
-        EmbossingName: 'ABDALHAMID AHMAD',
+      ApplicationDetails: {
+        cif: null,
+        ApplicationNumber: '3300000000073',
+        ExternalApplicationNumber: '3',
+        ApplicationStatus: '04',
+        Organization: 0,
+        Product: '1101',
+        ApplicatonDate: '2025-05-29',
+        ApplicationSource: 'O',
+        SalesSource: null,
+        DeliveryMethod: 'V',
+        ProgramCode: null,
+        Campaign: null,
+        Plastic: null,
+        Design: null,
+        ProcessStage: '99',
+        ProcessStageStatus: 'S',
+        Score: null,
+        ExternalScore: null,
+        RequestedLimit: 0,
+        SuggestedLimit: null,
+        AssignedLimit: 0,
+        AllowedLimitList: null,
+        EligibilityCheckResult: '00',
+        EligibilityCheckDescription: null,
         Title: 'Mr.',
         FirstName: 'Abdalhamid',
+        SecondName: null,
+        ThirdName: null,
         LastName: ' Ahmad',
-        Additional: false,
-        BatchNumber: 8849,
-        ServiceCode: '226',
-        Kinship: null,
+        FullName: 'Abdalhamid Ahmad',
+        EmbossName: 'ABDALHAMID AHMAD',
+        PlaceOfBirth: null,
         DateOfBirth: '1999-01-07',
-        LastActivity: null,
-        LastStatusChangeDate: '2025-06-03',
-        ActivationDate: null,
-        DateLastIssued: null,
-        PVV: null,
-        UserData: '4',
-        UserData1: '3',
-        UserData2: null,
-        UserData3: null,
-        UserData4: null,
-        UserData5: null,
-        Memo: null,
-        CardAuthorizationParameters: null,
-        L10NTitle: null,
-        L10NFirstName: null,
-        L10NLastName: null,
-        PinStatus: '40',
-        OldPinStatus: '0',
-        CustomerIdNumber: '1089055972',
-        Language: 0,
+        LocalizedDateOfBirth: '1999-01-07',
+        Age: 26,
+        Gender: 'M',
+        Married: 'U',
+        Nationality: '682',
+        IdType: '01',
+        IdNumber: '1089055972',
+        IdExpiryDate: '2031-09-17',
+        EducationLevel: null,
+        ProfessionCode: 0,
+        NumberOfDependents: 0,
+        EmployerName: 'N/A',
+        EmploymentYears: 0,
+        EmploymentMonths: 0,
+        CIF: null,
+        BankAccountNumber: ' ',
+        Currency: { CurrCode: '682', AlphaCode: 'SAR' },
+        CreditAccountNumber: '6000000000000000',
+        AccountType: '30',
+        Income: 0,
+        AdditionalIncome: 0,
+        TotalIncome: 0,
+        CurrentBalance: 0,
+        AverageBalance: 0,
+        AssetsBalance: 0,
+        InsuranceBalance: 0,
+        DepositAmount: 0,
+        GuarenteeAccountNumber: null,
+        GuarenteeAmount: 0,
+        InstalmentAmount: 0,
+        AutoDebit: 'N',
+        PaymentMethod: '2',
+        BillingCycle: 'C1',
+        MaximumDelinquency: null,
+        CreditBureauDecision: null,
+        ECommerce: 'N',
+        NumberOfCards: 0,
+        SocialCode: '000',
+        JobGrade: 0,
+        Flags: Array.from({ length: 64 }, (_, i) => ({
+          Position: i + 1,
+          Value: '0',
+        })),
+        CheckFlags: Array.from({ length: 64 }, (_, i) => ({
+          Position: i + 1,
+          Value: '0',
+        })),
       },
-    ],
-  },
-};
+
+      ApplicationStatusDetails: {
+        StatusCode: '04',
+        Description: 'Approved',
+        Canceled: false,
+      },
+
+      CustomerDetails: {
+        Id: 115158,
+        CustomerCode: '100000024619',
+        IdNumber: ' ',
+        TypeId: 0,
+        PreferredLanguage: 'EN',
+        ExternalCustomerCode: null,
+        Title: ' ',
+        FirstName: ' ',
+        LastName: ' ',
+        DateOfBirth: null,
+        UserData1: '2031-09-17',
+        UserData2: '01',
+        UserData3: null,
+        UserData4: '682',
+        CustomerSegment: null,
+        Gender: 'U',
+        Married: 'U',
+      },
+
+      AccountDetailsList: [
+        {
+          Id: randomDigits(5),
+          InstitutionCode: '1100',
+          AccountNumber: randomDigits(16),
+          Currency: { CurrCode: '682', AlphaCode: 'SAR' },
+          AccountTypeCode: '30',
+          ClassId: '2',
+          AccountStatus: '00',
+          VipFlag: '0',
+          BlockedAmount: 0,
+          AvailableBalance: 0,
+          UserData1: 'D36407C9AE4C28D2185',
+          UserData3: 'D36407C9AE4C28D2185',
+          UserData5: `SA${randomDigits(22)}`,
+        },
+      ],
+
+      CardDetailsList: [
+        {
+          pvv: null,
+          ResponseCardIdentifier: {
+            Id: randomDigits(5),
+            Pan: 'DDDDDDDDDDDDDDDDDDD',
+            MaskedPan: '999999_9999',
+            VPan: randomDigits(16),
+            Seqno: 0,
+          },
+          ExpiryDate: '2031-09-30',
+          EffectiveDate: '2025-06-02',
+          CardStatus: '30',
+          EmbossingName: 'ABDALHAMID AHMAD',
+          Title: 'Mr.',
+          FirstName: 'Abdalhamid',
+          LastName: ' Ahmad',
+          BatchNumber: 8849,
+          ServiceCode: '226',
+          DateOfBirth: '1999-01-07',
+          LastStatusChangeDate: '2025-06-03',
+          PinStatus: '40',
+          OldPinStatus: '0',
+          CustomerIdNumber: '1089055972',
+          Language: 0,
+        },
+      ],
+    },
+  };
+}

src/common/modules/neoleap/__mocks__/index.ts

@@ -1,3 +1,4 @@
+export * from './card-embossing-details.mock';
 export * from './create-application.mock';
 export * from './initiate-kyc.mock';
 export * from './inquire-application.mock';

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

@@ -19,5 +19,11 @@ export const getKycCallbackMock = (nationalId: string) => {
     professionTitle: 'Software Engineer',
     professionType: 'Full-Time',
     isPep: 'N',
+    country: '682',
+    region: 'Mecca',
+    city: 'At-Taif',
+    neighborhood: 'Al-Hamra',
+    street: 'Al-Masjid Al-Haram',
+    building: '123',
   };
 };

src/common/modules/neoleap/controllers/neotest.controller.ts

@@ -1,62 +0,0 @@
-import { Body, Controller, Post, UseGuards } from '@nestjs/common';
-import { ConfigService } from '@nestjs/config';
-import { ApiBearerAuth, ApiTags } from '@nestjs/swagger';
-import { IJwtPayload } from '~/auth/interfaces';
-import { CardService } from '~/card/services';
-import { AuthenticatedUser } from '~/common/decorators';
-import { AccessTokenGuard } from '~/common/guards';
-import { ApiDataResponse } from '~/core/decorators';
-import { ResponseFactory } from '~/core/utils';
-import { CustomerResponseDto } from '~/customer/dtos/response';
-import { CustomerService } from '~/customer/services';
-import { UpdateCardControlsRequestDto } from '../dtos/requests';
-import { CreateApplicationResponse, InquireApplicationResponse } from '../dtos/response';
-import { NeoLeapService } from '../services/neoleap.service';
-
-@Controller('neotest')
-@ApiTags('Neoleap Test API , for testing purposes only, will be removed in production')
-@UseGuards(AccessTokenGuard)
-@ApiBearerAuth()
-export class NeoTestController {
-  constructor(
-    private readonly neoleapService: NeoLeapService,
-    private readonly customerService: CustomerService,
-    private readonly cardService: CardService,
-    private readonly configService: ConfigService,
-  ) {}
-
-  @Post('update-kys')
-  @ApiDataResponse(CustomerResponseDto)
-  async updateKys(@AuthenticatedUser() user: IJwtPayload) {
-    const customer = await this.customerService.updateKyc(user.sub);
-
-    return ResponseFactory.data(new CustomerResponseDto(customer));
-  }
-
-  @Post('inquire-application')
-  @ApiDataResponse(InquireApplicationResponse)
-  async inquireApplication(@AuthenticatedUser() user: IJwtPayload) {
-    const customer = await this.customerService.findCustomerById(user.sub);
-    const data = await this.neoleapService.inquireApplication(customer.applicationNumber.toString());
-    return ResponseFactory.data(data);
-  }
-
-  @Post('create-application')
-  @ApiDataResponse(CreateApplicationResponse)
-  async createApplication(@AuthenticatedUser() user: IJwtPayload) {
-    const customer = await this.customerService.findCustomerById(user.sub);
-    const data = await this.neoleapService.createApplication(customer);
-    await this.cardService.createCard(customer.id, data);
-    return ResponseFactory.data(data);
-  }
-
-  @Post('update-card-controls')
-  async updateCardControls(
-    @AuthenticatedUser() user: IJwtPayload,
-    @Body() { amount, count }: UpdateCardControlsRequestDto,
-  ) {
-    const card = await this.cardService.getActiveCardForCustomer(user.sub);
-    await this.neoleapService.updateCardControl(card.cardReference, amount, count);
-    return ResponseFactory.data({ message: 'Card controls updated successfully' });
-  }
-}

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

@@ -96,4 +96,34 @@ export class KycWebhookRequest {
   @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;
 }

src/common/modules/neoleap/dtos/response/card-embossing-details.response.dto.ts

@@ -0,0 +1,26 @@
+import { ApiProperty } from '@nestjs/swagger';
+import { Expose } from 'class-transformer';
+
+export class CardEmbossingDetailsResponseDto {
+  @ApiProperty({
+    example: '997',
+  })
+  @Expose({ name: 'Cvv' })
+  cvv!: string;
+
+  @ApiProperty({ example: '4017786818471184' })
+  @Expose({ name: 'ClearPan' })
+  cardNumber!: string;
+
+  @ApiProperty({
+    example: '20311031',
+  })
+  @Expose({ name: 'ExpiryDate' })
+  expiryDate!: string;
+
+  @ApiProperty({
+    example: 'AMMAR QAFFAF',
+  })
+  @Expose({ name: 'EmbossingName' })
+  cardHolderName!: string;
+}

src/common/modules/neoleap/dtos/response/index.ts

@@ -1,3 +1,4 @@
+export * from './card-embossing-details.response.dto';
 export * from './create-application.response.dto';
 export * from './initiate-kyc.response.dto';
 export * from './inquire-application.response';

src/common/modules/neoleap/neoleap.module.ts

@@ -1,16 +1,11 @@
 import { HttpModule } from '@nestjs/axios';
-import { forwardRef, Module } from '@nestjs/common';
-import { CardModule } from '~/card/card.module';
-import { CustomerModule } from '~/customer/customer.module';
-import { NeoLeapWebhooksController } from './controllers/neoleap-webhooks.controller';
-import { NeoTestController } from './controllers/neotest.controller';
-import { NeoLeapWebhookService } from './services';
+import { Module } from '@nestjs/common';
 import { NeoLeapService } from './services/neoleap.service';
 
 @Module({
-  imports: [HttpModule, CardModule, forwardRef(() => CustomerModule)],
-  controllers: [NeoTestController, NeoLeapWebhooksController],
-  providers: [NeoLeapService, NeoLeapWebhookService],
+  imports: [HttpModule],
+  controllers: [],
+  providers: [NeoLeapService],
   exports: [NeoLeapService],
 })
 export class NeoLeapModule {}

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

@@ -1,2 +1,2 @@
-export * from './neoleap-webook.service';
+export * from '../../../../webhook/services/neoleap-webook.service';
 export * from './neoleap.service';

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

@@ -4,13 +4,20 @@ import { ConfigService } from '@nestjs/config';
 import { ClassConstructor, plainToInstance } from 'class-transformer';
 import moment from 'moment';
 import { v4 as uuid } from 'uuid';
+import { Card } from '~/card/entities';
 import { CountriesNumericISO } from '~/common/constants';
 import { InitiateKycRequestDto } from '~/customer/dtos/request';
 import { Customer } from '~/customer/entities';
-import { Gender, KycStatus } from '~/customer/enums';
-import { CREATE_APPLICATION_MOCK, INITIATE_KYC_MOCK, INQUIRE_APPLICATION_MOCK } from '../__mocks__/';
+import { Gender } from '~/customer/enums';
+import {
+  buildCreateApplicationMock,
+  CARD_EMBOSSING_DETAILS_MOCK,
+  INITIATE_KYC_MOCK,
+  INQUIRE_APPLICATION_MOCK,
+} from '../__mocks__/';
 import { getKycCallbackMock } from '../__mocks__/kyc-callback.mock';
 import {
+  CardEmbossingDetailsResponseDto,
   CreateApplicationResponse,
   InitiateKycResponseDto,
   InquireApplicationResponse,
@@ -41,7 +48,7 @@ export class NeoLeapService {
     this.useKycMock = [true, 'true'].includes(this.configService.get<boolean>('USE_KYC_MOCK', true));
   }
 
-  async initiateKyc(customerId: string, body: InitiateKycRequestDto) {
+  initiateKyc(customerId: string, body: InitiateKycRequestDto) {
     const responseKey = 'InitiateKycResponseDetails';
 
     if (this.useKycMock) {
@@ -84,19 +91,11 @@ export class NeoLeapService {
     );
   }
 
-  async createApplication(customer: Customer) {
+  createApplication(customer: Customer) {
     const responseKey = 'CreateNewApplicationResponseDetails';
 
-    if (customer.kycStatus !== KycStatus.APPROVED) {
-      throw new BadRequestException('CUSTOMER.KYC_NOT_APPROVED');
-    }
-
-    if (customer.cards.length > 0) {
-      throw new BadRequestException('CUSTOMER.ALREADY_HAS_CARD');
-    }
-
     if (!this.useGateway) {
-      return plainToInstance(CreateApplicationResponse, CREATE_APPLICATION_MOCK[responseKey], {
+      return plainToInstance(CreateApplicationResponse, buildCreateApplicationMock()[responseKey], {
         excludeExtraneousValues: true,
       });
     }
@@ -166,7 +165,82 @@ export class NeoLeapService {
     );
   }
 
-  async inquireApplication(externalApplicationNumber: string) {
+  createChildCard(parent: Customer, child: Customer, cardPin: string) {
+    const responseKey = 'CreateNewApplicationResponseDetails';
+
+    if (!this.useGateway) {
+      return plainToInstance(CreateApplicationResponse, buildCreateApplicationMock()[responseKey], {
+        excludeExtraneousValues: true,
+      });
+    }
+
+    const payload: ICreateApplicationRequest = {
+      CreateNewApplicationRequestDetails: {
+        ApplicationRequestDetails: {
+          InstitutionCode: this.institutionCode,
+          ExternalApplicationNumber: child.applicationNumber.toString(),
+          ApplicationType: '01',
+          Product: '1101',
+          ApplicationDate: moment().format('YYYY-MM-DD'),
+          BranchCode: '000',
+          ApplicationSource: 'O',
+          DeliveryMethod: 'V',
+        },
+        ApplicationProcessingDetails: {
+          SuggestedLimit: 0,
+          RequestedLimit: 0,
+          AssignedLimit: 0,
+          ProcessControl: 'STND',
+        },
+        ApplicationFinancialInformation: {
+          Currency: {
+            AlphaCode: 'SAR',
+          },
+          BillingCycle: 'C1',
+        },
+        ApplicationOtherInfo: {
+          ParentAccountNumber: parent.cards[0].account.accountNumber,
+        },
+        ApplicationCustomerDetails: {
+          FirstName: parent.firstName,
+          LastName: parent.lastName,
+          FullName: parent.fullName,
+          DateOfBirth: moment(parent.dateOfBirth).format('YYYY-MM-DD'),
+          EmbossName: child.fullName.toUpperCase(), // TODO Enter Emboss Name
+          IdType: '01',
+          IdNumber: parent.nationalId,
+          IdExpiryDate: moment(parent.nationalIdExpiry).format('YYYY-MM-DD'),
+          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],
+        },
+        ApplicationAddress: {
+          City: parent.city,
+          Country: CountriesNumericISO[parent.country],
+          Region: parent.region,
+          AddressLine1: `${parent.street} ${parent.building}`,
+          AddressLine2: parent.neighborhood,
+          AddressRole: 0,
+          Email: child.user.email,
+          Phone1: child.user.phoneNumber,
+          CountryDetails: {
+            DefaultCurrency: {},
+            Description: [],
+          },
+        },
+      },
+      RequestHeader: this.prepareHeaders('CreateNewApplication'),
+    };
+    return this.sendRequestToNeoLeap<ICreateApplicationRequest, CreateApplicationResponse>(
+      'application/CreateNewApplication',
+      payload,
+      responseKey,
+      CreateApplicationResponse,
+    );
+  }
+
+  inquireApplication(externalApplicationNumber: string) {
     const responseKey = 'InquireApplicationResponseDetails';
     if (!this.useGateway) {
       return plainToInstance(InquireApplicationResponse, INQUIRE_APPLICATION_MOCK[responseKey], {
@@ -198,7 +272,7 @@ export class NeoLeapService {
     );
   }
 
-  async updateCardControl(cardId: string, amount: number, count?: number) {
+  updateCardControl(cardId: string, amount: number, count?: number) {
     const responseKey = 'UpdateCardControlResponseDetails';
     if (!this.useGateway) {
       return;
@@ -227,6 +301,33 @@ export class NeoLeapService {
     );
   }
 
+  getEmbossingInformation(card: Card) {
+    const responseKey = 'GetEmbossingInformationResponseDetails';
+    if (!this.useGateway) {
+      return plainToInstance(CardEmbossingDetailsResponseDto, CARD_EMBOSSING_DETAILS_MOCK[responseKey], {
+        excludeExtraneousValues: true,
+      });
+    }
+
+    const payload = {
+      GetEmbossingInformationRequestDetails: {
+        InstitutionCode: this.institutionCode,
+        CardIdentifier: {
+          InstitutionCode: this.institutionCode,
+          Id: card.cardReference,
+        },
+      },
+      RequestHeader: this.prepareHeaders('GetEmbossingInformation'),
+    };
+
+    return this.sendRequestToNeoLeap<typeof payload, CardEmbossingDetailsResponseDto>(
+      'issuance/GetEmbossingInformation',
+      payload,
+      responseKey,
+      CardEmbossingDetailsResponseDto,
+    );
+  }
+
   private prepareHeaders(serviceName: string): INeoleapHeaderRequest['RequestHeader'] {
     return {
       Version: '1.0.0',

src/common/modules/notification/listeners/notification-created.listener.ts

@@ -21,7 +21,7 @@ export class NotificationCreatedListener {
   /**
    * Handles the NOTIFICATION_CREATED event by calling the appropriate channel logic.
    */
-  async handle(event: IEventInterface) {
+  handle(event: IEventInterface) {
     this.logger.log(
       `Handling ${EventType.NOTIFICATION_CREATED} event for notification ${event.id} (channel: ${event.channel})`,
     );

src/common/modules/notification/services/notifications.service.ts

@@ -68,7 +68,6 @@ export class NotificationsService {
     });
 
     this.logger.log(`emitting ${EventType.NOTIFICATION_CREATED} event`);
-
     return this.redisPubSubService.publishEvent(EventType.NOTIFICATION_CREATED, {
       ...notification,
       data: { otp },

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

@@ -19,7 +19,6 @@ export class OtpService {
   async generateAndSendOtp(sendOtpRequest: ISendOtp): Promise<string> {
     this.logger.log(`invalidate OTP for ${sendOtpRequest.recipient} and ${sendOtpRequest.otpType}`);
     await this.otpRepository.invalidateOtp(sendOtpRequest);
-
     this.logger.log(`Generating OTP for ${sendOtpRequest.recipient}`);
     const otp = this.useMock ? DEFAULT_OTP_DIGIT.repeat(DEFAULT_OTP_LENGTH) : generateRandomOtp(DEFAULT_OTP_LENGTH);
 

src/core/utils/index.ts

@@ -1,3 +1,4 @@
-export * from './response.factory.util';
-export * from './i18n-context-wrapper.util';
 export * from './class-validator-formatter.util';
+export * from './i18n-context-wrapper.util';
+export * from './patch.util';
+export * from './response.factory.util';

src/core/utils/patch.util.ts

@@ -0,0 +1,3 @@
+export const setIf = <T, K extends keyof T>(obj: T, key: K, val: T[K] | undefined) => {
+  if (typeof val !== 'undefined') obj[key] = val as T[K];
+};

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')
@@ -32,4 +32,14 @@ export class CustomerController {
 
     return ResponseFactory.data(new InitiateKycResponseDto(res.randomNumber));
   }
+
+  @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

@@ -6,17 +6,12 @@ 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 { CustomerService, MetadataService } from './services';
 
 @Module({
-  imports: [
-    TypeOrmModule.forFeature([Customer]),
-    forwardRef(() => UserModule),
-    GuardianModule,
-    forwardRef(() => NeoLeapModule),
-  ],
+  imports: [TypeOrmModule.forFeature([Customer]), GuardianModule, forwardRef(() => UserModule), NeoLeapModule],
   controllers: [CustomerController],
-  providers: [CustomerService, CustomerRepository],
+  providers: [CustomerService, CustomerRepository, MetadataService],
   exports: [CustomerService],
 })
 export class CustomerModule {}

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/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

@@ -15,7 +15,7 @@ import { CountryIso } from '~/common/enums';
 import { Guardian } from '~/guardian/entities/guradian.entity';
 import { Junior } from '~/junior/entities';
 import { User } from '~/user/entities';
-import { CustomerStatus, KycStatus } from '../enums';
+import { CustomerStatus, Gender, KycStatus } from '../enums';
 
 @Entity('customers')
 export class Customer extends BaseEntity {
@@ -62,7 +62,7 @@ export class Customer extends BaseEntity {
   isPep!: boolean;
 
   @Column('varchar', { length: 255, nullable: true, name: 'gender' })
-  gender!: string;
+  gender!: Gender;
 
   @Column('boolean', { default: false, name: 'is_junior' })
   isJunior!: boolean;

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/customer.repository.ts

@@ -14,8 +14,7 @@ export class CustomerRepository {
   findOne(where: FindOptionsWhere<Customer>) {
     return this.customerRepository.findOne({
       where,
-      relations: ['user',  'cards'],
-
+      relations: ['user', 'cards', 'cards.account'],
     });
   }
 
@@ -30,6 +29,7 @@ export class CustomerRepository {
         lastName: body.lastName,
         dateOfBirth: body.dateOfBirth,
         countryOfResidence: body.countryOfResidence,
+        gender: body.gender,
       }),
     );
   }

src/customer/services/customer.service.ts

@@ -12,6 +12,7 @@ import { InitiateKycRequestDto } from '../dtos/request';
 import { Customer } from '../entities';
 import { Gender, KycStatus } from '../enums';
 import { CustomerRepository } from '../repositories/customer.repository';
+import { MetadataService } from './metadata.service';
 
 @Injectable()
 export class CustomerService {
@@ -20,6 +21,7 @@ export class CustomerService {
     private readonly customerRepository: CustomerRepository,
     private readonly guardianService: GuardianService,
     @Inject(forwardRef(() => NeoLeapService)) private readonly neoleapService: NeoLeapService,
+    private readonly metadataService: MetadataService,
   ) {}
 
   async updateCustomer(userId: string, data: Partial<Customer>): Promise<Customer> {
@@ -33,7 +35,10 @@ export class CustomerService {
   async createJuniorCustomer(guardianId: string, juniorId: string, body: CreateJuniorRequestDto) {
     this.logger.log(`Creating junior customer for user ${juniorId}`);
 
-    return this.customerRepository.createCustomer(juniorId, body, false);
+    await this.customerRepository.createCustomer(juniorId, body, false);
+
+    this.logger.log(`Junior customer created for user ${juniorId} successfully`);
+    return this.customerRepository.findOne({ id: juniorId });
   }
 
   async findCustomerById(id: string) {
@@ -104,13 +109,18 @@ export class CustomerService {
       dateOfBirth: moment(body.dob, 'YYYYMMDD').toDate(),
       nationalId: body.nationalId,
       nationalIdExpiry: moment(body.nationalIdExpiry, 'YYYYMMDD').toDate(),
-      countryOfResidence: NumericToCountryIso[body.nationality],
-      country: NumericToCountryIso[body.nationality],
+      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,
     });
   }
 
@@ -141,6 +151,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/1757349525708-create-money-requests-table.ts

@@ -0,0 +1,25 @@
+import { MigrationInterface, QueryRunner } from 'typeorm';
+
+export class CreateMoneyRequestsTable1757349525708 implements MigrationInterface {
+  name = 'CreateMoneyRequestsTable1757349525708';
+
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(
+      `CREATE TABLE "money_requests" ("id" uuid NOT NULL DEFAULT uuid_generate_v4(), "amount" numeric(10,2) NOT NULL, "reason" character varying NOT NULL, "status" character varying NOT NULL DEFAULT 'PENDING', "rejection_reason" text, "junior_id" uuid NOT NULL, "guardian_id" uuid NOT NULL, "created_at" TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT now(), "updated_at" TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT now(), CONSTRAINT "PK_28cff23e9fb06cd5dbf73cd53e7" PRIMARY KEY ("id"))`,
+    );
+    await queryRunner.query(`ALTER TABLE "cards" ALTER COLUMN "color" SET DEFAULT 'DEEP_MAGENTA'`);
+    await queryRunner.query(
+      `ALTER TABLE "money_requests" ADD CONSTRAINT "FK_f7084c83efe7efaca37297d57ae" FOREIGN KEY ("junior_id") REFERENCES "juniors"("id") ON DELETE CASCADE ON UPDATE NO ACTION`,
+    );
+    await queryRunner.query(
+      `ALTER TABLE "money_requests" ADD CONSTRAINT "FK_09eadf4c4133b323f467ffc90f3" FOREIGN KEY ("guardian_id") REFERENCES "guardians"("id") ON DELETE CASCADE ON UPDATE NO ACTION`,
+    );
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`ALTER TABLE "money_requests" DROP CONSTRAINT "FK_09eadf4c4133b323f467ffc90f3"`);
+    await queryRunner.query(`ALTER TABLE "money_requests" DROP CONSTRAINT "FK_f7084c83efe7efaca37297d57ae"`);
+    await queryRunner.query(`ALTER TABLE "cards" ALTER COLUMN "color" SET DEFAULT 'BLUE'`);
+    await queryRunner.query(`DROP TABLE "money_requests"`);
+  }
+}

src/db/migrations/1757433339849-add-reservation-amount-to-account-entity.ts

@@ -0,0 +1,13 @@
+import { MigrationInterface, QueryRunner } from 'typeorm';
+
+export class AddReservationAmountToAccountEntity1757433339849 implements MigrationInterface {
+  name = 'AddReservationAmountToAccountEntity1757433339849';
+
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`ALTER TABLE "accounts" ADD "reserved_balance" numeric(10,2) NOT NULL DEFAULT '0'`);
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`ALTER TABLE "accounts" DROP COLUMN "reserved_balance"`);
+  }
+}

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/index.ts

@@ -1,3 +1,8 @@
 export * from './1754913378460-initial-migration';
 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';

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/entities/guradian.entity.ts

@@ -11,6 +11,7 @@ import {
 } from 'typeorm';
 import { Customer } from '~/customer/entities';
 import { Junior } from '~/junior/entities';
+import { MoneyRequest } from '~/money-request/entities/money-request.entity';
 
 @Entity('guardians')
 export class Guardian extends BaseEntity {
@@ -27,6 +28,9 @@ export class Guardian extends BaseEntity {
   @OneToMany(() => Junior, (junior) => junior.guardian)
   juniors!: Junior[];
 
+  @OneToMany(() => MoneyRequest, (moneyRequest) => moneyRequest.guardian)
+  moneyRequests!: MoneyRequest[];
+
   @CreateDateColumn({ name: 'created_at', type: 'timestamp with time zone', default: () => 'CURRENT_TIMESTAMP' })
   createdAt!: Date;
 

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": "تم التحقق من عنوان البريد الإلكتروني بالفعل.",
@@ -50,7 +54,9 @@
   "CUSTOMER": {
     "NOT_FOUND": "لم يتم العثور على العميل.",
     "ALREADY_EXISTS": "العميل موجود بالفعل.",
-    "KYC_NOT_APPROVED": "لم يتم الموافقة على هوية العميل بعد."
+    "KYC_NOT_APPROVED": "لم يتم الموافقة على هوية العميل بعد.",
+    "ALREADY_HAS_CARD": "العميل لديه بطاقة بالفعل.",
+    "DOES_NOT_HAVE_CARD": "العميل لا يملك بطاقة."
   },
 
   "GIFT": {
@@ -65,16 +71,15 @@
     "NOT_FOUND": "لم يتم العثور على الطفل.",
     "CIVIL_ID_REQUIRED": "مطلوب بطاقة الهوية المدنية.",
     "CIVIL_ID_NOT_CREATED_BY_GUARDIAN": "تم تحميل بطاقة الهوية المدنية من قبل شخص آخر غير ولي الأمر.",
-    "CIVIL_ID_ALREADY_EXISTS": "بطاقة الهوية المدنية مستخدمة بالفعل من قبل طفل آخر."
+    "CIVIL_ID_ALREADY_EXISTS": "بطاقة الهوية المدنية مستخدمة بالفعل من قبل طفل آخر.",
+    "CANNOT_UPDATE_REGISTERED_USER": "الطفل قد سجل بالفعل. لا يُسمح بتحديث البيانات.",
+    "CANNOT_DELETE_REGISTERED_USER": "الطفل قد سجل بالفعل. لا يُسمح بحذف الطفل."
   },
 
   "MONEY_REQUEST": {
-    "START_DATE_IN_THE_PAST": "لا يمكن أن يكون تاريخ البدء في الماضي.",
-    "END_DATE_IN_THE_PAST": "لا يمكن أن يكون تاريخ النهاية في الماضي.",
-    "END_DATE_BEFORE_START_DATE": "لا يمكن أن يكون تاريخ النهاية قبل تاريخ البدء.",
     "NOT_FOUND": "لم يتم العثور على طلب المال.",
-    "ENDED": "تم انتهاء طلب المال.",
-    "ALREADY_REVIEWED": "تمت مراجعة طلب المال بالفعل."
+    "ALREADY_APPROVED": "تمت الموافقة على طلب المال بالفعل.",
+    "ALREADY_REJECTED": "تم رفض طلب المال بالفعل."
   },
 
   "GOAL": {
@@ -100,5 +105,10 @@
   },
   "OTP": {
     "INVALID_OTP": "رمز التحقق الذي أدخلته غير صالح. يرجى المحاولة مرة أخرى."
+  },
+  "CARD": {
+    "INSUFFICIENT_BALANCE": "البطاقة لا تحتوي على رصيد كافٍ لإكمال هذا التحويل.",
+    "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.",
@@ -49,7 +53,9 @@
   "CUSTOMER": {
     "NOT_FOUND": "The customer was not found.",
     "ALREADY_EXISTS": "The customer already exists.",
-    "KYC_NOT_APPROVED": "The customer's KYC has not been approved yet."
+    "KYC_NOT_APPROVED": "The customer's KYC has not been approved yet.",
+    "ALREADY_HAS_CARD": "The customer already has a card.",
+    "DOES_NOT_HAVE_CARD": "The customer does not have a card."
   },
 
   "GIFT": {
@@ -64,16 +70,15 @@
     "NOT_FOUND": "The junior was not found.",
     "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."
+    "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_DELETE_REGISTERED_USER": "The junior has already registered. Deleting the junior is not allowed."
   },
 
   "MONEY_REQUEST": {
-    "START_DATE_IN_THE_PAST": "The start date cannot be in the past.",
-    "END_DATE_IN_THE_PAST": "The end date cannot be in the past.",
-    "END_DATE_BEFORE_START_DATE": "The end date cannot be before the start date.",
     "NOT_FOUND": "The money request was not found.",
-    "ENDED": "The money request has ended.",
-    "ALREADY_REVIEWED": "The money request has already been reviewed."
+    "ALREADY_APPROVED": "The money request has already been approved.",
+    "ALREADY_REJECTED": "The money request has already been rejected."
   },
 
   "GOAL": {
@@ -99,5 +104,10 @@
   },
   "OTP": {
     "INVALID_OTP": "The OTP you entered is invalid. Please try again."
+  },
+  "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.",
+    "NOT_FOUND": "The card was not found."
   }
 }

src/junior/controllers/junior.controller.ts

@@ -1,5 +1,17 @@
-import { Body, Controller, Get, Param, 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';
@@ -8,8 +20,20 @@ import { ApiDataPageResponse, ApiDataResponse, ApiLangRequestHeader } from '~/co
 import { PageOptionsRequestDto } from '~/core/dtos';
 import { CustomParseUUIDPipe } from '~/core/pipes';
 import { ResponseFactory } from '~/core/utils';
-import { CreateJuniorRequestDto, SetThemeRequestDto } from '../dtos/request';
-import { JuniorResponseDto, QrCodeValidationResponseDto, ThemeResponseDto } from '../dtos/response';
+import {
+  CreateJuniorRequestDto,
+  SetThemeRequestDto,
+  TransferToJuniorRequestDto,
+  UpdateJuniorRequestDto,
+} from '../dtos/request';
+import {
+  JuniorResponseDto,
+  QrCodeValidationResponseDto,
+  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')
@@ -59,6 +83,28 @@ export class JuniorController {
     return ResponseFactory.data(new JuniorResponseDto(junior));
   }
 
+  @Patch(':juniorId')
+  @UseGuards(RolesGuard)
+  @AllowedRoles(Roles.GUARDIAN)
+  @ApiDataResponse(JuniorResponseDto)
+  async updateJunior(
+    @AuthenticatedUser() user: IJwtPayload,
+    @Param('juniorId', CustomParseUUIDPipe) juniorId: string,
+    @Body() body: UpdateJuniorRequestDto,
+  ) {
+    const junior = await this.juniorService.updateJunior(juniorId, body, user.sub);
+
+    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)
@@ -86,4 +132,96 @@ export class JuniorController {
 
     return ResponseFactory.data(new QrCodeValidationResponseDto(junior));
   }
+
+  @Post(':juniorId/transfer')
+  @UseGuards(RolesGuard)
+  @AllowedRoles(Roles.GUARDIAN)
+  @ApiDataResponse(TransferToJuniorResponseDto)
+  async transferToJunior(
+    @AuthenticatedUser() user: IJwtPayload,
+    @Param('juniorId', CustomParseUUIDPipe) juniorId: string,
+    @Body() body: TransferToJuniorRequestDto,
+  ) {
+    const newAmount = await this.juniorService.transferToJunior(juniorId, body, user.sub);
+
+    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/request/create-junior.request.dto.ts

@@ -1,25 +1,19 @@
 import { ApiProperty } from '@nestjs/swagger';
-import { IsDateString, IsEmail, IsEnum, IsNotEmpty, IsOptional, IsString, IsUUID, Matches } from 'class-validator';
+import {
+  IsDateString,
+  IsEmail,
+  IsEnum,
+  IsNotEmpty,
+  IsNumberString,
+  IsOptional,
+  IsString,
+  IsUUID,
+} from 'class-validator';
 import { i18nValidationMessage as i18n } from 'nestjs-i18n';
-import { COUNTRY_CODE_REGEX } from '~/auth/constants';
-import { IsValidPhoneNumber } from '~/core/decorators/validations';
+import { CardColors } from '~/card/enums';
 import { Gender } from '~/customer/enums';
 import { Relationship } from '~/junior/enums';
 export class CreateJuniorRequestDto {
-  @ApiProperty({ example: '+962' })
-  @Matches(COUNTRY_CODE_REGEX, {
-    message: i18n('validation.Matches', { path: 'general', property: 'auth.countryCode' }),
-  })
-  @IsOptional()
-  countryCode: string = '+966';
-
-  @ApiProperty({ example: '787259134' })
-  @IsValidPhoneNumber({
-    message: i18n('validation.IsValidPhoneNumber', { path: 'general', property: 'auth.phoneNumber' }),
-  })
-  @IsOptional()
-  phoneNumber!: string;
-
   @ApiProperty({ example: 'John' })
   @IsString({ message: i18n('validation.IsString', { path: 'general', property: 'customer.firstName' }) })
   @IsNotEmpty({ message: i18n('validation.IsNotEmpty', { path: 'general', property: 'customer.firstName' }) })
@@ -30,9 +24,9 @@ export class CreateJuniorRequestDto {
   @IsNotEmpty({ message: i18n('validation.IsNotEmpty', { path: 'general', property: 'customer.lastName' }) })
   lastName!: string;
 
-  @ApiProperty({ example: 'MALE' })
+  @ApiProperty({ enum: Gender })
   @IsEnum(Gender, { message: i18n('validation.IsEnum', { path: 'general', property: 'customer.gender' }) })
-  gender!: string;
+  gender!: Gender;
 
   @ApiProperty({ example: '2020-01-01' })
   @IsDateString({}, { message: i18n('validation.IsDateString', { path: 'general', property: 'customer.dateOfBirth' }) })
@@ -46,13 +40,13 @@ export class CreateJuniorRequestDto {
   @IsEnum(Relationship, { message: i18n('validation.IsEnum', { path: 'general', property: 'junior.relationship' }) })
   relationship!: Relationship;
 
-  @ApiProperty({ example: 'bf342-3f3f-3f3f-3f3f' })
-  @IsUUID('4', { message: i18n('validation.IsUUID', { path: 'general', property: 'junior.civilIdFrontId' }) })
-  civilIdFrontId!: string;
+  @ApiProperty({ enum: CardColors })
+  @IsEnum(CardColors, { message: i18n('validation.IsEnum', { path: 'general', property: 'junior.cardColor' }) })
+  cardColor!: CardColors;
 
-  @ApiProperty({ example: 'bf342-3f3f-3f3f-3f3f' })
-  @IsUUID('4', { message: i18n('validation.IsUUID', { path: 'general', property: 'junior.civilIdBackId' }) })
-  civilIdBackId!: string;
+  @ApiProperty({ example: '1234' })
+  @IsNumberString({}, { message: i18n('validation.IsEnum', { path: 'general', property: 'junior.cardPin' }) })
+  cardPin!: string;
 
   @ApiProperty({ example: '123e4567-e89b-12d3-a456-426614174000' })
   @IsUUID('4', { message: i18n('validation.IsUUID', { path: 'general', property: 'customer.profilePictureId' }) })

src/junior/dtos/request/index.ts

@@ -1,2 +1,4 @@
 export * from './create-junior.request.dto';
 export * from './set-theme.request.dto';
+export * from './transfer-to-junior.request.dto';
+export * from './update-junior.request.dto';

src/junior/dtos/request/transfer-to-junior.request.dto.ts

@@ -0,0 +1,12 @@
+import { ApiProperty } from '@nestjs/swagger';
+import { IsNumber } from 'class-validator';
+import { i18nValidationMessage as i18n } from 'nestjs-i18n';
+
+export class TransferToJuniorRequestDto {
+  @ApiProperty({ example: 300.42 })
+  @IsNumber(
+    { maxDecimalPlaces: 3 },
+    { message: i18n('validation.IsNumber', { path: 'general', property: 'transferToJunior.amount' }) },
+  )
+  amount!: number;
+}

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

@@ -0,0 +1,5 @@
+import { OmitType, PartialType } from '@nestjs/swagger';
+import { CreateJuniorRequestDto } from './create-junior.request.dto';
+
+const omitted = OmitType(CreateJuniorRequestDto, ['cardColor', 'cardPin']);
+export class UpdateJuniorRequestDto extends PartialType(omitted) {}

src/junior/dtos/response/index.ts

@@ -2,3 +2,4 @@ export * from './junior.response.dto';
 export * from './qr-code-validation-details.response.dto';
 export * from './qr-code-validation.response.dto';
 export * from './theme.response.dto';
+export * from './transfer-to-junior.response.dto';

src/junior/dtos/response/junior.response.dto.ts

@@ -1,25 +1,51 @@
 import { ApiProperty } from '@nestjs/swagger';
+import { Gender } from '~/customer/enums';
 import { DocumentMetaResponseDto } from '~/document/dtos/response';
 import { Junior } from '~/junior/entities';
-import { Relationship } from '~/junior/enums';
+import { GuardianRelationship, Relationship } from '~/junior/enums';
 
 export class JuniorResponseDto {
   @ApiProperty({ example: 'id' })
   id!: string;
 
-  @ApiProperty({ example: 'fullName' })
-  fullName!: string;
+  @ApiProperty({ example: 'FirstName' })
+  firstName!: string;
 
-  @ApiProperty({ example: 'relationship' })
+  @ApiProperty({ example: 'LastName' })
+  lastName!: string;
+
+  @ApiProperty({ example: 'test@junior.com' })
+  email!: string;
+
+  @ApiProperty({ example: Gender.MALE })
+  gender!: Gender;
+
+  @ApiProperty({ example: '2000-01-01' })
+  dateOfBirth!: Date;
+
+  @ApiProperty({ enum: Relationship })
   relationship!: Relationship;
 
+  @ApiProperty({ enum: GuardianRelationship })
+  guardianRelationship!: GuardianRelationship;
+
   @ApiProperty({ type: DocumentMetaResponseDto })
   profilePicture!: DocumentMetaResponseDto | null;
 
+  @ApiProperty({ example: 2000.0, description: 'The available balance' })
+  availableBalance!: number | null;
+
   constructor(junior: Junior) {
+    const card = junior.customer?.cards?.[0];
     this.id = junior.id;
-    this.fullName = `${junior.customer.firstName} ${junior.customer.lastName}`;
+    this.firstName = junior.customer.firstName;
+    this.lastName = junior.customer.lastName;
+    this.email = junior.customer.user.email;
+    this.gender = junior.customer.gender;
+    this.dateOfBirth = junior.customer.dateOfBirth;
     this.relationship = junior.relationship;
+    this.guardianRelationship = GuardianRelationship[junior.relationship];
+    this.availableBalance = card ? Math.min(card.limit, card.account.balance) : null;
     this.profilePicture = junior.customer.user.profilePicture
       ? new DocumentMetaResponseDto(junior.customer.user.profilePicture)
       : null;

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/transfer-to-junior.response.dto.ts

@@ -0,0 +1,10 @@
+import { ApiProperty } from '@nestjs/swagger';
+
+export class TransferToJuniorResponseDto {
+  @ApiProperty({ example: 300.42 })
+  newAmount!: number;
+
+  constructor(newAmount: number) {
+    this.newAmount = newAmount;
+  }
+}