feat: IRIS Pay integration

.env.example

@@ -98,9 +98,14 @@ IRIS_AGENT_HASH=
 IRIS_USER_HASH=
 BANK_BIC=UNCRBGSF
 PLATFORM_IBAN=
+PAYMENT_SESSION_SECRET=your-payment-session-jwt-secret
+IRIS_WEBHOOK_SECRET=your-iris-webhook-hmac-secret
 IMPORT_TRX_TASK_INTERVAL_MINUTES=60
 #which hour of the day to run the check for consent
 CHECK_IRIS_CONSENT_TASK_HOUR=10
+
+
+
 BILLING_ADMIN_MAIL=billing_admin@podkrepi.bg
 CAMPAIGN_ADMIN_MAIL=responsible for campaign management
 
@@ -111,4 +116,4 @@ CACHE_TTL=30000
 ## AdminEmail ##
 ##############
 CAMPAIGN_COORDINATOR_EMAIL=campaign_coordinators@podkrepi.bg
-CORPORATE_DONORS_EMAIL=
+CORPORATE_DONORS_EMAIL=

apps/api/src/account/account.controller.ts

@@ -8,6 +8,7 @@ import { Person } from '../domain/generated/person/entities'
 import { UpdatePersonDto } from '../person/dto/update-person.dto'
 import { PersonService } from '../person/person.service'
 import { AccountService } from './account.service'
+import { ToggleBetaTesterDto } from './dto/toggle-beta-tester.dto'
 import { ApiTags } from '@nestjs/swagger'
 
 @Controller('account')
@@ -129,4 +130,16 @@ export class AccountController {
       !!data.profileEnabled,
     )
   }
+
+  @Patch(':keycloakId/beta-tester')
+  @Roles({
+    roles: [RealmViewSupporters.role, ViewSupporters.role],
+    mode: RoleMatchingMode.ANY,
+  })
+  async toggleBetaTester(
+    @Param('keycloakId') keycloakId: string,
+    @Body() data: ToggleBetaTesterDto,
+  ) {
+    return await this.accountService.toggleBetaTesterRole(keycloakId, data.assign)
+  }
 }

apps/api/src/account/account.service.ts

@@ -35,4 +35,8 @@ export class AccountService {
   async changeProfileActivationStatus(keycloakId: string, newStatus: boolean) {
     return await this.authService.changeEnabledStatus(keycloakId, newStatus)
   }
+
+  async toggleBetaTesterRole(keycloakId: string, assign: boolean) {
+    return await this.authService.toggleBetaTesterRole(keycloakId, assign)
+  }
 }

apps/api/src/account/dto/toggle-beta-tester.dto.ts

@@ -0,0 +1,10 @@
+import { ApiProperty } from '@nestjs/swagger'
+import { Expose } from 'class-transformer'
+import { IsBoolean } from 'class-validator'
+
+export class ToggleBetaTesterDto {
+  @ApiProperty()
+  @Expose()
+  @IsBoolean()
+  assign: boolean
+}

apps/api/src/app/app.module.ts

@@ -11,7 +11,7 @@
 import { AppController } from './app.controller'
 import { CustomAuthGuard } from './custom-auth.guard'
 import configuration from '../config/configuration'
 import { PrismaService } from '../prisma/prisma.service'
 import { AccountModule } from '../account/account.module'
 import { HealthModule } from '../health/health.module'
 import { SupportModule } from '../support/support.module'
@@ -64,6 +64,7 @@
 import { LoggerModule } from '../logger/logger.module'
 import { PrismaModule } from '../prisma/prisma.module'
 import { CampaignApplicationModule } from '../campaign-application/campaign-application.module'
