@open-mercato/checkout 0.6.4-develop.4371.1.8f3030407e → 0.6.4

package/src/modules/checkout/commands/__tests__/optimistic-lock.test.ts

@@ -0,0 +1,261 @@
+/** @jest-environment node */
+
+import { commandRegistry } from '@open-mercato/shared/lib/commands/registry'
+import type { CommandRuntimeContext } from '@open-mercato/shared/lib/commands/types'
+import { OPTIMISTIC_LOCK_HEADER_NAME } from '@open-mercato/shared/lib/crud/optimistic-lock-headers'
+
+const ORG_ID = '123e4567-e89b-12d3-a456-426614174000'
+const TENANT_ID = '123e4567-e89b-12d3-a456-426614174001'
+const LINK_ID = '123e4567-e89b-12d3-a456-426614174010'
+const TEMPLATE_ID = '123e4567-e89b-12d3-a456-426614174020'
+const CURRENT_VERSION = '2026-06-01T10:00:00.000Z'
+const STALE_VERSION = '2026-06-01T09:00:00.000Z'
+
+const FLUSH_SENTINEL = 'FLUSH_REACHED_AFTER_LOCK'
+
+const mockFindOneWithDecryption = jest.fn()
+
+jest.mock('@open-mercato/shared/lib/encryption/find', () => ({
+  findOneWithDecryption: jest.fn((...args: unknown[]) => mockFindOneWithDecryption(...args)),
+}))
+
+jest.mock('../../lib/gatewayProviderAvailability', () => ({
+  ensureGatewayProviderConfigured: jest.fn(async () => undefined),
+  getGatewayProviderConfigurationMessageKey: jest.fn(() => null),
+}))
+
+jest.mock('@open-mercato/shared/lib/commands/helpers', () => ({
+  setCustomFieldsIfAny: jest.fn(async () => undefined),
+}))
+
+jest.mock('@open-mercato/shared/lib/commands/customFieldSnapshots', () => ({
+  loadCustomFieldSnapshot: jest.fn(async () => ({})),
+  buildCustomFieldResetMap: jest.fn(() => ({})),
+}))
+
+jest.mock('@open-mercato/shared/lib/crud/custom-fields', () => ({
+  loadCustomFieldValues: jest.fn(async () => ({})),
+}))
+
+jest.mock('../../events', () => ({
+  emitCheckoutEvent: jest.fn(async () => undefined),
+}))
+
+// Importing the command modules registers the handlers via registerCommand.
+import '../links'
+import '../templates'
+
+// flush runs immediately AFTER the lock guard in both update commands. Throwing
+// a recognizable sentinel here lets the match / no-header cases prove the lock
+// guard PASSED, without mocking the full post-flush path (custom fields, events).
+const mockEm = {
+  flush: jest.fn(async () => {
+    throw new Error(FLUSH_SENTINEL)
+  }),
+  // delete commands count active transactions before flushing; 0 lets the
+  // happy path reach the flush sentinel so we can prove the lock guard passed.
+  count: jest.fn(async () => 0),
+}
+
+const mockDataEngine = {}
+
+function makeContext(headerVersion: string | null): CommandRuntimeContext {
+  const headers = new Headers()
+  if (headerVersion) headers.set(OPTIMISTIC_LOCK_HEADER_NAME, headerVersion)
+  const request = new Request('http://localhost/api/checkout/links/x', { method: 'PUT', headers })
+  return {
+    container: {
+      resolve: (token: string) => {
+        if (token === 'em') return mockEm
+        if (token === 'dataEngine') return mockDataEngine
+        if (token === 'paymentGatewayDescriptorService') return {}
+        return null
+      },
+    } as unknown as CommandRuntimeContext['container'],
+    auth: { orgId: ORG_ID, tenantId: TENANT_ID } as CommandRuntimeContext['auth'],
+    organizationScope: null,
+    selectedOrganizationId: ORG_ID,
+    organizationIds: [ORG_ID],
+    request,
+  }
+}
+
+function linkRecord() {
+  return {
+    id: LINK_ID,
+    organizationId: ORG_ID,
+    tenantId: TENANT_ID,
+    name: 'Pay link',
+    title: null,
+    slug: 'pay-link',
+    templateId: null,
+    status: 'draft',
+    isLocked: false,
+    pricingMode: 'fixed',
+    gatewayProviderKey: null,
+    gatewaySettings: {},
+    fixedPriceAmount: null,
+    fixedPriceOriginalAmount: null,
+    customAmountMin: null,
+    customAmountMax: null,
+    passwordHash: null,
+    updatedAt: new Date(CURRENT_VERSION),
+  }
+}
+
+function templateRecord() {
+  return {
+    id: TEMPLATE_ID,
+    organizationId: ORG_ID,
+    tenantId: TENANT_ID,
+    name: 'Template',
+    title: null,
+    status: 'draft',
+    pricingMode: 'fixed',
+    gatewayProviderKey: null,
+    gatewaySettings: {},
+    fixedPriceAmount: null,
+    fixedPriceOriginalAmount: null,
+    customAmountMin: null,
+    customAmountMax: null,
+    passwordHash: null,
+    updatedAt: new Date(CURRENT_VERSION),
+  }
+}
+
+async function runUpdate(commandId: string, input: Record<string, unknown>, headerVersion: string | null) {
+  const handler = commandRegistry.get(commandId)
+  if (!handler) throw new Error(`Command ${commandId} not registered`)
+  return handler.execute(input, makeContext(headerVersion))
+}
+
+describe('checkout command optimistic locking', () => {
+  beforeEach(() => {
+    jest.clearAllMocks()
+    delete process.env.OM_OPTIMISTIC_LOCK
+  })
+
+  describe('checkout.link.update', () => {
+    beforeEach(() => {
+      mockFindOneWithDecryption.mockResolvedValue(linkRecord())
+    })
+
+    it('rejects a stale expected version with a structured 409 conflict', async () => {
+      expect.assertions(4)
+      try {
+        await runUpdate('checkout.link.update', { id: LINK_ID, status: 'draft' }, STALE_VERSION)
+      } catch (error) {
+        const httpError = error as { status?: number; body?: Record<string, unknown> }
+        expect(httpError.status).toBe(409)
+        expect(httpError.body?.code).toBe('optimistic_lock_conflict')
+        expect(httpError.body?.currentUpdatedAt).toBe(CURRENT_VERSION)
+        expect(mockEm.flush).not.toHaveBeenCalled()
+      }
+    })
+
+    it('passes the lock guard when the expected version matches', async () => {
+      await expect(
+        runUpdate('checkout.link.update', { id: LINK_ID, status: 'draft' }, CURRENT_VERSION),
+      ).rejects.toThrow(FLUSH_SENTINEL)
+    })
+
+    it('passes the lock guard when no expected-version header is sent (strictly additive)', async () => {
+      await expect(
+        runUpdate('checkout.link.update', { id: LINK_ID, status: 'draft' }, null),
+      ).rejects.toThrow(FLUSH_SENTINEL)
+    })
+  })
+
+  describe('checkout.template.update', () => {
+    beforeEach(() => {
+      mockFindOneWithDecryption.mockResolvedValue(templateRecord())
+    })
+
+    it('rejects a stale expected version with a structured 409 conflict', async () => {
+      expect.assertions(3)
+      try {
+        await runUpdate('checkout.template.update', { id: TEMPLATE_ID, status: 'draft' }, STALE_VERSION)
+      } catch (error) {
+        const httpError = error as { status?: number; body?: Record<string, unknown> }
+        expect(httpError.status).toBe(409)
+        expect(httpError.body?.code).toBe('optimistic_lock_conflict')
+        expect(mockEm.flush).not.toHaveBeenCalled()
+      }
+    })
+
+    it('passes the lock guard when the expected version matches', async () => {
+      await expect(
+        runUpdate('checkout.template.update', { id: TEMPLATE_ID, status: 'draft' }, CURRENT_VERSION),
+      ).rejects.toThrow(FLUSH_SENTINEL)
+    })
+
+    it('passes the lock guard when no expected-version header is sent', async () => {
+      await expect(
+        runUpdate('checkout.template.update', { id: TEMPLATE_ID, status: 'draft' }, null),
+      ).rejects.toThrow(FLUSH_SENTINEL)
+    })
+  })
+
+  // QA round-6 (#2055): a stale DELETE after a conflict still deleted the
+  // record because the delete commands did not enforce the lock. These guard
+  // that the header now produces a 409 on a stale delete.
+  describe('checkout.link.delete', () => {
+    beforeEach(() => {
+      mockFindOneWithDecryption.mockResolvedValue(linkRecord())
+    })
+
+    it('rejects a stale expected version with a structured 409 conflict', async () => {
+      expect.assertions(3)
+      try {
+        await runUpdate('checkout.link.delete', { id: LINK_ID }, STALE_VERSION)
+      } catch (error) {
+        const httpError = error as { status?: number; body?: Record<string, unknown> }
+        expect(httpError.status).toBe(409)
+        expect(httpError.body?.code).toBe('optimistic_lock_conflict')
+        expect(mockEm.flush).not.toHaveBeenCalled()
+      }
+    })
+
+    it('passes the lock guard when the expected version matches', async () => {
+      await expect(
+        runUpdate('checkout.link.delete', { id: LINK_ID }, CURRENT_VERSION),
+      ).rejects.toThrow(FLUSH_SENTINEL)
+    })
+
+    it('passes the lock guard when no expected-version header is sent (strictly additive)', async () => {
+      await expect(
+        runUpdate('checkout.link.delete', { id: LINK_ID }, null),
+      ).rejects.toThrow(FLUSH_SENTINEL)
+    })
+  })
+
+  describe('checkout.template.delete', () => {
+    beforeEach(() => {
+      mockFindOneWithDecryption.mockResolvedValue(templateRecord())
+    })
+
+    it('rejects a stale expected version with a structured 409 conflict', async () => {
+      expect.assertions(3)
+      try {
+        await runUpdate('checkout.template.delete', { id: TEMPLATE_ID }, STALE_VERSION)
+      } catch (error) {
+        const httpError = error as { status?: number; body?: Record<string, unknown> }
+        expect(httpError.status).toBe(409)
+        expect(httpError.body?.code).toBe('optimistic_lock_conflict')
+        expect(mockEm.flush).not.toHaveBeenCalled()
+      }
+    })
+
+    it('passes the lock guard when the expected version matches', async () => {
+      await expect(
+        runUpdate('checkout.template.delete', { id: TEMPLATE_ID }, CURRENT_VERSION),
+      ).rejects.toThrow(FLUSH_SENTINEL)
+    })
+
+    it('passes the lock guard when no expected-version header is sent', async () => {
+      await expect(
+        runUpdate('checkout.template.delete', { id: TEMPLATE_ID }, null),
+      ).rejects.toThrow(FLUSH_SENTINEL)
+    })
+  })
+})

