@defra/forms-engine-plugin 4.0.43 → 4.0.44

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

@@ -0,0 +1,151 @@
+import Boom from '@hapi/boom'
+import { StatusCodes } from 'http-status-codes'
+import Joi from 'joi'
+
+import { EXTERNAL_STATE_APPENDAGE } from '~/src/server/constants.js'
+import { getPaymentContext } from '~/src/server/plugins/engine/routes/payment-helper.js'
+
+export const PAYMENT_RETURN_PATH = '/payment-callback'
+export const PAYMENT_SESSION_PREFIX = 'payment-'
+
+/**
+ * Flash form component state after successful payment
+ * @param {Request} request - the request
+ * @param {PaymentSessionData} session - the session data containing payment state
+ * @param {GetPaymentResponse} paymentStatus - the payment status response from GOV.UK Pay
+ */
+function flashComponentState(request, session, paymentStatus) {
+  /** @type {PaymentState} */
+  const paymentState = {
+    paymentId: paymentStatus.paymentId,
+    reference: session.reference,
+    amount: session.amount,
+    description: session.description,
+    uuid: session.uuid,
+    formId: session.formId,
+    isLivePayment: session.isLivePayment,
+    payerEmail: paymentStatus.email,
+    preAuth: {
+      status: 'success',
+      createdAt: new Date().toISOString()
+    }
+  }
+
+  /** @type {ExternalStateAppendage} */
+  const appendage = {
+    component: session.componentName,
+    data: /** @type {FormState} */ (/** @type {unknown} */ (paymentState))
+  }
+
+  request.yar.flash(EXTERNAL_STATE_APPENDAGE, appendage, true)
+}
+
+/**
+ * Gets the payment routes for handling GOV.UK Pay callbacks
+ * @returns {ServerRoute[]}
+ */
+export function getRoutes() {
+  return [getReturnRoute()]
+}
+
+/**
+ * Handles successful payment states (capturable/success)
+ * @param {Request} request - the request
+ * @param {ResponseToolkit} h - the response toolkit
+ * @param {PaymentSessionData} session - the session data
+ * @param {string} sessionKey - the session key
+ * @param {GetPaymentResponse} paymentStatus - the payment status from GOV.UK Pay
+ */
+function handlePaymentSuccess(request, h, session, sessionKey, paymentStatus) {
+  flashComponentState(request, session, paymentStatus)
+  request.yar.clear(sessionKey)
+  return h.redirect(session.returnUrl).code(StatusCodes.SEE_OTHER)
+}
+
+/**
+ * Handles failed/cancelled/error payment states
+ * @param {Request} request - the request
+ * @param {ResponseToolkit} h - the response toolkit
+ * @param {PaymentSessionData} session - the session data
+ * @param {string} sessionKey - the session key
+ */
+function handlePaymentFailure(request, h, session, sessionKey) {
+  request.yar.clear(sessionKey)
+  return h.redirect(session.failureUrl).code(StatusCodes.SEE_OTHER)
+}
+
+/**
+ * Route handler for payment return URL
+ * This is called when GOV.UK Pay redirects the user back after payment
+ * @returns {ServerRoute}
+ */
+function getReturnRoute() {
+  return {
+    method: 'GET',
+    path: PAYMENT_RETURN_PATH,
+    async handler(request, h) {
+      const { uuid } = /** @type {{ uuid: string }} */ (request.query)
+      const { session, sessionKey, paymentStatus } = await getPaymentContext(
+        request,
+        uuid
+      )
+
+      /**
+       * @see https://docs.payments.service.gov.uk/api_reference/#payment-status-lifecycle
+       */
+      const { status } = paymentStatus.state
+
+      switch (status) {
+        case 'capturable':
+        case 'success':
+          return handlePaymentSuccess(
+            request,
+            h,
+            session,
+            sessionKey,
+            paymentStatus
+          )
+
+        case 'cancelled':
+        case 'failed':
+        case 'error':
+          return handlePaymentFailure(request, h, session, sessionKey)
+
+        case 'created':
+        case 'started':
+        case 'submitted': {
+          const nextUrl = paymentStatus._links.next_url?.href
+
+          if (!nextUrl) {
+            throw Boom.badRequest(
+              `Payment in state '${status}' but no next_url available`
+            )
+          }
+
+          return h.redirect(nextUrl).code(StatusCodes.SEE_OTHER)
+        }
+
+        default: {
+          const unknownStatus = /** @type {string} */ (status)
+          throw Boom.internal(`Unknown payment status: ${unknownStatus}`)
+        }
+      }
+    },
+    options: {
+      validate: {
+        query: Joi.object()
+          .keys({
+            uuid: Joi.string().uuid().required()
+          })
+          .required()
+      }
+    }
+  }
+}
+
+/**
+ * @import { Request, ResponseToolkit, ServerRoute } from '@hapi/hapi'
+ * @import { GetPaymentResponse, PaymentSessionData } from '~/src/server/plugins/payment/types.js'
+ * @import { PaymentState } from '~/src/server/plugins/engine/components/PaymentField.types.js'
+ * @import { ExternalStateAppendage, FormState } from '~/src/server/plugins/engine/types.js'
+ */

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

