@defra/forms-engine-plugin 4.8.0 → 4.9.0

package/src/server/plugins/engine/pageControllers/QuestionPageController.ts

@@ -5,6 +5,7 @@ import {
   hasComponents,
   hasNext,
   hasRepeater,
+  isPaymentPage,
   type Link,
   type Page
 } from '@defra/forms-model'
@@ -19,6 +20,7 @@ import {
   PAYMENT_EXPIRED_NOTIFICATION
 } from '../../../constants.js'
 import { ComponentCollection } from '../components/ComponentCollection.js'
+import { PaymentField } from '../components/PaymentField.js'
 import { optionalText } from '../components/constants.js'
 import { type BackLink } from '../components/types.js'
 import {
@@ -44,6 +46,7 @@ import {
   type FormSubmissionState
 } from '../types.js'
 import { getComponentsByType } from '../validationHelpers.js'
+import { formatCurrency } from '../../payment/helper.js'
 import {
   FormAction,
   FormStatus,
@@ -182,6 +185,25 @@ export class QuestionPageController extends PageController {
       }
     }
 
+    // Override payment amount display with resolved conditional amount
+    // getViewModel() only has the current page's payload, not full form state.
+    // The full state is available via context.evaluationState.
+    for (const comp of components) {
+      if ('amount' in comp.model && 'paymentState' in comp.model) {
+        const paymentField = this.collection.fields.find(
+          (f): f is PaymentField => f instanceof PaymentField
+        )
+        if (paymentField) {
+          const resolvedAmount = PaymentField.resolveAmount(
+            paymentField.options,
+            this.model,
+            context.evaluationState
+          )
+          comp.model.amount = formatCurrency(resolvedAmount)
+        }
+      }
+    }
+
     const hasIncompletePayment = components.some(({ model }) => {
       if ('paymentState' in model) {
         const paymentState = model.paymentState as
@@ -199,7 +221,9 @@ export class QuestionPageController extends PageController {
       showTitle,
       components,
       errors,
-      allowSaveAndExit: this.shouldShowSaveAndExit(request.server),
+      allowSaveAndExit:
+        this.shouldShowSaveAndExit(request.server) &&
+        !isPaymentPage(this.pageDef),
       showSubmitButton: !hasIncompletePayment
     }
   }
@@ -246,6 +270,13 @@ export class QuestionPageController extends PageController {
             }
           }
 
+          // Skip payment pages in the normal page walk.
+          // Users reach the payment page via "Pay and submit" on CYA,
+          // not by navigating forward through the form.
+          if (isPaymentPage(page.pageDef)) {
+            return false
+          }
+
           return true
         })
 

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

@@ -6,6 +6,7 @@ import {
 } from '@defra/forms-model'
 import Boom from '@hapi/boom'
 import { type RouteOptions } from '@hapi/hapi'