package/src/modules/checkout/commands/__tests__/redo-coverage.test.ts

@@ -0,0 +1,21 @@
+import { commandRegistry } from '@open-mercato/shared/lib/commands/registry'
+import '../index'
+
+describe('checkout undoable create command redo coverage', () => {
+  it('requires every logged undoable *.create command to define redo', () => {
+    const missingRedo = commandRegistry
+      .list()
+      .sort()
+      .filter((id) => id.startsWith('checkout.') && id.endsWith('.create'))
+      .filter((id) => {
+        const handler = commandRegistry.get(id)
+        return Boolean(
+          handler?.isUndoable &&
+            typeof handler.buildLog === 'function' &&
+            typeof handler.redo !== 'function',
+        )
+      })
+
+    expect(missingRedo).toEqual([])
+  })
+})

package/src/modules/checkout/commands/links.ts

@@ -4,8 +4,10 @@ import type { CommandHandler } from '@open-mercato/shared/lib/commands'
 import { registerCommand } from '@open-mercato/shared/lib/commands'
 import { buildCustomFieldResetMap, loadCustomFieldSnapshot } from '@open-mercato/shared/lib/commands/customFieldSnapshots'
 import { setCustomFieldsIfAny } from '@open-mercato/shared/lib/commands/helpers'