@@ -0,0 +1,180 @@
+import { StatusCodes } from 'http-status-codes'
+
+import { createServer } from '~/src/server/index.js'
+import { getPaymentContext } from '~/src/server/plugins/engine/routes/payment-helper.js'
+import { renderResponse } from '~/test/helpers/component-helpers.js'
+
+jest.mock('~/src/server/plugins/engine/routes/payment-helper.js')
+
+describe('Payment routes', () => {
+  /** @type {Server} */
+  let server
+
+  beforeAll(async () => {
+    server = await createServer()
+    await server.initialize()
+  })
+
+  beforeEach(() => {
+    jest.resetAllMocks()
+  })
+
+  describe('Return route /payment-callback', () => {
+    const uuid = '06a5b11e-e3e0-48a2-8ac3-56c0fcb6c20d'
+    const options = {
+      method: 'get',
+      url: `/payment-callback?uuid=${uuid}`
+    }
+
+    const paymentSessionData = {
+      uuid,
+      formId: 'form-id',
+      reference: 'form-ref-123',
+      paymentId: 'payment-id',
+      amount: 123,
+      description: 'Payment desc',
+      isLivePayment: false,
+      componentName: 'my-component',
+      returnUrl: 'http://host.com/return-url',
+      failureUrl: 'http://host.com/failure-url'
+    }
+    const sessionKey = 'session-key'
+
+    test.each([
+      { status: 'capturable', finalUrl: 'http://host.com/return-url' },
+      { status: 'success', finalUrl: 'http://host.com/return-url' },
+      { status: 'cancelled', finalUrl: 'http://host.com/failure-url' },
+      { status: 'failed', finalUrl: 'http://host.com/failure-url' },
+      { status: 'error', finalUrl: 'http://host.com/failure-url' },
+      { status: 'created', finalUrl: '/next-url' },
+      { status: 'started', finalUrl: '/next-url' },
+      { status: 'submitted', finalUrl: '/next-url' }
+    ])('should handle payment status of $row.status', async (row) => {
+      const paymentStatus = {
+        paymentId: 'new-payment-id',
+        amount: 125,
+        _links: {
+          next_url: {
+            href: '/next-url',
+            method: 'get'
+          },
+          self: {
+            href: '/self',
+            method: 'get'
+          }
+        },
+        state: /** @type {PaymentResponseState} */ ({
+          status: row.status,
+          finished: true
+        })
+      }
+      jest.mocked(getPaymentContext).mockResolvedValueOnce({
+        session: paymentSessionData,
+        sessionKey,
+        paymentStatus
+      })
+      const { response } = await renderResponse(server, options)
+
+      expect(response.statusCode).toBe(StatusCodes.SEE_OTHER)
+      expect(response.headers.location).toBe(row.finalUrl)
+    })
+
+    it('should throw if nextUrl is missing', async () => {
+      const paymentStatus = {
+        paymentId: 'new-payment-id',
+        _links: {
+          next_url: {},
+          self: {
+            href: '/self',
+            method: 'get'
+          }
+        },
+        state: /** @type {PaymentResponseState} */ ({
+          status: 'created',
+          finished: true
+        })
+      }
+      jest.mocked(getPaymentContext).mockResolvedValueOnce({
+        session: paymentSessionData,
+        sessionKey,
+        // @ts-expect-error - deliberate missing element from object
+        paymentStatus
+      })
+      const { response } = await renderResponse(server, options)
+
+      expect(response.statusCode).toBe(StatusCodes.BAD_REQUEST)
+      // @ts-expect-error - error object
+      expect(response.result?.message).toBe(
+        "Payment in state 'created' but no next_url available"
+      )
+    })
+
+    it('should throw if invalid status', async () => {
+      const paymentStatus = {
+        paymentId: 'new-payment-id',
+        _links: {
+          next_url: {
+            href: '/next-url',
+            method: 'get'
+          },
+          self: {
+            href: '/self',
+            method: 'get'
+          }
+        },
+        state: {
+          status: 'invalid',
+          finished: true
+        }
+      }
+      jest.mocked(getPaymentContext).mockResolvedValueOnce({
+        session: paymentSessionData,
+        sessionKey,
+        // @ts-expect-error - deliberate invalid value which doesnt meet type
+        paymentStatus
+      })
+      const { response } = await renderResponse(server, options)
+
+      expect(response.statusCode).toBe(StatusCodes.INTERNAL_SERVER_ERROR)
+      // @ts-expect-error - error object
+      expect(response.result?.message).toBe('Unknown payment status: invalid')
+    })
+
+    it('should handle payment with email from GOV.UK Pay response', async () => {
+      const paymentStatus = {
+        paymentId: 'new-payment-id',
+        payment_id: 'new-payment-id',
+        amount: 125,
+        email: 'payer@example.com',
+        _links: {
+          next_url: {
+            href: '/next-url',
+            method: 'get'
+          },
+          self: {
+            href: '/self',
+            method: 'get'
+          }
+        },
+        state: /** @type {PaymentResponseState} */ ({
+          status: 'success',
+          finished: true
+        })
+      }
+      jest.mocked(getPaymentContext).mockResolvedValueOnce({
+        session: paymentSessionData,
+        sessionKey,
+        paymentStatus
+      })
+      const { response } = await renderResponse(server, options)
+
+      expect(response.statusCode).toBe(StatusCodes.SEE_OTHER)
+      expect(response.headers.location).toBe('http://host.com/return-url')
+    })
+  })
+})
+
+/**
+ * @import { Server } from '@hapi/hapi'
+ * @import { PaymentResponseState } from '~/src/server/plugins/payment/types.js'
+ */

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

