diff --git a/frontend/src/__tests__/contractErrorParser.test.ts b/frontend/src/__tests__/contractErrorParser.test.ts
new file mode 100644
index 00000000..79fc37c5
--- /dev/null
+++ b/frontend/src/__tests__/contractErrorParser.test.ts
@@ -0,0 +1,264 @@
+/**
+ * Integration tests for contractErrorParser
+ *
+ * Covers every mapped error code and verifies the fallback behaviour for
+ * unknown XDR strings.
+ *
+ * Run with: npx vitest run src/__tests__/contractErrorParser.test.ts
+ *
+ * Issue: https://github.com/Gildado/PayD/issues/82
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+  parseContractError,
+  getAllContractErrorCodes,
+} from '../services/contractErrorParser';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Wraps a numeric contract error code into the Soroban host error format. */
+function sorobanHostErr(n: number): string {
+  return `HostError: Value(ContractError(${n}))`;
+}
+
+// ---------------------------------------------------------------------------
+// Known error code mapping
+// ---------------------------------------------------------------------------
+
+describe('parseContractError — known error codes', () => {
+  it('recognises invoke_host_function_trapped via direct key', () => {
+    const result = parseContractError('invoke_host_function_trapped');
+    expect(result.known).toBe(true);
+    expect(result.error.code).toBe('invoke_host_function_trapped');
+    expect(result.error.description).toBeTruthy();
+    expect(result.error.suggestedAction).toBeTruthy();
+    expect(result.error.rawXdr).toBeUndefined();
+  });
+
+  it('recognises invoke_host_function_malformed via direct key', () => {
+    const result = parseContractError('invoke_host_function_malformed');
+    expect(result.known).toBe(true);
+    expect(result.error.code).toBe('invoke_host_function_malformed');
+  });
+
+  it('recognises auth_required via direct key', () => {
+    const result = parseContractError('auth_required');
+    expect(result.known).toBe(true);
+    expect(result.error.code).toBe('auth_required');
+  });
+
+  it('recognises bad_auth via direct key', () => {
+    const result = parseContractError('bad_auth');
+    expect(result.known).toBe(true);
+    expect(result.error.code).toBe('bad_auth');
+  });
+
+  it('recognises insufficient_refundable_fee', () => {
+    const result = parseContractError('insufficient_refundable_fee');
+    expect(result.known).toBe(true);
+    expect(result.error.code).toBe('insufficient_refundable_fee');
+  });
+
+  it('recognises resource_limit_exceeded', () => {
+    const result = parseContractError('resource_limit_exceeded');
+    expect(result.known).toBe(true);
+    expect(result.error.code).toBe('resource_limit_exceeded');
+  });
+
+  it('recognises invalid_ledger_entry_access', () => {
+    const result = parseContractError('invalid_ledger_entry_access');
+    expect(result.known).toBe(true);
+    expect(result.error.code).toBe('invalid_ledger_entry_access');
+  });
+
+  it('recognises payroll_duplicate_period', () => {
+    const result = parseContractError('payroll_duplicate_period');
+    expect(result.known).toBe(true);
+    expect(result.error.code).toBe('payroll_duplicate_period');
+  });
+
+  it('recognises payroll_employee_not_found', () => {
+    const result = parseContractError('payroll_employee_not_found');
+    expect(result.known).toBe(true);
+    expect(result.error.code).toBe('payroll_employee_not_found');
+  });
+
+  it('recognises swap_slippage_exceeded', () => {
+    const result = parseContractError('swap_slippage_exceeded');
+    expect(result.known).toBe(true);
+    expect(result.error.code).toBe('swap_slippage_exceeded');
+  });
+
+  it('recognises no_liquidity', () => {
+    const result = parseContractError('no_liquidity');
+    expect(result.known).toBe(true);
+    expect(result.error.code).toBe('no_liquidity');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Numeric ContractError(N) extraction
+// ---------------------------------------------------------------------------
+
+describe('parseContractError — numeric ContractError(N) codes', () => {
+  it.each([0, 1, 2, 3, 4, 5])(
+    'maps ContractError(%i) to contract_error_%i',
+    (n) => {
+      const result = parseContractError(sorobanHostErr(n));
+      expect(result.known).toBe(true);
+      expect(result.error.code).toBe(`contract_error_${n}`);
+      expect(result.error.description).toBeTruthy();
+      expect(result.error.suggestedAction).toBeTruthy();
+      expect(result.error.rawXdr).toBeUndefined();
+    }
+  );
+
+  it('returns rawXdr for an unmapped ContractError(99)', () => {
+    const input = sorobanHostErr(99);
+    const result = parseContractError(input);
+    expect(result.known).toBe(false);
+    expect(result.error.rawXdr).toBe(input);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Token-based heuristic matching
+// ---------------------------------------------------------------------------
+
+describe('parseContractError — heuristic token matching', () => {
+  it('detects "trapped" in a verbose error string', () => {
+    const result = parseContractError(
+      'Error executing contract: host function trapped during execution'
+    );
+    expect(result.known).toBe(true);
+    expect(result.error.code).toBe('invoke_host_function_trapped');
+  });
+
+  it('detects "malformed" in a verbose error string', () => {
+    const result = parseContractError('Invocation malformed: argument count mismatch');
+    expect(result.known).toBe(true);
+    expect(result.error.code).toBe('invoke_host_function_malformed');
+  });
+
+  it('detects "authrequired" (camelCase variant)', () => {
+    const result = parseContractError('ContractAuthRequired: missing signer');
+    expect(result.known).toBe(true);
+    expect(result.error.code).toBe('auth_required');
+  });
+
+  it('detects "refundable_fee" token', () => {
+    const result = parseContractError('InsufficientRefundableFee: fee too low');
+    expect(result.known).toBe(true);
+    expect(result.error.code).toBe('insufficient_refundable_fee');
+  });
+
+  it('detects "resource_limit" token', () => {
+    const result = parseContractError('resource_limit exceeded during execution');
+    expect(result.known).toBe(true);
+    expect(result.error.code).toBe('resource_limit_exceeded');
+  });
+
+  it('detects "ledger_entry_access" token', () => {
+    const result = parseContractError('InvalidLedgerEntryAccess: footprint mismatch');
+    expect(result.known).toBe(true);
+    expect(result.error.code).toBe('invalid_ledger_entry_access');
+  });
+
+  it('detects "badauth" (camelCase variant)', () => {
+    const result = parseContractError('BadAuth: signature verification failed');
+    expect(result.known).toBe(true);
+    expect(result.error.code).toBe('bad_auth');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Unknown / fallback behaviour
+// ---------------------------------------------------------------------------
+
+describe('parseContractError — unknown error fallback', () => {
+  it('falls back for an opaque base64 XDR blob', () => {
+    const rawXdr = 'AAAABAAAAAgAAAAA3kP6AAAAAQAAAAEAAAAAAAAAB9AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAlEXgQAAAAAAAAAAA==';
+    const result = parseContractError(rawXdr);
+    expect(result.known).toBe(false);
+    expect(result.error.code).toBe('unknown_contract_error');
+    expect(result.error.rawXdr).toBe(rawXdr);
+    expect(result.resultXdr).toBe(rawXdr);
+    expect(result.error.description).toBeTruthy();
+    expect(result.error.suggestedAction).toMatch(/copy/i);
+  });
+
+  it('falls back for a completely arbitrary string', () => {
+    const result = parseContractError('some random unrecognised error text');
+    expect(result.known).toBe(false);
+    expect(result.error.rawXdr).toBe('some random unrecognised error text');
+  });
+
+  it('handles an empty string gracefully', () => {
+    const result = parseContractError('');
+    expect(result.known).toBe(true); // treated as unknown_contract_error (mapped)
+    expect(result.error.code).toBe('unknown_contract_error');
+    expect(result.error.rawXdr).toBeUndefined();
+  });
+
+  it('handles a whitespace-only string gracefully', () => {
+    const result = parseContractError('   ');
+    expect(result.known).toBe(true);
+    expect(result.error.code).toBe('unknown_contract_error');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// resultXdr is always preserved
+// ---------------------------------------------------------------------------
+
+describe('parseContractError — resultXdr preservation', () => {
+  it('always returns the original resultXdr for known errors', () => {
+    const input = 'bad_auth';
+    const result = parseContractError(input);
+    expect(result.resultXdr).toBe(input);
+  });
+
+  it('always returns the original resultXdr for unknown errors', () => {
+    const input = 'AAAAABCXYZ123opaque';
+    const result = parseContractError(input);
+    expect(result.resultXdr).toBe(input);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// getAllContractErrorCodes
+// ---------------------------------------------------------------------------
+
+describe('getAllContractErrorCodes', () => {
+  it('returns an array of all mapped codes with description and suggestedAction', () => {
+    const codes = getAllContractErrorCodes();
+    expect(codes.length).toBeGreaterThan(0);
+    for (const entry of codes) {
+      expect(entry.code).toBeTruthy();
+      expect(entry.description).toBeTruthy();
+      expect(entry.suggestedAction).toBeTruthy();
+    }
+  });
+
+  it('includes all contract_error_N codes (0–5)', () => {
+    const codes = getAllContractErrorCodes().map((c) => c.code);
+    for (let n = 0; n <= 5; n++) {
+      expect(codes).toContain(`contract_error_${n}`);
+    }
+  });
+
+  it('includes payroll-specific codes', () => {
+    const codes = getAllContractErrorCodes().map((c) => c.code);
+    expect(codes).toContain('payroll_duplicate_period');
+    expect(codes).toContain('payroll_employee_not_found');
+  });
+
+  it('includes cross-asset payment codes', () => {
+    const codes = getAllContractErrorCodes().map((c) => c.code);
+    expect(codes).toContain('swap_slippage_exceeded');
+    expect(codes).toContain('no_liquidity');
+  });
+});
diff --git a/frontend/src/components/ContractErrorPanel.module.css b/frontend/src/components/ContractErrorPanel.module.css
new file mode 100644
index 00000000..c3c0376a
--- /dev/null
+++ b/frontend/src/components/ContractErrorPanel.module.css
@@ -0,0 +1,203 @@
+/* -----------------------------------------------------------------------
+   ContractErrorPanel — CSS Module
+   Issue: https://github.com/Gildado/PayD/issues/82
+   ----------------------------------------------------------------------- */
+
+.container {
+  border-radius: 1rem;
+  border: 1px solid rgba(239, 68, 68, 0.25);
+  background: rgba(239, 68, 68, 0.04);
+  overflow: hidden;
+}
+
+/* ---- Collapsible header ---- */
+.header {
+  display: flex;
+  align-items: center;
+  gap: 0.625rem;
+  padding: 0.875rem 1rem;
+  cursor: pointer;
+  user-select: none;
+  transition: background 0.15s;
+}
+
+.header:hover {
+  background: rgba(239, 68, 68, 0.06);
+}
+
+.headerIcon {
+  flex-shrink: 0;
+  color: #ef4444;
+  display: flex;
+  align-items: center;
+}
+
+.headerTitle {
+  flex: 1;
+  font-size: 0.8125rem;
+  font-weight: 800;
+  color: #ef4444;
+  letter-spacing: 0.02em;
+}
+
+.chevron {
+  color: #ef4444;
+  opacity: 0.6;
+  transition: transform 0.2s;
+}
+
+.chevronOpen {
+  transform: rotate(180deg);
+}
+
+/* ---- Collapsible body ---- */
+.body {
+  padding: 0 1rem 1rem;
+  border-top: 1px solid rgba(239, 68, 68, 0.15);
+}
+
+/* ---- Error card ---- */
+.errorCard {
+  margin-top: 1rem;
+  display: flex;
+  flex-direction: column;
+  gap: 0.75rem;
+}
+
+.codeRow {
+  display: flex;
+  align-items: center;
+  gap: 0.625rem;
+}
+
+.codeLabel {
+  font-size: 9px;
+  font-weight: 700;
+  text-transform: uppercase;
+  letter-spacing: 0.12em;
+  color: var(--muted, #6b7280);
+}
+
+.codeBadge {
+  font-family: var(--font-mono, monospace);
+  font-size: 10px;
+  font-weight: 700;
+  padding: 0.1875rem 0.5rem;
+  background: rgba(239, 68, 68, 0.15);
+  border: 1px solid rgba(239, 68, 68, 0.3);
+  border-radius: 4px;
+  color: #ef4444;
+}
+
+.description {
+  font-size: 0.8125rem;
+  color: var(--text, #e5e7eb);
+  line-height: 1.55;
+}
+
+/* ---- Suggested action ---- */
+.actionBox {
+  display: flex;
+  align-items: flex-start;
+  gap: 0.5rem;
+  padding: 0.625rem 0.75rem;
+  background: rgba(245, 158, 11, 0.06);
+  border: 1px solid rgba(245, 158, 11, 0.2);
+  border-radius: 0.5rem;
+}
+
+.actionIcon {
+  flex-shrink: 0;
+  color: #f59e0b;
+  margin-top: 0.125rem;
+}
+
+.actionText {
+  font-size: 0.8125rem;
+  color: #f59e0b;
+  line-height: 1.5;
+}
+
+/* ---- Raw XDR fallback block ---- */
+.rawXdrSection {
+  display: flex;
+  flex-direction: column;
+  gap: 0.5rem;
+}
+
+.rawXdrLabel {
+  font-size: 9px;
+  font-weight: 700;
+  text-transform: uppercase;
+  letter-spacing: 0.12em;
+  color: var(--muted, #6b7280);
+}
+
+.rawXdrBox {
+  position: relative;
+  background: rgba(0, 0, 0, 0.3);
+  border: 1px solid rgba(255, 255, 255, 0.08);
+  border-radius: 0.5rem;
+  padding: 0.625rem;
+}
+
+.rawXdrText {
+  font-family: var(--font-mono, monospace);
+  font-size: 10px;
+  color: var(--muted, #6b7280);
+  word-break: break-all;
+  line-height: 1.6;
+  white-space: pre-wrap;
+  max-height: 120px;
+  overflow-y: auto;
+}
+
+.copyBtn {
+  margin-top: 0.375rem;
+  display: inline-flex;
+  align-items: center;
+  gap: 0.375rem;
+  padding: 0.25rem 0.625rem;
+  background: rgba(255, 255, 255, 0.05);
+  border: 1px solid rgba(255, 255, 255, 0.1);
+  border-radius: 0.375rem;
+  font-size: 10px;
+  font-weight: 700;
+  color: var(--muted, #6b7280);
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  cursor: pointer;
+  transition: all 0.15s;
+}
+
+.copyBtn:hover {
+  background: rgba(255, 255, 255, 0.09);
+  color: var(--text, #e5e7eb);
+}
+
+.copyBtnCopied {
+  color: #10b981;
+  border-color: rgba(16, 185, 129, 0.3);
+}
+
+/* ---- Dismiss button ---- */
+.dismissBtn {
+  margin-top: 1rem;
+  width: 100%;
+  padding: 0.5rem;
+  background: transparent;
+  border: 1px solid rgba(239, 68, 68, 0.2);
+  border-radius: 0.5rem;
+  font-size: 11px;
+  font-weight: 700;
+  color: rgba(239, 68, 68, 0.6);
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  cursor: pointer;
+  transition: all 0.15s;
+}
+
+.dismissBtn:hover {
+  background: rgba(239, 68, 68, 0.07);
+  color: #ef4444;
+}
diff --git a/frontend/src/components/ContractErrorPanel.tsx b/frontend/src/components/ContractErrorPanel.tsx
new file mode 100644
index 00000000..17485374
--- /dev/null
+++ b/frontend/src/components/ContractErrorPanel.tsx
@@ -0,0 +1,222 @@
+/**
+ * ContractErrorPanel
+ *
+ * Collapsible error panel that decodes and displays Soroban contract
+ * invocation failures. Uses `parseContractError` to map known XDR result
+ * codes to human-readable descriptions and suggested remediation steps.
+ * Falls back to a raw XDR display with a copy button for unknown codes.
+ *
+ * Issue: https://github.com/Gildado/PayD/issues/82
+ */
+
+import React, { useState } from 'react';
+import { parseContractError } from '../services/contractErrorParser';
+import type { ContractErrorResult } from '../services/contractErrorParser';
+import styles from './ContractErrorPanel.module.css';
+
+// ---------------------------------------------------------------------------
+// Props
+// ---------------------------------------------------------------------------
+
+interface Props {
+  /**
+   * The result XDR or Soroban error string from a failed contract invocation.
+   * When null/undefined the panel renders nothing.
+   */
+  resultXdr: string | null | undefined;
+  /** Optional callback fired when the user dismisses the panel */
+  onDismiss?: () => void;
+}
+
+// ---------------------------------------------------------------------------
+// Icons (inline SVG — no extra deps)
+// ---------------------------------------------------------------------------
+
+const ErrorCircleIcon = () => (
+  <svg
+    width="16"
+    height="16"
+    viewBox="0 0 24 24"
+    fill="none"
+    stroke="currentColor"
+    strokeWidth="2.5"
+    strokeLinecap="round"
+    strokeLinejoin="round"
+  >
+    <circle cx="12" cy="12" r="10" />
+    <line x1="15" y1="9" x2="9" y2="15" />
+    <line x1="9" y1="9" x2="15" y2="15" />
+  </svg>
+);
+
+const LightbulbIcon = () => (
+  <svg
+    width="14"
+    height="14"
+    viewBox="0 0 24 24"
+    fill="none"
+    stroke="currentColor"
+    strokeWidth="2"
+    strokeLinecap="round"
+    strokeLinejoin="round"
+  >
+    <line x1="9" y1="18" x2="15" y2="18" />
+    <line x1="10" y1="22" x2="14" y2="22" />
+    <path d="M15.09 14c.18-.98.65-1.74 1.41-2.5A4.65 4.65 0 0 0 18 8 6 6 0 0 0 6 8c0 1 .23 2.23 1.5 3.5A4.61 4.61 0 0 1 8.91 14" />
+  </svg>
+);
+
+const CopyIcon = () => (
+  <svg
+    width="11"
+    height="11"
+    viewBox="0 0 24 24"
+    fill="none"
+    stroke="currentColor"
+    strokeWidth="2.5"
+    strokeLinecap="round"
+    strokeLinejoin="round"
+  >
+    <rect x="9" y="9" width="13" height="13" rx="2" ry="2" />
+    <path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1" />
+  </svg>
+);
+
+const CheckIcon = () => (
+  <svg
+    width="11"
+    height="11"
+    viewBox="0 0 24 24"
+    fill="none"
+    stroke="currentColor"
+    strokeWidth="3"
+    strokeLinecap="round"
+    strokeLinejoin="round"
+  >
+    <polyline points="20 6 9 17 4 12" />
+  </svg>
+);
+
+const ChevronDownIcon = () => (
+  <svg
+    width="14"
+    height="14"
+    viewBox="0 0 24 24"
+    fill="none"
+    stroke="currentColor"
+    strokeWidth="2.5"
+    strokeLinecap="round"
+    strokeLinejoin="round"
+  >
+    <polyline points="6 9 12 15 18 9" />
+  </svg>
+);
+
+// ---------------------------------------------------------------------------
+// Sub-component: CopyButton
+// ---------------------------------------------------------------------------
+
+interface CopyButtonProps {
+  text: string;
+}
+
+const CopyButton: React.FC<CopyButtonProps> = ({ text }) => {
+  const [copied, setCopied] = useState(false);
+
+  const handleCopy = async () => {
+    try {
+      await navigator.clipboard.writeText(text);
+      setCopied(true);
+      setTimeout(() => setCopied(false), 2000);
+    } catch {
+      // Clipboard API unavailable — silently skip
+    }
+  };
+
+  return (
+    <button
+      onClick={() => {
+        void handleCopy();
+      }}
+      className={`${styles.copyBtn} ${copied ? styles.copyBtnCopied : ''}`}
+    >
+      {copied ? <CheckIcon /> : <CopyIcon />}
+      {copied ? 'Copied!' : 'Copy XDR'}
+    </button>
+  );
+};
+
+// ---------------------------------------------------------------------------
+// Main component
+// ---------------------------------------------------------------------------
+
+export const ContractErrorPanel: React.FC<Props> = ({ resultXdr, onDismiss }) => {
+  const [isOpen, setIsOpen] = useState(true);
+
+  if (!resultXdr) return null;
+
+  const parsed: ContractErrorResult = parseContractError(resultXdr);
+  const { error } = parsed;
+
+  return (
+    <div className={styles.container} role="alert" aria-live="polite">
+      {/* Collapsible header */}
+      <div
+        className={styles.header}
+        onClick={() => setIsOpen((prev) => !prev)}
+        aria-expanded={isOpen}
+      >
+        <span className={styles.headerIcon}>
+          <ErrorCircleIcon />
+        </span>
+        <span className={styles.headerTitle}>Contract Invocation Failed</span>
+        <span className={`${styles.chevron} ${isOpen ? styles.chevronOpen : ''}`}>
+          <ChevronDownIcon />
+        </span>
+      </div>
+
+      {/* Collapsible body */}
+      {isOpen && (
+        <div className={styles.body}>
+          <div className={styles.errorCard}>
+            {/* Error code badge */}
+            <div className={styles.codeRow}>
+              <span className={styles.codeLabel}>Error Code</span>
+              <span className={styles.codeBadge}>{error.code}</span>
+            </div>
+
+            {/* Human-readable description */}
+            <p className={styles.description}>{error.description}</p>
+
+            {/* Suggested action */}
+            <div className={styles.actionBox}>
+              <span className={styles.actionIcon}>
+                <LightbulbIcon />
+              </span>
+              <span className={styles.actionText}>{error.suggestedAction}</span>
+            </div>
+
+            {/* Raw XDR fallback for unknown errors */}
+            {!parsed.known && error.rawXdr && (
+              <div className={styles.rawXdrSection}>
+                <span className={styles.rawXdrLabel}>Raw XDR</span>
+                <div className={styles.rawXdrBox}>
+                  <pre className={styles.rawXdrText}>{error.rawXdr}</pre>
+                </div>
+                <CopyButton text={error.rawXdr} />
+              </div>
+            )}
+          </div>
+
+          {onDismiss && (
+            <button onClick={onDismiss} className={styles.dismissBtn}>
+              Dismiss
+            </button>
+          )}
+        </div>
+      )}
+    </div>
+  );
+};
+
+export default ContractErrorPanel;
diff --git a/frontend/src/pages/CrossAssetPayment.tsx b/frontend/src/pages/CrossAssetPayment.tsx
index 71343860..f04da1b1 100644
--- a/frontend/src/pages/CrossAssetPayment.tsx
+++ b/frontend/src/pages/CrossAssetPayment.tsx
@@ -26,6 +26,7 @@ export default function CrossAssetPayment() {
   const [submissionTxHash, setSubmissionTxHash] = useState<string | null>(null);
   const [liveStatusMessage, setLiveStatusMessage] = useState<string>('Waiting for submission...');
   const [status, setStatus] = useState<string>('idle');
+  const [contractErrorXdr, setContractErrorXdr] = useState<string | null>(null);
 
   const selectedPath = useMemo(
     () => paths.find((path) => path.id === selectedPathId) || null,
@@ -142,10 +143,9 @@ export default function CrossAssetPayment() {
       notifySuccess('Payment submitted', `On-chain transaction hash: ${result.txHash}`);
     } catch (error) {
       setStatus('error');
-      notifyError(
-        'Payment failed',
-        error instanceof Error ? error.message : 'An unexpected error occurred.'
-      );
+      const xdr = error instanceof Error ? error.message : String(error);
+      setContractErrorXdr(xdr);
+      notifyError('Payment failed', 'Contract returned an error. See details below.');
     }
   };
 
diff --git a/frontend/src/pages/PayrollScheduler.tsx b/frontend/src/pages/PayrollScheduler.tsx
index 802f3c9c..64ca1200 100644
--- a/frontend/src/pages/PayrollScheduler.tsx
+++ b/frontend/src/pages/PayrollScheduler.tsx
@@ -3,6 +3,7 @@ import { AutosaveIndicator } from '../components/AutosaveIndicator';
 import { useAutosave } from '../hooks/useAutosave';
 import { useTransactionSimulation } from '../hooks/useTransactionSimulation';
 import { TransactionSimulationPanel } from '../components/TransactionSimulationPanel';
+import { ContractErrorPanel } from '../components/ContractErrorPanel';
 import { useNotification } from '../hooks/useNotification';
 import { useSocket } from '../hooks/useSocket';
 import { createClaimableBalanceTransaction, generateWallet } from '../services/stellar';
@@ -57,6 +58,7 @@ export default function PayrollScheduler() {
   const { socket, subscribeToTransaction, unsubscribeFromTransaction } = useSocket();
   const [formData, setFormData] = useState<PayrollFormState>(initialFormState);
   const [isBroadcasting, setIsBroadcasting] = useState(false);
+  const [contractErrorXdr, setContractErrorXdr] = useState<string | null>(null);
   const [isWizardOpen, setIsWizardOpen] = useState(false);
   const [activeSchedule, setActiveSchedule] = useState<{
     frequency: string;
@@ -120,6 +122,7 @@ export default function PayrollScheduler() {
     const { name, value } = e.target;
     setFormData((prev) => ({ ...prev, [name]: value }));
     if (simulationResult) resetSimulation();
+    if (contractErrorXdr) setContractErrorXdr(null);
   };
 
   useEffect(() => {
@@ -223,7 +226,9 @@ export default function PayrollScheduler() {
       setFormData(initialFormState);
     } catch (err) {
       console.error(err);
-      notifyError('Broadcast failed', 'Please check your network connection and try again.');
+      const xdr = err instanceof Error ? err.message : String(err);
+      setContractErrorXdr(xdr);
+      notifyError('Broadcast failed', 'Contract returned an error. See details below.');
     } finally {
       setIsBroadcasting(false);
     }
@@ -411,6 +416,11 @@ export default function PayrollScheduler() {
               onReset={resetSimulation}
             />
 
+            <ContractErrorPanel
+              resultXdr={contractErrorXdr}
+              onDismiss={() => setContractErrorXdr(null)}
+            />
+
             <div className="card glass noise h-fit">
               <Heading as="h3" size="xs" weight="bold" addlClassName="mb-4 flex items-center gap-2">
                 <svg
diff --git a/frontend/src/pages/VestingEscrow.tsx b/frontend/src/pages/VestingEscrow.tsx
new file mode 100644
index 00000000..ba33968b
--- /dev/null
+++ b/frontend/src/pages/VestingEscrow.tsx
@@ -0,0 +1,258 @@
+/**
+ * VestingEscrow
+ *
+ * UI for interacting with the vesting_escrow Soroban contract.
+ * Allows beneficiaries to view their vesting schedule and claim
+ * unlocked tokens. Contract errors are decoded and displayed via
+ * ContractErrorPanel.
+ *
+ * Issue: https://github.com/Gildado/PayD/issues/82
+ */
+
+import { useState } from 'react';
+import { Heading, Text, Button, Input } from '@stellar/design-system';
+import { ContractErrorPanel } from '../components/ContractErrorPanel';
+import { useNotification } from '../hooks/useNotification';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+interface VestingSchedule {
+  totalAmount: string;
+  claimedAmount: string;
+  claimableAmount: string;
+  startDate: string;
+  endDate: string;
+  cliffDate: string;
+}
+
+// ---------------------------------------------------------------------------
+// Mock helpers
+// ---------------------------------------------------------------------------
+
+/** Simulates fetching a vesting schedule from the Soroban contract. */
+async function mockFetchSchedule(beneficiary: string): Promise<VestingSchedule> {
+  await new Promise((resolve) => setTimeout(resolve, 900));
+  if (!beneficiary.startsWith('G') || beneficiary.length < 10) {
+    throw new Error('HostError: Value(ContractError(4))');
+  }
+  return {
+    totalAmount: '100,000',
+    claimedAmount: '25,000',
+    claimableAmount: '12,500',
+    startDate: '2024-01-01',
+    endDate: '2025-12-31',
+    cliffDate: '2024-04-01',
+  };
+}
+
+/** Simulates calling the claim function on the Soroban contract. */
+async function mockClaimTokens(beneficiary: string): Promise<void> {
+  await new Promise((resolve) => setTimeout(resolve, 1100));
+  if (!beneficiary.startsWith('G')) {
+    throw new Error('HostError: Value(ContractError(3))');
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Component
+// ---------------------------------------------------------------------------
+
+export default function VestingEscrow() {
+  const { notifySuccess, notifyError } = useNotification();
+  const [beneficiary, setBeneficiary] = useState('');
+  const [schedule, setSchedule] = useState<VestingSchedule | null>(null);
+  const [isFetching, setIsFetching] = useState(false);
+  const [isClaiming, setIsClaiming] = useState(false);
+  const [contractErrorXdr, setContractErrorXdr] = useState<string | null>(null);
+
+  const handleLookup = async () => {
+    if (!beneficiary.trim()) {
+      notifyError('Missing input', 'Please enter a beneficiary address.');
+      return;
+    }
+    setIsFetching(true);
+    setSchedule(null);
+    setContractErrorXdr(null);
+    try {
+      const result = await mockFetchSchedule(beneficiary);
+      setSchedule(result);
+    } catch (err) {
+      const xdr = err instanceof Error ? err.message : String(err);
+      setContractErrorXdr(xdr);
+      notifyError('Contract error', 'Could not fetch vesting schedule.');
+    } finally {
+      setIsFetching(false);
+    }
+  };
+
+  const handleClaim = async () => {
+    setIsClaiming(true);
+    setContractErrorXdr(null);
+    try {
+      await mockClaimTokens(beneficiary);
+      notifySuccess('Tokens claimed!', `${schedule?.claimableAmount ?? ''} USDC sent to your wallet.`);
+      setSchedule((prev) =>
+        prev
+          ? {
+              ...prev,
+              claimedAmount: String(
+                Number(prev.claimedAmount.replace(/,/g, '')) +
+                  Number(prev.claimableAmount.replace(/,/g, ''))
+              ),
+              claimableAmount: '0',
+            }
+          : null
+      );
+    } catch (err) {
+      const xdr = err instanceof Error ? err.message : String(err);
+      setContractErrorXdr(xdr);
+      notifyError('Claim failed', 'Contract returned an error. See details below.');
+    } finally {
+      setIsClaiming(false);
+    }
+  };
+
+  const progress = schedule
+    ? Math.round(
+        (Number(schedule.claimedAmount.replace(/,/g, '')) /
+          Number(schedule.totalAmount.replace(/,/g, ''))) *
+          100
+      )
+    : 0;
+
+  return (
+    <div className="flex-1 flex flex-col items-center justify-start p-12 max-w-4xl mx-auto w-full">
+      {/* Page header */}
+      <div className="w-full mb-12 border-b border-hi pb-8">
+        <Heading as="h1" size="lg" weight="bold" addlClassName="mb-2 tracking-tight">
+          Vesting{' '}
+          <span className="text-accent">Escrow</span>
+        </Heading>
+        <Text as="p" size="sm" weight="regular" addlClassName="text-muted font-mono tracking-wider uppercase">
+          Token vesting schedule &amp; claim interface
+        </Text>
+      </div>
+
+      <div className="w-full grid grid-cols-1 lg:grid-cols-5 gap-8">
+        {/* Left: lookup form */}
+        <div className="lg:col-span-3 flex flex-col gap-6">
+          <div className="card glass noise">
+            <Heading as="h3" size="xs" weight="bold" addlClassName="mb-4">
+              Beneficiary Lookup
+            </Heading>
+
+            <div className="flex flex-col gap-4">
+              <Input
+                id="beneficiary"
+                fieldSize="md"
+                label="Beneficiary Address"
+                placeholder="G..."
+                value={beneficiary}
+                onChange={(e) => {
+                  setBeneficiary(e.target.value);
+                  setContractErrorXdr(null);
+                }}
+              />
+              <Button
+                variant="primary"
+                size="md"
+                isFullWidth
+                disabled={isFetching}
+                onClick={() => {
+                  void handleLookup();
+                }}
+              >
+                {isFetching ? 'Looking up...' : 'Fetch Schedule'}
+              </Button>
+            </div>
+          </div>
+
+          {/* Contract error panel */}
+          {contractErrorXdr && (
+            <ContractErrorPanel
+              resultXdr={contractErrorXdr}
+              onDismiss={() => setContractErrorXdr(null)}
+            />
+          )}
+
+          {/* Schedule card */}
+          {schedule && (
+            <div className="card glass noise flex flex-col gap-5">
+              <Heading as="h3" size="xs" weight="bold">
+                Vesting Schedule
+              </Heading>
+
+              {/* Progress bar */}
+              <div>
+                <div className="flex justify-between text-xs text-muted mb-1">
+                  <span>Claimed</span>
+                  <span>{progress}%</span>
+                </div>
+                <div className="h-2 rounded-full bg-white/5 overflow-hidden">
+                  <div
+                    className="h-full bg-accent rounded-full transition-all"
+                    style={{ width: `${progress}%` }}
+                  />
+                </div>
+              </div>
+
+              <div className="grid grid-cols-2 gap-4 text-sm">
+                {[
+                  { label: 'Total', value: `${schedule.totalAmount} USDC` },
+                  { label: 'Claimed', value: `${schedule.claimedAmount} USDC` },
+                  { label: 'Available', value: `${schedule.claimableAmount} USDC` },
+                  { label: 'Cliff Date', value: schedule.cliffDate },
+                  { label: 'Start', value: schedule.startDate },
+                  { label: 'End', value: schedule.endDate },
+                ].map(({ label, value }) => (
+                  <div key={label}>
+                    <span className="text-xs text-muted uppercase font-bold tracking-wider block mb-0.5">
+                      {label}
+                    </span>
+                    <span className="font-mono font-semibold">{value}</span>
+                  </div>
+                ))}
+              </div>
+
+              <Button
+                variant="primary"
+                size="md"
+                isFullWidth
+                disabled={isClaiming || schedule.claimableAmount === '0'}
+                onClick={() => {
+                  void handleClaim();
+                }}
+              >
+                {isClaiming
+                  ? 'Claiming...'
+                  : schedule.claimableAmount === '0'
+                    ? 'Nothing to Claim'
+                    : `Claim ${schedule.claimableAmount} USDC`}
+              </Button>
+            </div>
+          )}
+        </div>
+
+        {/* Right: info panel */}
+        <div className="lg:col-span-2">
+          <div className="card glass noise h-fit">
+            <Heading as="h3" size="xs" weight="bold" addlClassName="mb-4">
+              How Vesting Works
+            </Heading>
+            <Text as="p" size="xs" weight="regular" addlClassName="text-muted leading-relaxed mb-4">
+              Token vesting ensures long-term alignment by releasing funds over a defined schedule.
+            </Text>
+            <ul className="text-xs text-muted space-y-2 list-disc pl-4 font-medium">
+              <li>Tokens are locked in a Soroban escrow contract</li>
+              <li>A cliff period must pass before any tokens are claimable</li>
+              <li>Tokens unlock linearly after the cliff date</li>
+              <li>Claims execute directly on-chain via contract invocation</li>
+            </ul>
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}
diff --git a/frontend/src/services/contractErrorParser.ts b/frontend/src/services/contractErrorParser.ts
new file mode 100644
index 00000000..f2c3465c
--- /dev/null
+++ b/frontend/src/services/contractErrorParser.ts
@@ -0,0 +1,265 @@
+/**
+ * Contract Error Parser
+ *
+ * Decodes Soroban invocation failures from XDR result codes into structured,
+ * human-readable error objects. Mirrors the pattern established in
+ * transactionSimulation.ts for Horizon errors, but targets Soroban contract
+ * invocation failures specifically.
+ *
+ * Issue: https://github.com/Gildado/PayD/issues/82
+ */
+
+// ---------------------------------------------------------------------------
+// Known contract error code mappings
+// ---------------------------------------------------------------------------
+
+/**
+ * Soroban host-level error codes returned inside the InvokeHostFunctionResult XDR.
+ * Keys are the canonical string codes surfaced by the Soroban RPC error field.
+ */
+const CONTRACT_ERROR_MESSAGES: Record<
+  string,
+  { description: string; suggestedAction: string }
+> = {
+  // ── Invocation failures ──────────────────────────────────────────────
+  invoke_host_function_trapped: {
+    description: 'The contract function panicked during execution.',
+    suggestedAction: 'Check the contract arguments for out-of-range values or invalid state.',
+  },
+  invoke_host_function_malformed: {
+    description: 'The invocation arguments are malformed or do not match the contract ABI.',
+    suggestedAction: 'Verify the argument types and ordering expected by the contract function.',
+  },
+
+  // ── Authorization failures ───────────────────────────────────────────
+  auth_required: {
+    description: 'The caller is not authorized to invoke this contract function.',
+    suggestedAction: 'Ensure the signing account has the required role or approval.',
+  },
+  bad_auth: {
+    description: 'Contract authorization check failed — signature invalid or missing.',
+    suggestedAction: 'Re-sign the transaction with the correct account keypair.',
+  },
+
+  // ── Footprint / resource failures ───────────────────────────────────
+  insufficient_refundable_fee: {
+    description: 'The fee is too low to cover Soroban resource usage for this invocation.',
+    suggestedAction: 'Increase the base fee or resource fee to meet the contract execution cost.',
+  },
+  resource_limit_exceeded: {
+    description: 'Contract execution exceeded CPU, memory, or ledger entry limits.',
+    suggestedAction:
+      'Simplify the invocation or batch fewer items per call to reduce resource usage.',
+  },
+  invalid_ledger_entry_access: {
+    description: 'The contract attempted to access a ledger entry not declared in the footprint.',
+    suggestedAction:
+      'Re-simulate the transaction to refresh the footprint before submitting.',
+  },
+
+  // ── Contract-defined error codes (numeric, surfaced as strings) ──────
+  contract_error_0: {
+    description: 'Contract error code 0 — operation not permitted in the current contract state.',
+    suggestedAction: 'Check that the contract is in the expected state before invoking.',
+  },
+  contract_error_1: {
+    description: 'Contract error code 1 — arithmetic overflow or underflow detected.',
+    suggestedAction: 'Verify that amount values are within the accepted range for this contract.',
+  },
+  contract_error_2: {
+    description: 'Contract error code 2 — vesting schedule has not started yet.',
+    suggestedAction: 'Wait until the vesting start date before claiming tokens.',
+  },
+  contract_error_3: {
+    description: 'Contract error code 3 — no vested tokens are available to claim at this time.',
+    suggestedAction: 'Check the vesting schedule to confirm the claimable amount.',
+  },
+  contract_error_4: {
+    description: 'Contract error code 4 — recipient address is not registered in this contract.',
+    suggestedAction: 'Confirm the recipient was added during contract initialization.',
+  },
+  contract_error_5: {
+    description: 'Contract error code 5 — insufficient token balance in the contract escrow.',
+    suggestedAction: 'Ensure the contract was funded before attempting a withdrawal.',
+  },
+
+  // ── Payroll-specific codes ───────────────────────────────────────────
+  payroll_duplicate_period: {
+    description: 'A payroll disbursement for this period has already been processed.',
+    suggestedAction: 'Advance to the next pay period before submitting.',
+  },
+  payroll_employee_not_found: {
+    description: 'The specified employee ID does not exist in the payroll contract.',
+    suggestedAction: 'Register the employee before scheduling a payment.',
+  },
+
+  // ── Cross-asset payment codes ────────────────────────────────────────
+  swap_slippage_exceeded: {
+    description: 'The swap could not be completed — price moved beyond the slippage tolerance.',
+    suggestedAction: 'Increase slippage tolerance or retry when market conditions stabilize.',
+  },
+  no_liquidity: {
+    description: 'Insufficient liquidity in the pool for this asset pair.',
+    suggestedAction: 'Try a different asset pair or reduce the payment amount.',
+  },
+
+  // ── Generic fallback ─────────────────────────────────────────────────
+  unknown_contract_error: {
+    description: 'An unrecognised contract error occurred.',
+    suggestedAction: 'Copy the raw XDR and open a support ticket for further investigation.',
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** A structured, parsed representation of a single contract error */
+export interface ContractError {
+  /** The canonical error code string */
+  code: string;
+  /** Human-readable description of what the error means */
+  description: string;
+  /** Suggested action for the user to resolve the issue */
+  suggestedAction: string;
+  /**
+   * The raw XDR result string, included when the error code was not
+   * recognised so the user can inspect or copy it directly.
+   */
+  rawXdr?: string;
+}
+
+/** The full result of calling `parseContractError` */
+export interface ContractErrorResult {
+  /** Whether a known error mapping was found */
+  known: boolean;
+  /** The primary parsed error */
+  error: ContractError;
+  /**
+   * The original result XDR passed in — always preserved so the UI can
+   * render a copy button regardless of whether the error was recognised.
+   */
+  resultXdr: string;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Attempts to extract a canonical error code string from a Soroban result XDR
+ * or error message string.
+ *
+ * The Soroban RPC `simulateTransaction` response surfaces errors as plain
+ * strings (e.g. "HostError: Value(ContractError(3))") or as result_xdr
+ * blobs. This function normalises both forms into the lookup key used by
+ * `CONTRACT_ERROR_MESSAGES`.
+ */
+function extractErrorCode(resultXdr: string): string | null {
+  const lower = resultXdr.toLowerCase();
+
+  // Direct key match — highest priority (e.g. from structured RPC error fields)
+  const directMatch = Object.keys(CONTRACT_ERROR_MESSAGES).find((key) =>
+    lower.includes(key.toLowerCase())
+  );
+  if (directMatch) return directMatch;
+
+  // Soroban host error pattern: "ContractError(N)" → contract_error_N
+  const contractErrMatch = /contracterror\((\d+)\)/i.exec(resultXdr);
+  if (contractErrMatch) {
+    const numericKey = `contract_error_${contractErrMatch[1]}`;
+    if (numericKey in CONTRACT_ERROR_MESSAGES) return numericKey;
+  }
+
+  // Soroban invoke_host_function result codes surfaced in result XDR strings
+  if (lower.includes('trapped')) return 'invoke_host_function_trapped';
+  if (lower.includes('malformed')) return 'invoke_host_function_malformed';
+  if (lower.includes('resourcelimitexceeded') || lower.includes('resource_limit'))
+    return 'resource_limit_exceeded';
+  if (lower.includes('insufficientrefundablefee') || lower.includes('refundable_fee'))
+    return 'insufficient_refundable_fee';
+  if (lower.includes('invalidledgerentryaccess') || lower.includes('ledger_entry_access'))
+    return 'invalid_ledger_entry_access';
+  if (lower.includes('authrequired') || lower.includes('auth_required')) return 'auth_required';
+  if (lower.includes('badauth') || lower.includes('bad_auth')) return 'bad_auth';
+
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Decodes a Soroban invocation failure from an XDR result code string into a
+ * structured `ContractErrorResult`.
+ *
+ * For known error codes the result includes a human-readable description and a
+ * suggested action. For unknown codes the raw XDR is surfaced so the user can
+ * inspect or copy it.
+ *
+ * @param resultXdr - The result XDR or error string from a failed invocation.
+ *   This can be a base64-encoded XDR blob, a Soroban RPC error message string,
+ *   or any representation that contains recognisable error tokens.
+ *
+ * @example
+ * // Known error
+ * const result = parseContractError('HostError: Value(ContractError(2))');
+ * // result.known === true
+ * // result.error.code === 'contract_error_2'
+ * // result.error.description === 'Vesting schedule has not started yet.'
+ *
+ * @example
+ * // Unknown error — falls back to raw XDR display
+ * const result = parseContractError('AAAABAAAAAgAAAAA...');
+ * // result.known === false
+ * // result.error.rawXdr is set to the original string
+ */
+export function parseContractError(resultXdr: string): ContractErrorResult {
+  if (!resultXdr || resultXdr.trim() === '') {
+    return {
+      known: true,
+      error: {
+        code: 'unknown_contract_error',
+        ...CONTRACT_ERROR_MESSAGES.unknown_contract_error,
+      },
+      resultXdr,
+    };
+  }
+
+  const code = extractErrorCode(resultXdr);
+
+  if (code && code in CONTRACT_ERROR_MESSAGES) {
+    return {
+      known: true,
+      error: {
+        code,
+        ...CONTRACT_ERROR_MESSAGES[code],
+      },
+      resultXdr,
+    };
+  }
+
+  // Unknown error — fall back to raw XDR display
+  return {
+    known: false,
+    error: {
+      code: 'unknown_contract_error',
+      description: 'An unrecognised contract error occurred.',
+      suggestedAction:
+        'Copy the raw XDR below and open a support ticket for further investigation.',
+      rawXdr: resultXdr,
+    },
+    resultXdr,
+  };
+}
+
+/**
+ * Returns all currently mapped error codes and their metadata.
+ * Useful for generating documentation or test fixtures.
+ */
+export function getAllContractErrorCodes(): Array<
+  { code: string } & { description: string; suggestedAction: string }
+> {
+  return Object.entries(CONTRACT_ERROR_MESSAGES).map(([code, meta]) => ({ code, ...meta }));
+}