@defra/forms-engine-plugin 4.0.43 → 4.0.44

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

@@ -0,0 +1,52 @@
+import { config } from '~/src/config/index.js'
+import {
+  formatPaymentAmount,
+  formatPaymentDate,
+  getPaymentApiKey
+} from '~/src/server/plugins/payment/helper.js'
+
+describe('getPaymentApiKey', () => {
+  config.set('paymentProviderApiKeyTest', 'TEST-API-KEY')
+  const formId = 'form-id'
+  process.env['PAYMENT_PROVIDER_API_KEY_LIVE_form-id'] = 'LIVE-API-KEY'
+  process.env['PAYMENT_PROVIDER_API_KEY_TEST_form-id'] = 'TEST-API-KEY'
+
+  it('should read test key when non-live form', () => {
+    const apiKey = getPaymentApiKey(false, formId)
+    expect(apiKey).toBe('TEST-API-KEY')
+  })
+
+  it('should read live key when live form', () => {
+    const apiKey = getPaymentApiKey(true, formId)
+    expect(apiKey).toBe('LIVE-API-KEY')
+  })
+
+  it('should throw if TEST key is missing', () => {
+    expect(() => getPaymentApiKey(false, 'form-id-missing')).toThrow(
+      'Missing payment api key for test form id form-id-missing'
+    )
+  })
+
+  it('should throw if LIVE key is missing', () => {
+    expect(() => getPaymentApiKey(true, 'form-id-missing')).toThrow(
+      'Missing payment api key for live form id form-id-missing'
+    )
+  })
+})
+
+describe('formatPaymentDate', () => {
+  it('should format ISO date string to en-GB format', () => {
+    const result = formatPaymentDate('2025-11-10T17:01:29.000Z')
+    expect(result).toBe('10 November 2025 5:01pm')
+  })
+})
+
+describe('formatPaymentAmount', () => {
+  it('should format whole number with two decimal places', () => {
+    expect(formatPaymentAmount(10)).toBe('£10.00')
+  })
+
+  it('should format decimal amount', () => {
+    expect(formatPaymentAmount(99.5)).toBe('£99.50')
+  })
+})

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