@@ -58,5 +58,12 @@ export const formsService = async () => {
     slug: 'simple-form'
   })
 
+  await loader.addForm('src/server/forms/payment-test.yaml', {
+    ...metadata,
+    id: 'b2c3d4e5-f6a7-8901-bcde-f01234567890',
+    title: 'Payment Test Form',
+    slug: 'payment-test'
+  })
+
   return loader.toFormsService()
 }

package/src/server/plugins/engine/types/schema.ts

@@ -43,6 +43,15 @@ export const formAdapterSubmissionMessageDataSchema =
   Joi.object<FormAdapterSubmissionMessageData>().keys({
     main: Joi.object(),
     repeaters: Joi.object(),
+    payment: Joi.object()
+      .keys({
+        paymentId: Joi.string().required(),
+        reference: Joi.string().required(),
+        amount: Joi.number().required(),
+        description: Joi.string().required(),
+        createdAt: Joi.string().required()
+      })
+      .optional(),
     files: Joi.object().pattern(
       Joi.string(),
       Joi.array().items(

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

@@ -17,7 +17,10 @@ import { type JoiExpression, type ValidationErrorItem } from 'joi'
 import { FormComponent } from '~/src/server/plugins/engine/components/FormComponent.js'
 import { type UkAddressState } from '~/src/server/plugins/engine/components/UkAddressField.js'
 import { type Component } from '~/src/server/plugins/engine/components/helpers/components.js'
-import { type FileUploadField } from '~/src/server/plugins/engine/components/index.js'
+import {
+  type FileUploadField,
+  type PaymentField
+} from '~/src/server/plugins/engine/components/index.js'
 import {
   type BackLink,
   type ComponentText,
@@ -329,6 +332,8 @@ export interface FormPageViewModel extends PageViewModelBase {
   errors?: FormSubmissionError[]
   hasMissingNotificationEmail?: boolean
   allowSaveAndExit: boolean
+  showSubmitButton?: boolean
+  showPaymentExpiredNotification?: boolean
 }
 
 export interface RepeaterSummaryPageViewModel extends PageViewModelBase {
@@ -393,6 +398,8 @@ export interface ExternalArgs {
   controller: QuestionPageController
   sourceUrl: string
   actionArgs: Record<string, string>
+  isLive: boolean
+  isPreview: boolean
 }
 
 export interface PostcodeLookupExternalArgs extends ExternalArgs {
@@ -454,6 +461,14 @@ export interface FormAdapterFile {
   userDownloadLink: string
 }
 
+export interface FormAdapterPayment {
+  paymentId: string
+  reference: string
+  amount: number
+  description: string
+  createdAt: string
+}
+
 export interface FormAdapterSubmissionMessageResult {
   files: {
     main: string
@@ -467,6 +482,13 @@ export interface FormAdapterSubmissionMessageResult {
 export type FileUploadFieldDetailitem = Omit<DetailItemField, 'field'> & {
   field: FileUploadField
 }
+
+/**
+ * A detail item specifically for payments
+ */
+export type PaymentFieldDetailItem = Omit<DetailItemField, 'field'> & {
+  field: PaymentField
+}
 export type RichFormValue =
   | FormValue
   | FormPayload
@@ -480,6 +502,7 @@ export interface FormAdapterSubmissionMessageData {
   main: Record<string, RichFormValue | null>
   repeaters: Record<string, Record<string, RichFormValue>[]>
   files: Record<string, FormAdapterFile[]>
+  payment?: FormAdapterPayment
 }
 
 export interface FormAdapterSubmissionMessagePayload {

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

@@ -20,7 +20,7 @@ export interface ExternalComponent {
     request: FormRequestPayload,
     h: FormResponseToolkit,
     args: ExternalArgs
-  ): ResponseObject
+  ): Promise<ResponseObject>
 }
 
 /**

package/src/server/plugins/engine/views/components/paymentfield.html

@@ -0,0 +1,42 @@
+{% from "govuk/components/warning-text/macro.njk" import govukWarningText %}
+{% from "govuk/components/button/macro.njk" import govukButton %}
+
+{% macro PaymentField(component) %}
+  {% set model = component.model %}
+  {% set amount = model.amount %}
+  {% set description = model.description %}
+  {% set paymentState = model.paymentState %}
+  {% set isPreAuthorised = paymentState and paymentState.preAuth and paymentState.preAuth.status == 'success' %}
+
+  <div class="app-payment-field">
+    {% if isPreAuthorised %}
+      {# Payment already pre-authorised - show confirmation message #}
+      <h2 class="govuk-heading-m">You have already authorised a payment for this form</h2>
+
+      <p class="govuk-body">Continue to submit the form. You will not be charged twice.</p>
+    {% else %}
+      {# No pre-authorisation - show payment form #}
+      <h2 class="govuk-heading-m">{{ model.label.text if model.label and model.label.text else "Payment details required" }}</h2>
+
+      <p class="govuk-body">{{ description }}</p>
+
+      {{ govukWarningText({
+        text: "You may see a pending transaction in your bank account but you will only be charged when you submit the form.",
+        iconFallbackText: "Warning"
+      }) }}
+
+      <p class="govuk-body">You can submit the form after you have added your payment details.</p>
+
+      <p class="govuk-body govuk-!-margin-bottom-1">Total amount:</p>
+      <p class="govuk-heading-l govuk-!-margin-bottom-4 govuk-!-padding-top-0">£{{ amount }}</p>
+
+      {{ govukButton({
+        text: "Add payment details",
+        attributes: {
+          name: "action",
+          value: "external-" + model.name
+        }
+      }) }}
+    {% endif %}
+  </div>
+{% endmacro %}

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

@@ -1,6 +1,7 @@
 {% extends baseLayoutPath %}
 
 {% from "govuk/components/error-summary/macro.njk" import govukErrorSummary %}
+{% from "govuk/components/notification-banner/macro.njk" import govukNotificationBanner %}
 {% from "partials/components.html" import componentList with context %}
 
 {% block content %}
@@ -10,7 +11,14 @@
         {% include "partials/preview-banner.html" %}
       {% endif %}
 
-      {% if errors | length  %}
+      {% if showPaymentExpiredNotification %}
+        {{ govukNotificationBanner({
+          titleText: "Important",
+          html: '<h3 class="govuk-notification-banner__heading">Your payment has been cancelled</h3><p class="govuk-body">Your payment details were deleted because the form was inactive for 5 days.</p><p class="govuk-body">Add your payment details again.</p>'
+        }) }}
+      {% endif %}
+
+      {% if errors | length and not showPaymentExpiredNotification %}
         {{ govukErrorSummary({
           titleText: "There is a problem",
           errorList: checkErrorTemplates(errors)

package/src/server/plugins/engine/views/partials/form.html

@@ -1,6 +1,19 @@
 {% from "govuk/components/button/macro.njk" import govukButton %}
 {% from "govuk/components/summary-list/macro.njk" import govukSummaryList -%}
 
+{% set noPaymentFields = true %}
+{% set hasIncompletePayment = false %}
+
+{% for comp in components %}
+  {% if comp.type == 'PaymentField' %}
+    {% set noPaymentFields = false %}
+    {# Check if payment is incomplete (no preAuth status) #}
+    {% if not comp.model.paymentState or not comp.model.paymentState.preAuth or comp.model.paymentState.preAuth.status != 'success' %}
+      {% set hasIncompletePayment = true %}
+    {% endif %}
+  {% endif %}
+{% endfor %}
+
 <form method="post" novalidate>
   <input type="hidden" name="crumb" value="{{ crumb }}">
 
@@ -15,11 +28,13 @@
   {% endif %}
 
   <div class="govuk-button-group">
-    {{ govukButton({
-      text: buttonText,
-      isStartButton: isStartPage,
-      preventDoubleClick: true
-    }) }}
+    {% if showSubmitButton !== false and not hasIncompletePayment %}
+      {{ govukButton({
+        text: buttonText,
+        isStartButton: isStartPage,
+        preventDoubleClick: true
+      }) }}
+    {% endif %}
 
     {% if allowSaveAndExit %}
       {{ govukButton({

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

@@ -3,6 +3,7 @@
 {% from "govuk/components/error-summary/macro.njk" import govukErrorSummary %}
 {% from "govuk/components/summary-list/macro.njk" import govukSummaryList %}
 {% from "govuk/components/button/macro.njk" import govukButton %}
+{% from "govuk/components/notification-banner/macro.njk" import govukNotificationBanner %}
 {% from "partials/components.html" import componentList with context %}
 {% from "govuk/components/input/macro.njk" import govukInput %}
 
@@ -13,6 +14,14 @@
         {% include "partials/preview-banner.html" %}
       {% endif %}
 
+      {% if paymentState and paymentState.preAuth and paymentState.preAuth.status == 'success' %}
+        {{ govukNotificationBanner({
+          type: "success",
+          titleText: "Success",
+          html: "<h3 class=\"govuk-notification-banner__heading\">We have your payment details</h3><p class=\"govuk-body\">Your payment is on hold. We will charge you when you submit the form.</p>"
+        }) }}
+      {% endif %}
+
       {% if errors %}
         {{ govukErrorSummary({
           titleText: "There is a problem",
@@ -41,6 +50,13 @@
         {% endif %}
       {% endfor %}
 
+      {% if paymentDetails %}
+        <h2 class="govuk-heading-m">
+          {{ paymentDetails.title.text }}
+        </h2>
+        {{ govukSummaryList(paymentDetails.summaryList) }}
+      {% endif %}
+
       <form method="post" novalidate>
         <input type="hidden" name="crumb" value="{{ crumb }}">
 
@@ -59,7 +75,7 @@
           {% set isDeclaration = declaration or components | length %}
 
           {{ govukButton({
-            text: "Accept and send" if isDeclaration else "Send",
+            text: "Accept and submit" if isDeclaration else "Submit",
             name: "action",
             value: "send",
             preventDoubleClick: true

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

@@ -0,0 +1,56 @@
+import { format } from 'date-fns'
+
+import { PaymentService } from '~/src/server/plugins/payment/service.js'
+
+export const DEFAULT_PAYMENT_HELP_URL =
+  'https://www.gov.uk/government/organisations/department-for-environment-food-rural-affairs'
+
+/**
+ * Determine which payment API key value to use.
+ * If a draft preview form or a live preview form, read the TEST API key value specific to that form.
+ * If a live (non-preview) form, read the LIVE API key value specific to that form.
+ * @param {boolean} isLivePayment - true if this is a live payment (as opposed to a test one)
+ * @param {string} formId - id of the form
+ * @returns {string}
+ */
+export function getPaymentApiKey(isLivePayment, formId) {
+  const apiKeyValue = isLivePayment
+    ? process.env[`PAYMENT_PROVIDER_API_KEY_LIVE_${formId}`]
+    : process.env[`PAYMENT_PROVIDER_API_KEY_TEST_${formId}`]
+
+  if (!apiKeyValue) {
+    throw new Error(
+      `Missing payment api key for ${isLivePayment ? 'live' : 'test'} form id ${formId}`
+    )
+  }
+  return apiKeyValue
+}
+
+/**
+ * Creates a PaymentService instance with the appropriate API key
+ * @param {boolean} isLivePayment - true if this is a live payment
+ * @param {string} formId - id of the form
+ * @returns {PaymentService}
+ */
+export function createPaymentService(isLivePayment, formId) {
+  const apiKey = getPaymentApiKey(isLivePayment, formId)
+  return new PaymentService(apiKey)
+}
+
+/**
+ * Formats a payment date for display
+ * @param {string} isoString - ISO date string
+ * @returns {string} Formatted date string (e.g., "26 January 2026 5:01pm")
+ */
+export function formatPaymentDate(isoString) {
+  return format(new Date(isoString), 'd MMMM yyyy h:mmaaa')
+}
+
+/**
+ * Formats a payment amount with two decimal places
+ * @param {number} amount - amount in pounds
+ * @returns {string} Formatted amount (e.g., "£10.00")
+ */
+export function formatPaymentAmount(amount) {
+  return `£${amount.toFixed(2)}`
+}