@open-mercato/core 0.4.7-develop-0a657b411f → 0.4.7-develop-e249d3e7d0

package/src/modules/payment_gateways/api/capture/route.ts

@@ -0,0 +1,56 @@
+import { NextResponse } from 'next/server'
+import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import { readJsonSafe } from '@open-mercato/shared/lib/http/readJsonSafe'
+import { captureSchema } from '../../data/validators'
+import type { PaymentGatewayService } from '../../lib/gateway-service'
+import { paymentGatewaysTag } from '../openapi'
+
+export const metadata = {
+  path: '/payment_gateways/capture',
+  POST: { requireAuth: true, requireFeatures: ['payment_gateways.capture'] },
+}
+
+export async function POST(req: Request) {
+  const auth = await getAuthFromRequest(req)
+  if (!auth?.tenantId || !auth.orgId) {
+    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+  }
+
+  const payload = await readJsonSafe<unknown>(req)
+  const parsed = captureSchema.safeParse(payload)
+  if (!parsed.success) {
+    return NextResponse.json({ error: 'Invalid payload', details: parsed.error.flatten() }, { status: 422 })
+  }
+
+  const container = await createRequestContainer()
+  const service = container.resolve('paymentGatewayService') as PaymentGatewayService
+
+  try {
+    const result = await service.capturePayment(
+      parsed.data.transactionId,
+      parsed.data.amount,
+      { organizationId: auth.orgId as string, tenantId: auth.tenantId },
+    )
+    return NextResponse.json(result)
+  } catch (err: unknown) {
+    const message = err instanceof Error ? err.message : 'Capture failed'
+    return NextResponse.json({ error: message }, { status: 502 })
+  }
+}
+
+export const openApi = {
+  tags: [paymentGatewaysTag],
+  summary: 'Capture an authorized payment',
+  methods: {
+    POST: {
+      summary: 'Capture payment',
+      tags: [paymentGatewaysTag],
+      responses: [
+        { status: 200, description: 'Payment captured' },
+        { status: 422, description: 'Invalid payload' },
+        { status: 502, description: 'Gateway provider error' },
+      ],
+    },
+  },
+}

package/src/modules/payment_gateways/api/interceptors.ts

@@ -0,0 +1,22 @@
+import type { ApiInterceptor } from '@open-mercato/shared/lib/crud/api-interceptor'
+import { getGatewayAdapter } from '@open-mercato/shared/modules/payment_gateways/types'
+
+export const interceptors: ApiInterceptor[] = [
+  {
+    id: 'payment_gateways.validate-provider',
+    targetRoute: 'sessions',
+    methods: ['POST'],
+    priority: 100,
+    async before(request) {
+      const providerKey = request.body?.providerKey
+      if (typeof providerKey !== 'string' || providerKey.trim().length === 0) {
+        return { ok: false, statusCode: 422, message: 'providerKey is required' }
+      }
+      const adapter = getGatewayAdapter(providerKey.trim())
+      if (!adapter) {
+        return { ok: false, statusCode: 422, message: `Unknown payment provider: ${providerKey}` }
+      }
+      return { ok: true }
+    },
+  },
+]

package/src/modules/payment_gateways/api/openapi.ts

@@ -0,0 +1 @@
+export const paymentGatewaysTag = 'PaymentGateways'

package/src/modules/payment_gateways/api/refund/route.ts