+import { resolveRedoSnapshot } from '@open-mercato/shared/lib/commands/redo'
 import { loadCustomFieldValues } from '@open-mercato/shared/lib/crud/custom-fields'
 import { CrudHttpError } from '@open-mercato/shared/lib/crud/errors'
+import { enforceCommandOptimisticLock } from '@open-mercato/shared/lib/crud/optimistic-lock-command'
 import { findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'
 import { resolveTranslations } from '@open-mercato/shared/lib/i18n/server'
 import { CheckoutLink, CheckoutLinkTemplate, CheckoutTransaction } from '../data/entities'
@@ -199,6 +201,59 @@ const createLinkCommand: CommandHandler<Record<string, unknown>, { id: string; s
     link.deletedAt = new Date()
     await em.flush()
   },
+  redo: async ({ logEntry, ctx }) => {
+    const after = resolveRedoSnapshot<CheckoutLinkSnapshot>(logEntry)
+    if (!after) throw new CrudHttpError(400, { error: '[internal] redo snapshot unavailable for checkout link create' })
+    const em = ctx.container.resolve('em') as EntityManager
+    const dataEngine = ctx.container.resolve('dataEngine') as DataEngine
+    let link = await findOneWithDecryption(
+      em,
+      CheckoutLink,
+      { id: after.id },
+      {},
+      { tenantId: after.tenantId, organizationId: after.organizationId },
+    )
+    if (link) {
+      restoreLinkFromSnapshot(link, after)
+      link.deletedAt = null
+      link.slug = await resolveRestoredLinkSlug(em, after)
+    } else {
+      link = em.create(CheckoutLink, {
+        ...createLinkFromSnapshot(after),
+        slug: await resolveRestoredLinkSlug(em, after),
+      })
+      em.persist(link)
+    }
+    await em.flush()
+    const reset = buildCustomFieldResetMap(after.custom, undefined)
+    if (Object.keys(reset).length) {
+      await setCustomFieldsIfAny({
+        dataEngine,
+        entityId: CHECKOUT_ENTITY_IDS.link,
+        recordId: after.id,
+        tenantId: after.tenantId,
+        organizationId: after.organizationId,
+        values: reset,
+        notify: false,
+      })
+    }
+    await emitCheckoutEvent('checkout.link.created', {
+      id: link.id,
+      slug: link.slug,
+      status: link.status,
+      tenantId: after.tenantId,
+      organizationId: after.organizationId,
+    }).catch(() => undefined)
+    if (link.status === 'active') {
+      await emitCheckoutEvent('checkout.link.published', {
+        id: link.id,
+        slug: link.slug,
+        tenantId: after.tenantId,
+        organizationId: after.organizationId,
+      }).catch(() => undefined)
+    }
+    return { id: link.id, slug: link.slug }
+  },
 }
 
 const updateLinkCommand: CommandHandler<Record<string, unknown>, { ok: true; slug: string }> = {
@@ -234,6 +289,12 @@ const updateLinkCommand: CommandHandler<Record<string, unknown>, { ok: true; slu
       deletedAt: null,
     }, undefined, scope)
     if (!link) throw new CrudHttpError(404, { error: 'Link not found' })