+import { IrisPayModule } from '../iris-pay/iris-pay.module'
 
 @Module({
   imports: [
@@ -135,6 +136,7 @@
     LoggerModule,
     CampaignApplicationModule,
     StripeModule,
+    IrisPayModule,
   ],
   controllers: [AppController],
   providers: [

apps/api/src/auth/auth.service.ts

@@ -231,7 +231,7 @@ export class AuthService {
       }
       person = await this.createPerson(registerDto, user.id, company?.id)
 
-      if (isCorporateReg) { 
+      if (isCorporateReg) {
         const mail = new CorporateActivationEmailDto({
           corporateActivationTitle: 'Нова корпоративна регистрация',
           companyName: registerDto.companyName || '',
@@ -242,7 +242,7 @@ export class AuthService {
         await this.sendEmail.sendFromTemplate(
           mail,
           { to: [this.config.get('CORPORATE_DONORS_EMAIL', '')] },
-          { bypassUnsubscribeManagement: { enable: true } }
+          { bypassUnsubscribeManagement: { enable: true } },
         )
       }
     } catch (error) {
@@ -430,6 +430,25 @@ export class AuthService {
     return true
   }
 
+  async toggleBetaTesterRole(keycloakId: string, assign: boolean) {
+    await this.authenticateAdmin()
+    let role = await this.admin.roles.findOneByName({ name: 'beta-tester' })
+    if (!role || !role.id || !role.name) {
+      await this.admin.roles.create({ name: 'beta-tester' })
+      role = await this.admin.roles.findOneByName({ name: 'beta-tester' })
+    }
+    if (!role || !role.id || !role.name) {
+      throw new NotFoundException('Failed to create or retrieve beta-tester role in Keycloak realm')
+    }
+    const payload = { id: keycloakId, roles: [{ id: role.id, name: role.name }] }
+    if (assign) {
+      await this.admin.users.addRealmRoleMappings(payload)
+    } else {
+      await this.admin.users.delRealmRoleMappings(payload)
+    }
+    return { keycloakId, betaTester: assign }
+  }
+
   async changeEnabledStatus(keycloakId: string, enabled: boolean) {
     await this.authenticateAdmin()
     // check if user is admin before attempting to activate/deactivate

apps/api/src/config/configuration.ts

@@ -47,6 +47,8 @@ export default () => ({
     banksEndPoint: process.env.IRIS_API_URL + '/banks?country=bulgaria',
     ibansEndPoint: process.env.IRIS_API_URL + '/ibans',
     transactionsEndPoint: process.env.IRIS_API_URL + '/transactions',
+    paymentSessionSecret: process.env.PAYMENT_SESSION_SECRET,
+    irisWebhookSecret: process.env.IRIS_WEBHOOK_SECRET,
   },
   mail: {
     billingAdminEmail: process.env.BILLING_ADMIN_MAIL,
@@ -56,5 +58,6 @@ export default () => ({
   },
   tasks: {
     import_transactions: { interval: process.env.IMPORT_TRX_TASK_INTERVAL_MINUTES },
+    payment_sessions_purge: { cron: process.env.PAYMENT_SESSIONS_PURGE_CRON },
   },
 })

apps/api/src/config/validation.config.ts

@@ -58,4 +58,8 @@ export const validationSchema = Joi.object({
   PAYPAL_CLIENT_ID: Joi.string().required(),
   PAYPAL_CLIENT_SECRET: Joi.string().required(),
   PAYPAL_WEBHOOK_ID: Joi.string().required(),
+
+  // Iris Pay
+  PAYMENT_SESSION_SECRET: Joi.string().required(),
+  IRIS_WEBHOOK_SECRET: Joi.string().required(),
 })

apps/api/src/domain/generated/paymentSession/dto/connect-paymentSession.dto.ts

@@ -0,0 +1,3 @@
+export class ConnectPaymentSessionDto {
+  jti: string
+}

apps/api/src/domain/generated/paymentSession/dto/create-paymentSession.dto.ts

@@ -0,0 +1,4 @@
+export class CreatePaymentSessionDto {
+  jti: string
+  expiresAt: Date
+}

apps/api/src/domain/generated/paymentSession/dto/index.ts

@@ -0,0 +1,3 @@
+export * from './connect-paymentSession.dto'
+export * from './create-paymentSession.dto'
+export * from './update-paymentSession.dto'

apps/api/src/domain/generated/paymentSession/dto/update-paymentSession.dto.ts

@@ -0,0 +1,3 @@
+export class UpdatePaymentSessionDto {
+  expiresAt?: Date
+}

apps/api/src/domain/generated/paymentSession/entities/index.ts

@@ -0,0 +1 @@
+export * from './paymentSession.entity'

apps/api/src/domain/generated/paymentSession/entities/paymentSession.entity.ts

@@ -0,0 +1,5 @@
+export class PaymentSession {
+  jti: string
+  consumedAt: Date
+  expiresAt: Date
+}

apps/api/src/donations/helpers/donation-status-updates.ts

@@ -24,7 +24,7 @@ function isChangeable(status: PaymentStatus) {
   return changeable.includes(status)
 }
 
-function isFinal(status: PaymentStatus) {
+export function isFinal(status: PaymentStatus) {
   return final.includes(status)
 }
 

apps/api/src/iris-pay/README.md

@@ -0,0 +1,65 @@
+# Iris Pay Module
+
+This module handles Iris Pay integration for the Podkrepi.bg platform.
+
+## Endpoints
+
+### POST /iris-pay/finish
+
+Finishes the payment process by updating the donation status in the system.
+
+#### Request Body
+
+```typescript
+{
+  hookHash: string,           // Payment identifier from iris-pay
+  status: string,             // Payment status ('CONFIRMED', 'FAILED', 'WAITTING')
+  amount: number,             // Payment amount in smallest currency unit
+  billingName?: string,       // Optional billing name
+  billingEmail?: string,      // Optional billing email
+  metadata: {
+    campaignId: string,       // ID of the campaign receiving the donation
+    personId: string | null,  // ID of the donor (null for anonymous)
+    isAnonymous: 'true' | 'false', // Whether the donation is anonymous
+    type: string              // Donation type (e.g., 'donation')
+  }
+}
+```
+
+#### Response
+
+```typescript
+{
+  donationId?: string  // ID of the created/updated donation
+}
+```
+
+#### Status Mapping
+
+The endpoint maps iris-pay status strings to internal PaymentStatus enum values:
+
+- `'CONFIRMED'` → `PaymentStatus.succeeded` (payment executed)
+- `'FAILED'` → `PaymentStatus.declined` (payment rejected)
+- `'WAITTING'` → `PaymentStatus.waiting` (waiting to be processed by ASPSP)
+- `'WAITING'` → `PaymentStatus.waiting` (also supports correct spelling)
+- Any other status → `PaymentStatus.waiting` (with warning log)
+
+#### Example Usage
+
+```bash
+curl -X POST http://localhost:5010/api/v1/iris-pay/finish \
+  -H "Content-Type: application/json" \
+  -d '{
+    "hookHash": "payment-123",
+    "status": "CONFIRMED",
+    "amount": 5000,
+    "billingName": "John Doe",
+    "billingEmail": "john.doe@example.com",
+    "metadata": {
+      "campaignId": "campaign-456",
+      "personId": "person-789",
+      "isAnonymous": "false",
+      "type": "donation"
+    }
+  }'
+```

apps/api/src/iris-pay/decorators/payment-step.decorator.ts

@@ -0,0 +1,4 @@
+import { SetMetadata } from '@nestjs/common'
+
+export const PAYMENT_STEP_KEY = 'paymentStep'
+export const PaymentStep = (step: string) => SetMetadata(PAYMENT_STEP_KEY, step)

apps/api/src/iris-pay/dto/create-iris-customer.ts

@@ -0,0 +1,53 @@
+import { ApiProperty } from '@nestjs/swagger'
+import { Expose } from 'class-transformer'
+import { IsOptional, IsString, ValidateIf } from 'class-validator'
+
+export class IrisCreateCustomerDto {
+  @ApiProperty()
+  @Expose()
+  @IsString()
+  @IsOptional()
+  companyName?: string
+
+  @ApiProperty()
+  @Expose()
+  @ValidateIf((obj) => obj.companyName !== undefined)
+  @IsString()
+  uic?: string
+
+  @ApiProperty()
+  @Expose()
+  @IsString()
+  @IsOptional()
+  name?: string
+
+  @ApiProperty()
+  @Expose()
+  @IsString()
+  @IsOptional()
+  middleName?: string
+
+  @ApiProperty()
+  @Expose()
+  @IsString()
+  @IsOptional()
+  family?: string
+
+  @ApiProperty()
+  @Expose()
+  @IsString()
+  @IsOptional()
+  identityHash?: string
+
+  @ApiProperty()
+  @Expose()
+  @ValidateIf((obj) => obj.name !== undefined)
+  @IsString()
+  email: string
+
+  @ApiProperty()
+  @Expose()
+  @IsString()
+  @IsOptional()
+  webhookUrl?: string
+}

apps/api/src/iris-pay/dto/create-iris-pay.dto.ts

@@ -0,0 +1,66 @@
+import { ApiProperty } from '@nestjs/swagger'
+import { Expose } from 'class-transformer'
+import {
+  IsBoolean,
+  IsEmail,
+  IsEnum,
+  IsInt,
+  IsOptional,
+  IsString,
+  IsUUID,
+  Min,
+  ValidateIf,
+} from 'class-validator'
+import { DonationType } from '@prisma/client'
+import { IrisCreateCustomerDto } from './create-iris-customer'
+
+export class IRISCreateCheckoutSessionDto extends IrisCreateCustomerDto {
+  @ApiProperty()
+  @IsString()
+  @Expose()
+  campaignId!: string
+
+  @ApiProperty()
+  @IsInt()
+  @Min(1)
+  @Expose()
+  amount!: number
+
+  @ApiProperty({ enum: DonationType })
+  @IsEnum(DonationType)
+  @Expose()
+  type!: DonationType
+
+  @ApiProperty()
+  @IsBoolean()
+  @Expose()
+  isAnonymous!: boolean
+
+  @ApiProperty({ required: false })
+  @ValidateIf((obj: IRISCreateCheckoutSessionDto) => !obj.isAnonymous)
+  @IsUUID()
+  @Expose()
+  personId?: string
+
+  @ApiProperty()
+  @IsString()
+  @Expose()
+  billingName!: string
+
+  @ApiProperty()
+  @IsEmail()
+  @Expose()
+  billingEmail!: string
+
+  @ApiProperty({ required: false })
+  @IsString()
+  @Expose()
+  @IsOptional()
+  successUrl?: string
+
+  @ApiProperty({ required: false })
+  @IsString()
+  @Expose()
+  @IsOptional()
+  errorUrl?: string
+}