@defra/forms-engine-plugin 4.0.42 → 4.0.44

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

@@ -0,0 +1,367 @@
+import { randomUUID } from 'node:crypto'
+
+import {
+  type FormMetadata,
+  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 {
+  PaymentErrorTypes,
+  PaymentPreAuthError,
+  PaymentSubmissionError
+} from '~/src/server/plugins/engine/pageControllers/errors.js'
+import {
+  type AnyFormRequest,
+  type FormContext,
+  type FormRequestPayload,
+  type FormResponseToolkit
+} from '~/src/server/plugins/engine/types/index.js'
+import {
+  type ErrorMessageTemplateList,
+  type FormPayload,
+  type FormState,
+  type FormStateValue,
+  type FormSubmissionError,
+  type FormSubmissionState
+} from '~/src/server/plugins/engine/types.js'
+import { createPaymentService } from '~/src/server/plugins/payment/helper.js'
+
+export class PaymentField extends FormComponent {
+  declare options: PaymentFieldComponent['options']
+  declare formSchema: ObjectSchema
+  declare stateSchema: ObjectSchema
+  isAppendageStateSingleObject = true
+
+  constructor(
+    def: PaymentFieldComponent,
+    props: ConstructorParameters<typeof FormComponent>[1]
+  ) {
+    super(def, props)
+
+    this.options = def.options
+
+    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(),
+        formId: joi.string().required(),
+        isLivePayment: joi.boolean().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
+    // 'required()' forces the payment page to be invalid until we have valid payment state
+    // i.e. the user will automatically be directed back to the payment page
+    // if they attempt to access future pages when no payment entered yet
+    this.stateSchema = paymentStateSchema.required()
+  }
+
+  /**
+   * Gets the PaymentState from form submission state
+   */
+  getPaymentStateFromState(
+    state: FormSubmissionState
+  ): PaymentState | undefined {
+    const value = state[this.name]
+    return this.isPaymentState(value) ? value : undefined
+  }
+
+  getDisplayStringFromState(state: FormSubmissionState): string {
+    const value = this.getPaymentStateFromState(state)
+
+    if (!value) {
+      return ''
+    }
+
+    return `£${value.amount.toFixed(2)} - ${value.description}`
+  }
+
+  getViewModel(payload: FormPayload, errors?: FormSubmissionError[]) {
+    const viewModel = super.getViewModel(payload, errors)
+
+    // Payload is pre-populated from state if a payment has already been made
+    const paymentState = this.isPaymentState(payload[this.name] as unknown)
+      ? (payload[this.name] as unknown as PaymentState)
+      : undefined
+
+    // When user initially visits the payment page, there is no payment state yet so the amount is read form the form definition.
+    const amount = paymentState?.amount ?? this.options.amount
+
+    const formattedAmount = amount.toFixed(2)
+
+    return {
+      ...viewModel,
+      amount: formattedAmount,
+      description: this.options.description,
+      paymentState
+    }
+  }
+
+  /**
+   * Type guard to check if value is PaymentState
+   */
+  isPaymentState(value: unknown): value is PaymentState {
+    return PaymentField.isPaymentState(value)
+  }
+
+  /**
+   * Static type guard to check if value is PaymentState
+   */
+  static isPaymentState(value: unknown): value is PaymentState {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+      return false
+    }
+
+    const state = value as PaymentState
+    return (
+      typeof state.paymentId === 'string' &&
+      typeof state.amount === 'number' &&
+      typeof state.description === 'string'
+    )
+  }
+
+  /**
+   * Override base isState to validate PaymentState
+   */
+  isState(value?: FormStateValue | FormState): value is FormState {
+    return this.isPaymentState(value)
+  }
+
+  getFormValue(value?: FormStateValue | FormState) {
+    return this.isPaymentState(value)
+      ? (value as unknown as NonNullable<FormStateValue>)
+      : undefined
+  }
+
+  getContextValueFromState(state: FormSubmissionState) {
+    return this.isPaymentState(state)
+      ? `Reference: ${state.reference}\nAmount: ${state.amount.toFixed(2)}`
+      : ''
+  }
+
+  /**
+   * For error preview page that shows all possible errors on a component
+   */
+  getAllPossibleErrors(): ErrorMessageTemplateList {
+    return PaymentField.getAllPossibleErrors()
+  }
+
+  /**
+   * Static version of getAllPossibleErrors that doesn't require a component instance.
+   */
+  static getAllPossibleErrors(): ErrorMessageTemplateList {
+    return {
+      baseErrors: [
+        {
+          type: 'paymentRequired',
+          template: 'Complete the payment to continue'
+        }
+      ],
+      advancedSettingsErrors: []
+    }
+  }
+
+  /**
+   * Dispatcher for external redirect to GOV.UK Pay
+   */
+  static async dispatcher(
+    request: FormRequestPayload,
+    h: FormResponseToolkit,
+    args: PaymentDispatcherArgs
+  ): Promise<unknown> {
+    const { options, name: componentName } = args.component
+    const { model } = args.controller
+
+    const state = await args.controller.getState(request)
+    const { baseUrl } = getPluginOptions(request.server)
+    const summaryUrl = `${baseUrl}/${model.basePath}/summary`
+
+    const existingPaymentState = state[componentName]
+    if (
+      PaymentField.isPaymentState(existingPaymentState) &&
+      existingPaymentState.preAuth?.status === 'success'
+    ) {
+      return h.redirect(summaryUrl).code(StatusCodes.SEE_OTHER)
+    }
+
+    const isLivePayment = args.isLive && !args.isPreview
+    const formId = args.controller.model.formId
+    const paymentService = createPaymentService(isLivePayment, formId)
+
+    const uuid = randomUUID()
+
+    const reference = state.$$__referenceNumber as string
+    const amount = options.amount
+
+    const description = options.description
+
+    const slug = `/${model.basePath}`
+
+    const payCallbackUrl = `${baseUrl}/payment-callback?uuid=${uuid}`
+    const paymentPageUrl = args.sourceUrl
+
+    const amountInPence = Math.round(amount * 100)
+    const payment = await paymentService.createPayment(
+      amountInPence,
+      description,
+      payCallbackUrl,
+      reference,
+      { formId, slug }
+    )
+
+    const sessionData: PaymentSessionData = {
+      uuid,
+      formId,
+      reference,
+      amount,
+      description,
+      paymentId: payment.paymentId,
+      componentName,
+      returnUrl: summaryUrl,
+      failureUrl: paymentPageUrl,
+      isLivePayment
+    }
+
+    request.yar.set(`payment-${uuid}`, sessionData)
+
+    return h.redirect(payment.paymentUrl).code(StatusCodes.SEE_OTHER)
+  }
+
+  /**
+   * Called on form submission to capture the payment
+   * @see https://docs.payments.service.gov.uk/delayed_capture/#delay-taking-a-payment
+   */
+  async onSubmit(
+    request: FormRequestPayload,
+    _metadata: FormMetadata,
+    context: FormContext
+  ): Promise<void> {
+    const paymentState = this.getPaymentStateFromState(context.state)
+
+    if (!paymentState) {
+      throw new PaymentPreAuthError(
+        this,
+        'Complete the payment to continue',
+        true,
+        PaymentErrorTypes.PaymentIncomplete
+      )
+    }
+
+    if (paymentState.capture?.status === 'success') {
+      return
+    }
+
+    const { paymentId, isLivePayment, formId } = paymentState
+    const paymentService = createPaymentService(isLivePayment, formId)
+
+    /**
+     * @see https://docs.payments.service.gov.uk/api_reference/#payment-status-lifecycle
+     */
+    const status = await paymentService.getPaymentStatus(paymentId)
+
+    PaymentSubmissionError.checkPaymentAmount(
+      status.amount,
+      this.options.amount,
+      this
+    )
+
+    if (status.state.status === 'success') {
+      await this.markPaymentCaptured(request, paymentState)
+      return
+    }
+
+    if (status.state.status !== 'capturable') {
+      throw new PaymentPreAuthError(
+        this,
+        'Your payment authorisation has expired. Please add your payment details again.',
+        true,
+        PaymentErrorTypes.PaymentExpired
+      )
+    }
+
+    const captured = await paymentService.capturePayment(paymentId)
+
+    if (!captured) {
+      throw new PaymentPreAuthError(
+        this,
+        'There was a problem and your form was not submitted. Try submitting the form again.',
+        false
+      )
+    }
+
+    await this.markPaymentCaptured(request, paymentState)
+  }
+
+  /**
+   * Updates payment state to mark capture as successful
+   * This ensures we don't try to re-capture on submission retry
+   */
+  private async markPaymentCaptured(
+    request: FormRequestPayload,
+    paymentState: PaymentState
+  ): Promise<void> {
+    const updatedState: PaymentState = {
+      ...paymentState,
+      capture: {
+        status: 'success',
+        createdAt: new Date().toISOString()
+      }
+    }
+
+    if (this.page) {
+      const currentState = await this.page.getState(request)
+      await this.page.mergeState(request, currentState, {
+        [this.name]: updatedState
+      })
+    }
+  }
+}
+
+export interface PaymentDispatcherArgs {
+  controller: {
+    model: {
+      formId: string
+      basePath: string
+      name: string
+    }
+    getState: (request: AnyFormRequest) => Promise<FormSubmissionState>
+  }
+  component: PaymentField
+  sourceUrl: string
+  isLive: boolean
+  isPreview: boolean
+}
+
+/**
+ * Session data stored when dispatching to GOV.UK Pay
+ */
+export interface PaymentSessionData {
+  uuid: string
+  formId: string
+  reference: string
+  amount: number
+  description: string
+  paymentId: string
+  componentName: string
+  returnUrl: string
+  failureUrl: string
+  isLivePayment: boolean
+}

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

