WIP

Author: mokhld

src/server/plugins/engine/components/FormComponent.ts

@@ -191,7 +191,7 @@ export class FormComponent extends ComponentBase {
       return value.filter(isFormValue)
     }
 
-    return this.isValue(value) ? value : null
+    return this.isValue(value) ? (value as Item['value']) : null
   }
 
   getContextValueFromState(

src/server/plugins/engine/components/PaymentField.ts

@@ -5,9 +5,11 @@ import {
   type PaymentFieldComponent
 } from '@defra/forms-model'
 import { StatusCodes } from 'http-status-codes'
+import joi, { type ObjectSchema } from 'joi'
 
 import { FormComponent } from '~/src/server/plugins/engine/components/FormComponent.js'
 import { type PaymentState } from '~/src/server/plugins/engine/components/PaymentField.types.js'
+import { getPluginOptions } from '~/src/server/plugins/engine/helpers.js'
 import {
   type AnyFormRequest,
   type FormContext,
@@ -17,13 +19,17 @@ import {
 import {
   type ErrorMessageTemplateList,
   type FormPayload,
+  type FormState,
+  type FormStateValue,
   type FormSubmissionError,
   type FormSubmissionState
 } from '~/src/server/plugins/engine/types.js'
 import { PaymentService } from '~/src/server/plugins/payment/service.js'
 
 export class PaymentField extends FormComponent {
   declare options: PaymentFieldComponent['options']
+  declare formSchema: ObjectSchema
+  declare stateSchema: ObjectSchema
 
   constructor(
     def: PaymentFieldComponent,
@@ -32,6 +38,30 @@ export class PaymentField extends FormComponent {
     super(def, props)
 
     this.options = def.options
+
+    // Payment state is validated as an object with the required fields
+    const paymentStateSchema = joi
+      .object({
+        paymentId: joi.string().required(),
+        reference: joi.string().required(),
+        amount: joi.number().required(),
+        description: joi.string().required(),
+        uuid: joi.string().uuid().required(),
+        preAuth: joi
+          .object({
+            status: joi
+              .string()
+              .valid('success', 'failed', 'started')
+              .required(),
+            createdAt: joi.string().isoDate().required()
+          })
+          .required()
+      })
+      .unknown(true)
+      .label(this.label)
+
+    this.formSchema = paymentStateSchema
+    this.stateSchema = paymentStateSchema.default(null).allow(null)
   }
 
   /**
@@ -40,7 +70,7 @@ export class PaymentField extends FormComponent {
   getPaymentStateFromState(
     state: FormSubmissionState
   ): PaymentState | undefined {
-    const value = state[this.name] as unknown
+    const value = state[this.name]
     return this.isPaymentState(value) ? value : undefined
   }
 
@@ -88,6 +118,13 @@ export class PaymentField extends FormComponent {
     )
   }
 
+  /**
+   * Override base isState to validate PaymentState
+   */
+  isState(value?: FormStateValue | FormState): value is FormState {
+    return this.isPaymentState(value)
+  }
+
   /**
    * For error preview page that shows all possible errors on a component
    */
@@ -112,7 +149,6 @@ export class PaymentField extends FormComponent {
 
   /**
    * Dispatcher for external redirect to GOV.UK Pay
-   * STUB - Jez to implement
    */
   static async dispatcher(
     request: FormRequestPayload,
@@ -121,38 +157,52 @@ export class PaymentField extends FormComponent {
   ): Promise<unknown> {
     const paymentService = new PaymentService()
 
-    // 1. Generate UUID token and store in session
+    // 1. Generate UUID token
     const uuid = randomUUID()
 
-    const { options } = args.component
+    const { options, name: componentName } = args.component
     const { model } = args.controller
 
     const state = await args.controller.getState(request)
-
-    const data = {
-      uuid,
-      reference: state.$$__referenceNumber,
-      description: options.description,
-      amount: options.amount
-    } as PaymentState
-
-    request.yar.set(`${request.url.pathname}-payment`, data)
+    const reference = state.$$__referenceNumber as string
+    const amount = options.amount ?? 0
+    const description = options.description ?? ''
 
     const formId = model.formId
     const slug = `/${model.basePath}`
 
-    // 2. Call paymentService.createPayment()
+    // 2. Build the return URL for GOV.UK Pay
+    const { baseUrl } = getPluginOptions(request.server)
+    const returnUrl = `${baseUrl}/payment-callback?uuid=${uuid}`
+
+    // Build the summary URL to redirect to after payment
+    const summaryUrl = `${baseUrl}/${model.basePath}/summary`
+
+    // 3. Call paymentService.createPayment()
     // GOV.UK Pay expects amount in pence, so multiply pounds by 100
-    const amountInPence = Math.round(data.amount * 100)
+    const amountInPence = Math.round(amount * 100)
     const payment = await paymentService.createPayment(
       amountInPence,
-      data.description,
-      uuid,
-      data.reference,
+      description,
+      returnUrl,
+      reference,
       { formId, slug }
     )
 
-    // 3. Redirect to GOV.UK Pay paymentUrl
+    // 4. Store session data for the return route to use
+    const sessionData: PaymentSessionData = {
+      uuid,
+      reference,
+      amount,
+      description,
+      paymentId: payment.paymentId,
+      componentName,
+      sourceUrl: summaryUrl
+    }
+
+    request.yar.set(`payment-${uuid}`, sessionData)
+
+    // 5. Redirect to GOV.UK Pay paymentUrl
     return h.redirect(payment.paymentUrl).code(StatusCodes.SEE_OTHER)
   }
 
@@ -189,3 +239,16 @@ export interface PaymentDispatcherArgs {
   sourceUrl: string
   paymentService: PaymentService
 }
+
+/**
+ * Session data stored when dispatching to GOV.UK Pay
+ */
+export interface PaymentSessionData {
+  uuid: string
+  reference: string
+  amount: number
+  description: string
+  paymentId: string
+  componentName: string
+  sourceUrl: string
+}

src/server/plugins/engine/components/PaymentField.types.ts

@@ -16,41 +16,3 @@ export interface PaymentState {
     createdAt: string
   }
 }
-
-/**
- * Response from GOV.UK Pay API
- */
-export interface PaymentStatus {
-  amount: number
-  state: {
-    status:
-      | 'created'
-      | 'started'
-      | 'submitted'
-      | 'capturable'
-      | 'success'
-      | 'failed'
-      | 'cancelled'
-      | 'error'
-    finished: boolean
-    message?: string
-    code?: string
-    canRetry?: boolean
-  }
-  createdDate: string
-}
-
-/**
- * Service interface for GOV.UK Pay integration
- */
-export interface PaymentService {
-  createPayment(
-    amount: number,
-    description: string,
-    metadata: { formId: string; slug: string }
-  ): Promise<{ paymentId: string; paymentUrl: string }>
-
-  getPaymentStatus(paymentId: string): Promise<PaymentStatus>
-
-  capturePayment(paymentId: string): Promise<boolean>
-}

src/server/plugins/engine/models/SummaryViewModel.ts

@@ -1,5 +1,7 @@
 import { SchemaVersion, type Section } from '@defra/forms-model'
 
+import { PaymentField } from '~/src/server/plugins/engine/components/PaymentField.js'
+import { type PaymentState } from '~/src/server/plugins/engine/components/PaymentField.types.js'
 import {
   getAnswer,
   type Field
@@ -52,6 +54,8 @@ export class SummaryViewModel {
   hasMissingNotificationEmail?: boolean
   components?: ComponentViewModel[]
   allowSaveAndExit = false
+  paymentState?: PaymentState
+  paymentDetails?: CheckAnswers
 
   constructor(
     request: FormContextRequest,
@@ -144,6 +148,10 @@ export class SummaryViewModel {
           )
         } else {
           for (const field of collection.fields) {
+            // PaymentField is rendered in its own section, skip it here
+            if (field instanceof PaymentField) {
+              continue
+            }
             items.push(ItemField(page, state, field, { path, errors }))
           }
         }

src/server/plugins/engine/pageControllers/SummaryPageController.ts

@@ -9,6 +9,7 @@ import { type RouteOptions } from '@hapi/hapi'
 
 import { COMPONENT_STATE_ERROR } from '~/src/server/constants.js'
 import { ComponentCollection } from '~/src/server/plugins/engine/components/ComponentCollection.js'
+import { PaymentField } from '~/src/server/plugins/engine/components/PaymentField.js'
 import { getAnswer } from '~/src/server/plugins/engine/components/helpers/components.js'
 import {
   checkEmailAddressForLiveFormSubmission,
@@ -65,7 +66,7 @@ export class SummaryPageController extends QuestionPageController {
     const viewModel = new SummaryViewModel(request, this, context)
 
     const { query } = request
-    const { payload, errors } = context
+    const { payload, errors, state } = context
     const components = this.collection.getViewModel(payload, errors, query)
 
     // We already figure these out in the base page controller. Take them and apply them to our page-specific model.
@@ -77,9 +78,76 @@ export class SummaryPageController extends QuestionPageController {
     viewModel.allowSaveAndExit = this.shouldShowSaveAndExit(request.server)
     viewModel.errors = errors
 
+    // Find PaymentField and extract payment state for the summary banner
+    const paymentField = context.relevantPages
+      .flatMap((page) => page.collection.fields)
+      .find((field): field is PaymentField => field instanceof PaymentField)
+
+    if (paymentField) {
+      const paymentState = paymentField.getPaymentStateFromState(state)
+      if (paymentState) {
+        viewModel.paymentState = paymentState
+        viewModel.paymentDetails = this.buildPaymentDetails(
+          paymentField,
+          paymentState
+        )
+      }
+    }
+
     return viewModel
   }
 
+  private buildPaymentDetails(
+    paymentField: PaymentField,
+    paymentState: NonNullable<
+      ReturnType<PaymentField['getPaymentStateFromState']>
+    >
+  ) {
+    const formatDate = (isoString: string) => {
+      const date = new Date(isoString)
+      return (
+        date.toLocaleDateString('en-GB', {
+          day: 'numeric',
+          month: 'long',
+          year: 'numeric'
+        }) +
+        ' – ' +
+        date.toLocaleTimeString('en-GB', {
+          hour: '2-digit',
+          minute: '2-digit',
+          second: '2-digit'
+        })
+      )
+    }
+
+    const rows = [
+      {
+        key: { text: 'Payment for' },
+        value: { text: paymentState.description }
+      },
+      {
+        key: { text: 'Total amount' },
+        value: { text: `£${paymentState.amount}` }
+      },
+      {
+        key: { text: 'Reference' },
+        value: { text: paymentState.reference }
+      }
+    ]
+
+    if (paymentState.preAuth?.createdAt) {
+      rows.push({
+        key: { text: 'Date details were entered' },
+        value: { text: formatDate(paymentState.preAuth.createdAt) }
+      })
+    }
+
+    return {
+      title: { text: 'Payment details' },
+      summaryList: { rows }
+    }
+  }
+
   /**
    * Returns an async function. This is called in plugin.ts when there is a GET request at `/{id}/{path*}`,
    */