@@ -0,0 +1,57 @@
+import { NextResponse } from 'next/server'
+import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import { readJsonSafe } from '@open-mercato/shared/lib/http/readJsonSafe'
+import { refundSchema } from '../../data/validators'
+import type { PaymentGatewayService } from '../../lib/gateway-service'
+import { paymentGatewaysTag } from '../openapi'
+
+export const metadata = {
+  path: '/payment_gateways/refund',
+  POST: { requireAuth: true, requireFeatures: ['payment_gateways.refund'] },
+}
+
+export async function POST(req: Request) {
+  const auth = await getAuthFromRequest(req)
+  if (!auth?.tenantId || !auth.orgId) {
+    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+  }
+
+  const payload = await readJsonSafe<unknown>(req)
+  const parsed = refundSchema.safeParse(payload)
+  if (!parsed.success) {
+    return NextResponse.json({ error: 'Invalid payload', details: parsed.error.flatten() }, { status: 422 })
+  }
+
+  const container = await createRequestContainer()
+  const service = container.resolve('paymentGatewayService') as PaymentGatewayService
+
+  try {
+    const result = await service.refundPayment(
+      parsed.data.transactionId,
+      parsed.data.amount,
+      parsed.data.reason,
+      { organizationId: auth.orgId as string, tenantId: auth.tenantId },
+    )
+    return NextResponse.json(result)
+  } catch (err: unknown) {
+    const message = err instanceof Error ? err.message : 'Refund failed'
+    return NextResponse.json({ error: message }, { status: 502 })
+  }
+}
+
+export const openApi = {
+  tags: [paymentGatewaysTag],
+  summary: 'Refund a captured payment',
+  methods: {
+    POST: {
+      summary: 'Refund payment',
+      tags: [paymentGatewaysTag],
+      responses: [
+        { status: 200, description: 'Payment refunded' },
+        { status: 422, description: 'Invalid payload' },
+        { status: 502, description: 'Gateway provider error' },
+      ],
+    },
+  },
+}

package/src/modules/payment_gateways/api/sessions/route.ts

@@ -0,0 +1,76 @@
+import { NextResponse } from 'next/server'
+import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import { readJsonSafe } from '@open-mercato/shared/lib/http/readJsonSafe'
+import { createSessionSchema } from '../../data/validators'
+import type { PaymentGatewayService } from '../../lib/gateway-service'
+import { paymentGatewaysTag } from '../openapi'
+
+export const metadata = {
+  path: '/payment_gateways/sessions',
+  POST: { requireAuth: true, requireFeatures: ['payment_gateways.manage'] },
+}
+
+export async function POST(req: Request) {
+  const auth = await getAuthFromRequest(req)
+  if (!auth?.tenantId || !auth.orgId) {
+    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+  }
+
+  const payload = await readJsonSafe<unknown>(req)
+  const parsed = createSessionSchema.safeParse(payload)
+  if (!parsed.success) {
+    return NextResponse.json({ error: 'Invalid payload', details: parsed.error.flatten() }, { status: 422 })
+  }
+
+  const container = await createRequestContainer()
+  const service = container.resolve('paymentGatewayService') as PaymentGatewayService
+
+  try {
+    const { transaction, session } = await service.createPaymentSession({
+      providerKey: parsed.data.providerKey,
+      paymentId: crypto.randomUUID(),
+      orderId: parsed.data.orderId,
+      amount: parsed.data.amount,
+      currencyCode: parsed.data.currencyCode,
+      captureMethod: parsed.data.captureMethod,
+      description: parsed.data.description,
+      successUrl: parsed.data.successUrl,
+      cancelUrl: parsed.data.cancelUrl,
+      metadata: parsed.data.metadata,
+      organizationId: auth.orgId as string,
+      tenantId: auth.tenantId,
+    })
+
+    return NextResponse.json({
+      transactionId: transaction.id,
+      sessionId: session.sessionId,
+      providerKey: transaction.providerKey,
+      clientSecret: session.clientSecret,
+      redirectUrl: session.redirectUrl,
+      providerData: session.providerData ?? null,
+      status: session.status,
+      paymentId: transaction.paymentId,
+    }, { status: 201 })
+  } catch (err: unknown) {
+    const message = err instanceof Error ? err.message : 'Failed to create payment session'
+    const status = message.includes('No gateway adapter') ? 422 : 502
+    return NextResponse.json({ error: message }, { status })
+  }
+}
+
+export const openApi = {
+  tags: [paymentGatewaysTag],
+  summary: 'Create a payment session via a gateway provider',
+  methods: {
+    POST: {
+      summary: 'Create payment session',
+      tags: [paymentGatewaysTag],
+      responses: [
+        { status: 201, description: 'Payment session created' },
+        { status: 422, description: 'Invalid payload or unknown provider' },
+        { status: 502, description: 'Gateway provider error' },
+      ],
+    },
+  },
+}

package/src/modules/payment_gateways/api/status/route.ts