@@ -0,0 +1,171 @@
+import { StatusCodes } from 'http-status-codes'
+
+import { createLogger } from '~/src/server/common/helpers/logging/logger.js'
+import { get, post, postJson } from '~/src/server/services/httpService.js'
+
+const PAYMENT_BASE_URL = 'https://publicapi.payments.service.gov.uk'
+const PAYMENT_ENDPOINT = '/v1/payments'
+
+const logger = createLogger()
+
+/**
+ * @param {string} apiKey
+ * @returns {{ Authorization: string }}
+ */
+function getAuthHeaders(apiKey) {
+  return {
+    Authorization: `Bearer ${apiKey}`
+  }
+}
+
+export class PaymentService {
+  /** @type {string} */
+  #apiKey
+
+  /**
+   * @param {string} apiKey - API key to use (global config for test value, per-form config for live value)
+   */
+  constructor(apiKey) {
+    this.#apiKey = apiKey
+  }
+
+  /**
+   * Creates a payment with delayed capture (pre-authorisation)
+   * @param {number} amount - in pence
+   * @param {string} description
+   * @param {string} returnUrl
+   * @param {string} reference
+   * @param {{ formId: string, slug: string }} metadata
+   */
+  async createPayment(amount, description, returnUrl, reference, metadata) {
+    const response = await this.postToPayProvider({
+      amount,
+      description,
+      reference,
+      metadata,
+      return_url: returnUrl,
+      delayed_capture: true
+    })
+
+    return {
+      paymentId: response.payment_id,
+      paymentUrl: response._links.next_url.href
+    }
+  }
+
+  /**
+   * @param {string} paymentId
+   * @returns {Promise<GetPaymentResponse>}
+   */
+  async getPaymentStatus(paymentId) {
+    const getByType = /** @type {typeof get<GetPaymentApiResponse>} */ (get)
+
+    try {
+      const response = await getByType(
+        `${PAYMENT_BASE_URL}${PAYMENT_ENDPOINT}/${paymentId}`,
+        {
+          headers: getAuthHeaders(this.#apiKey),
+          json: true
+        }
+      )
+
+      if (response.error) {
+        const errorMessage =
+          response.error instanceof Error
+            ? response.error.message
+            : JSON.stringify(response.error)
+        throw new Error(`Failed to get payment status: ${errorMessage}`)
+      }
+
+      return {
+        state: response.payload.state,
+        _links: response.payload._links,
+        email: response.payload.email,
+        paymentId: response.payload.payment_id,
+        amount: response.payload.amount
+      }
+    } catch (err) {
+      const error = /** @type {Error} */ (err)
+      logger.error(
+        error,
+        `[payment] Error getting payment status for paymentId=${paymentId}: ${error.message}`
+      )
+      throw err
+    }
+  }
+
+  /**
+   * Captures a payment that is in 'capturable' status
+   * @param {string} paymentId
+   * @returns {Promise<boolean>}
+   */
+  async capturePayment(paymentId) {
+    try {
+      const response = await post(
+        `${PAYMENT_BASE_URL}${PAYMENT_ENDPOINT}/${paymentId}/capture`,
+        {
+          headers: getAuthHeaders(this.#apiKey)
+        }
+      )
+
+      const statusCode = response.res.statusCode
+
+      if (
+        statusCode === StatusCodes.OK ||
+        statusCode === StatusCodes.NO_CONTENT
+      ) {
+        logger.info(`[payment] Successfully captured payment ${paymentId}`)
+        return true
+      }
+
+      logger.error(
+        `[payment] Capture failed for paymentId=${paymentId}: HTTP ${statusCode}`
+      )
+      return false
+    } catch (err) {
+      const error = /** @type {Error} */ (err)
+      logger.error(
+        error,
+        `[payment] Error capturing payment for paymentId=${paymentId}: ${error.message}`
+      )
+      throw err
+    }
+  }
+
+  /**
+   * @param {CreatePaymentRequest} payload
+   */
+  async postToPayProvider(payload) {
+    const postJsonByType =
+      /** @type {typeof postJson<CreatePaymentResponse>} */ (postJson)
+
+    try {
+      const response = await postJsonByType(
+        `${PAYMENT_BASE_URL}${PAYMENT_ENDPOINT}`,
+        {
+          payload,
+          headers: getAuthHeaders(this.#apiKey)
+        }
+      )
+
+      if (response.payload?.state.status !== 'created') {
+        throw new Error(
+          `Failed to create payment for reference=${payload.reference}`
+        )
+      }
+
+      return response.payload
+    } catch (err) {
+      const error = /** @type {Error} */ (err)
+      logger.error(
+        error,
+        `[payment] Error creating payment for reference=${payload.reference}: ${error.message}`
+      )
+      throw err
+    }
+  }
+}
+
+/**
+ * @import { CreatePaymentRequest, CreatePaymentResponse, GetPaymentApiResponse, GetPaymentResponse } from '~/src/server/plugins/payment/types.js'
+ */

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

@@ -0,0 +1,205 @@
+import { PaymentService } from '~/src/server/plugins/payment/service.js'
+import { get, post, postJson } from '~/src/server/services/httpService.js'
+
+jest.mock('~/src/server/services/httpService.ts')
+
+describe('payment service', () => {
+  const service = new PaymentService('my-api-key')
+  describe('constructor', () => {
+    it('should create instance', () => {
+      expect(service).toBeDefined()
+    })
+  })
+
+  describe('createPayment', () => {
+    it('should create a payment', async () => {
+      const createPaymentResult = {
+        payment_id: 'payment-id-12345',
+        _links: {
+          next_url: {
+            href: 'http://next-url-href/payment'
+          }
+        },
+        state: {
+          status: 'created'
+        }
+      }
+      jest.mocked(postJson).mockResolvedValueOnce({
+        res: /** @type {IncomingMessage} */ ({
+          statusCode: 200,
+          headers: {}
+        }),
+        payload: createPaymentResult,
+        error: undefined
+      })
+
+      const referenceNumber = 'ABC-DEF-123'
+      const returnUrl = 'http://localhost:3009/payment-callback-handler'
+      const metadata = { formId: 'form-id', slug: 'my-form-slug' }
+      const payment = await service.createPayment(
+        100,
+        'Payment description',
+        returnUrl,
+        referenceNumber,
+        metadata
+      )
+      expect(payment.paymentId).toBe('payment-id-12345')
+      expect(payment.paymentUrl).toBe('http://next-url-href/payment')
+    })
+
+    it('should throw if fails to create a payment - failed API call', async () => {
+      jest
+        .mocked(postJson)
+        .mockRejectedValueOnce(new Error('internal creation error'))
+
+      const referenceNumber = 'ABC-DEF-123'
+      const returnUrl = 'http://localhost:3009/payment-callback-handler'
+      const metadata = { formId: 'form-id', slug: 'my-form-slug' }
+      await expect(() =>
+        service.createPayment(
+          100,
+          'Payment description',
+          returnUrl,
+          referenceNumber,
+          metadata
+        )
+      ).rejects.toThrow('internal creation error')
+    })
+
+    it('should throw if fails to create a payment - bad result from API call', async () => {
+      const createPaymentResult = {
+        state: {
+          status: 'failed'
+        }
+      }
+      jest.mocked(postJson).mockResolvedValueOnce({
+        res: /** @type {IncomingMessage} */ ({
+          statusCode: 200,
+          headers: {}
+        }),
+        payload: createPaymentResult,
+        error: undefined
+      })
+
+      const referenceNumber = 'ABC-DEF-123'
+      const returnUrl = 'http://localhost:3009/payment-callback-handler'
+      const metadata = { formId: 'form-id', slug: 'my-form-slug' }
+      await expect(() =>
+        service.createPayment(
+          100,
+          'Payment description',
+          returnUrl,
+          referenceNumber,
+          metadata
+        )
+      ).rejects.toThrow('Failed to create payment')
+    })
+  })
+
+  describe('getPaymentStatus', () => {
+    it('should get payment status if exists', async () => {
+      const getPaymentStatusResult = {
+        payment_id: 'payment-id-12345',
+        _links: {
+          next_url: {
+            href: 'http://next-url-href/payment'
+          }
+        },
+        state: {
+          status: 'created'
+        }
+      }
+
+      jest.mocked(get).mockResolvedValueOnce({
+        res: /** @type {IncomingMessage} */ ({
+          statusCode: 200,
+          headers: {}
+        }),
+        payload: getPaymentStatusResult,
+        error: undefined
+      })
+
+      const paymentStatus = await service.getPaymentStatus('payment-id-12345')
+      expect(paymentStatus.paymentId).toBe('payment-id-12345')
+      expect(paymentStatus._links.next_url?.href).toBe(
+        'http://next-url-href/payment'
+      )
+    })
+
+    it('should handle payment status error', async () => {
+      jest.mocked(get).mockResolvedValueOnce({
+        res: /** @type {IncomingMessage} */ ({
+          statusCode: 200,
+          headers: {}
+        }),
+        payload: undefined,
+        error: new Error('some-error')
+      })
+
+      await expect(() =>
+        service.getPaymentStatus('payment-id-12345')
+      ).rejects.toThrow('Failed to get payment status: some-error')
+    })
+  })
+
+  describe('capturePayment', () => {
+    it('should return true when successful capture with statusCode 200', async () => {
+      const capturePaymentResult = {}
+      jest.mocked(post).mockResolvedValueOnce({
+        res: /** @type {IncomingMessage} */ ({
+          statusCode: 200,
+          headers: {}
+        }),
+        payload: capturePaymentResult,
+        error: undefined
+      })
+
+      const captureResult = await service.capturePayment('payment-id-12345')
+      expect(captureResult).toBe(true)
+    })
+
+    it('should return true when successful capture with statusCode 204', async () => {
+      const capturePaymentResult = {}
+      jest.mocked(post).mockResolvedValueOnce({
+        res: /** @type {IncomingMessage} */ ({
+          statusCode: 204,
+          headers: {}
+        }),
+        payload: capturePaymentResult,
+        error: undefined
+      })
+
+      const captureResult = await service.capturePayment('payment-id-12345')
+      expect(captureResult).toBe(true)
+    })
+
+    it('should return false when status code not 200 or 204', async () => {
+      const capturePaymentResult = {}
+      jest.mocked(post).mockResolvedValueOnce({
+        res: /** @type {IncomingMessage} */ ({
+          statusCode: 500,
+          headers: {}
+        }),
+        payload: capturePaymentResult,
+        error: undefined
+      })
+
+      const captureResult = await service.capturePayment('payment-id-12345')
+      expect(captureResult).toBe(false)
+    })
+
+    it('should throw when internal error', async () => {
+      jest
+        .mocked(post)
+        .mockRejectedValueOnce(new Error('internal capture error'))
+
+      await expect(() =>
+        service.capturePayment('payment-id-12345')
+      ).rejects.toThrow('internal capture error')
+    })
+  })
+})
+
+/**
+ * @import  { IncomingMessage } from 'node:http'
+ */

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

@@ -0,0 +1,77 @@
+/**
+ * @typedef {object} PaymentResponseState
+ * @property {'created' | 'started' | 'submitted' | 'capturable' | 'success' | 'failed' | 'cancelled' | 'error'} status - Current status of the payment
+ * @property {boolean} finished - Whether the payment process has completed
+ * @property {string} [message] - Human-readable message about the payment state
+ * @property {string} [code] - Error or status code for the payment state
+ */
+
+/**
+ * @typedef {object} PaymentLink
+ * @property {string} href - URL of the linked resource
+ * @property {string} method - HTTP method to use for the link
+ */
+
+/**
+ * @typedef {object} CreatePaymentRequest
+ * @property {number} amount - Payment amount in pence
+ * @property {string} reference - Unique reference for the payment
+ * @property {string} description - Human-readable description of the payment
+ * @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
+ */
+
+/**
+ * @typedef {object} CreatePaymentResponse
+ * @property {string} payment_id - Unique identifier for the created payment
+ * @property {PaymentResponseState} state - Current state of the payment
+ * @property {{ next_url: PaymentLink }} _links - HATEOAS links for the payment
+ */
+
+/**
+ * Base response from GOV.UK Pay GET /v1/payments/{PAYMENT_ID} endpoint
+ * @typedef {object} GetPaymentResponseBase
+ * @property {PaymentResponseState} state - Current state of the payment
+ * @property {{ self: PaymentLink, next_url?: PaymentLink }} _links - HATEOAS links for the payment
+ * @property {string} [email] - The paying user's email address
+ */
+
+/**
+ * Response from GOV.UK Pay GET /v1/payments/{PAYMENT_ID} endpoint - not underscore in property name
+ * @typedef {object} GetPaymentApiResponsePaymentProp
+ * @property {string} payment_id - Unique identifier for the payment
+ * @property {number} amount - amount of the payment
+ */
+
+/**
+ * Response from GOV.UK Pay GET /v1/payments/{PAYMENT_ID} endpoint
+ * @typedef {GetPaymentResponseBase & GetPaymentApiResponsePaymentProp} GetPaymentApiResponse
+ */
+
+/**
+ * Response returned from getPaymentStatus - subtley different from GetPaymentApiResponse
+ * @typedef {object} GetPaymentResponsePaymentProp
+ * @property {string} paymentId - Unique identifier for the payment - note no underscore in property name
+ * @property {number} amount - amount of the payment
+ */
+
+/**
+ * Response returned from getPaymentStatus - subtley different from GetPaymentApiResponse
+ * @typedef {GetPaymentResponseBase & GetPaymentResponsePaymentProp} GetPaymentResponse
+ */
+
+/**
+ * Payment session data stored when dispatching to GOV.UK Pay
+ * @typedef {object} PaymentSessionData
+ * @property {string} uuid - unique identifier for this payment attempt
+ * @property {string} formId - id of the form
+ * @property {string} reference - form reference number
+ * @property {number} amount - amount in pounds
+ * @property {string} description - payment description
+ * @property {string} paymentId - GOV.UK Pay payment ID
+ * @property {string} componentName - name of the PaymentField component
+ * @property {string} returnUrl - URL to redirect to after successful payment
+ * @property {string} failureUrl - URL to redirect to after failed/cancelled payment
+ * @property {boolean} isLivePayment - whether the payment is using live API key
+ */

package/src/server/types.ts

@@ -15,6 +15,7 @@ import {
   type PluginOptions,
   type PreparePageEventRequestOptions
 } from '~/src/server/plugins/engine/types.js'
+import { type PaymentService } from '~/src/server/plugins/payment/service.js'
 import {
   type FormRequestPayload,
   type FormStatus
@@ -42,6 +43,7 @@ export interface Services {
   formsService: FormsService
   formSubmissionService: FormSubmissionService
   outputService: OutputService
+  paymentService?: PaymentService
 }
 
 export interface RouteConfig {

package/src/typings/hapi/index.d.ts

@@ -40,6 +40,7 @@ declare module '@hapi/hapi' {
         request: AnyFormRequest | null
       ) => Record<string, unknown> | Promise<Record<string, unknown>>
       saveAndExit?: PluginOptions['saveAndExit']
+      baseUrl: string
     }
   }