+import { StatusCodes } from 'http-status-codes'
 
 import {
   COMPONENT_STATE_ERROR,
@@ -65,6 +66,16 @@ export class SummaryPageController extends QuestionPageController {
    * The controller which is used when Page["controller"] is defined as "./pages/summary.js"
    */
 
+  /**
+   * Finds the PaymentField component across all pages in the model.
+   * Payment pages are skipped in the normal page walk
+   */
+  private findPaymentField(): PaymentField | undefined {
+    return this.model.pages
+      .flatMap((page) => page.collection.fields)
+      .find((field): field is PaymentField => field instanceof PaymentField)
+  }
+
   constructor(model: FormModel, pageDef: Page) {
     super(model, pageDef)
     this.viewName = 'summary'
@@ -85,19 +96,34 @@ export class SummaryPageController extends QuestionPageController {
     const { query } = request
     const { payload, errors, state } = context
 
-    const paymentField = context.relevantPages
-      .flatMap((page) => page.collection.fields)
-      .find((field): field is PaymentField => field instanceof PaymentField)
+    const paymentField = this.findPaymentField()
 
     if (paymentField) {
+      const resolvedAmount = PaymentField.resolveAmount(
+        paymentField.options,
+        this.model,
+        state
+      )
       const paymentState = paymentField.getPaymentStateFromState(state)
-      if (paymentState) {
+
+      if (paymentState?.amount === resolvedAmount) {
         viewModel.paymentState = paymentState
         viewModel.paymentDetails = this.buildPaymentDetails(
           paymentField,
           paymentState
         )
       }
+
+      if (resolvedAmount > 0) {
+        viewModel.paymentRequired = true
+      }
+      if (
+        paymentState &&
+        paymentState.preAuth?.status === 'success' &&
+        paymentState.amount === resolvedAmount
+      ) {
+        viewModel.paymentPreAuthorized = true
+      }
     }
 
     const components = this.collection.getViewModel(payload, errors, query)
@@ -157,6 +183,18 @@ export class SummaryPageController extends QuestionPageController {
     ) => {
       const { viewName } = this
 
+      // After GOV.UK Pay callback, auto-submit the form instead of
+      // showing CYA again. The payment is already pre-authorized.
+      if (request.query.paymentComplete === 'true') {
+        return this.handleFormSubmit(
+          request as unknown as FormRequestPayload,
+          context,
+          h
+        )
+      }
+
+      await this.reconcilePaymentState(request, context)
+
       const viewModel = this.getSummaryViewModel(request, context)
 
       viewModel.hasMissingNotificationEmail =
@@ -166,6 +204,33 @@ export class SummaryPageController extends QuestionPageController {
     }
   }
 
+  /**
+   * Checks if the resolved payment amount has changed since pre-auth
+   * and invalidates stale payment state if so.
+   */
+  private async reconcilePaymentState(
+    request: FormRequest,
+    context: FormContext
+  ) {
+    const paymentField = this.findPaymentField()
+
+    if (!paymentField) {
+      return
+    }
+
+    const resolvedAmount = PaymentField.resolveAmount(
+      paymentField.options,
+      this.model,
+      context.state
+    )
+    const paymentState = paymentField.getPaymentStateFromState(context.state)
+
+    if (paymentState && paymentState.amount !== resolvedAmount) {
+      const cacheService = getCacheService(request.server)
+      await cacheService.resetComponentStates(request, [paymentField.name])
+    }
+  }
+
   /**
    * Returns an async function. This is called in plugin.ts when there is a POST request at `/{id}/{path*}`.
    * If a form is incomplete, a user will be redirected to the start page.
@@ -293,6 +358,18 @@ export class SummaryPageController extends QuestionPageController {
       }
     }
 
+    // Payment page is skipped in the page walk, so proceed() would redirect
+    // to an earlier page. For PaymentIncomplete, redirect directly to the
+    // payment page using its href.
+    if (
+      error.errorType === PaymentErrorTypes.PaymentIncomplete &&
+      error.component.page
+    ) {
+      return h
+        .redirect(error.component.page.getHref(error.component.page.path))
+        .code(StatusCodes.SEE_OTHER)
+    }
+
     const govukError = createError(error.component.name, error.userMessage)
     request.yar.flash(COMPONENT_STATE_ERROR, govukError, true)
 
@@ -345,9 +422,9 @@ export async function submitForm(
   model: FormModel,
   emailAddress: string
 ) {
-  await finaliseComponents(request, formMetadata, context)
+  await finaliseComponents(request, formMetadata, context, model)
 
-  const paymentWasCaptured = hasPaymentBeenCaptured(context)
+  const paymentWasCaptured = hasPaymentBeenCaptured(context, model)
 
   const formStatus = checkFormStatus(request.params)
   const logTags = ['submit', 'submissionApi']
@@ -395,8 +472,11 @@ export async function submitForm(
 /**
  * Checks if any payment component has been captured
  */
-function hasPaymentBeenCaptured(context: FormContext): boolean {
-  for (const page of context.relevantPages) {
+function hasPaymentBeenCaptured(
+  context: FormContext,
+  model: FormModel
+): boolean {
+  for (const page of model.pages) {
     for (const field of page.collection.fields) {
       if (field instanceof PaymentField) {
         const paymentState = field.getPaymentStateFromState(context.state)
@@ -419,17 +499,19 @@ function hasPaymentBeenCaptured(context: FormContext): boolean {
 async function finaliseComponents(
   request: FormRequestPayload,
   metadata: FormMetadata,
-  context: FormContext
+  context: FormContext,
+  model: FormModel
 ) {
-  const relevantFields = context.relevantPages.flatMap(
-    (page) => page.collection.fields
-  )
+  // Get fields from relevant pages (normal components)
+  // plus PaymentField from all pages (payment page is skipped in the page walk)
+  const allFields = new Set([
+    ...context.relevantPages.flatMap((page) => page.collection.fields),
+    ...model.pages
+      .flatMap((page) => page.collection.fields)
+      .filter((field) => field instanceof PaymentField)
+  ])
 
-  for (const component of relevantFields) {
-    /*
-      Each component will throw InvalidComponent if its state is invalid, which is handled
-      by handleFormSubmit
-    */
+  for (const component of allFields) {
     await component.onSubmit(request, metadata, context)
   }
 }

package/src/server/plugins/engine/pageControllers/errors.ts

@@ -64,10 +64,10 @@ export class PaymentSubmissionError extends Error {
 
   static checkPaymentAmount(
     stateAmount: number,
-    definitionAmount: number | undefined,
+    expectedAmount: number | undefined,
     component: FormComponent
   ) {
-    if (stateAmount / 100 !== definitionAmount) {
+    if (stateAmount / 100 !== expectedAmount) {
       throw new PaymentPreAuthError(
         component,
         'The pre-authorised payment amount is somehow different from that requested. Try adding payment details again.',

package/src/server/plugins/engine/routes/index.ts

@@ -1,3 +1,4 @@
+import { isPaymentPage } from '@defra/forms-model'
 import Boom from '@hapi/boom'
 import {
   type ResponseObject,
@@ -102,8 +103,14 @@ export async function redirectOrMakeHandler(
     return proceed(request, h, resumeInRepeaterUrl)
   }
 
-  // Return handler for relevant pages or preview URL direct access
-  if (relevantPath.startsWith(page.path) || context.isForceAccess) {
+  // Return handler for relevant pages, payment pages, or preview URL direct access.
+  // Payment pages are skipped in the normal page walk but must render when the user
+  // is redirected there from CYA "Pay and submit".
+  if (
+    relevantPath.startsWith(page.path) ||
+    isPaymentPage(page.pageDef) ||
+    context.isForceAccess
+  ) {
     return makeHandler(page, context)
   }
 

package/src/server/plugins/engine/routes/payment.js

@@ -103,7 +103,13 @@ function logPaymentFailure(session, paymentStatus) {
 function handlePaymentSuccess(request, h, session, sessionKey, paymentStatus) {
   flashComponentState(request, session, paymentStatus)
   request.yar.clear(sessionKey)
-  return h.redirect(session.returnUrl).code(StatusCodes.SEE_OTHER)
+
+  // Append paymentComplete flag so the summary page auto-submits
+  // instead of showing CYA again
+  const separator = session.returnUrl.includes('?') ? '&' : '?'
+  const returnUrl = `${session.returnUrl}${separator}paymentComplete=true`
+
+  return h.redirect(returnUrl).code(StatusCodes.SEE_OTHER)
 }
 
 /**

package/src/server/plugins/engine/services/localFormsService.js

@@ -65,5 +65,12 @@ export const formsService = async () => {
     slug: 'payment-test'
   })
 
+  await loader.addForm('src/server/forms/payment-v2-test.yaml', {
+    ...metadata,
+    id: 'c3d4e5f6-a7b8-9012-cdef-012345678901',
+    title: 'Apply for a lock and weir fishing permit (v2 payment test)',
+    slug: 'payment-v2-test'
+  })
+
   return loader.toFormsService()
 }

package/src/server/plugins/engine/views/summary.html

@@ -73,9 +73,10 @@
 
         <div class="govuk-button-group">
           {% set isDeclaration = declaration or components | length %}
+          {% set paymentPending = paymentRequired and not paymentState %}
 
           {{ govukButton({
-            text: "Accept and submit" if isDeclaration else "Submit",
+            text: "Pay and submit" if paymentPending else ("Accept and submit" if isDeclaration else "Submit"),
             name: "action",
             value: "send",
             preventDoubleClick: true

package/src/server/plugins/payment/service.js

@@ -41,6 +41,7 @@ export class PaymentService {
    * @param {string} reference
    * @param {boolean} isLivePayment
    * @param {{ formId: string, slug: string } | undefined } metadata
+   * @param {string} [email] - optional email to prepopulate on GOV.UK Pay
    */
   async createPayment(
     amount,
@@ -48,17 +49,26 @@ export class PaymentService {
     returnUrl,
     reference,
     isLivePayment,
-    metadata
+    metadata,
+    email
   ) {
     try {
-      const response = await this.postToPayProvider({
+      /** @type {CreatePaymentRequest} */
+      const payload = {
         amount,
         description,
         reference,
         metadata,
         return_url: returnUrl,
         delayed_capture: true
-      })
+      }
+
+      // Prepopulate email on GOV.UK Pay if provided
+      if (email) {
+        payload.email = email
+      }
+
+      const response = await this.postToPayProvider(payload)
 
       logger.info(
         buildPaymentInfo(

package/src/server/plugins/payment/types.js

@@ -20,6 +20,7 @@
  * @property {string} return_url - URL to redirect the user to after payment
  * @property {boolean} [delayed_capture] - Whether to delay capturing the payment
  * @property {{ formId: string, slug: string }} [metadata] - Additional metadata for the payment
+ * @property {string} [email] - Email to prepopulate on GOV.UK Pay (max 254 chars)
  */
 
 /**