@@ -0,0 +1,69 @@
+import { NextResponse } from 'next/server'
+import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import type { PaymentGatewayService } from '../../lib/gateway-service'
+import { paymentGatewaysTag } from '../openapi'
+
+export const metadata = {
+  path: '/payment_gateways/status',
+  GET: { requireAuth: true, requireFeatures: ['payment_gateways.view'] },
+}
+
+export async function GET(req: Request) {
+  const auth = await getAuthFromRequest(req)
+  if (!auth?.tenantId || !auth.orgId) {
+    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+  }
+
+  const url = new URL(req.url)
+  const transactionId = url.searchParams.get('transactionId')
+  if (!transactionId) {
+    return NextResponse.json({ error: 'transactionId is required' }, { status: 400 })
+  }
+
+  const container = await createRequestContainer()
+  const service = container.resolve('paymentGatewayService') as PaymentGatewayService
+
+  try {
+    const scope = { organizationId: auth.orgId as string, tenantId: auth.tenantId }
+    const transaction = await service.findTransaction(transactionId, scope)
+    if (!transaction) {
+      return NextResponse.json({ error: 'Transaction not found' }, { status: 404 })
+    }
+
+    const status = await service.getPaymentStatus(transactionId, scope)
+
+    return NextResponse.json({
+      transactionId: transaction.id,
+      paymentId: transaction.paymentId,
+      providerKey: transaction.providerKey,
+      sessionId: transaction.providerSessionId,
+      status: status.status,
+      gatewayStatus: transaction.gatewayStatus,
+      amount: status.amount,
+      amountReceived: status.amountReceived,
+      currencyCode: status.currencyCode,
+      redirectUrl: transaction.redirectUrl,
+      createdAt: transaction.createdAt.toISOString(),
+      updatedAt: transaction.updatedAt.toISOString(),
+    })
+  } catch (err: unknown) {
+    const message = err instanceof Error ? err.message : 'Failed to get status'
+    return NextResponse.json({ error: message }, { status: 500 })
+  }
+}
+
+export const openApi = {
+  tags: [paymentGatewaysTag],
+  summary: 'Get payment transaction status',
+  methods: {
+    GET: {
+      summary: 'Get transaction status',
+      tags: [paymentGatewaysTag],
+      responses: [
+        { status: 200, description: 'Transaction status' },
+        { status: 404, description: 'Transaction not found' },
+      ],
+    },
+  },
+}

package/src/modules/payment_gateways/api/transactions/[id]/route.ts