+    enforceCommandOptimisticLock({
+      resourceKind: 'checkout.link',
+      resourceId: link.id,
+      current: link.updatedAt ?? null,
+      request: ctx.request ?? null,
+    })
     if (link.isLocked) {
       throw new CrudHttpError(422, { error: 'This link has active transactions and cannot be edited' })
     }
@@ -380,6 +441,12 @@ const deleteLinkCommand: CommandHandler<Record<string, unknown>, { ok: true }> =
       deletedAt: null,
     }, undefined, scope)
     if (!link) throw new CrudHttpError(404, { error: 'Link not found' })
+    enforceCommandOptimisticLock({
+      resourceKind: 'checkout.link',
+      resourceId: link.id,
+      current: link.updatedAt ?? null,
+      request: ctx.request ?? null,
+    })
     const activeCount = await em.count(CheckoutTransaction, {
       linkId: link.id,
       organizationId: scope.organizationId,

package/src/modules/checkout/commands/templates.ts

@@ -4,7 +4,9 @@ import type { CommandHandler } from '@open-mercato/shared/lib/commands'
 import { registerCommand } from '@open-mercato/shared/lib/commands'
 import { buildCustomFieldResetMap, loadCustomFieldSnapshot } from '@open-mercato/shared/lib/commands/customFieldSnapshots'
 import { setCustomFieldsIfAny } from '@open-mercato/shared/lib/commands/helpers'
+import { resolveRedoSnapshot } from '@open-mercato/shared/lib/commands/redo'
 import { CrudHttpError } from '@open-mercato/shared/lib/crud/errors'
+import { enforceCommandOptimisticLock, enforceRecordGoneIsConflict } from '@open-mercato/shared/lib/crud/optimistic-lock-command'
 import { findOneWithDecryption, findWithDecryption } from '@open-mercato/shared/lib/encryption/find'
 import { resolveTranslations } from '@open-mercato/shared/lib/i18n/server'
 import { CheckoutLink, CheckoutLinkTemplate } from '../data/entities'
@@ -188,6 +190,45 @@ const createTemplateCommand: CommandHandler<Record<string, unknown>, { id: strin
     template.deletedAt = new Date()
     await em.flush()
   },
+  redo: async ({ logEntry, ctx }) => {
+    const after = resolveRedoSnapshot<CheckoutTemplateSnapshot>(logEntry)
+    if (!after) throw new CrudHttpError(400, { error: '[internal] redo snapshot unavailable for checkout template create' })
+    const em = ctx.container.resolve('em') as EntityManager
+    const dataEngine = ctx.container.resolve('dataEngine') as DataEngine
+    let template = await findOneWithDecryption(
+      em,
+      CheckoutLinkTemplate,
+      { id: after.id },
+      {},
+      { tenantId: after.tenantId, organizationId: after.organizationId },
+    )
+    if (template) {
+      restoreTemplateFromSnapshot(template, after)
+      template.deletedAt = null
+    } else {
+      template = em.create(CheckoutLinkTemplate, createTemplateFromSnapshot(after))
+      em.persist(template)
+    }
+    await em.flush()
+    const reset = buildCustomFieldResetMap(after.custom, undefined)
+    if (Object.keys(reset).length) {
+      await setCustomFieldsIfAny({
+        dataEngine,
+        entityId: CHECKOUT_ENTITY_IDS.template,
+        recordId: after.id,
+        tenantId: after.tenantId,
+        organizationId: after.organizationId,
+        values: reset,
+        notify: false,
+      })
+    }
+    await emitCheckoutEvent('checkout.template.created', {
+      id: template.id,
+      tenantId: after.tenantId,
+      organizationId: after.organizationId,
+    }).catch(() => undefined)
+    return { id: template.id }
+  },
 }
 
 const updateTemplateCommand: CommandHandler<Record<string, unknown>, { ok: true }> = {
@@ -225,7 +266,23 @@ const updateTemplateCommand: CommandHandler<Record<string, unknown>, { ok: true
       tenantId: scope.tenantId,
       deletedAt: null,
     }, undefined, scope)
-    if (!template) throw new CrudHttpError(404, { error: 'Template not found' })
+    if (!template) {
+      // The template was deleted in another tab. When the client opted into
+      // optimistic locking, surface the unified conflict bar instead of a bare
+      // 404 (#2529); otherwise the plain 404 still fires for API consumers.
+      enforceRecordGoneIsConflict({
+        resourceKind: 'checkout.template',
+        resourceId: parsed.id,
+        request: ctx.request ?? null,
+      })
+      throw new CrudHttpError(404, { error: 'Template not found' })
+    }
+    enforceCommandOptimisticLock({
+      resourceKind: 'checkout.template',
+      resourceId: template.id,
+      current: template.updatedAt ?? null,
+      request: ctx.request ?? null,
+    })
     const beforeCustom = await loadCustomFieldSnapshot(em, {
       entityId: CHECKOUT_ENTITY_IDS.template,
       recordId: template.id,
@@ -375,7 +432,22 @@ const deleteTemplateCommand: CommandHandler<Record<string, unknown>, { ok: true
       tenantId: scope.tenantId,
       deletedAt: null,
     }, undefined, scope)
-    if (!template) throw new CrudHttpError(404, { error: 'Template not found' })
+    if (!template) {
+      // Already deleted elsewhere — convert to a 409 conflict when the client
+      // sent the optimistic-lock header so the stale edit surfaces cleanly (#2529).
+      enforceRecordGoneIsConflict({
+        resourceKind: 'checkout.template',
+        resourceId: templateId,
+        request: ctx.request ?? null,
+      })
+      throw new CrudHttpError(404, { error: 'Template not found' })
+    }
+    enforceCommandOptimisticLock({
+      resourceKind: 'checkout.template',
+      resourceId: template.id,
+      current: template.updatedAt ?? null,
+      request: ctx.request ?? null,
+    })
     template.deletedAt = new Date()
     await em.flush()
     await emitCheckoutEvent('checkout.template.deleted', {

package/src/modules/checkout/components/GatewaySettingsFields.tsx

@@ -6,6 +6,14 @@ import { Input } from '@open-mercato/ui/primitives/input'
 import { Label } from '@open-mercato/ui/primitives/label'
 import { Alert, AlertDescription } from '@open-mercato/ui/primitives/alert'
 import { Textarea } from '@open-mercato/ui/primitives/textarea'
+import { Checkbox } from '@open-mercato/ui/primitives/checkbox'
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from '@open-mercato/ui/primitives/select'
 
 type Descriptor = {
   providerKey: string
@@ -31,6 +39,19 @@ export function GatewaySettingsFields({ providerKey, value, onChange }: Props) {
   const t = useT()
   const [descriptor, setDescriptor] = React.useState<Descriptor | null>(null)
 
+  const patchSetting = React.useCallback(
+    (fieldKey: string, nextValue: unknown) => {
+      const next = { ...(value ?? {}) }
+      if (nextValue === undefined || nextValue === null || nextValue === '') {
+        delete next[fieldKey]
+      } else {
+        next[fieldKey] = nextValue
+      }
+      onChange(next)
+    },
+    [onChange, value],
+  )
+
   const toggleMultiselectValue = React.useCallback(
     (fieldKey: string, optionValue: string) => {
       const current = Array.isArray(value?.[fieldKey])
@@ -39,9 +60,9 @@ export function GatewaySettingsFields({ providerKey, value, onChange }: Props) {
       const next = current.includes(optionValue)
         ? current.filter((entry) => entry !== optionValue)
         : [...current, optionValue]
-      onChange({ ...(value ?? {}), [fieldKey]: next })
+      patchSetting(fieldKey, next.length ? next : undefined)
     },
-    [onChange, value],
+    [patchSetting, value],
   )
 
   React.useEffect(() => {
@@ -88,16 +109,19 @@ export function GatewaySettingsFields({ providerKey, value, onChange }: Props) {
           <div key={field.key} className="space-y-2 rounded-lg border border-border/70 bg-muted/30 p-3">
             <Label>{field.label}</Label>
             {field.type === 'select' ? (
-              <select
-                className="w-full rounded-md border bg-background px-3 py-2 text-sm"
+              <Select
                 value={typeof currentValue === 'string' ? currentValue : ''}
-                onChange={(event) => onChange({ ...(value ?? {}), [field.key]: event.target.value })}
+                onValueChange={(next) => patchSetting(field.key, next)}
               >
-                <option value="">{t('checkout.gatewaySettings.selectPlaceholder')}</option>
-                {(field.options ?? []).map((option) => (
-                  <option key={option.value} value={option.value}>{option.label}</option>
-                ))}
-              </select>
+                <SelectTrigger>
+                  <SelectValue placeholder={t('checkout.gatewaySettings.selectPlaceholder')} />
+                </SelectTrigger>
+                <SelectContent>
+                  {(field.options ?? []).map((option) => (
+                    <SelectItem key={option.value} value={option.value}>{option.label}</SelectItem>
+                  ))}
+                </SelectContent>
+              </Select>
             ) : field.type === 'multiselect' ? (
               <div className="grid gap-2 sm:grid-cols-2">
                 {(field.options ?? []).map((option) => {
@@ -110,10 +134,9 @@ export function GatewaySettingsFields({ providerKey, value, onChange }: Props) {
                       key={option.value}
                       className="flex items-center gap-2 rounded-md border bg-background px-3 py-2 text-sm"
                     >
-                      <input
-                        type="checkbox"
+                      <Checkbox
                         checked={checked}
-                        onChange={() => toggleMultiselectValue(field.key, option.value)}
+                        onCheckedChange={() => toggleMultiselectValue(field.key, option.value)}
                       />
                       <span>{option.label}</span>
                     </label>
@@ -122,23 +145,22 @@ export function GatewaySettingsFields({ providerKey, value, onChange }: Props) {
               </div>
             ) : field.type === 'boolean' ? (
               <label className="flex items-center gap-2 text-sm">
-                <input
-                  type="checkbox"
+                <Checkbox
                   checked={currentValue === true}
-                  onChange={(event) => onChange({ ...(value ?? {}), [field.key]: event.target.checked })}
+                  onCheckedChange={(next) => patchSetting(field.key, next === true)}
                 />
                 {t('checkout.common.enabled')}
               </label>
             ) : field.type === 'textarea' ? (
               <Textarea
                 value={typeof currentValue === 'string' ? currentValue : ''}
-                onChange={(event) => onChange({ ...(value ?? {}), [field.key]: event.target.value })}
+                onChange={(event) => patchSetting(field.key, event.target.value)}
               />
             ) : (
               <Input
                 type={field.type === 'number' ? 'number' : field.type === 'secret' ? 'password' : 'text'}
                 value={typeof currentValue === 'string' || typeof currentValue === 'number' ? `${currentValue}` : ''}
-                onChange={(event) => onChange({ ...(value ?? {}), [field.key]: event.target.value })}
+                onChange={(event) => patchSetting(field.key, event.target.value)}
               />
             )}
             {field.description ? <p className="text-xs text-muted-foreground">{field.description}</p> : null}

package/src/modules/checkout/components/LinkTemplateForm.tsx

@@ -24,7 +24,9 @@ import { CrudForm, type CrudField, type CrudFormGroup, type CrudFormGroupCompone
 import { ComboboxInput, type ComboboxOption } from '@open-mercato/ui/backend/inputs'
 import { Page, PageBody } from '@open-mercato/ui/backend/Page'
 import { SwitchableMarkdownInput } from '@open-mercato/ui/backend/inputs'
-import { apiCall, apiCallOrThrow, readApiResultOrThrow } from '@open-mercato/ui/backend/utils/apiCall'
+import { apiCall, apiCallOrThrow, readApiResultOrThrow, withScopedApiRequestHeaders } from '@open-mercato/ui/backend/utils/apiCall'
+import { buildOptimisticLockHeader } from '@open-mercato/ui/backend/utils/optimisticLock'
+import { surfaceRecordConflict } from '@open-mercato/ui/backend/conflicts'
 import { collectCustomFieldValues } from '@open-mercato/ui/backend/utils/customFieldValues'
 import { Button } from '@open-mercato/ui/primitives/button'
 import { ColorPicker } from '@open-mercato/ui/primitives/color-picker'
@@ -260,6 +262,7 @@ function normalizeFormValues(value: FormValues | null | undefined, t?: Translate
     primaryColor: readString(source.primaryColor).trim() || defaults.primaryColor,
     secondaryColor: readString(source.secondaryColor).trim() || defaults.secondaryColor,
     backgroundColor: readString(source.backgroundColor).trim() || defaults.backgroundColor,
+    gatewayProviderKey: readString(source.gatewayProviderKey).trim(),
     gatewaySettings: isRecord(source.gatewaySettings) ? source.gatewaySettings : {},
     customFieldsetCode: readString(source.customFieldsetCode).trim() || null,
     collectCustomerDetails: readBoolean(source.collectCustomerDetails, true),
@@ -1638,11 +1641,20 @@ export function LinkTemplateForm({ mode, recordId }: Props) {
                 customFields: collectCustomFieldValues(values),
               }
               const endpoint = `/api/checkout/${mode === 'link' ? 'links' : 'templates'}${recordId ? `/${encodeURIComponent(recordId)}` : ''}`
-              const response = await readApiResultOrThrow<{ id?: string; slug?: string; ok?: boolean }>(endpoint, {
-                method: recordId ? 'PUT' : 'POST',
-                headers: { 'Content-Type': 'application/json' },
-                body: JSON.stringify(payload),
-              })
+              let response: { id?: string; slug?: string; ok?: boolean }
+              try {
+                response = await withScopedApiRequestHeaders(
+                  recordId ? buildOptimisticLockHeader(readString(initialValues?.updatedAt) || null) : {},
+                  () => readApiResultOrThrow<{ id?: string; slug?: string; ok?: boolean }>(endpoint, {
+                    method: recordId ? 'PUT' : 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify(payload),
+                  }),
+                )
+              } catch (error) {
+                if (surfaceRecordConflict(error, t)) return
+                throw error
+              }
               const targetId = recordId ?? (typeof response?.id === 'string' ? response.id : null)
               const logoAttachmentId = readString(values.logoAttachmentId)
               if (
@@ -1687,7 +1699,15 @@ export function LinkTemplateForm({ mode, recordId }: Props) {
                 : `/backend/checkout/templates?flash=${encodeURIComponent(t('checkout.common.flash.saved'))}&type=success`
             }}
             onDelete={recordId ? async () => {
-              await apiCallOrThrow(`/api/checkout/${mode === 'link' ? 'links' : 'templates'}/${encodeURIComponent(recordId)}`, { method: 'DELETE' })
+              try {
+                await withScopedApiRequestHeaders(
+                  buildOptimisticLockHeader(readString(initialValues?.updatedAt) || null),
+                  () => apiCallOrThrow(`/api/checkout/${mode === 'link' ? 'links' : 'templates'}/${encodeURIComponent(recordId)}`, { method: 'DELETE' }),
+                )
+              } catch (error) {
+                if (surfaceRecordConflict(error, t)) return
+                throw error
+              }
               window.location.href = mode === 'link'
                 ? `/backend/checkout/pay-links?flash=${encodeURIComponent(t('checkout.common.flash.deleted'))}&type=success`
                 : `/backend/checkout/templates?flash=${encodeURIComponent(t('checkout.common.flash.deleted'))}&type=success`