@@ -0,0 +1,21 @@
+/**
+ * Component state stored in session after pre-auth
+ */
+export interface PaymentState {
+  paymentId: string
+  reference: string
+  amount: number
+  description: string
+  uuid: string
+  formId: string
+  isLivePayment: boolean
+  payerEmail?: string
+  capture?: {
+    status: 'success' | 'failed'
+    createdAt: string
+  }
+  preAuth?: {
+    status: 'success' | 'failed' | 'started'
+    createdAt: string
+  }
+}

package/src/server/plugins/engine/components/UkAddressField.ts

@@ -284,7 +284,8 @@ export class UkAddressField extends FormComponent {
     )
   }
 
-  static dispatcher(
+  // eslint-disable-next-line @typescript-eslint/require-await
+  static async dispatcher(
     request: FormRequestPayload,
     h: FormResponseToolkit,
     args: PostcodeLookupExternalArgs

package/src/server/plugins/engine/components/helpers/components.ts

@@ -35,6 +35,7 @@ export type Field = InstanceType<
   | typeof Components.UkAddressField
   | typeof Components.FileUploadField
   | typeof Components.HiddenField
+  | typeof Components.PaymentField
 >
 
 // Guidance component instances only
@@ -191,6 +192,10 @@ export function createComponent(
     case ComponentType.HiddenField:
       component = new Components.HiddenField(def, options)
       break
+
+    case ComponentType.PaymentField:
+      component = new Components.PaymentField(def, options)
+      break
   }
 
   if (typeof component === 'undefined') {

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

@@ -29,3 +29,4 @@ export { OsGridRefField } from '~/src/server/plugins/engine/components/OsGridRef
 export { NationalGridFieldNumberField } from '~/src/server/plugins/engine/components/NationalGridFieldNumberField.js'
 export { LatLongField } from '~/src/server/plugins/engine/components/LatLongField.js'
 export { HiddenField } from '~/src/server/plugins/engine/components/HiddenField.js'
+export { PaymentField } from '~/src/server/plugins/engine/components/PaymentField.js'

package/src/server/plugins/engine/configureEnginePlugin.ts

@@ -22,7 +22,8 @@ export const configureEnginePlugin = async (
     preparePageEventRequestOptions,
     onRequest,
     saveAndExit,
-    ordnanceSurveyApiKey
+    ordnanceSurveyApiKey,
+    ordnanceSurveyApiSecret
   }: RouteConfig = {},
   cache?: CacheService
 ): Promise<{
@@ -65,7 +66,8 @@ export const configureEnginePlugin = async (
       onRequest,
       baseUrl: 'http://localhost:3009', // always runs locally
       saveAndExit,
-      ordnanceSurveyApiKey
+      ordnanceSurveyApiKey,
+      ordnanceSurveyApiSecret
     }
   }
 }

package/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 }))
           }
         }

