WIP: progress commit

Author: mokhld

src/config/index.ts

@@ -268,6 +268,14 @@ export const config = convict({
     nullable: true,
     default: undefined,
     env: 'PAYMENT_PROVIDER_API_KEY_TEST'
+  } as SchemaObj<string | undefined>,
+
+  paymentProviderApiKeyLive: {
+    doc: 'A live API key for integrating with a payment provider',
+    format: String,
+    nullable: true,
+    default: undefined,
+    env: 'PAYMENT_PROVIDER_API_KEY_LIVE'
   } as SchemaObj<string | undefined>
 })
 

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

@@ -10,6 +10,7 @@ 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 { InvalidComponentStateError } from '~/src/server/plugins/engine/pageControllers/errors.js'
 import {
   type AnyFormRequest,
   type FormContext,
@@ -47,6 +48,7 @@ export class PaymentField extends FormComponent {
         amount: joi.number().required(),
         description: joi.string().required(),
         uuid: joi.string().uuid().required(),
+        isLive: joi.boolean().required(),
         preAuth: joi
           .object({
             status: joi
@@ -155,7 +157,8 @@ export class PaymentField extends FormComponent {
     h: FormResponseToolkit,
     args: PaymentDispatcherArgs
   ): Promise<unknown> {
-    const paymentService = new PaymentService()
+    const { isLive } = args
+    const paymentService = new PaymentService({ isLive })
 
     // 1. Generate UUID token
     const uuid = randomUUID()
@@ -173,18 +176,19 @@ export class PaymentField extends FormComponent {
 
     // 2. Build the return URL for GOV.UK Pay
     const { baseUrl } = getPluginOptions(request.server)
-    const returnUrl = `${baseUrl}/payment-callback?uuid=${uuid}`
+    const payCallbackUrl = `${baseUrl}/payment-callback?uuid=${uuid}`
 
-    // Build the summary URL to redirect to after payment
+    // Build URLs for redirect after payment
     const summaryUrl = `${baseUrl}/${model.basePath}/summary`
+    const paymentPageUrl = args.sourceUrl
 
     // 3. Call paymentService.createPayment()
     // GOV.UK Pay expects amount in pence, so multiply pounds by 100
     const amountInPence = Math.round(amount * 100)
     const payment = await paymentService.createPayment(
       amountInPence,
       description,
-      returnUrl,
+      payCallbackUrl,
       reference,
       { formId, slug }
     )
@@ -197,7 +201,9 @@ export class PaymentField extends FormComponent {
       description,
       paymentId: payment.paymentId,
       componentName,
-      sourceUrl: summaryUrl
+      returnUrl: summaryUrl,
+      failureUrl: paymentPageUrl,
+      isLive
     }
 
     request.yar.set(`payment-${uuid}`, sessionData)
@@ -208,21 +214,86 @@ export class PaymentField extends FormComponent {
 
   /**
    * Called on form submission to capture the payment
-   * STUB - Jez to implement
+   * @see https://docs.payments.service.gov.uk/delayed_capture/#delay-taking-a-payment
    */
-  onSubmit(
-    _request: FormRequestPayload,
+  async onSubmit(
+    request: FormRequestPayload,
     _metadata: FormMetadata,
-    _context: FormContext
+    context: FormContext
   ): Promise<void> {
-    // TODO: Implement
-    // 1. Get payment state from context
-    // 2. If already captured, skip
-    // 3. Call paymentService.getPaymentStatus() to validate pre-auth
-    // 4. Call paymentService.capturePayment()
-    // 5. Update payment state with capture status
-    // 6. If capture fails, throw InvalidComponentStateError
-    return Promise.resolve()
+    const paymentState = this.getPaymentStateFromState(context.state)
+
+    if (!paymentState) {
+      // No payment state - redirect to payment page to complete payment
+      throw new InvalidComponentStateError(
+        this,
+        'Complete the payment to continue',
+        { shouldResetState: true }
+      )
+    }
+
+    // Skip if already captured
+    if (paymentState.capture?.status === 'success') {
+      return
+    }
+
+    const { paymentId, isLive } = paymentState
+    const paymentService = new PaymentService({ isLive })
+
+    // Verify payment is still in capturable state
+    const status = await paymentService.getPaymentStatus(paymentId)
+
+    // If already captured (success state), mark as captured and continue
+    if (status.state.status === 'success') {
+      await this.markPaymentCaptured(request, paymentState)
+      return
+    }
+
+    if (status.state.status !== 'capturable') {
+      throw new InvalidComponentStateError(
+        this,
+        'Your payment authorisation has expired. Please add your payment details again.',
+        { shouldResetState: true }
+      )
+    }
+
+    // Capture the payment
+    const captured = await paymentService.capturePayment(paymentId)
+
+    if (!captured) {
+      throw new InvalidComponentStateError(
+        this,
+        'There was a problem and your form was not submitted. Try submitting the form again.',
+        { shouldResetState: 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()
+      }
+    }
+
+    // Update the state in the page controller
+    if (this.page) {
+      const currentState = await this.page.getState(request)
+      await this.page.mergeState(request, currentState, {
+        [this.name]: updatedState
+      })
+    }
   }
 }
 
@@ -237,7 +308,7 @@ export interface PaymentDispatcherArgs {
   }
   component: PaymentField
   sourceUrl: string
-  paymentService: PaymentService
+  isLive: boolean
 }
 
 /**
@@ -250,5 +321,7 @@ export interface PaymentSessionData {
   description: string
   paymentId: string
   componentName: string
-  sourceUrl: string
+  returnUrl: string
+  failureUrl: string
+  isLive: boolean
 }

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

@@ -7,6 +7,7 @@ export interface PaymentState {
   amount: number
   description: string
   uuid: string
+  isLive: boolean
   capture?: {
     status: 'success' | 'failed'
     createdAt: string

src/server/plugins/engine/outputFormatters/machine/v2.ts

@@ -1,7 +1,10 @@
 import { type SubmitResponsePayload } from '@defra/forms-model'
 
 import { config } from '~/src/config/index.js'
-import { FileUploadField } from '~/src/server/plugins/engine/components/index.js'
+import {
+  FileUploadField,
+  PaymentField
+} from '~/src/server/plugins/engine/components/index.js'
 import { type checkFormStatus } from '~/src/server/plugins/engine/helpers.js'
 import { type FormModel } from '~/src/server/plugins/engine/models/index.js'
 import {
@@ -12,7 +15,9 @@ import {
 import {
   type FileUploadFieldDetailitem,
   type FormAdapterFile,
+  type FormAdapterPayment,
   type FormContext,
+  type PaymentFieldDetailItem,
   type RichFormValue
 } from '~/src/server/plugins/engine/types.js'
 
@@ -71,6 +76,14 @@ export function format(
  *          userDownloadLink: 'https://forms-designer/file-download/123-456-789'
  *        }
  *      ]
+ *    },
+ *    payments: {
+ *      paymentComponentName: {
+ *        paymentId: 'abc123',
+ *        reference: 'REF-123',
+ *        amount: 10.00,
+ *        description: 'Application fee'
+ *      }
  *    }
  * }
  */
@@ -82,7 +95,16 @@ export function categoriseData(items: DetailItem[]) {
       string,
       { fileId: string; fileName: string; userDownloadLink: string }[]
     >
-  } = { main: {}, repeaters: {}, files: {} }
+    payments: Record<
+      string,
+      {
+        paymentId: string
+        reference: string
+        amount: number
+        description: string
+      }
+    >
+  } = { main: {}, repeaters: {}, files: {}, payments: {} }
 
   items.forEach((item) => {
     const { name, state } = item
@@ -91,6 +113,11 @@ export function categoriseData(items: DetailItem[]) {
       output.repeaters[name] = extractRepeaters(item)
     } else if (isFileUploadFieldItem(item)) {
       output.files[name] = extractFileUploads(item)
+    } else if (isPaymentFieldItem(item)) {
+      const payment = extractPayment(item)
+      if (payment) {
+        output.payments[name] = payment
+      }
     } else {
       output.main[name] = item.field.getFormValueFromState(state)
     }
@@ -148,3 +175,31 @@ function isFileUploadFieldItem(
 ): item is FileUploadFieldDetailitem {
   return item.field instanceof FileUploadField
 }
+
+function isPaymentFieldItem(
+  item: DetailItemField
+): item is PaymentFieldDetailItem {
+  return item.field instanceof PaymentField
+}
+
+/**
+ * Returns the "payments" section of the response body
+ * @param item - the payment item in the form
+ * @returns the payment data
+ */
+function extractPayment(
+  item: PaymentFieldDetailItem
+): FormAdapterPayment | undefined {
+  const paymentState = item.field.getPaymentStateFromState(item.state)
+
+  if (!paymentState) {
+    return undefined
+  }
+
+  return {
+    paymentId: paymentState.paymentId,
+    reference: paymentState.reference,
+    amount: paymentState.amount,
+    description: paymentState.description
+  }
+}

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

@@ -21,6 +21,7 @@ import { ComponentCollection } from '~/src/server/plugins/engine/components/Comp
 import { optionalText } from '~/src/server/plugins/engine/components/constants.js'
 import { type BackLink } from '~/src/server/plugins/engine/components/types.js'
 import {
+  checkFormStatus,
   getCacheService,
   getErrors,
   getSaveAndExitHelpers,
@@ -47,6 +48,7 @@ import {
 import { getComponentsByType } from '~/src/server/plugins/engine/validationHelpers.js'
 import {
   FormAction,
+  FormStatus,
   type FormRequest,
   type FormRequestPayload,
   type FormRequestPayloadRefs,
@@ -616,11 +618,16 @@ export class QuestionPageController extends PageController {
     // Clear any previous state appendage
     request.yar.clear(EXTERNAL_STATE_APPENDAGE)
 
+    // Determine if this is a live form (not preview/draft)
+    const { state } = checkFormStatus(request.params)
+    const isLive = state === FormStatus.Live
+
     return await selectedComponent.dispatcher(request, h, {
       component,
       controller: this,
       sourceUrl: request.url.toString(),
-      actionArgs: args
+      actionArgs: args,
+      isLive
     })
   }