@@ -0,0 +1,123 @@
+import { NextResponse } from 'next/server'
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import { findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import type { IntegrationLogService } from '../../../../integrations/lib/log-service'
+import { GatewayTransaction } from '../../../data/entities'
+import { paymentGatewaysTag } from '../../openapi'
+
+export const metadata = {
+  path: '/payment_gateways/transactions/[id]',
+  GET: { requireAuth: true, requireFeatures: ['payment_gateways.view'] },
+}
+
+function toIsoString(value: unknown): string | null {
+  if (!value) return null
+  if (value instanceof Date) return value.toISOString()
+  if (typeof value === 'string') {
+    const parsed = new Date(value)
+    if (!Number.isNaN(parsed.getTime())) return parsed.toISOString()
+    return value
+  }
+  const parsed = new Date(value as string | number)
+  return Number.isNaN(parsed.getTime()) ? null : parsed.toISOString()
+}
+
+export async function GET(req: Request, { params }: { params: Promise<{ id: string }> | { id: string } }) {
+  const auth = await getAuthFromRequest(req)
+  if (!auth?.tenantId || !auth.orgId) {
+    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+  }
+
+  const resolvedParams = await params
+  const transactionId = resolvedParams?.id
+  if (!transactionId) {
+    return NextResponse.json({ error: 'Transaction id is required' }, { status: 400 })
+  }
+
+  const { resolve } = await createRequestContainer()
+  const scope = { organizationId: auth.orgId as string, tenantId: auth.tenantId }
+  const em = resolve('em') as EntityManager
+  const integrationLogService = resolve('integrationLogService') as IntegrationLogService
+  const transaction = await findOneWithDecryption(
+    em,
+    GatewayTransaction,
+    {
+      id: transactionId,
+      organizationId: scope.organizationId,
+      tenantId: scope.tenantId,
+      deletedAt: null,
+    },
+    undefined,
+    scope,
+  )
+
+  if (!transaction) {
+    return NextResponse.json({ error: 'Transaction not found' }, { status: 404 })
+  }
+
+  const integrationId = `gateway_${transaction.providerKey}`
+  const { items: logRows } = await integrationLogService.query(
+    {
+      integrationId,
+      entityType: 'payment_transaction',
+      entityId: transactionId,
+      page: 1,
+      pageSize: 100,
+    },
+    scope,
+  )
+
+  return NextResponse.json({
+    transaction: {
+      id: transaction.id,
+      paymentId: transaction.paymentId,
+      providerKey: transaction.providerKey,
+      providerSessionId: transaction.providerSessionId ?? null,
+      gatewayPaymentId: transaction.gatewayPaymentId ?? null,
+      gatewayRefundId: transaction.gatewayRefundId ?? null,
+      unifiedStatus: transaction.unifiedStatus,
+      gatewayStatus: transaction.gatewayStatus ?? null,
+      redirectUrl: transaction.redirectUrl ?? null,
+      amount: transaction.amount,
+      currencyCode: transaction.currencyCode,
+      gatewayMetadata: transaction.gatewayMetadata ?? null,
+      webhookLog: Array.isArray(transaction.webhookLog) ? transaction.webhookLog : [],
+      lastWebhookAt: toIsoString(transaction.lastWebhookAt),
+      lastPolledAt: toIsoString(transaction.lastPolledAt),
+      expiresAt: toIsoString(transaction.expiresAt),
+      createdAt: toIsoString(transaction.createdAt),
+      updatedAt: toIsoString(transaction.updatedAt),
+    },
+    logs: logRows.map((row) => ({
+      id: row.id,
+      integrationId: row.integrationId,
+      runId: row.runId ?? null,
+      scopeEntityType: row.scopeEntityType ?? null,
+      scopeEntityId: row.scopeEntityId ?? null,
+      level: row.level,
+      message: row.message,
+      code: row.code ?? null,
+      payload: row.payload ?? null,
+      createdAt: toIsoString(row.createdAt),
+    })),
+  })
+}
+
+export const openApi = {
+  tags: [paymentGatewaysTag],
+  summary: 'Get payment transaction details',
+  methods: {
+    GET: {
+      summary: 'Get payment transaction details',
+      tags: [paymentGatewaysTag],
+      responses: [
+        { status: 200, description: 'Payment transaction details' },
+        { status: 404, description: 'Transaction not found' },
+      ],
+    },
+  },
+}
+
+export default GET

package/src/modules/payment_gateways/api/transactions/route.ts

@@ -0,0 +1,120 @@
+import { NextResponse } from 'next/server'
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import { GatewayTransaction } from '../../data/entities'
+import { listTransactionsQuerySchema } from '../../data/validators'
+import { paymentGatewaysTag } from '../openapi'
+
+export const metadata = {
+  path: '/payment_gateways/transactions',
+  GET: { requireAuth: true, requireFeatures: ['payment_gateways.view'] },
+}
+
+function escapeLikePattern(value: string): string {
+  return value.replace(/[\\%_]/g, '\\$&')
+}
+
+function formatDateValue(value: unknown): string | null {
+  if (!value) return null
+  if (value instanceof Date) return value.toISOString()
+  if (typeof value === 'string') {
+    const parsed = new Date(value)
+    if (!Number.isNaN(parsed.getTime())) return parsed.toISOString()
+    return value
+  }
+  const fallback = new Date(value as string | number)
+  return Number.isNaN(fallback.getTime()) ? null : fallback.toISOString()
+}
+
+export async function GET(req: Request) {
+  const auth = await getAuthFromRequest(req)
+  if (!auth?.tenantId || !auth.orgId) {
+    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+  }
+
+  const url = new URL(req.url)
+  const parsed = listTransactionsQuerySchema.safeParse(Object.fromEntries(url.searchParams.entries()))
+  if (!parsed.success) {
+    return NextResponse.json({ error: 'Invalid query', details: parsed.error.flatten() }, { status: 400 })
+  }
+
+  const { page, pageSize, search, providerKey, status } = parsed.data
+  const offset = (page - 1) * pageSize
+  const { resolve } = await createRequestContainer()
+  const em = resolve('em') as EntityManager
+  const qb = em.createQueryBuilder(GatewayTransaction, 'gt')
+
+  qb.where({
+    organizationId: auth.orgId,
+    tenantId: auth.tenantId,
+    deletedAt: null,
+  })
+
+  if (providerKey) {
+    qb.andWhere({ providerKey })
+  }
+  if (status) {
+    qb.andWhere({ unifiedStatus: status })
+  }
+  if (search) {
+    const pattern = `%${escapeLikePattern(search)}%`
+    qb.andWhere(`(
+      cast(gt.id as text) ilike ?
+      or cast(gt.payment_id as text) ilike ?
+      or coalesce(gt.provider_key, '') ilike ?
+      or coalesce(gt.provider_session_id, '') ilike ?
+      or coalesce(gt.gateway_payment_id, '') ilike ?
+      or coalesce(gt.gateway_refund_id, '') ilike ?
+    ) escape '\\'`, [pattern, pattern, pattern, pattern, pattern, pattern])
+  }
+
+  const countQb = qb.clone()
+  qb.orderBy({ createdAt: 'desc' })
+  qb.limit(pageSize).offset(offset)
+
+  const [items, total] = await Promise.all([
+    qb.getResultList(),
+    countQb.count('gt.id', true),
+  ])
+
+  return NextResponse.json({
+    items: items.map((item) => ({
+      id: item.id,
+      paymentId: item.paymentId,
+      providerKey: item.providerKey,
+      providerSessionId: item.providerSessionId ?? null,
+      gatewayPaymentId: item.gatewayPaymentId ?? null,
+      gatewayRefundId: item.gatewayRefundId ?? null,
+      unifiedStatus: item.unifiedStatus,
+      gatewayStatus: item.gatewayStatus ?? null,
+      amount: item.amount,
+      currencyCode: item.currencyCode,
+      redirectUrl: item.redirectUrl ?? null,
+      lastWebhookAt: formatDateValue(item.lastWebhookAt),
+      lastPolledAt: formatDateValue(item.lastPolledAt),
+      createdAt: formatDateValue(item.createdAt),
+      updatedAt: formatDateValue(item.updatedAt),
+    })),
+    total,
+    page,
+    pageSize,
+    totalPages: Math.max(1, Math.ceil(total / pageSize)),
+  })
+}
+
+export const openApi = {
+  tags: [paymentGatewaysTag],
+  summary: 'List payment transactions',
+  methods: {
+    GET: {
+      summary: 'List payment transactions',
+      tags: [paymentGatewaysTag],
+      responses: [
+        { status: 200, description: 'Payment transaction list' },
+      ],
+    },
+  },
+}
+
+export default GET

package/src/modules/payment_gateways/api/webhook/[provider]/route.ts

@@ -0,0 +1,161 @@
+import { NextResponse } from 'next/server'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import { findWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import { readJsonSafe } from '@open-mercato/shared/lib/http/readJsonSafe'
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { getWebhookHandler } from '@open-mercato/shared/modules/payment_gateways/types'
+import type { IntegrationLogService } from '../../../../integrations/lib/log-service'
+import type { PaymentGatewayService } from '../../../lib/gateway-service'
+import type { CredentialsService } from '../../../../integrations/lib/credentials-service'
+import { GatewayTransaction } from '../../../data/entities'
+import { getPaymentGatewayQueue } from '../../../lib/queue'
+import { processPaymentGatewayWebhookJob } from '../../../lib/webhook-processor'
+import { paymentGatewaysTag } from '../../openapi'
+
+export const metadata = {
+  path: '/payment_gateways/webhook/[provider]',
+  POST: { requireAuth: false },
+}
+
+function readScopeFromEventData(data: Record<string, unknown>): { organizationId: string; tenantId: string } | null {
+  const metadata = data.metadata
+  if (!metadata || typeof metadata !== 'object') return null
+
+  const metadataRecord = metadata as Record<string, unknown>
+  const organizationId = typeof metadataRecord.organizationId === 'string'
+    ? metadataRecord.organizationId.trim()
+    : ''
+  const tenantId = typeof metadataRecord.tenantId === 'string'
+    ? metadataRecord.tenantId.trim()
+    : ''
+
+  if (!organizationId || !tenantId) return null
+  return { organizationId, tenantId }
+}
+
+export async function POST(req: Request, { params }: { params: Promise<{ provider: string }> | { provider: string } }) {
+  const resolvedParams = await params
+  const providerKey = resolvedParams.provider
+  const container = await createRequestContainer()
+  const registration = getWebhookHandler(providerKey)
+  if (!registration) {
+    return NextResponse.json({ error: `No webhook handler for provider: ${providerKey}` }, { status: 404 })
+  }
+
+  const rawBody = await req.text()
+  const headers: Record<string, string> = {}
+  req.headers.forEach((value, key) => {
+    headers[key] = value
+  })
+
+  const service = container.resolve('paymentGatewayService') as PaymentGatewayService
+  const em = container.resolve('em') as EntityManager
+  const integrationCredentialsService = container.resolve('integrationCredentialsService') as CredentialsService
+  const queue = getPaymentGatewayQueue(registration.queue ?? 'payment-gateways-webhook')
+  const payload = await readJsonSafe<Record<string, unknown>>(rawBody)
+  const sessionIdHint = registration.readSessionIdHint?.(payload) ?? null
+
+  try {
+    const candidates = sessionIdHint
+      ? await findWithDecryption(
+        em,
+        GatewayTransaction,
+        {
+          providerKey,
+          providerSessionId: sessionIdHint,
+          deletedAt: null,
+        },
+        { limit: 10, orderBy: { createdAt: 'desc' } },
+      )
+      : []
+
+    let transaction = null as GatewayTransaction | null
+    let matchedScope = null as { organizationId: string; tenantId: string } | null
+    let event = null as Awaited<ReturnType<typeof registration.handler>> | null
+    let lastVerificationError: unknown = null
+
+    for (const candidate of candidates) {
+      const candidateScope = { organizationId: candidate.organizationId, tenantId: candidate.tenantId }
+      const credentials = await integrationCredentialsService.resolve(`gateway_${providerKey}`, candidateScope) ?? {}
+      try {
+        event = await registration.handler({ rawBody, headers, credentials })
+        transaction = candidate
+        matchedScope = candidateScope
+        break
+      } catch (error: unknown) {
+        lastVerificationError = error
+      }
+    }
+
+    if (!event) {
+      try {
+        event = await registration.handler({ rawBody, headers, credentials: {} })
+      } catch (error: unknown) {
+        throw lastVerificationError ?? error
+      }
+    }
+    if (!event) {
+      throw new Error('Webhook verification failed')
+    }
+
+    if (!transaction && sessionIdHint) {
+      const derivedScope = readScopeFromEventData(event.data)
+      if (derivedScope) {
+        transaction = await service.findTransactionBySessionId(sessionIdHint, derivedScope, providerKey)
+        matchedScope = transaction
+          ? { organizationId: transaction.organizationId, tenantId: transaction.tenantId }
+          : derivedScope
+      }
+    }
+
+    const scope = transaction
+      ? { organizationId: transaction.organizationId, tenantId: transaction.tenantId }
+      : matchedScope ?? readScopeFromEventData(event.data)
+
+    const jobPayload = {
+      providerKey,
+      event,
+      transactionId: transaction?.id ?? null,
+      scope,
+    }
+
+    if (process.env.QUEUE_STRATEGY === 'async') {
+      await queue.enqueue({
+        name: 'payment-gateway-webhook',
+        payload: jobPayload,
+      })
+    } else {
+      await processPaymentGatewayWebhookJob(
+        {
+          em: container.resolve('em') as EntityManager,
+          paymentGatewayService: service,
+          integrationLogService: container.resolve('integrationLogService') as IntegrationLogService,
+        },
+        jobPayload,
+      )
+    }
+
+    return NextResponse.json({ received: true, queued: true }, { status: 202 })
+  } catch (err: unknown) {
+    const message = err instanceof Error ? err.message : 'Webhook verification failed'
+    return NextResponse.json({ error: message }, { status: 401 })
+  }
+}
+
+export const openApi = {
+  tags: [paymentGatewaysTag],
+  summary: 'Receive payment gateway webhook',
+  methods: {
+    POST: {
+      summary: 'Process inbound webhook from payment provider',
+      tags: [paymentGatewaysTag],
+      responses: [
+        { status: 202, description: 'Webhook accepted for async processing' },
+        { status: 401, description: 'Signature verification failed' },
+        { status: 404, description: 'Unknown provider' },
+      ],
+    },
+  },
+}
+
+export default POST