package/src/server/plugins/engine/options.js

@@ -26,7 +26,8 @@ const pluginRegistrationOptionsSchema = Joi.object({
   onRequest: Joi.function().optional(),
   baseUrl: Joi.string().uri().required(),
   saveAndExit: Joi.function().optional(),
-  ordnanceSurveyApiKey: Joi.string().optional()
+  ordnanceSurveyApiKey: Joi.string().optional(),
+  ordnanceSurveyApiSecret: Joi.string().optional()
 })
 
 /**

package/src/server/plugins/engine/outputFormatters/human/v1.payment.test.ts

@@ -0,0 +1,147 @@
+import { format as dateFormat } from 'date-fns'
+import { outdent } from 'outdent'
+
+import { type PaymentState } from '~/src/server/plugins/engine/components/PaymentField.types.js'
+import { FormModel } from '~/src/server/plugins/engine/models/index.js'
+import { format } from '~/src/server/plugins/engine/outputFormatters/human/v1.js'
+import {
+  SummaryPageController,
+  getFormSubmissionData
+} from '~/src/server/plugins/engine/pageControllers/SummaryPageController.js'
+import { buildFormContextRequest } from '~/src/server/plugins/engine/pageControllers/__stubs__/request.js'
+import { type FormSubmissionState } from '~/src/server/plugins/engine/types.js'
+import { FormStatus } from '~/src/server/routes/types.js'
+import definitionPayment from '~/test/form/definitions/payment.js'
+
+describe('v1 human formatter', () => {
+  describe('Payment', () => {
+    const modelPayment = new FormModel(definitionPayment, {
+      basePath: 'test'
+    })
+
+    const submitResponse = {
+      message: 'Submit completed',
+      result: {
+        files: {
+          main: '00000000-0000-0000-0000-000000000000',
+          repeaters: {
+            pizza: '11111111-1111-1111-1111-111111111111'
+          }
+        }
+      }
+    }
+
+    const statePayment = {
+      $$__referenceNumber: 'foobar',
+      licenceLength: 365,
+      fullName: 'John Smith',
+      paymentField: {
+        paymentId: 'payment-id',
+        reference: 'payment-ref',
+        amount: 250,
+        description: 'Payment desc',
+        uuid: 'uuid',
+        formId: 'form-id',
+        isLivePayment: false,
+        preAuth: {
+          status: 'success',
+          createdAt: '2026-01-02T11:02:04+0000'
+        }
+      } as PaymentState
+    }
+
+    const pageUrl = new URL('http://example.com/repeat/pizza-order/summary')
+
+    const requestPayment = buildFormContextRequest({
+      method: 'get',
+      url: pageUrl,
+      path: pageUrl.pathname,
+      params: {
+        path: 'summary',
+        slug: 'payment'
+      },
+      query: {},
+      app: { model: modelPayment }
+    })
+
+    const pageDefPayment = definitionPayment.pages[2]
+
+    const controllerPayment = new SummaryPageController(
+      modelPayment,
+      pageDefPayment
+    )
+
+    const contextPayment = modelPayment.getFormContext(
+      requestPayment,
+      statePayment as unknown as FormSubmissionState
+    )
+    const summaryViewModelPayment = controllerPayment.getSummaryViewModel(
+      requestPayment,
+      contextPayment
+    )
+
+    const itemsPayment = getFormSubmissionData(
+      summaryViewModelPayment.context,
+      summaryViewModelPayment.details
+    )
+
+    it('should add payment details', () => {
+      const body = format(
+        contextPayment,
+        itemsPayment,
+        modelPayment,
+        submitResponse,
+        {
+          state: FormStatus.Draft,
+          isPreview: true
+        }
+      )
+
+      const dateNow = new Date()
+
+      expect(body).toContain(
+        outdent`
+              ${definitionPayment.name} form received at ${dateFormat(dateNow, 'h:mmaaa')} on ${dateFormat(dateNow, 'd MMMM yyyy')}.
+
+              ---
+
+              ## Which fishing licence do you want to get?
+
+              12 months \\(365\\)
+
+              ---
+
+              ## What\\'s your name?
+
+              John Smith
+
+              ---
+
+              [Download main form \\(CSV\\)](https://forms-designer/file-download/00000000-0000-0000-0000-000000000000)
+
+              ---
+
+              # Your payment of £250.00 was successful
+
+              ## Payment for
+
+              Payment desc
+
+              ---
+
+              ## Total amount
+
+              £250.00
+
+              ---
+
+              ## Date of payment
+
+              2 January 2026 11:02am
+
+              ---
+            `
+      )
+    })
+  })
+})